customics 0.1.1

CustOmics: a versatile deep-learning based strategy for multi-omics integration

Integrate RNA-seq, CNV, DNA methylation, and more into a single predictive model.

customics is a Python package for integrating multiple genomic data modalities using a hierarchical deep-learning architecture. It supports classification, survival outcome prediction, and SHAP-based explainability — all in a single scikit-learn-style API, built on MuData from scverse.

Documentation

Check customics's documentation to get started. It contains installation explanations, API details, and tutorials.

Installation

customics can be installed from PyPI on all OS, for any Python version >=3.11:

pip install customics

Features

• Multi-omics integration — a hierarchical architecture (per-source autoencoders feeding a central VAE) that fuses heterogeneous, high-dimensional modalities into a shared latent space.
• Built-in tasks — tumor classification and survival prediction (Cox), with one scikit-learn-style fit / predict / evaluate API.
• Explainability — per-source feature attribution via SHAP.
• Visualization — latent-space projection (t-SNE) and Kaplan-Meier survival stratification out of the box.

Usage

import customics
from customics import CustOMICS

# --- 1. Load and prepare data ---
# toy_dataset() returns a MuData object: one modality per omics source,
# with clinical annotations in `.obs`.
mdata = customics.toy_dataset()
customics.prepare_input(
    mdata,
    label="PAM50",       # classification target column
    event="OS",          # survival event column (0/1)
    surv_time="OS.time", # survival time column
)

# --- 2. Instantiate the model ---
# Each config dict tunes one component. See the configuration reference for the
# full schema: https://prism-oncology.github.io/customics/hyperparameter_tuning/
model = CustOMICS(
    source_params=source_params,
    central_params=central_params,
    classif_params=classif_params,
    surv_params=surv_params,
    train_params=train_params
)

# --- 3. Train ---
model.fit(mdata, batch_size=32, n_epochs=30, verbose=True)

# --- 4. Evaluate ---
metrics = model.evaluate(mdata, task="classification")  # Accuracy, F1, AUC, …
ci = model.evaluate(mdata, task="survival")             # concordance index

# --- 5. Visualise & explain ---
model.plot_loss()
model.plot_representation(mdata, color="PAM50")
model.stratify(mdata, show=True)
model.explain(sample_ids, mdata, source="rna", subtype="Her2")

[!NOTE] See this usage section for more details about usage.

Reproducing Paper Results

Download TCGA data from the GDC Data Portal or cBioPortal. Pre-computed 5-fold CV splits for BRCA, LUAD, UCEC, BLCA, GBM, OV, and PANCAN are included in the data/splits/ directory.

See our documentation for a complete end-to-end walkthrough using the bundled toy dataset.

Citation

If you use customics in your research, please cite:

@article{benkirane2023,
    doi       = {10.1371/journal.pcbi.1010921},
    author    = {Benkirane, Hakim AND Pradat, Yoann AND Michiels, Stefan AND Cournède, Paul-Henry},
    journal   = {PLOS Computational Biology},
    publisher = {Public Library of Science},
    title     = {CustOmics: A versatile deep-learning based strategy for multi-omics integration},
    year      = {2023},
    month     = {03},
    volume    = {19},
    pages     = {1--19},
    number    = {3}
}