nico-wrapper provides Python APIs and Typer command-line tools for running the main NiCo (nico-sc-sp) workflow on reference single-cell RNA-seq data and spatial/Xenium query data.
nico-wrapper is being developed at the Grün Lab at the Institute for Systems Immunology under the leadership of Dominic Grün.
It covers the practical pipeline around NiCo:
- preprocessing raw reference and spatial data into NiCo-ready AnnData files;
- transferring reference labels onto spatial/query cells;
- running NiCo niche / spatial cell-type interaction analysis;
- running NiCo latent-factor covariation analysis and selected exports/reports.
This project is a wrapper around the upstream nico-sc-sp package, not a replacement for NiCo and not a fork of the NiCo method.
NiCo still performs the core scientific computations, including anchor discovery, label propagation, niche interaction modeling, and covariation analysis. nico-wrapper adds:
- repository-local CLI entry points;
- typed configuration objects and pipeline functions;
- input/output validation before expensive NiCo calls;
- predictable output locations;
- small sidecar exports such as manifests, metrics tables, and coefficient tables where available.
When you need methodological details, cite or consult NiCo. When you need a structured way to execute the workflow from this repository, use nico-wrapper.
Version 1.0.0 supports Python 3.11 on Linux and macOS.
Install uv with Homebrew, your system package manager, or the official standalone installer. See the uv installation documentation for the available methods.
Run nico-wrapper directly in an isolated environment without installing it permanently:
uvx --python 3.11 nico-wrapper --help
uvx --python 3.11 nico-wrapper preprocess --helpuvx installs and caches the package. The explicit Python request makes uv select or download Python 3.11; if your default interpreter is already Python 3.11, you can omit --python 3.11.
Install nico-wrapper as a persistent command-line tool:
uv tool install --python 3.11 nico-wrapper
nico-wrapper --helpAlternatively, install it in a project-local virtual environment:
uv venv --python 3.11
source .venv/bin/activate
uv pip install nico-wrapperWith uvx, use the umbrella command groups:
uvx --python 3.11 nico-wrapper preprocess --help
uvx --python 3.11 nico-wrapper transfer --help
uvx --python 3.11 nico-wrapper niche --help
uvx --python 3.11 nico-wrapper covariation --helpA minimal end-to-end CLI skeleton is documented in CLI usage.
| Command | Purpose |
|---|---|
nico-wrapper preprocess |
Convert/build NiCo-ready reference and spatial inputs |
nico-wrapper transfer |
Transfer reference labels onto spatial/query cells |
nico-wrapper niche |
Run spatial niche interaction analysis |
nico-wrapper covariation |
Run latent-factor covariation analysis and reports |
The vignettes/ directory contains worked examples for different starting points:
| Goal | Start here |
|---|---|
| Run the minimal CLI workflow | Core CLI pipeline |
| Run the complete CLI analysis with exports and plots | Full CLI analysis |
| Work interactively through the full Python API | Full Python workflow |
| Explore results from an existing run | Interactive result exploration |
| Use existing spatial cell-type annotations | Starting from pre-annotated spatial data |
New CLI users should begin with the core pipeline, which covers preprocessing, label transfer, niche analysis, and covariation analysis. The full CLI example adds exports, diagnostic plots, proximity analysis, covariation reports, ligand–receptor analysis, and pathway enrichment.
See the CLI documentation for command options and the Python API documentation for programmatic usage.
nico-wrapper is licensed under the MIT License.
NiCo is used as an external library dependency. When using this wrapper, cite the upstream NiCo method:
Agrawal A, Thomann S, Basu S, Grün D. NiCo identifies extrinsic drivers of cell state modulation by niche covariation analysis. Nature Communications. 2024;15:10628. doi:10.1038/s41467-024-54973-w.
See CONTRIBUTORS.md.