Metadata-Version: 2.4
Name: annzarro
Version: 0.2.0
Summary: Read-only browser viewer for AnnData (zarr, h5ad) built around cell-by-cell and gene-by-gene matrices
Author: Siddharth Baasri
Author-email: "Dominik J. Otto" <dotto@fredhutch.org>, Manu Setty <msetty@fredhutch.org>
Maintainer-email: "Dominik J. Otto" <dotto@fredhutch.org>
License-Expression: MIT
Project-URL: Homepage, https://github.com/settylab/annzarro
Project-URL: Documentation, https://annzarro.readthedocs.io
Project-URL: Source, https://github.com/settylab/annzarro
Project-URL: Issues, https://github.com/settylab/annzarro/issues
Keywords: single-cell,visualization,genomics,anndata,zarr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: annzarro/THIRD_PARTY_LICENSES/Apache-2.0.txt
License-File: annzarro/THIRD_PARTY_LICENSES/README.md
License-File: annzarro/THIRD_PARTY_LICENSES/bootstrap.txt
License-File: annzarro/THIRD_PARTY_LICENSES/chroma.txt
License-File: annzarro/THIRD_PARTY_LICENSES/datatables.txt
License-File: annzarro/THIRD_PARTY_LICENSES/filesaver.txt
License-File: annzarro/THIRD_PARTY_LICENSES/fontawesome.txt
License-File: annzarro/THIRD_PARTY_LICENSES/jquery.txt
License-File: annzarro/THIRD_PARTY_LICENSES/plotly-bundled.txt
License-File: annzarro/THIRD_PARTY_LICENSES/plotly.txt
License-File: annzarro/THIRD_PARTY_LICENSES/popper.txt
License-File: annzarro/THIRD_PARTY_LICENSES/select2.txt
Requires-Dist: flask>=2.0.0
Requires-Dist: flask-cors>=3.0.0
Requires-Dist: zarr>=2.13.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: werkzeug>=2.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: h5py>=3.0.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: requests>=2.28.0; extra == "dev"
Requires-Dist: pandas>=1.3.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: requests>=2.28.0; extra == "test"
Requires-Dist: pandas>=1.3.0; extra == "test"
Provides-Extra: desktop
Requires-Dist: pyinstaller>=5.0.0; extra == "desktop"
Requires-Dist: Pillow>=9.0.0; extra == "desktop"
Provides-Extra: remote
Requires-Dist: fsspec>=2023.1.0; extra == "remote"
Requires-Dist: s3fs>=2023.1.0; extra == "remote"
Requires-Dist: gcsfs>=2023.1.0; extra == "remote"
Requires-Dist: aiohttp>=3.8.0; extra == "remote"
Dynamic: license-file

<!-- Images use absolute URLs on the main branch so that PyPI renders them too; they resolve
     once this branch is merged to main. -->
# <img src="https://raw.githubusercontent.com/settylab/annzarro/main/annzarro/desktop/electron/icons/icon.png" width="40" height="40" align="center" alt=""> AnnZarro

<!-- PyPI version and Tests resolve after the first PyPI release and PR #50 (tests.yml). -->
[![PyPI](https://img.shields.io/pypi/v/annzarro)](https://pypi.org/project/annzarro/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/settylab/annzarro/blob/main/LICENSE)
[![Docs](https://readthedocs.org/projects/annzarro/badge/?version=latest)](https://annzarro.readthedocs.io)
[![Tests](https://github.com/settylab/annzarro/actions/workflows/tests.yml/badge.svg)](https://github.com/settylab/annzarro/actions/workflows/tests.yml)

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](https://annzarro.readthedocs.io)** (tutorials, user guide,
data preparation, deployment and reference). Developed by the [Setty Lab](https://settylab.org).

![Clicking a cell moves the diffusion-walk colouring; clicking a gene recolours its correlations and per-cell fold change](https://raw.githubusercontent.com/settylab/annzarro/main/docs/_static/readme/focus.gif)

## 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.

![Cell x cell, gene x gene, cells x genes and table filters](https://raw.githubusercontent.com/settylab/annzarro/main/docs/_static/readme/features.png)

## Install

```bash
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](https://github.com/settylab/annzarro/releases). From source:
`git clone https://github.com/settylab/annzarro.git && pip install -e ./annzarro`.
Details: [installation](https://annzarro.readthedocs.io/en/latest/getting-started/installation.html),
[desktop app](https://annzarro.readthedocs.io/en/latest/getting-started/desktop-app.html).

## Quickstart

```bash
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](https://annzarro.readthedocs.io/en/latest/getting-started/quickstart.html).

## 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](https://annzarro.readthedocs.io/en/latest/data/index.html).

## Deployment

- **Desktop app**: one person, data on the same computer. [Set up](https://annzarro.readthedocs.io/en/latest/getting-started/desktop-app.html)
- **Personal server**: `annzarro start` on a laptop or an HPC node, reached over an SSH tunnel. [Set up](https://annzarro.readthedocs.io/en/latest/deployment/personal-server.html)
- **Lab server**: gunicorn behind HTTPS, read-only, with login and shared panel sets. [Set up](https://annzarro.readthedocs.io/en/latest/deployment/lab-server.html)

## Documentation

[annzarro.readthedocs.io](https://annzarro.readthedocs.io): tutorials on cell and gene
similarity, the user guide, data preparation, deployment, and the CLI, configuration and HTTP API reference.

## Citation

Otto D.J., Baasri S. and Setty M. AnnZarro. Protocol preprint in preparation.

```bibtex
% PLACEHOLDER: replace with the preprint entry once it has a DOI.
@unpublished{otto_annzarro,
  author = {Otto, Dominik J. and Baasri, Siddharth and Setty, Manu},
  title  = {AnnZarro},
  note   = {Preprint in preparation},
  year   = {2026}
}
```

## Development

`npm ci` once (Node.js 22+), then `python -m pytest` runs the Python tests, every JS suite and
ESLint. See [running the tests](https://annzarro.readthedocs.io/en/latest/getting-started/installation.html#running-the-tests).

## Licence

MIT ([LICENSE](https://github.com/settylab/annzarro/blob/main/LICENSE)). The web interface bundles unmodified third-party libraries under their
own permissive licences, listed in [`annzarro/THIRD_PARTY_LICENSES/`](https://github.com/settylab/annzarro/tree/main/annzarro/THIRD_PARTY_LICENSES).
