Autocorrelation Indicator

Parameters: length = 20 | max_lag = 99 | use_test_signal =

Overview

Autocorrelation Indicator looks for repeating cycle structure by comparing the current filtered signal against lagged copies of itself. The indicator first smooths the input series with an ultimate smoother, then computes a rolling correlation score for every lag from 1 up to the configured maximum. That turns the result into a surface rather than a single line: one filtered series plus a matrix of correlation rows.

The practical use is cycle discovery. Strong positive correlation at a particular lag suggests the filtered signal is repeating on roughly that cadence. Weak or unstable correlation suggests the cycle structure is noisy or shifting. The optional internal test signal is useful for debugging chart and binding code because it replaces the source stream with a clean sine wave of known period.

Defaults: Autocorrelation Indicator uses `length = 20`, `max_lag = 99`, and `use_test_signal = false`.

Implementation Examples

Compute the filtered series and lag-by-time correlation surface from a slice or from a candle source field.

use vector_ta::indicators::autocorrelation_indicator::{
    autocorrelation_indicator,
    AutocorrelationIndicatorInput,
    AutocorrelationIndicatorParams,
};
use vector_ta::utilities::data_loader::{Candles, read_candles_from_csv};

let close = vec![100.0, 100.7, 101.3, 101.0, 101.8, 102.4, 102.0, 102.9];

let output = autocorrelation_indicator(&AutocorrelationIndicatorInput::from_slice(
    &close,
    AutocorrelationIndicatorParams {
        length: Some(20),
        max_lag: Some(30),
        use_test_signal: Some(false),
    },
))?;

let candles: Candles = read_candles_from_csv("data/sample.csv")?;
let candle_output = autocorrelation_indicator(
    &AutocorrelationIndicatorInput::with_default_candles(&candles)
)?;

println!("Filtered sample: {:?}", &output.filtered[..output.cols.min(5)]);
println!("Lag rows: {}", output.lag_count);
println!("Candle cols: {}", candle_output.cols);

API Reference

Input Methods ▼ 
// From candles and a named source field
AutocorrelationIndicatorInput::from_candles(&Candles, &str, AutocorrelationIndicatorParams)
    -> AutocorrelationIndicatorInput

// From a slice
AutocorrelationIndicatorInput::from_slice(&[f64], AutocorrelationIndicatorParams)
    -> AutocorrelationIndicatorInput

// From candles with default parameters
AutocorrelationIndicatorInput::with_default_candles(&Candles)
    -> AutocorrelationIndicatorInput
Parameters Structure ▼ 
pub struct AutocorrelationIndicatorParams {
    pub length: Option<usize>,           // default 20
    pub max_lag: Option<usize>,          // default 99
    pub use_test_signal: Option<bool>,   // default false
}
Output Structure ▼ 
pub struct AutocorrelationIndicatorOutput {
    pub filtered: Vec<f64>,
    pub correlations: Vec<f64>,
    pub lag_count: usize,
    pub cols: usize,
}
Validation, Warmup & NaNs ▼
  • The input series must be non-empty.
  • length must be greater than zero and no larger than the data length. max_lag must be greater than zero.
  • With normal input mode, the indicator requires at least one valid run of finite values that is at least as long as length.
  • With use_test_signal = true, the indicator bypasses the source stream and analyzes an internal sine-wave test signal instead.
  • The filtered line can start early, but correlation rows for lag L need at least length + L filtered samples before they become finite.
  • The streaming warmup period is length + max_lag - 1.
  • Batch mode rejects unsupported kernels and can also fail on output-size overflow if the requested matrix shape is too large.
Builder, Streaming & Batch APIs ▼ 
// Builder
AutocorrelationIndicatorBuilder::new()
    .length(usize)
    .max_lag(usize)
    .use_test_signal(bool)
    .kernel(Kernel)
    .apply_slice(&[f64])

