Crate tda 

Topological Data Analysis (TDA) Library for Neuroscience

This library provides comprehensive tools for topological data analysis with a focus on neuroscience applications. It includes:

• Persistent Homology: Compute topological features (connected components, loops, voids) and track their evolution across scales
• Persistence Diagrams: Visualize and compare topological features using birth-death diagrams
• Mapper Algorithm: Create graph-based visualizations of high-dimensional data
• Simplicial Complexes: Build and manipulate Vietoris-Rips, Čech, and other complexes
• Distance Metrics: Euclidean, correlation, and spike train distances (Victor-Purpura, van Rossum)
• Neural TDA: Specialized tools for spike train analysis, cell assembly detection, and functional connectivity

Theory Background

Persistent Homology

Persistent homology is a method from algebraic topology that computes topological features of a space at different scales. For a point cloud in Euclidean space, we build a nested sequence of simplicial complexes (a filtration) and track when topological features (connected components, loops, voids) appear and disappear.

The key insight is that important topological features persist across many scales, while noise creates features that appear and disappear quickly.

Vietoris-Rips Complex

Given a point cloud and a distance threshold r, the Vietoris-Rips complex includes:

• All points as 0-simplices (vertices)
• An edge between points i and j if distance(i,j) ≤ r
• A k-simplex if all its edges are present

This creates a simplicial complex that captures the “shape” of the data at scale r.

Mapper Algorithm

Mapper is a method for topological visualization of high-dimensional data:

1. Apply a filter function to project data to lower dimensions
2. Cover the filter space with overlapping intervals
3. Cluster points within each interval
4. Build a graph where nodes are clusters and edges connect overlapping clusters

This creates a graph that captures the global structure of the data.

Neuroscience Applications

Spike Train Analysis

Neural activity is often recorded as spike trains - sequences of action potential times. TDA can analyze spike train similarity and detect patterns:

• Victor-Purpura distance: Measures cost of transforming one spike train to another
• van Rossum distance: Based on convolution with exponential kernels
• Persistence diagrams: Reveal topological structure in spike train ensembles

Cell Assembly Detection

Neurons that fire together form functional assemblies. TDA detects these using clique topology - groups of strongly connected neurons in the functional connectivity graph.

Functional Connectivity

TDA can compute functional connectivity matrices from spike trains and analyze their topological structure to understand network organization.

Examples

Basic Persistent Homology

use nalgebra::DMatrix;
use tda::persistent_homology::persistent_homology_rips;
use tda::distances::euclidean_distance_matrix;

// Create a circle point cloud
let n = 20;
let mut points = Vec::new();
for i in 0..n {
    let angle = 2.0 * std::f64::consts::PI * (i as f64) / (n as f64);
    points.push(angle.cos());
    points.push(angle.sin());
}
let point_matrix = DMatrix::from_row_slice(n, 2, &points);

// Compute distance matrix
let dist = euclidean_distance_matrix(&point_matrix).unwrap();

// Compute persistent homology
let pairs = persistent_homology_rips(&dist, 2.0, 1).unwrap();

// Should detect a loop (1-dimensional feature)
let loops: Vec<_> = pairs.iter().filter(|p| p.dimension == 1).collect();
assert!(!loops.is_empty());

Spike Train Analysis

use tda::distances::SpikeTrain;
use tda::neural_tda::NeuralPopulation;

// Create spike trains
let train1 = SpikeTrain::new(vec![1.0, 2.0, 3.0, 5.0, 8.0]).unwrap();
let train2 = SpikeTrain::new(vec![1.1, 2.1, 3.1, 5.2, 8.1]).unwrap();
let train3 = SpikeTrain::new(vec![10.0, 11.0, 12.0]).unwrap();

// Create neural population
let population = NeuralPopulation::new(vec![train1, train2, train3]).unwrap();

// Compute persistence diagram
let diagram = population.persistence_diagram_vp(1.0, 5.0, 1).unwrap();
println!("Detected {} topological features", diagram.len());

Mapper Algorithm

use nalgebra::DMatrix;
use tda::mapper::{MapperBuilder, CoverStrategy, ClusteringMethod, filters};
use tda::distances::euclidean_distance_matrix;

// Create some data
let data = DMatrix::from_row_slice(10, 2, &[
    0.0, 0.0, 1.0, 0.0, 2.0, 0.0, 3.0, 0.0, 4.0, 0.0,
    5.0, 1.0, 6.0, 1.0, 7.0, 1.0, 8.0, 1.0, 9.0, 1.0,
]);

let dist = euclidean_distance_matrix(&data).unwrap();

// Build Mapper graph
let graph = MapperBuilder::new()
    .filter(filters::coordinate_projection(0))
    .cover(CoverStrategy::Uniform {
        num_intervals: 3,
        overlap_percent: 0.3,
    })
    .clustering(ClusteringMethod::SingleLinkage { threshold: 2.0 })
    .build(&data, &dist)
    .unwrap();

println!("Mapper graph has {} nodes", graph.node_count());

Re-exports

pub use error::Result;

pub use error::TdaError;

pub use distances::euclidean_distance_matrix;

pub use distances::correlation_distance_matrix;

pub use distances::SpikeTrain;

pub use distances::victor_purpura_distance;

pub use distances::van_rossum_distance;

pub use simplicial_complex::Simplex;

pub use simplicial_complex::SimplicialComplex;

pub use simplicial_complex::FilteredSimplex;

pub use simplicial_complex::FiltrationType;

pub use simplicial_complex::vietoris_rips_complex;

pub use simplicial_complex::cech_complex;

pub use persistent_homology::PersistentPair;

pub use persistent_homology::compute_persistence;

pub use persistent_homology::persistent_homology_rips;

pub use persistent_homology::persistent_homology_cech;

pub use persistent_homology::betti_number;

pub use persistent_homology::euler_characteristic;

pub use persistence_diagram::PersistenceDiagram;

pub use persistence_diagram::bottleneck_distance;

pub use persistence_diagram::wasserstein_distance;

pub use persistence_diagram::persistence_landscape;

pub use persistence_diagram::persistence_entropy;

pub use persistence_diagram::persistent_betti_curve;

pub use mapper::MapperBuilder;

pub use mapper::MapperGraph;

pub use mapper::MapperNode;

pub use mapper::ClusteringMethod;

pub use mapper::CoverStrategy;

pub use mapper::filters;

pub use neural_tda::NeuralPopulation;

pub use neural_tda::SlidingWindowAnalysis;

pub use neural_tda::CellAssembly;

pub use neural_tda::detect_cell_assemblies;

pub use neural_tda::functional_connectivity;

pub use neural_tda::topological_features;

pub use neural_tda::burst_synchrony_analysis;

Modules

distances

Distance metrics for point clouds and spike trains.

error

Error types for the TDA library.

mapper

Mapper algorithm for topological data visualization.

neural_tda

Neuroscience-specific topological data analysis.

persistence_diagram

Persistence diagrams and their distance metrics.

persistent_homology

Persistent homology computation.

prelude

Prelude module for convenient imports

simplicial_complex

Simplicial complex data structures and operations.