Module density_fda 

Density-valued functional data analysis (LQD transform, Wasserstein barycenter, density FPCA).

This module implements the log-quantile-density (LQD) transformation framework of Petersen and Mueller (2016) for probability-density-valued functional data. The LQD map embeds the constraint-carrying space of probability densities into the unconstrained Hilbert space L²([0,1]), where ordinary FPCA applies. The inverse map always returns a valid (non-negative, unit-integral) probability density.

Types

• LqdFpcaResult — output of lqd_fpca, embedding the LQD-space crate::regression::FpcaResult plus fraction of variance explained (FVE).

R baseline

The algorithms in this module are based on the R package fdadensity 0.1.4 (https://cran.r-project.org/package=fdadensity), specifically:

• dens2lqd — forward LQD transform
• lqd2dens — inverse LQD transform
• FPCAdens — functional PCA of densities via LQD space
• getWFmean — Wasserstein Fréchet mean (quantile average)

Reference: Petersen, A. and Mueller, H.-G. (2016). Functional data analysis for density functions by transformation to a Hilbert space. Annals of Statistics, 44(1):183–218. https://doi.org/10.1214/15-AOS1363

Examples

use fdars_core::density_fda::{normalize_density, lqd_transform, inverse_lqd};

// Uniform density on [0, 1]: ψ(t) = 0 for all t
let argvals: Vec<f64> = (0..51).map(|i| i as f64 / 50.0).collect();
let uniform: Vec<f64> = vec![1.0; 51];

let normed = normalize_density(&uniform, &argvals).unwrap();
let psi = lqd_transform(&normed, &argvals, Some(51)).unwrap();
// ψ ≡ 0 for the uniform density (analytic result)
assert!(psi.iter().all(|&v| v.abs() < 1e-6));

// Round-trip back to density space
let t_grid: Vec<f64> = (0..51).map(|i| i as f64 / 50.0).collect();
let recovered = inverse_lqd(&psi, &t_grid, &argvals).unwrap();
// Recovered density integrates to 1

Divergences from fdadensity

1. Quantile interpolation: fdadensity uses spline(..., method = 'natural') (natural cubic spline) for the CDF→t mapping in dens2lqd and the Q→target-grid back-mapping in lqd2dens. This implementation uses crate::helpers::linear_interp (piecewise linear). Effect: the round-trip (lqd_transform → inverse_lqd) L∞ error is larger than the cubic-spline reference. Measured on a truncated standard Gaussian at 201 points it is ~1.0e-2 (vs. ~5e-3 for cubic spline); on flatter/smoother densities or denser grids it is smaller. Callers needing tighter round-trip accuracy should supply a finer density grid or a smoother reference. The reconstructed density always integrates to 1 and is non-negative regardless of interpolation error.

2. useSplines integration path: fdadensity::lqd2dens has an optional path that integrates exp(spline(ψ)) analytically per panel. This implementation always uses cumulative_trapz(exp(ψ), t_grid), trading a small accuracy difference for code simplicity and zero new dependencies.

3. wasserstein_barycenter weights: fdadensity::getWFmean does not support a weight parameter. This implementation accepts weights: Option<&[f64]>, defaulting to uniform 1/n — a strict superset of fdadensity capability.

4. Silent normalization: fdadensity emits a warning when |trapz(dens) − 1| > 1e-5. This implementation normalizes silently without a warning and documents the behaviour here.

Structs

LqdFpcaResult

Result of functional PCA on log-quantile-density (LQD) transformed densities.

Functions

inverse_lqd

Inverse LQD transform: reconstruct a normalized probability density on target_argvals.

lqd_fpca

Functional PCA of probability densities in LQD space.

lqd_transform

Log-quantile-density (LQD) forward transform.

normalize_density

Normalize a density so that it integrates to 1 via trapezoidal quadrature.

wasserstein_barycenter

1D Wasserstein Fréchet mean (quantile-average barycenter) of a collection of densities.