fn_registry/cpp/functions/datascience/autocorr.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
autocorr	function	cpp	datascience	1.0.0	pure	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)	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.	autocorrelation acf mcmc ess time_series datascience				false		cstddef cmath	false			cpp/functions/datascience/autocorr.cpp	name desc x Serie temporal (cadena MCMC, balance de sesion, log-returns...). name desc n Longitud de la serie. name desc k Lag para autocorr_lag. r(0) = 1 si var > 0. name desc max_lag Lag maximo. ACF emite max_lag valores; tau_int trunca aqui si nunca baja del cutoff. name desc cutoff (tau) Umbral |r(k)| bajo el cual se trunca la suma. Default 0.05 (recomendacion estandar). name desc out (acf) buffer destino double[max_lag].	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)

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

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.