Metadata-Version: 2.4
Name: cytearc
Version: 1.0.0
Summary: Out-of-core, graph-first workflows for million-cell RNA-seq and CITE-seq
Author-email: Parashar Dhapola <parashar.dhapola@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/NygenAnalytics/CyteArc
Project-URL: Documentation, https://docs.nygen.io/CyteArc/
Project-URL: Installation, https://docs.nygen.io/CyteArc/installation
Project-URL: Issues, https://github.com/NygenAnalytics/CyteArc/issues
Keywords: single-cell,scRNA-seq,scATAC-seq,CITE-seq,Harmony,WNN,batch-correction,Zarr,memory-efficient
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: h5py>=3.11
Requires-Dist: hnswlib>=0.8
Requires-Dist: leidenalg>=0.12
Requires-Dist: loguru>=0.7
Requires-Dist: networkx>=3
Requires-Dist: numba>=0.60
Requires-Dist: numcodecs>=0.16
Requires-Dist: numpy>=2
Requires-Dist: packaging
Requires-Dist: pandas>=2.2.2
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scipy!=1.17.0,>=1.15
Requires-Dist: statsmodels>=0.14.5
Requires-Dist: threadpoolctl>=3.5.0
Requires-Dist: tqdm>=4.60
Requires-Dist: umap-learn>=0.5.12
Requires-Dist: zarr>=3.2.0
Requires-Dist: obstore>=0.5.1
Requires-Dist: huggingface-hub>=2.0.0
Requires-Dist: zstandard>=0.25.0
Requires-Dist: igraph>=1.0.0
Provides-Extra: cytebase
Requires-Dist: duckdb>=1.5.5; extra == "cytebase"
Requires-Dist: httpx>=0.28.1; extra == "cytebase"
Requires-Dist: matplotlib>=3.9; extra == "cytebase"
Requires-Dist: pytz>=2026.3.post1; extra == "cytebase"
Requires-Dist: seaborn>=0.13; extra == "cytebase"
Provides-Extra: agent
Requires-Dist: pydantic-ai-slim[openai]>=2.51.0; extra == "agent"
Provides-Extra: extra
Requires-Dist: anndata>=0.12; extra == "extra"
Requires-Dist: kneed>=0.8.1; extra == "extra"
Requires-Dist: matplotlib>=3.9; extra == "extra"
Requires-Dist: seaborn>=0.13; extra == "extra"
Requires-Dist: ipython-autotime>=0.3; extra == "extra"
Requires-Dist: ipywidgets>=8; extra == "extra"
Provides-Extra: tsne
Requires-Dist: sgtsnepi>=0.7; extra == "tsne"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Requires-Dist: pytest-xdist>=3; extra == "test"
Requires-Dist: anndata>=0.12; extra == "test"
Requires-Dist: scikit-network>=0.33.1; extra == "test"
Requires-Dist: rdata>=1.1.0; extra == "test"
Requires-Dist: pydantic-ai-slim[openai]>=2.51.0; extra == "test"
Requires-Dist: sgtsnepi>=0.7; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "test"
Provides-Extra: docs
Requires-Dist: mystmd>=1.11.0; extra == "docs"
Requires-Dist: jupytext>=1.19.6; extra == "docs"
Requires-Dist: ipykernel>=7.3.0; extra == "docs"
Requires-Dist: nbclient; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sgtsnepi>=0.7; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "docs"
Dynamic: license-file

# CyteArc

<p align="left">
  <a href="https://github.com/NygenAnalytics/CyteArc/actions/workflows/pytest.yml"><img src="https://github.com/NygenAnalytics/CyteArc/actions/workflows/pytest.yml/badge.svg" alt="Tests"></a>
  <a href="https://codecov.io/gh/NygenAnalytics/CyteArc"><img src="https://codecov.io/gh/NygenAnalytics/CyteArc/graph/badge.svg" alt="Coverage"></a>
  <a href="https://docs.nygen.io/CyteArc/"><img src="https://github.com/NygenAnalytics/CyteArc/actions/workflows/pages.yml/badge.svg" alt="Docs"></a>
  <a href="https://pypi.org/project/cytearc"><img src="https://img.shields.io/pypi/v/cytearc.svg?color=4c72b0" alt="PyPI"></a>
  <a href="https://pypi.org/project/cytearc"><img src="https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-4c72b0.svg" alt="Python 3.12, 3.13, and 3.14"></a>
  <a href="https://pepy.tech/projects/cytearc"><img src="https://static.pepy.tech/personalized-badge/cytearc?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="Downloads"></a>
</p>


CyteArc is a **fast Python framework for single-cell RNA, ATAC, protein, and multi-omic analysis that scales to 100M+ cells**. In benchmarks, it processed **one million cells within 15 minutes**, from cell filtering through UMAP and clustering to marker gene identification. On **Tahoe-100M**, the same workflow ran in **under 20 hours without any subsampling**.

