Metadata-Version: 2.4
Name: cnverse
Version: 0.1.0
Summary: 1. Harmonise CNV/CNA caller outputs (Numbat, XClone, CalicoST, inferCNV, CopyKAT, ...) into a unified AnnData. 2. General CNV visualization and exploration
Project-URL: Homepage, https://github.com/Rongtingting/cnverse
Project-URL: Source, https://github.com/Rongtingting/cnverse
Project-URL: Issues, https://github.com/Rongtingting/cnverse/issues
Author-email: Rongting Huang <rthuang@stanford.edu>
License: MIT
License-File: LICENSE
Keywords: CNA,CNV,anndata,copy-number,single-cell,spatial-transcriptomics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: anndata>=0.10
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# cnverse

Harmonise the outputs of heterogeneous CNV/CNA callers into **one unified
AnnData**, so downstream exploration and visualisation can be written once.

`cnverse` is a thin interoperability layer, not another CNV caller. You run
XClone / Numbat / CalicoST / inferCNV / CopyKAT yourself; `cnverse` reads
each one's output and returns an AnnData with a consistent layout.

```python
import cnverse as cnv

adata = cnv.io.read_xclone("path/to/xclone_out/")
cnv.schema.validate(adata)
# -> AnnData (cells x segments) with a canonical schema, ready to explore
```

## Supported readers

| modality | tool | flavour | reader | status |
|---|---|---|---|---|
| scRNA-seq | inferCNV | expression-only | `read_infercnv` | working |
| scRNA-seq | CopyKAT  | expression-only | `read_copykat`  | working |
| scRNA-seq | Numbat   | allele-aware    | `read_numbat`   | best-effort scaffold |
| scRNA-seq | XClone   | allele-aware    | `read_xclone`   | best-effort scaffold |
| spatial   | CalicoST | allele-specific | `read_calicost` | scaffold (NotImplemented) |

The allele-aware readers expose their tool-specific column names as
constants at the top of each module — edit those to match your installed
version rather than rewriting the reader.

## Canonical schema (v0.1)

- `X` — primary continuous CNV signal; its meaning is recorded in
  `uns["cnverse"]["x_meaning"]`.
- `var` — genomic features (`gene` | `segment` | `bin`) with
  `chrom, start, end, feature_type`.
- `obs` — `clone`, `clone_prob`, `ploidy_status`, `cnverse_tool`.
- `layers` — any of `total_cn, major_cn, minor_cn, cnv_state, baf, rdr, prob`.
- `obsm["spatial"]` — coordinates for spatial modalities.
- `uns["cnverse"]` — provenance + `cnv_states` legend; `uns["clone_tree"]`
  for tools that infer a phylogeny.

See `cnverse/schema.py` for the authoritative definition.

## Install (dev)

```bash
pip install -e ".[dev]"
pytest
```

## Adding a tool

Create `src/cnverse/io/<tool>.py` with a `read_<tool>(...)` that returns
`cnverse.schema.make_cnv_anndata(...)`, then re-export it from
`src/cnverse/io/__init__.py`.
