trace_acf.h File Reference

Autocorrelation coefficients of a trace at the requested lags. More...

#include <cstddef>
#include <vector>
#include "line/api/trace/autocov.h"
#include "line/api/trace/trace_types.h"
#include "line/num/number.h"
#include "line/util/error.h"

Include dependency graph for trace_acf.h:

Go to the source code of this file.

Namespaces
namespace	line
namespace	line::trace

Functions
template<class T>
std::vector< T >	line::trace::trace_acf (const std::vector< T > &S, const std::vector< int > &lags)
	Autocorrelation coefficients of a trace at the requested lags.
template<class T>
std::vector< T >	line::trace::trace_acf (const std::vector< T > &S)
	Lag-1 autocorrelation, the MATLAB and JAR default.

Detailed Description

Autocorrelation coefficients of a trace at the requested lags.

rho(k) = acv(k) / acv(0)

Templated port of matlab/lib/kpctoolbox/trace/trace_acf.m, cross-checked against jar/src/main/java/jline/api/trace/Trace_var.java#trace_acf.

DIVERGENCE INSIDE MATLAB: trace_acf.m has two branches. When the Signal Processing Toolbox is present it uses xcorr(...,'coeff'), whose estimator divides every lag by the same n (the biased estimator); otherwise it falls back to autocov, which divides lag p by n-p. The two therefore differ by the factor n/(n-p) at lag p – the same trace gives different acf values depending on which toolboxes are installed. Measured on the trace 1,2,3,4,5: MATLAB with the toolbox returns 0.4 and -0.1 at lags 1 and 2, while the JAR and the MATLAB fallback return 1/2 and -1/6. The JAR ports the fallback branch, and so does this header – it is the branch the two codebases share, and the one whose lag-0 value is the sample variance.

OUT-OF-RANGE LAGS: MATLAB clamps them to n-2 and then deletes the clamped entries, the JAR filters out every lag outside (0, n-2]. Both silently return fewer values than lags requested; this port follows the JAR filter and documents it rather than throwing, so that trace_summary and trace_gamma keep working on short traces.

ARITHMETIC: a ratio of autocovariances, exact in Rational.

Definition in file trace_acf.h.