pulsatrix 1.1.0
Loading...
Searching...
No Matches
significance.hpp File Reference

Is a loop real? Significance tests for persistence diagrams: the universal null distribution, bootstrap confidence bands, and baseline comparisons against Gaussian clouds or a random network. More...

#include <cstdint>
#include <vector>
#include "pulsatrix/tda/distance_matrix.hpp"
#include "pulsatrix/tda/persistence_diagram.hpp"
#include "pulsatrix/tda/rips_persistence.hpp"
#include "pulsatrix/tensor.hpp"
Include dependency graph for significance.hpp:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  pulsatrix::FeatureSignificance
 One feature's result in UniversalNullTest(). More...
 
struct  pulsatrix::UniversalNullResult
 UniversalNullTest()'s result. More...
 
struct  pulsatrix::BootstrapOptions
 BootstrapBand()'s settings. More...
 
struct  pulsatrix::BootstrapBandResult
 BootstrapBand()'s result. More...
 

Namespaces

namespace  pulsatrix
 

Functions

UniversalNullResult pulsatrix::UniversalNullTest (const PersistenceDiagram &diagram, double alpha=0.05)
 Bobrowski and Skraba's universal null test for every feature of a Vietoris-Rips diagram in dimension 1 or above: ell = log log(death / birth) - L-bar - (Euler-Mascheroni's constant), compared with the left-skewed Gumbel, whose survival function is exp(-e^ell).
 
BootstrapBandResult pulsatrix::BootstrapBand (const DistanceMatrix &distances, int dimension, const BootstrapOptions &options={})
 A bootstrap confidence band for a Rips diagram (after Fasy, Lecci, Rinaldo, Wasserman, Balakrishnan and Singh, Ann. Statist. 2014): resample the points with replacement, compute each resample's diagram, and take the (1 - alpha) quantile of their bottleneck distances to the original.
 
Tensor pulsatrix::GaussianBaseline (const Tensor &points, int64_t count, uint32_t seed=0)
 count points from a Gaussian with the mean and sample covariance of the rows of points: mu + Z^T (X - mu) / sqrt(n - 1) with Z standard normal (one GEMM on points' backend), so no decomposition of the covariance is needed and its rank is kept.
 
double pulsatrix::BaselinePValue (double observed, const std::vector< double > &baselines)
 The rank p-value of an observed statistic against the same statistic on baselines: (1 + #{baseline >= observed}) / (1 + baselines.size()). Small means the observed value is larger than chance gives; the smallest possible is 1 / (1 + baselines.size()).
 
double pulsatrix::MaxPersistence (const PersistenceDiagram &diagram)
 The largest finite persistence in a diagram, 0 if it has none: a common statistic for BaselinePValue().
 
DistanceMatrix pulsatrix::SubDistanceMatrix (const DistanceMatrix &distances, const std::vector< int64_t > &indices)
 A sub-matrix of a distance matrix: the distances among the given points (repeats allowed), in the given order.
 

Detailed Description

Is a loop real? Significance tests for persistence diagrams: the universal null distribution, bootstrap confidence bands, and baseline comparisons against Gaussian clouds or a random network.

A persistence diagram of noise is full of short-lived features, and a few of them always live longer than the rest. Every reported feature needs a test that says how surprising it is:

  • UniversalNullTest(): Bobrowski and Skraba (Sci. Rep. 2023) found that, suitably normalized, the death/birth ratios of random point clouds follow one distribution whatever the cloud came from. It gives every feature a p-value from one diagram, with no resampling. It is a conjecture backed by experiments, and assumes most of the diagram is noise.
  • BootstrapBand(): Fasy et al. (Ann. Statist. 2014). Resamples the cloud and measures how far the diagram moves; features farther from the diagonal than that are significant.
  • Baselines: the same statistic on clouds with nothing to find, a Gaussian with the same mean and covariance (GaussianBaseline()) or a randomly initialized network's activations (NullModelBaseline), and a rank p-value (BaselinePValue()).