Installation¶

Requirements¶

cycombinepy supports Python 3.10, 3.11, and 3.12. The core pipeline depends on numpy, pandas, scipy, scikit-learn, anndata, scanpy, inmoose (ComBat), flowsom (SOM clustering) and formulaic (model-matrix construction).

Install from PyPI¶

pip install cycombinepy

This pulls in the core dependencies. The following optional extras add dependencies for specific modules:

Extra	Adds
`[io]`	`pytometry` for reading raw FCS files via `cycombinepy.io.read_fcs_dir`
`[plotting]`	`matplotlib` + `seaborn` for the `cycombinepy.plotting` helpers
`[eval]`	`scib-metrics` for `cycombinepy.evaluate.scib_metrics`
`[benchmark]`	`muon`, `harmonypy`, `scvi-tools`, plus `[eval,plotting]` for vignettes
`[all]`	`[io]`, `[eval]`, and `[plotting]`; excludes heavy benchmark packages

Install with extras, e.g.:

pip install "cycombinepy[all]"

The CITE-seq ADT benchmark notebook uses heavier multimodal dependencies and downloads the public scvi-tools PBMC10k/PBMC5k MuData file, about 425 MB. Install that environment only when you plan to run the benchmark:

pip install "cycombinepy[benchmark]"

Install from source (development)¶

Clone the repository and install in editable mode:

git clone https://github.com/mdmanurung/cyCombinePy.git
cd cyCombinePy
pip install -e ".[all,dev]"

The [dev] extra adds pytest, pytest-cov, build, and twine for the release workflow. After installation you can run the test suite with:

pytest -q

Building the documentation¶

The documentation site is built with Sphinx, myst-nb, and the furo theme. Install the docs extra and build locally:

pip install -e ".[all,docs]"
sphinx-build -b html docs/source docs/build/html

The generated site is written to docs/build/html/. Open index.html in a browser, or serve it locally with:

python -m http.server -d docs/build/html 8000

The public documentation is deployed to GitHub Pages at https://mdmanurung.github.io/cyCombinePy/. The deployment workflow builds this Sphinx source tree on pushes to master or main.

The tutorial notebooks under docs/source/notebooks/ are source-only in documentation builds. Deterministic documentation snippets are tested in CI. To refresh notebook outputs locally:

jupyter nbconvert --to notebook --execute --inplace \
    docs/source/notebooks/cycombine.ipynb \
    docs/source/notebooks/detect_batch_effects.ipynb

The CITE-seq ADT notebook stores rendered outputs in the documentation source so the website can include benchmark tables and figures without re-executing the heavy workflow during Sphinx builds. For manual validation, install cycombinepy[benchmark], optionally set CYCOMBINEPY_CITESEQ_CELLS_PER_BATCH and TOTALVI_MAX_EPOCHS=2, then execute docs/source/notebooks/citeseq_adt_batch_correction.ipynb.

Verifying the installation¶

import cycombinepy as pc
print(pc.__version__)

# Functional smoke test: create a tiny AnnData and run the pipeline.
import anndata as ad
import numpy as np
import pandas as pd

rng = np.random.default_rng(0)
X = np.vstack([rng.normal(0, 1, (200, 5)),
               rng.normal(1, 1, (200, 5))])
obs = pd.DataFrame({"batch": ["a"] * 200 + ["b"] * 200})
obs.index = obs.index.astype(str)
adata = ad.AnnData(X=X, obs=obs)
adata.var_names = [f"CD{i}" for i in range(5)]

pc.batch_correct(adata, xdim=4, ydim=4, rlen=3, seed=0)
print("corrected layer:", adata.layers["cycombine_corrected"].shape)

If that prints a (400, 5) shape without raising, your installation is working.

Installing the agent skill¶

cyCombinePy bundles a Claude Code/Codex skill inside the installed package. Copy it into the default personal skill directories with:

cycombinepy-install-skills

The default target is both ~/.claude/skills/cycombinepy/ and ~/.codex/skills/cycombinepy/. To install one target:

cycombinepy-install-skills --agent claude
cycombinepy-install-skills --agent codex

Use --force after upgrading cyCombinePy to refresh an existing copy. Use --print-path to print the bundled skill directory when a tool should load the package copy directly.