Main workflow: TopOGraph¶

The easiest way to use TopoMetry is through the TopOGraph orchestrator, which runs the full geometry-learning and layout pipeline and stores the results as accessible properties.

topo.topograph.TopOGraph ¶

TopOGraph(
    base_knn: int = 30,
    graph_knn: int = 30,
    min_eigs: int = 128,
    n_jobs: int = -1,
    projection_methods: Sequence[str] | None = None,
    base_kernel=None,
    base_kernel_version: str = "bw_adaptive",
    graph_kernel_version: str = "bw_adaptive",
    base_metric: str = "cosine",
    graph_metric: str = "euclidean",
    diff_t: int = 0,
    delta: float = 1.0,
    cknn_candidate_neighbors: int | None = None,
    cknn_exact: bool = False,
    sigma: float = 0.1,
    low_memory: bool = False,
    eigen_tol: float = 1e-08,
    eigensolver: str = "arpack",
    backend: str = "sklearn",
    verbosity: int = 0,
    random_state=42,
    laplacian_type: str = "normalized",
    id_method: str = "fsa",
    id_ks=50,
    id_metric: str = "euclidean",
    id_quantile: float = 0.99,
    id_min_components: int = 128,
    id_max_components: int = 1024,
    id_headroom: float = 0.5,
    uom: bool = False,
)

Bases: GraphBuildMixin, EigenBuildMixin, LayoutBuildMixin, UoMMixin

Geometry-aware estimator for spectral scaffolds, operators and layouts.

Learns spectral scaffolds, refined operators and 2-D layouts from data.

Use this for standard end-to-end workflows. It orchestrates building neighborhood graphs, diffusion operators, spectral scaffolds, and 2-D layouts.

Notation Glossary: * X = original input data * Z = fixed-time spectral scaffold * msZ = multiscale spectral scaffold * P = diffusion / Markov transition operator * kNN = sparse nearest-neighbor distance graph * ID = intrinsic dimensionality

Parameters:

Name	Type	Description	Default
`base_knn`	`int`	k-nearest neighbors for the base graph on input space.	`30`
`graph_knn`	`int`	k-nearest neighbors for the refined graph built in spectral scaffold space.	`30`
`min_eigs`	`int`	Minimum number of eigenpairs to compute for the scaffold.	`128`
`base_kernel`	`Kernel or None`	Pre-fitted kernel to reuse; if provided, `fit` skips base graph construction.	`None`
`laplacian_type`	`(normalized, unnormalized, random_walk)`	Laplacian normalization for spectral computations.	`"normalized"`
`base_kernel_version`	`str`	Kernel choice for the base graph.	`"bw_adaptive"`
`graph_kernel_version`	`str`	Kernel choice for scaffold graphs.	`"bw_adaptive"`
`backend`	`(sklearn, hnswlib)`	Nearest-neighbor backend. Use "sklearn" for exact search and "hnswlib" for optional dense-vector HNSW search.	`"sklearn"`
`base_metric`	`str`	Distance metric for the base kNN graph.	`"cosine"`
`graph_metric`	`str`	Distance metric for kNN in scaffold space.	`"euclidean"`
`diff_t`	`int`	Diffusion time for single-time scaffold.	`0`
`sigma`	`float`	Bandwidth for Gaussian kernels.	`0.1`
`delta`	`float`	Unitless edge threshold for CkNN kernels.	`1.0`
`cknn_candidate_neighbors`	`int or None`	Number of candidate neighbors tested in approximate CkNN mode.	`None`
`cknn_exact`	`bool`	If True, threshold all pairwise distances for paper-faithful CkNN construction. This is quadratic in samples.	`False`
`n_jobs`	`int`	Threads for kNN searches; -1 uses all cores.	`-1`
`low_memory`	`bool`	Avoid caching large kernel objects.	`False`
`eigen_tol`	`float`	Tolerance for the eigensolver.	`1e-8`
`eigensolver`	`(arpack, lobpcg, amg, dense)`	Solver for eigendecomposition.	`"arpack"`
`projection_methods`	`sequence of str or None`	Layouts to compute during `fit`. If None, uses ["MAP", "PaCMAP"].	`None`
`verbosity`	`int`	Logging verbosity.	`0`
`random_state`	`int, RandomState, or None`	Random seed.	`42`
`id_method`	`(fsa, mle)`	Intrinsic-dimensionality estimator for scaffold sizing.	`"fsa"`
`id_ks`	`int or iterable`	Neighborhood sizes for I.D. estimation.	`50`
`id_metric`	`str`	Metric for I.D. estimation.	`"euclidean"`
`id_quantile`	`float`	Quantile of local intrinsic-dimensionality estimates used to choose the scaffold dimensionality.	`0.99`
`id_min_components`	`int`	Lower bound on the number of spectral components computed.	`128`
`id_max_components`	`int`	Upper bound on the number of spectral components computed.	`1024`
`id_headroom`	`float`	Fractional safety margin added to the intrinsic-dimensionality estimate.	`0.5`
`uom`	`bool`	Enable Union-of-Manifolds block-diagonal scaffolds.	`False`

