Metadata-Version: 2.4
Name: insitucnv-copykat
Version: 0.3.0
Summary: InSituCNV (Jensen et al.) with an optional CopyKAT backend, and dependency bounds relaxed for modern anndata/pandas.
Author: Augusta
Maintainer: Srinivasa Rao Rao
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/sraorao/insituCNV-copykat
Project-URL: Repository, https://github.com/sraorao/insituCNV-copykat
Project-URL: Issues, https://github.com/sraorao/insituCNV-copykat/issues
Project-URL: Upstream project, https://github.com/Moldia/InSituCNV
Project-URL: Upstream documentation, https://insitucnv.readthedocs.io/
Keywords: copy-number-variation,spatial-transcriptomics,single-cell,bioinformatics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10
Requires-Dist: infercnvpy>=0.6.0
Requires-Dist: igraph>=0.11
Requires-Dist: leidenalg>=0.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: scanpy>=1.10
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Dist: scvelo>=0.3.3
Requires-Dist: tqdm>=4.66
Provides-Extra: copykat
Requires-Dist: rpy2>=3.5; extra == "copykat"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-nb>=1.0; extra == "docs"
Requires-Dist: ipython>=8.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# InSituCNV + CopyKAT backend

> ## ⚠️ Attribution — this is a fork
>
> This repository is a **fork of [Moldia/InSituCNV](https://github.com/Moldia/InSituCNV)**.
> **All credit for InSituCNV — the method, the package, and the original code — belongs to
> the InSituCNV authors (Jensen et al., Moldia lab).** This fork adds *only* an optional
> [CopyKAT](https://github.com/navinlabcode/copykat) backend as an alternative to
> `infercnvpy`; everything else is their work, unchanged.
>
> - Original repository: https://github.com/Moldia/InSituCNV
> - Original paper: Jensen et al., *In Situ* inference of copy number variations in
>   image-based spatial transcriptomics, bioRxiv (2025),
>   https://doi.org/10.1101/2025.07.02.662761
> - CopyKAT: Gao et al., [navinlabcode/copykat](https://github.com/navinlabcode/copykat)
>
> If you use this work, please cite the original InSituCNV paper (and CopyKAT if you use
> that backend). Please direct questions about the core method to the upstream project.

Reusable notebook workflow for inferring copy-number variation (CNV) profiles
from image-based spatial transcriptomics data.

This repository contains the general package version of the workflow used in
***In Situ* Inference of Copy Number Variations in Image-Based Spatial
Transcriptomics** by Jensen et al. The manuscript reproduction code is kept in a
separate repository: https://github.com/Moldia/InSituCNV-manuscript

## CopyKAT backend (this fork)

This fork adds an alternative CNV-calling engine based on the R package
[CopyKAT](https://github.com/navinlabcode/copykat) as a drop-in replacement for
`infercnvpy`. Everything else in the pipeline — loading, spatial smoothing,
CNV-space clustering, chromosome heatmaps and spatial plots — is shared between
the two backends, because `run_copykat` writes CopyKAT's output into the same
`adata.obsm["X_cnv"]` / `adata.uns["cnv"]["chr_pos"]` keys that `infercnvpy` uses.

Select the backend with the `backend` argument:

```python
import insitucnv as icv

# inferCNV (default)
icv.run_insitucnv(adata, output_dir="out_infercnv", reference_key="cell_type")

# CopyKAT
icv.run_insitucnv(
    adata,
    output_dir="out_copykat",
    reference_key="cell_type",
    backend="copykat",
    copykat_kwargs={"genome": "hg20", "min_gene_per_cell": 5},  # e.g. use_raw_counts=True
)
```

By default CopyKAT is fed InSituCNV's spatially-smoothed layer (`"M"`); pass
`copykat_kwargs={"use_raw_counts": True}` to use raw counts instead. Reference
cells (`reference_categories`) are handed to CopyKAT as `norm.cell.names` to seed
its diploid baseline. **Note:** CopyKAT was built for scRNA-seq with thousands of
genes; its `min.gene.per.cell` default (200) is relaxed here for small image-based
panels. See `insitucnv/tl/copykat.py` for details.

**Runtime.** CopyKAT's cost is ~O(cells²) (repeated cell×cell `parallelDist` +
`hclust`), e.g. ~2 h for ~10k cells. `run_copykat` skips CopyKAT's redundant internal
heatmap by default (`skip_internal_plots=True`, ~30% faster, identical results). Using
fewer cells is the strongest lever; to still label every cell from a fast subsampled
run, `insitucnv.tl.propagate_cnv_labels` (or the comparison script's `--propagate`
flag) copies the calls to all cells by transcriptomic cluster or kNN — a copied label,
not per-cell inferred CNV.

### Environment and install (CopyKAT backend)

```bash
conda env create -f insitucnv_copykat.yml
conda activate insitucnv_copykat
R -e 'remotes::install_github("navinlabcode/copykat", dependencies=FALSE)'
pip install -e .
```

From the command line:

```bash
python scripts/run_insitucnv_copykat.py \
    --input-dir /path/to/xenium_output \
    --output-dir results/sample1 \
    --reference-key cell_type
```

## References

InSituCNV builds upon several excellent packages in the single-cell and spatial
transcriptomics ecosystem:

- **[infercnvpy](https://github.com/icbi-lab/infercnvpy)**: Core CNV inference logic.
- **[scVelo](https://github.com/theislab/scvelo)**: Transcriptomic smoothing and analysis.
- **[Scanpy](https://github.com/scverse/scanpy)**: General single-cell analysis framework.
- **[AnnData](https://github.com/scverse/anndata)**: Data structures for single-cell data.

If you use InSituCNV in your research, please cite:

Jensen et al. *In Situ* inference of copy number variations in image-based spatial transcriptomics. bioRxiv (2025).
https://doi.org/10.1101/2025.07.02.662761

## Installation

This fork is published on PyPI as **`insitucnv-copykat`**, because `insitucnv` is
upstream's name. The import name is unchanged:

```bash
pip install insitucnv-copykat     # then: import insitucnv
```

Install upstream's own release with `pip install insitucnv` instead if you do not need
the CopyKAT backend or the relaxed anndata/pandas bounds.

Clone the repository and install the package in editable mode:

```bash
git clone https://github.com/Moldia/InSituCNV.git
cd InSituCNV
conda env create -f insitucnv.yml
conda activate insitucnv_env
pip install -e ".[dev,docs]"
jupyter lab
```

Open the notebooks from the `notebooks/` directory in JupyterLab.

## Development Setup

Install the package and development tools into your active environment:

```bash
pip install -e ".[dev,docs]"
```

Notebooks and examples should import the installed package directly:

```python
import insitucnv as icv
```

No `sys.path` edits are required when the editable install is active.

## Running Tests

```bash
pytest
```

## Building Docs Locally

```bash
sphinx-build -b html docs docs/_build/html
```

The documentation uses Sphinx, the Read the Docs theme, autodoc/autosummary API
pages, and `myst-nb` for notebook tutorials.

## Releasing Package

Build the source distribution and wheel locally:

```bash
python -m build
```

Publish TestPyPI releases through the `publish-testpypi.yml` GitHub Actions
workflow after configuring Trusted Publishing in TestPyPI. Do not store PyPI or
TestPyPI API tokens in the repository.

## What You Need Before Running

Prepare an `.h5ad` file with the information needed by the notebooks:

- raw counts, preferably in `adata.layers["raw_counts"]`; if raw counts are in
  `adata.X`, the first notebook can copy them into `adata.layers["raw_counts"]`;
- spatial coordinates in `adata.obsm["spatial"]`;
- a nearest-neighbor graph for smoothing, usually from `scanpy.pp.neighbors`;
- an `adata.obs` column that identifies normal or healthy reference cells for
  `infercnvpy`;
- the exact category names in that reference column that should be used as the
  normal reference, for example immune, stromal, or other non-tumor cell types;
- gene names that can be matched to genomic coordinates. The package includes
  the default `infercnvpy` gene coordinate table, and the notebooks show where
  to adjust this if your gene annotation differs.

Do not use normalized or log-transformed values as raw counts. The CNV workflow
normalizes, smooths, and log-transforms the raw counts itself.

## Notebook Workflow

Run the notebooks in order for your own dataset, editing the setup cells at the
top of each notebook.

### 1. Run InSituCNV

`notebooks/run_insitucnv.ipynb`

Use this notebook to run the full CNV analysis step by step:

- load your spatial transcriptomics `.h5ad` file;
- choose the raw count layer name with `RAW_LAYER`;
- choose the normal/reference annotation with `REFERENCE_KEY` and
  `REFERENCE_CATEGORIES`;
- normalize raw counts;
- smooth normalized counts over the neighbor graph;
- add genomic positions;
- run `infercnvpy`;
- cluster CNV profiles across selected Leiden resolutions;
- visualize chromosome heatmaps and spatial CNV cluster plots.

After reviewing the heatmap and spatial plot, manually edit:

- `NORMAL_CLUSTERS`;
- `TUMOR_CLUSTERS`, if you want to specify tumor clusters directly;
- `TUMOR_CLONE_CLUSTERS`, if some tumor clusters have distinct enough CNV
  profiles to report as separate tumor clones.

No cluster is marked as normal automatically.

## Outputs

The notebooks write results under their configured output directories, usually
`results/...` or `outputs/...`. Typical outputs include:

- checked input `.h5ad` files;
- AnnData objects with CNV values and CNV cluster labels;
- CNV chromosome heatmaps;
- spatial CNV cluster plots;
- optional manually annotated tumor/normal and tumor-clone cell group tables;
- optional mean CNV profiles for manually selected tumor cells.
