Developer / Internal Reference

This page contains reference documentation for advanced functional tools for signal processing on learned graphs and other internal utilities.

Measure how each sample uses the axes of a spectral scaffold.

These diagnostics summarize per-sample structure in a fitted DM/msDM scaffold. They are useful for exploratory interpretation: identifying points dominated by one spectral mode, points lying far from the scaffold center, and neighborhoods that are locally axis-like. They are not clustering labels and should be interpreted together with the embedding and graph metrics.

Parameters:

Name	Type	Description	Default
Z	(ndarray, shape(n, m))	Spectral scaffold coordinates, where rows are samples and columns are eigenvector-derived coordinates.	required
evals	ndarray or None	Eigenvalues matching the scaffold columns. If provided, they weight axes so smoother or more persistent modes can contribute more strongly. If None, all axes are weighted equally.	None
weight_mode	(lambda_over_one_minus_lambda, 'lambda', none, uniform)	How eigenvalues are converted to axis weights. 'lambda_over_one_minus_lambda' mirrors msDM weighting, 'lambda' uses raw non-negative eigenvalues, and 'none'/'uniform' gives uniform weights.	'lambda_over_one_minus_lambda'
standardize	bool	If True, center and scale scaffold columns before computing diagnostics.	True
k_neighbors	int	Neighborhood size used for radiality and local axial coherence.	30
metric	str	Metric used for scaffold-space nearest-neighbor searches.	'euclidean'
P	sparse matrix, dense ndarray, or None	Optional diffusion operator used to smooth scalar diagnostic fields.	None
smooth_t	int	Number of smoothing steps when P is provided.	0

Returns:

Type

Description

dict

Dictionary with one value per sample: EAS Entropy-based axis selectivity; larger values mean the sample's scaffold energy is concentrated in fewer axes. RayScore Axis selectivity modulated by radial separation from neighboring samples. LAC Local axial coherence; larger values mean nearby points are arranged more like a one-dimensional local direction in scaffold space. axis Index of the dominant scaffold axis for each sample. axis_sign Sign of the dominant axis coordinate, encoded as 0/1. radius Euclidean distance of each standardized sample from the scaffold origin.

Smooth a one-dimensional graph signal by applying P^t.

The input is one scalar value per sample. Repeated multiplication by the diffusion operator averages that signal over graph neighborhoods, with larger t spreading information farther across the fitted geometry.

Parameters:

Name	Type	Description	Default
signal	(array - like, shape(n))	Scalar per-sample values to smooth.	required
P	sparse matrix or dense ndarray	Diffusion/operator matrix whose rows and columns correspond to samples.	required
t	int	Number of diffusion steps. t=0 returns the input signal as a float array; larger values smooth more strongly.	8

Returns:

Type	Description
(ndarray, shape(n))	Smoothed signal with one value per sample.

Diffuse every column of a data matrix over a graph operator.

This treats each feature column as a graph signal and applies P^t. The result is a geometry-smoothed version of the input matrix. It is useful for denoising or exploratory imputation, but the amount of smoothing is entirely controlled by the fitted operator and t.

Parameters:

Name	Type	Description	Default
X	(array - like or sparse, shape(n, d))	Data matrix with one row per graph sample and one column per feature or signal.	required
P	sparse matrix or dense ndarray	Diffusion/operator matrix with shape (n, n).	required
t	int	Number of diffusion steps. Larger values smooth more aggressively.	8
output	(auto, sparse, dense)	Output format. 'auto' preserves input sparsity when possible.	'auto'
dtype	numpy dtype	Numeric dtype used for the diffusion computation.	float64

Returns:

Type	Description
sparse matrix or ndarray	Diffused matrix with the same shape as X.

Estimate local distortion of a two-dimensional embedding.

The function computes a Riemannian metric field for a 2-D layout relative to a graph Laplacian/operator and optionally derives scalar deformation maps. It is intended for diagnosing where a visualization contracts, expands, or distorts local directions.

Parameters:

Name	Type	Description	Default
Y	(ndarray, shape(n, 2))	Two-dimensional embedding to diagnose.	required
L	array-like or sparse matrix	Graph Laplacian or operator defining the reference geometry.	required
center	(median, mean)	Center used when converting metric tensors into deformation values.	'median'
diffusion_t	int	Number of diffusion smoothing steps for deformation maps.	0
diffusion_op	sparse matrix, dense ndarray, or None	Operator used for smoothing when diffusion_t > 0.	None
normalize	str	Normalization mode passed to the deformation calculation.	'symmetric'
clip_percentile	float	Percentile used to clip deformation extremes for stable visualization limits.	2.0
return_limits	bool	If True, include suggested plotting limits for deformation fields.	True
compute_metric	bool	If True, include the local metric tensor G.	True
compute_scalars	bool	If True, include scalar summaries derived from G.	True
compute_deformation	bool	If True, include the deformation scalar from calculate_deformation.	True

Returns:

Type	Description
dict	Dictionary that may include: G Local metric tensor for each sample, shape (n, 2, 2). anisotropy Log ratio between the largest and smallest local metric eigenvalues. logdetG Log determinant of the local metric tensor. deformation Centered/scaled deformation scalar useful for plotting. limits Suggested robust plotting limits when return_limits=True.