TopoMAP `property` ¶

TopoMAP: ndarray

2-D MAP layout optimized on the fixed-time DM refined graph.

msTopoMAP `property` ¶

msTopoMAP: ndarray

2-D MAP layout optimized on the msDM refined graph.

TopoPaCMAP `property` ¶

TopoPaCMAP: ndarray

2-D PaCMAP layout optimized on the fixed-time DM refined graph.

msTopoPaCMAP `property` ¶

msTopoPaCMAP: ndarray

2-D PaCMAP layout optimized on the msDM refined graph.

eigenvalues `property` ¶

eigenvalues: ndarray | dict[str, Any]

Eigenvalues of the active spectral scaffold.

global_id `property` ¶

global_id: float

The estimated global intrinsic dimensionality of the dataset.

intrinsic_dim `property` ¶

intrinsic_dim: dict[str, Any]

Structured intrinsic-dimensionality information.

fit ¶

fit(X=None)

Run the full pipeline on X.

Builds base kNN → base kernel P(X) → dual eigenbases (DM + msDM) → refined scaffold graphs → 2-D projections. When uom=True, detects disconnected components and builds per-component scaffolds and block-diagonal operators.

spectral_scaffold ¶

spectral_scaffold(
    multiscale: bool = True,
) -> np.ndarray | csr_matrix

Return fitted spectral scaffold coordinates.

save ¶

save(
    filename: str | PathLike[str] = "topograph.pkl",
) -> None

Save this TopOGraph to a pickle file.

Advanced graph state¶

These properties are fitted attributes that cache the intermediate states of the graphs.

Bases: GraphBuildMixin, EigenBuildMixin, LayoutBuildMixin, UoMMixin

Geometry-aware estimator for spectral scaffolds, operators and layouts.

Learns spectral scaffolds, refined operators and 2-D layouts from data.

Use this for standard end-to-end workflows. It orchestrates building neighborhood graphs, diffusion operators, spectral scaffolds, and 2-D layouts.

Notation Glossary: * X = original input data * Z = fixed-time spectral scaffold * msZ = multiscale spectral scaffold * P = diffusion / Markov transition operator * kNN = sparse nearest-neighbor distance graph * ID = intrinsic dimensionality

Parameters:

