Installation

topometry-nosc is implemented in Python, with models that inherit from scikit-learn BaseEstimator and TransformerMixin. This makes the building-block classes compatible with scikit-learn pipelines and easy to combine with other workflows.

The core install includes numpy, scipy, scikit-learn, numba, joblib, matplotlib, pandas, jupyterlab, and umap-learn:

pip install topometry-nosc            # core
pip install "topometry-nosc[all]"     # core + ANN backends, extra layouts

Do not install alongside upstream topometry

This fork ships the same import package name (topo) as the original topometry. Installing both distributions in one environment makes them silently overwrite each other's topo/ files.

To prevent broken installs, import topo fails fast with an ImportError if it detects the upstream topometry distribution present in the same environment:

Conflicting installation detected: the upstream 'topometry' distribution is
installed in the same environment as this fork ('topometry-nosc')...

Use a fresh virtual environment, or run pip uninstall topometry before installing this fork.

Optional dependencies (extras)

Optional features are grouped into extras — install only what you need:

Extra	Adds
ann	hnswlib (fast approximate nearest neighbors)
amg	pyamg (algebraic-multigrid eigensolver='amg')
layouts	pacmap, pymde, trimap (extra projections)
all	everything above

pip install "topometry-nosc[layouts]"     # one extra
pip install "topometry-nosc[ann,layouts]" # several

Missing an optional dependency raises a clear message telling you which extra to install (e.g. pip install topometry-nosc[layouts]).

Approximate Nearest Neighbors

The kNN-graph builder (topo.base.ann.kNN) wraps several ANN backends. If none of the optional libraries is installed, it falls back to scikit-learn neighborhood search (slower on large datasets). Supported backends include HNSWlib (default, via the ann extra) and

Additional layout methods

Fast implementations of Isomap and a cross-entropy–minimization layout (MAP) are built in. UMAP fuzzy-graph construction and the projection_method="UMAP" layout are provided by the core umap-learn dependency. Other layout algorithms are available via the layouts extra: PaCMAP, pacmap; TriMAP, trimap; IsomorphicMDE / IsometricMDE, pymde. These are handled by topo.layouts.Projector.

Development install

This project uses uv:

uv sync --all-extras   # package + all extras + dev tooling
uv run pytest -q       # run the tests

To build the documentation locally:

uv sync --group docs
uv run mkdocs serve