cmp::statistics Namespace Reference

Classes
class	Bootstrap
	Bootstrap resampling index generator. More...
class	KFold
	K-Fold cross-validation partition generator. More...
class	PairwiseDistanceStats
	Computes and stores pairwise spatial distances between high-dimensional data points. More...

Functions
Eigen::VectorXd	mean (const Eigen::Ref< const Eigen::MatrixXd > &data)
	Computes the empirical mean vector of a dataset.
Eigen::MatrixXd	covariance (const Eigen::Ref< const Eigen::MatrixXd > &data)
	Computes the sample covariance matrix of a dataset.
double	quantile (const Eigen::Ref< const Eigen::VectorXd > &data, double quantile)
	Computes a specific quantile of a 1D vector of data.
Eigen::VectorXd	interQuantileRange (const Eigen::Ref< const Eigen::MatrixXd > &data, double lowerQuantile, double upperQuantile)
	Computes the interquartile range (IQR) column-wise for a dataset.
Eigen::MatrixXd	pearsonCorrelation (const Eigen::Ref< const Eigen::MatrixXd > &data1, const Eigen::Ref< const Eigen::MatrixXd > &data2)
	Computes the Pearson correlation matrix between two datasets.
Eigen::MatrixXd	laggedCorrelation (const Eigen::Ref< const Eigen::MatrixXd > &data1, const Eigen::Ref< const Eigen::MatrixXd > &data2, int lag)
	Computes the cross-correlation matrix between two datasets with a specified temporal lag.
std::vector< Eigen::MatrixXd >	laggedCorrelation (const Eigen::Ref< const Eigen::MatrixXd > &data1, const Eigen::Ref< const Eigen::MatrixXd > &data2, int minLag, int maxLag)
	Returns the cross-correlation matrices between two datasets for a sequence of lags.
std::pair< Eigen::VectorXd, double >	selfCorrelationLength (const Eigen::Ref< const Eigen::MatrixXd > &data)
	Computes the self-correlation (autocorrelation) length and the effective sample size.
std::vector< Eigen::MatrixXd >	selfCrossCorrelationFFT (const Eigen::Ref< const Eigen::MatrixXd > &data)
	Computes the complete auto- and cross-correlation functions across all lags efficiently using the Fast Fourier Transform (FFT).

Function Documentation

covariance()

Eigen::MatrixXd cmp::statistics::covariance

(

const Eigen::Ref< const Eigen::MatrixXd > &

data

)

Computes the sample covariance matrix of a dataset.

Mathematical Formulation

Given a dataset matrix \(\mathbf{X} \in \mathbb{R}^{N \times D}\) with mean vector \(\boldsymbol{\mu}\), the unbiased sample covariance matrix \(\mathbf{\Sigma} \in \mathbb{R}^{D \times D}\) is:

\[ \mathbf{\Sigma} = \frac{1}{N-1} (\mathbf{X} - \mathbf{1}\boldsymbol{\mu}^T)^T (\mathbf{X} - \mathbf{1}\boldsymbol{\mu}^T) \]

Parameters

data	A reference to an Eigen matrix containing the data (points in rows).

Returns

The covariance matrix of the data.

Exceptions

std::invalid_argument

if the input matrix has fewer than 2 rows.

interQuantileRange()

Eigen::VectorXd cmp::statistics::interQuantileRange	(	const Eigen::Ref< const Eigen::MatrixXd > &	data,
		double	lowerQuantile,
		double	upperQuantile
	)

Computes the interquartile range (IQR) column-wise for a dataset.

Mathematical Formulation

For each feature column \( j \):

\[ \text{IQR}_j = Q_{\text{upper}, j} - Q_{\text{lower}, j} \]

where \(Q\) represents the value at the specified quantile probabilities.

• Parameters

  data	A reference to an Eigen matrix containing the data (points in rows).
  lowerQuantile	The lower probability bound (e.g., 0.25).
  upperQuantile	The upper probability bound (e.g., 0.75).

  Returns

  A vector containing the IQR for each feature column.

  Exceptions

  std::invalid_argument

  if the input matrix is empty or the quantiles are invalid.

laggedCorrelation() [1/2]

Eigen::MatrixXd cmp::statistics::laggedCorrelation	(	const Eigen::Ref< const Eigen::MatrixXd > &	data1,
		const Eigen::Ref< const Eigen::MatrixXd > &	data2,
		int	lag
	)

Computes the cross-correlation matrix between two datasets with a specified temporal lag.

Correlates \(X(t)\) from data1 with \(Y(t + \tau)\) from data2 where \(\tau\) is the lag.