[CyteBase](https://docs.nygen.io/CyteArc/tutorials/cytebase) is a **ready-to-connect repository of CyteArc datastores**, containing approximately **200 million cells and 1.1 TB of data** on [Hugging Face](https://huggingface.co/buckets/Nygen/cytebase). Mount remote datasets for reanalysis and build or reuse references for mapping new cells, without downloading the complete count matrix. Counts stay remote while you save your own results in a store you control.

CyteArc's **built-in provenance** connects saved results to the exact cells, features, parameters, and upstream computations that produced them, so you can reuse completed work and trace each analysis.

| Problem | How CyteArc solves it | What you get |
| :-- | :-- | :-- |
| Your **dataset is larger than RAM** | Out-of-core algorithms, and neighbour search streams from cell-major and gene-major layouts, inside a memory budget you set | Analyse the selected cells with [explicit memory controls](https://docs.nygen.io/CyteArc/concepts/memory-and-execution) |
| The **data is stored remotely** and requires downloading | Fetches only the chunks an operation touches, and writes results to a store you own | Start analysing immediately, with one authoritative copy |
| A **single parameter change costs hours** of computation | Each step is fingerprinted by its settings and inputs, so reuse is by content, not by layer name | Only what changed recomputes, and the old version stays for comparison |
| Sub-population analysis leaves **scattered copies that nobody can trace back** | Subsets are masks in one file, and every result carries the cells and parameters behind it | A year later, a result still explains itself |

## Install

Python 3.12+.

```bash
uv venv --python 3.12
uv pip install --python .venv "cytearc[extra]"
```

Detailed installation instructions [here](https://docs.nygen.io/CyteArc/installation)

## Quick start

```python
import cytearc

ds = cytearc.DataStore(
    "s3://bucket/cells.zarr",  # also gs://, hf://, or a local path
)
run = ds.pipeline.run()  # durable QC → graph → UMAP → clustering → marker run

ds.plots.embedding(
    run=run,
    layout="umap",
    color_by="clusters",
)
```

Read the [scRNA-seq tutorial](https://docs.nygen.io/CyteArc/tutorials/scrna-seq) for a granular workflow, or [remote stores](https://docs.nygen.io/CyteArc/tutorials/remote-stores) for cloud setups.

## CyteBase

CyteBase provides a searchable catalog of public datasets stored as cloud-hosted CyteArc DataStores. Search by study, tissue, disease, or organism, then explore published cell annotations and available embeddings. Public access needs no credentials.

Install the CyteBase extra alongside the analysis extras:

```bash
uv pip install --python .venv --prerelease allow "cytearc[cytebase,extra]"
```

```python
from cytearc import cytebase

catalog = cytebase.Catalog()
matches = catalog.search("kidney")
print(matches)

# Open one of the matching datasets for read-only exploration.
dataset_id = matches[0]["cytebase_id"]
ds = catalog.open_datastore(dataset_id)

# Create a writable local store for your own analysis, keeping counts remote.
analysis = catalog.mount_datastore(dataset_id, at="kidney_analysis.zarr")
```

Use `analysis` with the pipeline shown above to save new results locally. Computation runs in your Python environment, reading count blocks over the network as needed.

Follow the [CyteBase tutorial](https://docs.nygen.io/CyteArc/tutorials/cytebase) for catalog filters, plotting, and example notebooks, or see the [CyteBase API reference](https://docs.nygen.io/CyteArc/api/cytebase.html).

## Documentation

Read workflow vignettes and API references in the **[documentation](https://docs.nygen.io/CyteArc/)**.

## CyteArc's capabilities

| Area | Methods |
| :-- | :-- |
| Modalities | scRNA-seq, scATAC-seq, CITE-seq, matched multi-omics |
| Core workflow | Quality control, feature selection, normalization, PCA and LSI, KNN graph, UMAP, densMAP, t-SNE (optional `tsne` extra), Leiden, Paris, marker search |
| Integration | Harmony, partial PCA, shared and weighted nearest neighbours, integration metrics |
| Mapping | Symphony-style reference mapping, label transfer, projection diagnostics |
| Trajectory | Population Balance Analysis pseudotime, expression dynamics and modules, multi-sink fate probabilities |
| Also included | Cell-cycle scoring, gene-set activity, graph-diffusion imputation, doublet scores, HTO demultiplexing, pseudobulk export |

## Support

[GitHub issues](https://github.com/NygenAnalytics/CyteArc/issues)

CyteArc is open source software released under the [BSD 3-Clause License](LICENSE) and maintained by [Nygen](https://nygen.io).
