Autocorrelation Utility

Compute autocorrelation metrics for one-dimensional numerical signals.

This module provides reusable autocorrelation functions for one-dimensional signals used in analysis tasks and workflows. It focuses on normalized lag correlation outputs that can be used directly in downstream analysis and plots.

Usage context

Signal analysis: Estimate lag-dependent self-similarity of trajectories.
Time-series workflows: Compute ACF in index space or physical-time space.
Feature extraction: Derive correlation decay behavior for model inputs.

Function: `autocorrelation`

Compute autocorrelation for non-negative lags.

Computes lag-0 through lag-max_lag autocorrelation values with optional centering and selectable normalization strategies.

Parameters:

Name	Type	Description	Default
`signal`	`array - like`	Input 1D signal.	required
`max_lag`	`int`	Maximum lag to return. Default returns all lags `0..N-1`.	`None`
`normalize`	`('none', 'biased', 'unbiased', 'coeff')`	Normalization mode: - 'none': raw correlation sum - 'biased': divide by N - 'unbiased': divide by N-lag - 'coeff': normalized so lag-0 equals 1.0	`'none'`
`center`	`bool`	If True, subtract signal mean before correlation.	`True`

Returns:

Type	Description
`dict[str, ndarray]`	Dictionary with keys: - 'lag': integer lag indices - 'acf': autocorrelation values for each lag

Notes

The autocorrelation is computed using the full convolution method via numpy.correlate for efficiency.
- Numpy main docmentation for np.correlate can be found at https://numpy.org/doc/2.3/reference/generated/numpy.correlate.html
- An example can be found at https://ipython-books.github.io/103-computing-the-autocorrelation-of-a-time-series/
The output lags are non-negative integers up to max_lag or N-1.
Normalization modes allow for different interpretations of the ACF values depending on the analysis context.

Examples:

>>> autocorrelation([1.0, 2.0, 3.0], normalize="coeff")
{'lag': array([0, 1, 2]), 'acf': array([ 1. ,  0. , -0.5])}

Function: `autocorrelation_time`

Compute autocorrelation against physical lag time.

Calls :func:autocorrelation and maps lag indices to physical lag values using tau = lag * dt.