AnnZarro

A read-only browser viewer for AnnData in zarr (or h5ad) built around the matrices other viewers leave out: cell x cell kernels and distances (obsp) and gene x gene similarities (varp), explored one focused cell or gene at a time and linked to the cell x gene layers.

Documentation: annzarro.readthedocs.io (tutorials, user guide, data preparation, deployment and reference). Developed by the Setty Lab.

What it does

• Colours any plot by the focused cell's row of an obsp matrix or the focused gene's row of a varp matrix.
• Plots any obs, var, obsm, varm column or layers row/column against any other, spatial coordinates included.
• Links cells and genes: one cell's values across genes, one gene's values across cells, in every layer.
• Filters cell and gene tables with AND/OR conditions that mask the plots; saves layouts as panel sets and share links.
• Reads only the chunks behind what is on screen, so cost follows the view, not the dataset size; locally or from S3, GCS and HTTP.
• Never writes to your data and never runs code: a lab server can show datasets without giving write or compute access.

Install

pip install annzarro              # or 'annzarro[remote]' for s3://, gs:// and https:// stores

Desktop apps for Windows, macOS and Linux (no Python needed, works offline) are on the releases page. From source: git clone https://github.com/settylab/annzarro.git && pip install -e ./annzarro. Details: installation, desktop app.

Quickstart

mkdir -p ~/annzarro-data
ln -s /path/to/your.zarr ~/annzarro-data/
annzarro start --data-dir ~/annzarro-data      # opens http://127.0.0.1:8000

Walkthrough with the demonstration data: quickstart.

Prepare your data

Any AnnData written with adata.write_zarr(...) opens as is. Which slot feeds which view, how to precompute obsp/varp matrices and how to chunk for speed: preparing data.

Deployment

• Desktop app: one person, data on the same computer. Set up
• Personal server: annzarro start on a laptop or an HPC node, reached over an SSH tunnel. Set up
• Lab server: gunicorn behind HTTPS, read-only, with login and shared panel sets. Set up

Documentation

annzarro.readthedocs.io: tutorials on cell and gene similarity, the user guide, data preparation, deployment, and the CLI, configuration and HTTP API reference.

Citation

Citation metadata are in CITATION.cff (GitHub's "Cite this repository"). From v0.4.1, each release is archived on Zenodo with a DOI. The DOI below always resolves to the latest release; cite the version DOI of the release you used, listed on the Zenodo record (v0.4.1: 10.5281/zenodo.23222217):

@software{otto_annzarro_software,
  author    = {Otto, Dominik J. and Baasri, Siddharth and Setty, Manu},
  title     = {AnnZarro},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.23222216},
  url       = {https://doi.org/10.5281/zenodo.23222216}
}

Development

npm ci once (Node.js 22+), then python -m pytest runs the Python tests, every JS suite and ESLint. See running the tests.

Licence

MIT (LICENSE). The web interface bundles unmodified third-party libraries under their own permissive licences, listed in annzarro/THIRD_PARTY_LICENSES/.