nico-wrapper

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:

1. preprocessing raw reference and spatial data into NiCo-ready AnnData files;
2. transferring reference labels onto spatial/query cells;
3. running NiCo niche / spatial cell-type interaction analysis;
4. running NiCo latent-factor covariation analysis and selected exports/reports.

Relationship to NiCo

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.

Documentation

• Installation
• CLI usage
• Python API
• Changelog

Installation

Version 1.1.0 supports Python 3.12 on Linux and macOS.

1. Install uv

Install uv with Homebrew, your system package manager, or the official standalone installer. See the uv installation documentation for the available methods.

2. Run nico-wrapper with uvx

Run nico-wrapper directly in an isolated environment without installing it permanently:

uvx --python 3.12 nico-wrapper --help
uvx --python 3.12 nico-wrapper preprocess --help

uvx installs and caches the package. The explicit Python request makes uv select or download Python 3.12; if your default interpreter is already Python 3.12, you can omit --python 3.12.

3. Install nico-wrapper

Install nico-wrapper as a persistent command-line tool:

uv tool install --python 3.12 nico-wrapper
nico-wrapper --help

Alternatively, install it in a project-local virtual environment:

uv venv --python 3.12
source .venv/bin/activate
uv pip install nico-wrapper

Quick start

With uvx, use the umbrella command groups:

uvx --python 3.12 nico-wrapper preprocess --help
uvx --python 3.12 nico-wrapper transfer --help
uvx --python 3.12 nico-wrapper niche --help
uvx --python 3.12 nico-wrapper covariation --help

A minimal end-to-end CLI skeleton is documented in CLI usage.

Main command groups

Vignettes: start here

The vignettes/ directory contains worked examples for different starting points:

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.

License and citation

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.

Contributors

See CONTRIBUTORS.md.