cmp::statistics::PairwiseDistanceStats Class Reference

Computes and stores pairwise spatial distances between high-dimensional data points. More...

#include <statistics.h>

Public Member Functions
	PairwiseDistanceStats ()
	Default constructor.
void	compute (const Eigen::MatrixXd &data)
	Computes the upper triangle of the pairwise Euclidean distance matrix.
double	mean () const
	Retrieves the mean pairwise distance \( \bar{d} \).
double	quantile (double q)
	Fast quantile retrieval without executing a full sort.
std::vector< double >	correlation_integral (const std::vector< double > &r_thresholds) const
	Computes the spatial Correlation Integral \( C(r) \) for a grid of radial thresholds.

Private Attributes
std::vector< double >	distances
	1D flattened array of the strictly upper triangular distance matrix.
double	mean_val
	The globally computed mean distance across all pairs.
bool	is_computed
	Flag indicating if the distances have been computed and the class is ready to query.

Detailed Description

Computes and stores pairwise spatial distances between high-dimensional data points.

Efficiently computes the upper triangle of the distance matrix to save memory, utilizing OpenMP for multi-threaded parallel execution. Provides fast access to mean distances, spatial quantiles, and the spatial correlation integral.

Constructor & Destructor Documentation

PairwiseDistanceStats()

cmp::statistics::PairwiseDistanceStats::PairwiseDistanceStats ( )

inline

Default constructor.

Member Function Documentation

compute()

void cmp::statistics::PairwiseDistanceStats::compute ( const Eigen::MatrixXd &  data )

inline

Computes the upper triangle of the pairwise Euclidean distance matrix.

Mathematical Formulation

Evaluates the \( L_2 \)-norm between all unique pairs:

\[ d_{ij} = ||\mathbf{x}_i - \mathbf{x}_j||_2 \quad \text{for } 1 \le i < j \le N \]

Utilizes OpenMP dynamic scheduling to balance the uneven workload of the triangular nested loops.

• Parameters

  data	Matrix of size (N, D) where N is number of points, D is dimensions.

  Exceptions

  std::invalid_argument

  if fewer than 2 points are provided.

correlation_integral()

std::vector< double > cmp::statistics::PairwiseDistanceStats::correlation_integral ( const std::vector< double > &  r_thresholds ) const

inline

Computes the spatial Correlation Integral \( C(r) \) for a grid of radial thresholds.

Mathematical Formulation

Computes the fraction of pairwise distances strictly less than \( r \):

\[ C(r) = \frac{2}{N(N-1)} \sum_{i=1}^{N-1} \sum_{j=i+1}^N \Theta(r - d_{ij}) \]

where \( \Theta \) is the Heaviside step function.

• ### Implementation Algorithm

1. Copies and sorts the requested threshold bounds \( r \).
2. Utilizes OpenMP parallelization and binary search (std::upper_bound) in \( \mathcal{O}(\log K) \) to rapidly bin every pairwise distance into thread-local histograms.
3. Calculates the cumulative sum globally to construct the integral profile \( C(r) \).

• Parameters

  r_thresholds

  A vector of spatial radii ( \( r \)). Does not need to be pre-sorted.

  Returns

  std::vector<double> The fraction of pairwise distances less than each corresponding radius \( r \).

  Exceptions

  std::runtime_error

  if called before compute().

mean()

double cmp::statistics::PairwiseDistanceStats::mean ( ) const

inline

Retrieves the mean pairwise distance \( \bar{d} \).

Returns

The mean distance.

Exceptions

std::runtime_error

if called before compute().

quantile()

double cmp::statistics::PairwiseDistanceStats::quantile ( double  q )

inline

Fast quantile retrieval without executing a full sort.

• Uses std::nth_element to achieve \( \mathcal{O}(M) \) partial sorting performance compared to \( \mathcal{O}(M \log M) \) for full sorting. Note this mutates the internal distance array's ordering but preserves the exact values.

• Parameters

  q	Target quantile probability \( p \in [0, 1] \) (e.g., 0.5 for median).

  Returns

  The distance value representing that quantile.

  Exceptions

  std::runtime_error	if called before compute().
  std::invalid_argument	if \( p \) is outside bounds.

Member Data Documentation

distances

std::vector<double> cmp::statistics::PairwiseDistanceStats::distances

private

1D flattened array of the strictly upper triangular distance matrix.

is_computed

bool cmp::statistics::PairwiseDistanceStats::is_computed

private

Flag indicating if the distances have been computed and the class is ready to query.

mean_val

double cmp::statistics::PairwiseDistanceStats::mean_val

private

The globally computed mean distance across all pairs.

---

The documentation for this class was generated from the following file:

• include/statistics.h