Metadata-Version: 2.1
Name: champollion-omics
Version: 0.1.0
Summary: Semi-paired single-cell multimodal integration with Champollion
License: GPL-3.0-or-later
Author: jules-samaran
Author-email: samaran.jules@gmail.com
Requires-Python: >=3.12.7,<3.13
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: wandb
Requires-Dist: anndata (>=0.10.9,<0.11.0)
Requires-Dist: flatten-dict (>=0.4.2,<0.5.0)
Requires-Dist: furo (>=2025.7.19,<2026.0.0) ; extra == "docs"
Requires-Dist: gprofiler-official (>=1.0.0,<2.0.0)
Requires-Dist: ipykernel (>=7.0.0,<8.0.0)
Requires-Dist: matplotlib (>=3.7)
Requires-Dist: mudata (>=0.3.1,<0.4.0)
Requires-Dist: muon (>=0.1.6,<0.2.0)
Requires-Dist: myst-parser (>=4.0.0,<5.0.0) ; extra == "docs"
Requires-Dist: nbsphinx (>=0.9.7,<0.10.0) ; extra == "docs"
Requires-Dist: notebook (>=7.4.7,<8.0.0)
Requires-Dist: pykeops (>=2.2.3,<3.0.0)
Requires-Dist: pytest (>=8.3.2,<9.0.0)
Requires-Dist: pytest-cov (>=7.0.0,<8.0.0) ; extra == "dev"
Requires-Dist: ruff (>=0.14.0,<0.15.0) ; extra == "dev"
Requires-Dist: scikit-misc (>=0.5.1,<0.6.0)
Requires-Dist: seaborn (>=0.12)
Requires-Dist: sphinx (>=8.2.0,<9.0.0) ; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints (>=3.5.0,<4.0.0) ; extra == "docs"
Requires-Dist: torch (>=2.2,<2.7)
Requires-Dist: wandb (>=0.17.3,<0.18.0) ; extra == "wandb"
Requires-Dist: zarr (>=2.18,<4)
Description-Content-Type: text/markdown

# Champollion

[![Tests](https://github.com/cantinilab/champollion/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/cantinilab/champollion/actions/workflows/tests.yml)
[![Lint](https://github.com/cantinilab/champollion/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/cantinilab/champollion/actions/workflows/lint.yml)
[![Docs](https://github.com/cantinilab/champollion/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/cantinilab/champollion/actions/workflows/docs.yml)
[![Build](https://github.com/cantinilab/champollion/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/cantinilab/champollion/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/cantinilab/champollion/branch/main/graph/badge.svg)](https://codecov.io/gh/cantinilab/champollion)

Champollion learns an interpretable cross-modality cost from paired bridge cells and uses it to integrate unpaired single-cell profiles across modalities. It is designed for scverse workflows with `AnnData` and `MuData`, and exposes utilities for annotation transfer, barycentric projection, and interpretation of the learned interaction matrix.

![Champollion model overview](docs/source/_static/champollion_model.png)

## Install

Install the latest stable release from PyPI (recommended):

```bash
pip install champollion-omics
```

Optional Weights & Biases logging can be installed with:

```bash
pip install "champollion-omics[wandb]"
```

To install the latest development version from GitHub instead:

```bash
pip install "git+https://github.com/cantinilab/champollion.git"
```

Champollion is designed to take advantage of a GPU and runs much faster with one, typically taking only a few minutes on datasets with thousands of cells.

## Documentation

Documentation is available at [champollion-omics.readthedocs.io](https://champollion-omics.readthedocs.io/en/latest/).

Two tutorials are available there to demonstrate classic use cases of the package: fitting Champollion on bridge cells, transporting unpaired cells, transferring annotations, building a joint visualization, interpreting the learnt `A` matrix.

## Getting Started

For a concrete application, see the tutorials; the example below is only a compact overview of the API. Champollion is fitted on a paired bridge stored in a `MuData` object. It can then be applied to modality-specific `AnnData` objects containing unpaired cells.

```python
from champollion import Champollion

model = Champollion(
    epsilon=1.0,
    gamma=0.001,
    lambda_prior=20.0,
    use_keops=False,
    device="auto",
    random_state=0,
)

model.fit(
    mdata_bridge,
    modality_1="rna",
    modality_2="atac",
    x_1_rep="X_pca",
    x_2_rep="X_lsi",
    y_prior_1_rep="X_prior",
    y_prior_2_rep="X_prior",
)

result = model.transport(
    {"rna": adata_rna, "atac": adata_atac},
    x_reps={"rna": "X_pca", "atac": "X_lsi"},
    y_prior_reps={"rna": "X_prior", "atac": "X_prior"},
)

predicted_atac_labels = result.transfer_obs(
    key="cell_type",
    source="rna",
    kind="categorical",
)
```

The learned matrix can be inspected directly:

```python
A = model.A_dataframe()
top_links = model.top_interactions("CD18", modality="protein", k=10)
```

## Citation

The preprint is in preparation. Citation information will be added before the official release.
if you're looking for the repository to reproduce the results in the article, please see the [champollion_reproducibility](https://github.com/cantinilab/champollion_reproducibility) repository!