• Parameters

  data1	First dataset (time series points in rows).
  data2	Second dataset (time series points in rows).
  lag	The discrete time lag \( \tau \) to apply to the second dataset.

  Returns

  The lagged correlation matrix.

laggedCorrelation() [2/2]

std::vector< Eigen::MatrixXd > cmp::statistics::laggedCorrelation	(	const Eigen::Ref< const Eigen::MatrixXd > &	data1,
		const Eigen::Ref< const Eigen::MatrixXd > &	data2,
		int	minLag,
		int	maxLag
	)

Returns the cross-correlation matrices between two datasets for a sequence of lags.

Parameters

data1	First dataset (time series points in rows).
data2	Second dataset (time series points in rows).
minLag	Minimum lag \( \tau_{\text{min}} \) to consider.
maxLag	Maximum lag \( \tau_{\text{max}} \) to consider.

Returns

A std::vector of correlation matrices, ordered from minLag to maxLag.

mean()

Eigen::VectorXd cmp::statistics::mean

(

const Eigen::Ref< const Eigen::MatrixXd > &

data

)

Computes the empirical mean vector of a dataset.

Mathematical Formulation

For a dataset matrix \(\mathbf{X} \in \mathbb{R}^{N \times D}\), the mean vector \(\boldsymbol{\mu} \in \mathbb{R}^D\) is:

\[ \boldsymbol{\mu} = \frac{1}{N} \sum_{i=1}^N \mathbf{x}_i \]

Parameters

data	A reference to a matrix containing the data (points in rows, features in columns).

Returns

A column vector containing the mean of each feature.

Exceptions

std::invalid_argument

if the input matrix is empty.

pearsonCorrelation()

Eigen::MatrixXd cmp::statistics::pearsonCorrelation	(	const Eigen::Ref< const Eigen::MatrixXd > &	data1,
		const Eigen::Ref< const Eigen::MatrixXd > &	data2
	)

Computes the Pearson correlation matrix between two datasets.

Mathematical Formulation

For columns \(X_i\) from data1 and \(Y_j\) from data2, the correlation coefficient is:

\[ \rho_{ij} = \frac{\mathrm{cov}(X_i, Y_j)}{\sigma_{X_i} \sigma_{Y_j}} \]

Manages the case where the datasets have different numbers of points by aligning them appropriately if supported by the implementation.

• Parameters

  data1	First dataset (points in rows).
  data2	Second dataset (points in rows).

  Returns

  The Pearson correlation matrix \( \mathbf{R} \in \mathbb{R}^{D_1 \times D_2} \).

quantile()

double cmp::statistics::quantile	(	const Eigen::Ref< const Eigen::VectorXd > &	data,
		double	quantile
	)

Computes a specific quantile of a 1D vector of data.

Parameters

data	A reference to an Eigen vector containing the data.
quantile	The target probability quantile \( p \in [0, 1] \).

Returns

The computed value representing the \( p \)-th quantile.

Exceptions

std::invalid_argument

if the input vector is empty or the quantile is out of bounds.

selfCorrelationLength()

std::pair< Eigen::VectorXd, double > cmp::statistics::selfCorrelationLength

(

const Eigen::Ref< const Eigen::MatrixXd > &

data

)

Computes the self-correlation (autocorrelation) length and the effective sample size.

• Useful for MCMC diagnostics to determine the number of independent samples.

• Parameters

  data	the dataset containing the samples (each sample is a row).

  Returns

  a std::pair containing:

1. An Eigen::VectorXd of correlation lengths for each feature.
2. A double representing the overall effective sample size (ESS).

selfCrossCorrelationFFT()

std::vector< Eigen::MatrixXd > cmp::statistics::selfCrossCorrelationFFT ( const Eigen::Ref< const Eigen::MatrixXd > &  data )

inline

Computes the complete auto- and cross-correlation functions across all lags efficiently using the Fast Fourier Transform (FFT).

Mathematical Formulation (Wiener-Khinchin Theorem)

The cross-correlation \(R_{ij}(\tau)\) between feature \(i\) and \(j\) can be computed in the frequency domain:

\[ R_{ij}(\tau) = \mathcal{F}^{-1}\left\{ \mathcal{F}\{x_i\} \cdot \mathcal{F}\{x_j\}^* \right\} \]

where \(\mathcal{F}\) is the discrete Fourier transform. Data is mean-centered, zero-padded to the next power of 2 to avoid circular convolution artifacts, and properly normalized by sample variances.

• Parameters

  data	A reference to the dataset matrix (time points in rows, features in columns).

  Returns

  A vector of length nPoints. Each element is a nFeatures x nFeatures matrix representing the correlation at lag \(\tau\).