Installation#

Requirements#

Python 3.10 or later, PyTorch 2.0 or later, and a working scanpy installation. A CUDA capable GPU is optional but speeds up training by 10 to 50x.

Install from PyPI#

pip install nicheverse

Install from source#

git clone https://github.com/digvijayky/nicheverse
cd nicheverse
pip install -e .

To add the developer tools (pytest, ruff):

pip install -e ".[dev]"

Pinned environment for reproducibility#

The published model was trained with the 0.2.0 release. Pin it for a reproducible environment:

pip install nicheverse==0.2.0

The 0.2.0 defaults define the released architecture and training trajectory (mlp_deep encoder, vq quantizer, 256 cell / 32 niche codes, per-sample knn_radius graph at radius 50 microns, k = 20, seed 9, 300 epochs). The study model additionally concatenates a 7-micron segmentation-free transcript-context field onto the segmented counts (a 732-dimensional cell input); build it with nicheverse.data.transcript_context as shown in the transcript-context notebook. Code assignment is deterministic for a fixed model and seed.

GPU setup#

CUDA is auto detected at runtime. If you want to force CPU on a GPU machine, pass --device cpu to the CLI or device="cpu" to the Python API. The default seed is 9 and determinism is on; on GPU we set torch.backends.cudnn.deterministic=True and CUBLAS_WORKSPACE_CONFIG=:4096:8 to enable bit identical runs across invocations on the same hardware.

Verifying the install#

python -c "import nicheverse; print(nicheverse.__version__)"
nicheverse --help
pytest -q   # if installed from source with the dev extras

The full test suite should pass in well under a minute on CPU.

Hardware notes#

Training a 173 sample cohort (5.66M cells) at the default configuration on a 366-gene input (batch size 32768, seed 9, spatial graph knn_radius at radius 50 microns, k_neighbors 20) takes about 17 seconds per epoch on a single NVIDIA A100, so 300 epochs complete in about 1.4 hours at a peak GPU memory of about 43 GB. The study model doubles the cell input to 732 dimensions with the transcript-context field, which roughly doubles per-epoch time (about 7.9 hours for 300 epochs). Inference (predict) on the same cohort takes under 10 minutes on that GPU and scales with cohort size on a CPU (the neighborhood graph build dominates). RAM use peaks around 40 GB during k-NN graph construction; you can reduce this by pre splitting the cohort by sample and concatenating outputs.

On this page