Struct KnnGraph 

pub struct KnnGraph {
    pub adjacency: CscMatrix<f32>,
    pub edges: Vec<(usize, usize)>,
    pub distances: Vec<f32>,
    pub n_nodes: usize,
}

Fields

adjacency: CscMatrix<f32>

Symmetric CSC adjacency matrix (n_nodes x n_nodes)

edges: Vec<(usize, usize)>

Sorted edge list (i < j), deduplicated

distances: Vec<f32>

Edge distances/weights, parallel to edges

n_nodes: usize

Number of nodes

Implementations

impl KnnGraph

pub fn from_columns( points: &DMatrix<f32>, args: KnnGraphArgs, ) -> Result<KnnGraph>

Build a KNN graph from column vectors.

• points - transposed coordinate matrix (d x n), where each column is a point
• args - KNN graph construction parameters

pub fn from_rows(data: &DMatrix<f32>, args: KnnGraphArgs) -> Result<KnnGraph>

Build a KNN graph from row vectors (cells × features).

• data - matrix (n x d), where each row is a point
• args - KNN graph construction parameters

pub fn from_rows_fuzzy( data: &DMatrix<f32>, args: KnnGraphArgs, ) -> Result<(KnnGraph, Vec<f32>)>

KnnGraph::from_columns_fuzzy over row vectors.

pub fn from_columns_fuzzy( points: &DMatrix<f32>, args: KnnGraphArgs, ) -> Result<(KnnGraph, Vec<f32>)>

The kNN graph of the columns of points, and UMAP’s fuzzy membership of each edge (parallel to edges), as umap-learn and uwot compute it:

1. each point’s weights over its OWN knn neighbours only: exp(-(d - ρ) / σ), ρ its nearest distance, σ set so they sum to log2(knn + 1) (UMAP counts the point itself among its n_neighbors, so knn others is n_neighbors = knn + 1);
2. zero toward a point it did not list;
3. the fuzzy union of the two directions, a + b - a·b.

KnnGraph::fuzzy_kernel_weights instead calibrates each point over every edge touching it after the union, so a point many others list gets a wider kernel and a one-sided edge a weight from both ends.

pub fn union_with( &self, other: &KnnGraph, policy: DistanceMerge, ) -> Result<(KnnGraph, Vec<EdgeSource>)>

Merge two graphs over the same nodes, keeping every pair exactly once and reporting which input each came from.

Borrows both inputs: a caller that unions a spatial graph with an expression one generally still needs the spatial graph afterwards, as the topology for anything that reasons about physical adjacency.

Neither input is assumed sorted, nor assumed to store i < j. Edge order is a constructor invariant here, not a type invariant, and a hand-built KnnGraph can violate both.

distances after a union are NOT a metric. Under DistanceMerge::SourceRank they are within-source quantile ranks, which keeps them comparable across sources without pretending the two measurements are the same quantity. When an edge is in both inputs the smaller value wins, matching the reciprocal: false convention in build_from_dict.

pub fn neighbors(&self, node: usize) -> &[usize]

Get neighbors of a node from the CSC adjacency matrix

pub fn num_edges(&self) -> usize

pub fn num_nodes(&self) -> usize

pub fn exp_kernel_weights(&self) -> Vec<f32>

Convert distances to similarity weights using an exponential kernel: w = exp(-d / σ) where σ = median distance.

Returns weights parallel to self.edges, all in (0, 1]. Consistent with the softmax(-d) pattern used in counterfactual inference (data_beans::alg) but with a global bandwidth.

pub fn fuzzy_kernel_weights(&self) -> Vec<f32>

Adaptive-bandwidth kernel weights with local connectivity.

Per-point sigma calibration (originated in t-SNE, van der Maaten & Hinton 2008) ensures every node has the same effective number of neighbors, preventing isolated singletons in sparse regions. The rho subtraction and fuzzy-union symmetrization follow UMAP (McInnes et al. 2018), matching the scanpy default for Leiden.

Algorithm:

1. rho_i = distance to nearest neighbor (local connectivity)
2. sigma_i via binary search: sum_j exp(-(d_ij - rho_i)/sigma_i) = log2(k)
3. Directed weight: w(i→j) = exp(-(d_ij - rho_i) / sigma_i)
4. Symmetrize: w_sym = w(i→j) + w(j→i) - w(i→j) * w(j→i)

Returns weights parallel to self.edges, all in (0, 1].

impl KnnGraph

pub fn to_leiden_network(&self) -> (Network, f64)

Convert this KNN graph to a Leiden Network with modularity objective.

Node weights = weighted degree, edge weights = fuzzy kernel weights. Returns (network, total_edge_weight). Pass total_edge_weight to modularity_to_cpm_resolution to get a CPM-scale resolution.

pub fn to_leiden_network_with(&self, weights: &[f32]) -> (Network, f64)

KnnGraph::to_leiden_network with the edge weights given, parallel to edges (e.g. from KnnGraph::from_rows_fuzzy).

Trait Implementations

impl WeightedGraph for KnnGraph

fn num_nodes(&self) -> usize

fn num_edges(&self) -> usize

fn neighbors_with_weight<'a>( &'a self, node: usize, ) -> Box<dyn Iterator<Item = (usize, f32)> + 'a>

fn degree(&self, node: usize) -> usize

fn weighted_degree(&self, node: usize) -> f32