Metadata-Version: 2.5
Name: cytorete
Version: 0.1.1
Summary: Cytorete — cell-type-resolved inference of gene regulatory networks and their dynamics.
Project-URL: Homepage, https://github.com/genecell/cytorete
Project-URL: Repository, https://github.com/genecell/cytorete
Author-email: Min Dai <dai@broadinstitute.org>
Maintainer-email: Min Dai <dai@broadinstitute.org>
License: BSD-3-Clause
License-File: LICENSE
Keywords: ATAC,GRN,cistrome,gene regulatory network,multiome,regulon,scATAC-seq,scRNA-seq,single-cell,transcription factor
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Requires-Dist: anndata>=0.8
Requires-Dist: cosg>=1.1.2
Requires-Dist: cytome<1.0,>=0.2.5
Requires-Dist: matplotlib>=3.5.2
Requires-Dist: numpy>=1.21.6
Requires-Dist: pandas>=1.3
Requires-Dist: piaso-tools>=1.2.2
Requires-Dist: scipy>=1.7
Provides-Extra: dev
Requires-Dist: py2bit; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: motif
Requires-Dist: py2bit; extra == 'motif'
Description-Content-Type: text/markdown

# cytorete

**Cell-type-resolved inference of gene regulatory networks and their dynamics.**

## The name

**cytorete** = *cyto-* + *rete*, "the cell's network" — Ancient Greek
**κύτος** (*kýtos*), the combining form for **cell**, and Latin **rēte**,
"**net**", the word anatomy already uses in *rete mirabile* and *rete testis*.

Pronounced **sy-toh-REE-tee** (/ˌsaɪtoʊˈriːtiː/) — *rete* keeps its
two-syllable English anatomical sound, not a one-syllable "reet".

## What this package does

cytorete infers cell-type-resolved gene regulatory networks (GRNs) from
single-cell data, combining COSG-derived co-specificity, marker-gene
dimensionality reduction (GDR), and motif-cistrome evidence into TF→gene
regulons with per-cell-type activity.

It is built on the **PIASO** single-cell stack (a one-directional dependency,
`cytorete → piaso-tools`): it reuses PIASO's public API for scoring, GDR,
co-specificity, motif scanning (Rust-accelerated), and the cytome streaming
backend, so it scales from small AnnData objects to atlas-scale on-disk
cytomes.

**This release ships the RNA regulon workflow**, end to end:

> promoter cistrome → `inferRegulon` → `regulonActivity` /
> `regulonSpecificity` → plots

The multiome (RNA+ATAC) GRN chain, the ATAC TF-activity chain and the peak
cistrome are not part of this distribution. Their names exist in the package
and raise an `ImportError` at call time saying so, rather than failing at
import — so `import cytorete` behaves the same either way.

## Installation

```bash
pip install cytorete          # pulls piaso-tools, cosg, cytome
pip install "cytorete[motif]" # + py2bit for .2bit genome sequence extraction
```

## Documentation

Tutorials live with the rest of the stack on **[piaso.org](https://piaso.org)**:

- [RNA regulon inference](https://piaso.org/tutorials/cytorete-regulons/) — the end-to-end workflow
- [Motif analysis](https://piaso.org/tutorials/motif-analysis/) — scanning and motif databases

cytorete shares PIASO's scoring, GDR and co-specificity, so its tutorials sit
beside theirs rather than on a site of their own.

## Quickstart

```python
import cytorete as cr

# 1. Promoter cistrome: which TF motifs occur in each gene's promoter
cistrome = cr.pp.build_cistrome(promoter_seqs, tf_motif_map)

# 2. Regulons: motif evidence x trans co-specificity across cell types
regulons = cr.tl.inferRegulon(adata, groupby="cell_type", copy=True)

# 3. Per-cell-type activity and specificity
cr.tl.regulonActivity(adata, regulons)
spec = cr.tl.regulonSpecificity(adata, groupby="cell_type", copy=True)

# 4. Plots
cr.pl.plotRegulon(adata, regulon="SOX2")
```

`inferRegulon` and `regulonSpecificity` follow the scanpy convention: they
write in place and return `None` unless `copy=True`. `regulonSpecificity`
returns **long-form** results — pivot before passing them to a heatmap.

Both `snake_case` (`infer_regulon`) and `camelCase` (`inferRegulon`) names are
provided; `camelCase` matches `piaso.tl` for continuity.

Calling a name from a withheld chain tells you so at the call site:

```python
>>> cr.inferGRN(ds)
ImportError: cytorete.inferGRN is not part of this distribution: it requires
the multiome (RNA+ATAC) GRN chain, which is not yet released. The RNA regulon
workflow (build_promoter_cistrome -> inferRegulon -> regulonActivity) is
fully available.
```

## Relationship to PIASO

The dependency runs one way — `cytorete → piaso-tools` — and never back.
cytorete is deliberately *not* a dependency of PIASO, which would be a
packaging cycle.

| Concern | Lives in | |
|---|---|---|
| Regulons, promoter cistrome, regulon activity & specificity, regulon plots | **cytorete** (this package) | [docs](https://piaso.org/tutorials/cytorete-regulons/) |
| Scoring, INFOG normalization, GDR, co-specificity, motif scanning (`pp.scan_motifs`), motif/genome loaders | [PIASO](https://github.com/genecell/PIASO) (`piaso-tools`) | [piaso.org](https://piaso.org) · [PyPI](https://pypi.org/project/piaso-tools/) |
| Streaming on-disk backend | [cytome](https://github.com/genecell/cytome) | [docs](https://piaso.org/tutorials/cytome-basics/) · [PyPI](https://pypi.org/project/cytome/) |
| Marker specificity scoring | [COSG](https://github.com/genecell/COSG) | [PyPI](https://pypi.org/project/cosg/) · [R](https://github.com/genecell/COSGR) |

The GRN entry points that used to live in `piaso.tl` remain there as thin
forwarders: each resolves cytorete at call time and, if it is not installed,
raises an `ImportError` pointing at `pip install cytorete`. They exist for
existing notebooks — new code should `import cytorete` directly.

## License

BSD 3-Clause. Copyright (c) 2025, Min Dai.
