Autocovariance and Autocorrelation

Install and import#

npm install fintech-algorithms

import { autocovarianceAndAutocorrelation } from "fintech-algorithms/foundations/financial-time-series-foundations/autocovariance-and-autocorrelation";

Signature#

autocovarianceAndAutocorrelation(input)

Measures how far a series moves with its own past at a given lag, using the population convention that divides by the full observation count.

Parameters#

Returns#

D00Output

autocovariance is the mean product of deviations lag apart, autocorrelation is that figure divided by the population variance, and lag is echoed back.

Errors#

• When values is absent, empty, or holds a non-finite number — throws RangeError
• When timestamps and values have different lengths — throws RangeError
• When the series holds fewer than two observations — throws RangeError
• When lag is not an integer between one and the observation count minus one — throws RangeError
• When the series is constant, so its population variance is zero — throws RangeError

Complexity: time O(n^2), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "timestamps": [
    "2025-01-01T00:00:00Z",
    "2025-01-02T00:00:00Z",
    "2025-01-03T00:00:00Z",
    "2025-01-04T00:00:00Z",
    "2025-01-05T00:00:00Z",
    "2025-01-06T00:00:00Z"
  ],
  "values": [100, 102, 101, 104, 106, 105],
  "lag": 1,
  "window": 3,
  "resampleSize": 2,
  "period": 3,
  "stationarityTolerance": 3,
  "alpha": 0.4,
  "splitIndex": 4
}

Call#

autocovarianceAndAutocorrelation(input)

Returns#

object with 2 fields: autocovariance, autocorrelation

{
  "autocovariance": 2,
  "autocorrelation": 0.42857142857142855
}

Diagrams#

Calculation flow#

flowchart LR
    A["Synthetic input + metadata"] --> B{"Contract valid?"}
    B -->|No| C["Reject or route with reason"]
    B -->|Yes| D["Apply Autocovariance and Autocorrelation"]
    D --> E["Formula: γk=(1/n)Σₜ₌k(xₜ−x̄)(xₜ₋ₖ−x̄); ρk=γk/γ0"]
    E --> F["Verified fixture output"]
    F --> G{"Interpretation within boundary?"}
    G -->|Yes| H["Report value + convention + audit"]
    G -->|No| I["Add companion view or narrower claim"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Time Series Plot — NIST/SEMATECH e-Handbook
• Common Pitfalls and Recommended Practices — scikit-learn
• Historical-example decision

The rest of the Financial Time-Series Foundations family#

• Time Order, Frequency, Regularity, and Financial CalendarsChecks whether a timestamped series runs in chronological order and whether its observations are evenly spaced, reporting the c…
• Levels, Changes, Differences, and ReturnsConverts a level series into its period-over-period differences and its simple returns, keeping the original levels alongside t…
• Lags, Leads, and Temporal DependencePairs every observation with the value lag positions behind it, and exposes the same series shifted forward as the lead.
• Rolling and Expanding WindowsComputes a fixed-length rolling mean of the series next to its expanding mean, so a window that forgets can be compared with on…
• Resampling, Aggregation, and Time AlignmentCuts the series into consecutive fixed-size buckets and averages each one, coarsening the sampling frequency.
• Trend, Seasonality, Cycles, and RemainderSeparates a series into a rolling-mean trend, a seasonal difference taken period steps back, and the remainder left once the …
• Stationarity and Differencing IntuitionCompares the average level of the second half of a series with the first half, and reports the first differences, as a rough re…
• Smoothing, Baselines, and Naive ForecastsRuns simple exponential smoothing over the series and reports both the naive last-value forecast and the smoothed one.
• Look-Ahead Leakage and Time-Aware Data SplitsSplits a timestamped series at a given position and reports whether the training block reaches into the testing block's time ra…