AutocorrelationIndicatorBuilder::new()
    .apply_candles(&Candles, &str)

AutocorrelationIndicatorBuilder::new()
    .into_stream()

// Stream
AutocorrelationIndicatorStream::try_new(AutocorrelationIndicatorParams)
AutocorrelationIndicatorStream::update(f64) -> Option<AutocorrelationIndicatorStreamPoint>
AutocorrelationIndicatorStream::reset()
AutocorrelationIndicatorStream::get_warmup_period() -> usize

// Batch
AutocorrelationIndicatorBatchBuilder::new()
    .length_range((usize, usize, usize))
    .max_lag(usize)
    .use_test_signal(bool)
    .kernel(Kernel)
    .apply_slice(&[f64])
Error Handling ▼ 
pub enum AutocorrelationIndicatorError {
    EmptyInputData,
    AllValuesNaN,
    InvalidLength { length: usize, data_len: usize },
    InvalidMaxLag { max_lag: usize },
    NotEnoughValidData { needed: usize, valid: usize },
    FilteredOutputLengthMismatch { expected: usize, got: usize },
    CorrelationsOutputLengthMismatch { expected: usize, got: usize },
    InvalidRange { start: usize, end: usize, step: usize },
    InvalidKernelForBatch(Kernel),
    InvalidInput { msg: String },
}

Python Bindings

Python exposes a dictionary-returning single-run function, a streaming class, and a batch function. The single-run binding returns the filtered vector plus a 2D correlations matrix shaped as (lag_count, cols). Batch returns a 2D filtered matrix, a 3D correlation matrix shaped as (rows, lag_count, cols), and the tested lengths. 

import numpy as np
from vector_ta import (
    autocorrelation_indicator,
    autocorrelation_indicator_batch,
    AutocorrelationIndicatorStream,
)

data = np.asarray(close_values, dtype=np.float64)

result = autocorrelation_indicator(
    data,
    length=20,
    max_lag=30,
    use_test_signal=False,
    kernel="auto",
)

print(result["filtered"][-1], result["correlations"].shape)

batch = autocorrelation_indicator_batch(
    data,
    length_range=(16, 24, 4),
    max_lag=30,
    use_test_signal=False,
    kernel="auto",
)

stream = AutocorrelationIndicatorStream(20, 30, False)
print(stream.update(data[-1]))

JavaScript/WASM Bindings

The WASM surface exposes one object-returning function for a normal run and one for batch sweeps, along with allocation and in-place APIs for raw buffer management. The normal wrapper returns filtered, correlations, lag_count, and cols. The batch wrapper adds rows and combos. 

import init, {
  autocorrelation_indicator_js,
  autocorrelation_indicator_batch_js,
} from "/pkg/vector_ta.js";

await init();

const data = new Float64Array(closeValues);

const result = autocorrelation_indicator_js(data, 20, 30, false);
console.log(result.filtered, result.correlations, result.lag_count, result.cols);

const batch = autocorrelation_indicator_batch_js(data, {
  length_range: [16, 24, 4],
  max_lag: 30,
  use_test_signal: false,
});

console.log(batch.filtered, batch.correlations, batch.rows, batch.cols, batch.combos);

CUDA Bindings (Rust)

Additional details for the CUDA bindings can be found inside the VectorTA repository.

Performance Analysis

Comparison:
View:
Placeholder data (no recorded benchmarks for this indicator)

Across sizes, Rust CPU runs about 1.14× faster than Tulip C in this benchmark.

Loading chart...

AMD Ryzen 9 9950X (CPU) | NVIDIA RTX 4090 (GPU)

Related Indicators

High-Low Correlation

Technical analysis indicator

Correlation Cycle

Technical analysis indicator

Deviation

Technical analysis indicator

Directional Indicator (+DI/-DI)

Technical analysis indicator

Kurtosis

Technical analysis indicator

Linear Regression Angle

Technical analysis indicator