---
name: autocorr
kind: function
lang: cpp
domain: datascience
version: "1.0.0"
purity: pure
signature: "double autocorr_lag(const double* x, size_t n, size_t k); void autocorr_acf(const double* x, size_t n, size_t max_lag, double* out); double autocorr_tau(const double* x, size_t n, size_t max_lag, double cutoff)"
description: "Autocorrelacion de series temporales: r(k) por lag, ACF completa hasta max_lag, y tiempo de autocorrelacion integrado (tau_int de Sokal) para Effective Sample Size en MCMC."
tags: [autocorrelation, acf, mcmc, ess, time_series, datascience]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [cstddef, cmath]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/datascience/autocorr.cpp"
params:
  - name: x
    desc: "Serie temporal (cadena MCMC, balance de sesion, log-returns...)."
  - name: n
    desc: "Longitud de la serie."
  - name: k
    desc: "Lag para autocorr_lag. r(0) = 1 si var > 0."
  - name: max_lag
    desc: "Lag maximo. ACF emite max_lag valores; tau_int trunca aqui si nunca baja del cutoff."
  - name: cutoff
    desc: "(tau) Umbral |r(k)| bajo el cual se trunca la suma. Default 0.05 (recomendacion estandar)."
  - name: out
    desc: "(acf) buffer destino double[max_lag]."
output: "Escalar (lag, tau) o array (acf). Definicion clasica r(k) = cov(x_t, x_{t+k}) / var(x). Si var=0 devuelve 0/1 segun el caso."
---

# autocorr

Autocorrelacion para diagnostico de cadenas MCMC. Las 4 calculadoras MCMC del set lo usan para detectar cuando las muestras estan demasiado correladas (= la cadena no esta explorando bien).

## Patron de uso (ACF plot)

```cpp
constexpr int max_lag = 40;
std::vector<double> acf(max_lag);
fn::ds::autocorr_acf(chain.data(), chain.size(), max_lag, acf.data());

// Pasar a line_plot_cpp_viz, eje X = 0..max_lag-1
fn::viz::line_plot(acf.data(), max_lag, /*...*/);
```

## Effective Sample Size

```cpp
double tau = fn::ds::autocorr_tau(chain.data(), chain.size());
double ess = static_cast<double>(chain.size()) / tau;
// Cadena de 10000 con tau=20 -> ESS=500. Bayesian rule of thumb: ESS > 100
// para inferencia decente; > 1000 para CIs ajustados.
```

## Definicion

`r(k) = (1/(n-k)) * sum_{i=0}^{n-k-1} (x_i - mu)(x_{i+k} - mu) / var(x)` donde `var(x) = (1/n) * sum (x_i - mu)^2` (poblacional). Esta es la convencion mas comun (numpy.correlate scaled, statsmodels.acf con `unbiased=False, fft=False`).

`tau_int = 1 + 2 * sum_{k=1}^{kmax} r(k)` con kmax = primer k tal que |r(k)| < cutoff. Es la formula de Sokal usada en MCMC diagnostics (similar a la de la libreria emcee).

## Performance

`autocorr_acf` es O(n * max_lag). Para cadenas de 10^5-10^6 con max_lag=40 son ~10ms — suficiente para refresh interactivo. Para max_lag mayores considerar FFT-based ACF (no incluida).

## Notas

- Usa la formula time-domain (sin FFT). Hasta n=10^7 con max_lag=100 es OK; mas alla, FFT.
- No corrige el sesgo small-sample. Para cadenas cortas (<200 samples) el estimador es biased — pasar a versiones unbiased si la app lo requiere.