Name	Type	Description	Default
`base_knn`	`int`	k-nearest neighbors for the base graph on input space.	`30`
`graph_knn`	`int`	k-nearest neighbors for the refined graph built in spectral scaffold space.	`30`
`min_eigs`	`int`	Minimum number of eigenpairs to compute for the scaffold.	`128`
`base_kernel`	`Kernel or None`	Pre-fitted kernel to reuse; if provided, `fit` skips base graph construction.	`None`
`laplacian_type`	`(normalized, unnormalized, random_walk)`	Laplacian normalization for spectral computations.	`"normalized"`
`base_kernel_version`	`str`	Kernel choice for the base graph.	`"bw_adaptive"`
`graph_kernel_version`	`str`	Kernel choice for scaffold graphs.	`"bw_adaptive"`
`backend`	`(sklearn, hnswlib)`	Nearest-neighbor backend. Use "sklearn" for exact search and "hnswlib" for optional dense-vector HNSW search.	`"sklearn"`
`base_metric`	`str`	Distance metric for the base kNN graph.	`"cosine"`
`graph_metric`	`str`	Distance metric for kNN in scaffold space.	`"euclidean"`
`diff_t`	`int`	Diffusion time for single-time scaffold.	`0`
`sigma`	`float`	Bandwidth for Gaussian kernels.	`0.1`
`delta`	`float`	Unitless edge threshold for CkNN kernels.	`1.0`
`cknn_candidate_neighbors`	`int or None`	Number of candidate neighbors tested in approximate CkNN mode.	`None`
`cknn_exact`	`bool`	If True, threshold all pairwise distances for paper-faithful CkNN construction. This is quadratic in samples.	`False`
`n_jobs`	`int`	Threads for kNN searches; -1 uses all cores.	`-1`
`low_memory`	`bool`	Avoid caching large kernel objects.	`False`
`eigen_tol`	`float`	Tolerance for the eigensolver.	`1e-8`
`eigensolver`	`(arpack, lobpcg, amg, dense)`	Solver for eigendecomposition.	`"arpack"`
`projection_methods`	`sequence of str or None`	Layouts to compute during `fit`. If None, uses ["MAP", "PaCMAP"].	`None`
`verbosity`	`int`	Logging verbosity.	`0`
`random_state`	`int, RandomState, or None`	Random seed.	`42`
`id_method`	`(fsa, mle)`	Intrinsic-dimensionality estimator for scaffold sizing.	`"fsa"`
`id_ks`	`int or iterable`	Neighborhood sizes for I.D. estimation.	`50`
`id_metric`	`str`	Metric for I.D. estimation.	`"euclidean"`
`id_quantile`	`float`	Quantile of local intrinsic-dimensionality estimates used to choose the scaffold dimensionality.	`0.99`
`id_min_components`	`int`	Lower bound on the number of spectral components computed.	`128`
`id_max_components`	`int`	Upper bound on the number of spectral components computed.	`1024`
`id_headroom`	`float`	Fractional safety margin added to the intrinsic-dimensionality estimate.	`0.5`
`uom`	`bool`	Enable Union-of-Manifolds block-diagonal scaffolds.	`False`

knn_X `property` ¶

knn_X: csr_matrix

The base k-nearest-neighbors graph in the original input space.

P_of_X `property` ¶

P_of_X: csr_matrix

The base diffusion operator on the original input space.

knn_Z `property` ¶

knn_Z: csr_matrix

The k-nearest-neighbors graph built in the fixed-time DM scaffold space.

P_of_Z `property` ¶

P_of_Z: csr_matrix

The diffusion operator on the fixed-time DM scaffold.

knn_msZ `property` ¶

knn_msZ: csr_matrix

The k-nearest-neighbors graph built in the msDM scaffold space.

P_of_msZ `property` ¶

P_of_msZ: csr_matrix

The diffusion operator on the msDM scaffold.

Persistence¶

Save a TopOGraph object to a pickle file.

Load a TopOGraph from a trusted pickle file.

Pickle can execute arbitrary code while loading. Only load files from a trusted source.

Main workflow: TopOGraph¶

topo.topograph.TopOGraph ¶

TopoMAP property ¶

msTopoMAP property ¶

TopoPaCMAP property ¶

msTopoPaCMAP property ¶

eigenvalues property ¶

global_id property ¶

intrinsic_dim property ¶