Skip to main content

SampleDisco

A cross-omics, cross-condition sample embedding tool for single-cell data.

SampleDisco takes a cell-level embedding (from any standard scRNA / scATAC / multi-omics integration method) and lifts it to a sample-level embedding that captures both cell-type composition and the per-cell-type state of each sample. Every downstream analysis — sample-to-sample distance, clustering, trajectory inference, phenotype association — then runs on that single shared sample embedding, regardless of modality.

Documentation and tutorial: https://j041120h.github.io/SampleDisco_tutorial/


What the method does

For each modality (RNA, ATAC, or integrated multi-omics) the pipeline produces two cell-level views:

Key Role Source
Z_comp sample-removed embedding — used for cell typing and the composition blocks Harmony (single-omics) / Harmony post-pass on scGLUE (multi-omics)
Z_rmd sample-preserved embedding — used for the reference-relative mean displacement (RMD) block second Harmony pass (single-omics) / scGLUE primary output (multi-omics)

It then assembles four blocks per sample (or per sample × modality for multi-omics):

  1. A1 — one-hot cell-type composition
  2. A2 — soft k-means composition at K_med (≈120)
  3. A3 — soft k-means composition at K_fine (≈300)
  4. RMD — leave-one-out cell-type-resolved displacement on Z_rmd

The four blocks are inverse-variance weighted, Frobenius-stacked, PCA-reduced to 10 dimensions, and Harmony-corrected at sample level. The result is stored as adata.uns['X_DR_sample'] and feeds every downstream module.


Repository layout

code/
├── pyproject.toml                 # package metadata; `pip install -e .` installs the `sampledisco` command
├── config/                        # 10 YAML configs for the paper's datasets: covid / blood (1M-scBloodNL) / eye / heart / ENCODE / healthy-aging PBMC / long_covid / unpaired (+ RNA-tuned) / default
├── src/sampledisco/               # the package
│   ├── cli.py                     # `sampledisco` command: `-m complex --config <yaml>`, `--init-config <path>`
│   ├── config/config_demo.yaml    # demo config written by `sampledisco --init-config`
│   ├── wrapper/                   # Orchestration
│   │   ├── wrapper.py             # Master wrapper; gates RNA + ATAC + multiomics + shared downstream
│   │   ├── rna_wrapper.py
│   │   ├── atac_wrapper.py
│   │   └── multiomics_wrapper.py
│   ├── preparation/               # Preprocessing
│   │   ├── rna_preprocess_{cpu,gpu}.py   # QC → HVG → PCA → dual Harmony → Z_comp + Z_rmd
│   │   ├── atac_preprocess_{cpu,gpu}.py  # QC → TF-IDF → HVF → LSI → dual Harmony → Z_comp + Z_rmd
│   │   ├── cell_type_{cpu,gpu}.py        # Leiden clustering on Z_comp (RNA or ATAC)
│   │   ├── ATAC_cell_type{,_gpu}.py      # ATAC-specific cell typing variants
│   │   ├── multi_omics_glue.py           # scGLUE integration (cross-modality VAE + guidance graph)
│   │   ├── multi_omics_batch_correction.py # Harmony post-pass on X_glue → Z_comp
│   │   ├── multi_omics_merge.py          # post-GLUE merge + per-modality preprocess/slimming
│   │   └── multi_omics_cell_type_{cpu,gpu}.py  # RNA-Leiden + k-NN label transfer to ATAC
│   ├── sample_embedding/          # Core method
│   │   ├── blocks.py              # composition, RMD, weighting, Frobenius stack, final PCA + Harmony
│   │   ├── sample_embedding.py    # CPU pipeline
│   │   └── sample_embedding_gpu.py # GPU pipeline (cuML + cupy)
│   ├── parameter_selection/
│   │   └── autotune.py            # Bayesian GP sweep over RMD α; adaptive proxy ensemble
│   ├── sample_distance/           # Pairwise sample distances (DR / EMD / chi-square / JS)
│   ├── sample_clustering/         # Hierarchical (HRA / HRC / NN / UPGMA / consensus), K-means, proportion test, RAISIN
│   ├── sample_trajectory/         # CCA (supervised) and TSCAN (unsupervised) + GAM-based trajectory DGE
│   ├── sample_association/        # Per-PC variance explained vs sample-level covariates (permutation FDR)
│   ├── sample_prediction/         # Cross-validated phenotype prediction from the PCs; kNN label transfer
│   ├── visualization/             # Embedding plots, dendrograms, DGE volcanos, modality-aware multi-omics scatters
│   ├── utils/                     # Shared helpers: seed, safe h5ad I/O, limma, TF-IDF, batch regress, Grouping
│   └── gene_activity/             # ATAC peak → gene activity inference + RNA-ATAC validation
├── Benchmark_covid/, Benchmark_multiomics/  # benchmark drivers used for the paper
└── claude/                        # one-off run scripts (rerun launchers, monitored runs, parameter sweeps)

Usage

Run — YAML-driven

sampledisco -m complex --config config/config.yaml     # same as: python -m sampledisco.cli -m complex --config ...

The YAML drives every flag and parameter for all three pipelines:

  • Pipeline gates (top-level): run_rna_pipeline, run_atac_pipeline, run_multiomics_pipeline
  • Per-modality phase gates (Phase 1): *_preprocessing, *_cell_type_cluster, *_derive_sample_embedding
  • Per-modality downstream gates (Phase 2): *_sample_distance_calculation, *_trajectory_analysis, *_trajectory_dge, *_sample_cluster, *_proportion_test, *_cluster_dge, *_visualize_data, *_dimension_association_analysis
  • Multi-omics-specific: multiomics_run_glue_*, multiomics_treat_sample_as_batch, multiomics_run_glue_twice_for_sample_removal

The 10 ready-to-use configs in config/ are point-in-time snapshots for the datasets used in the paper; copy one and adjust paths / column names for your own data.

Starter config

sampledisco --init-config my_config.yaml

writes the demo config (tuned for the Zenodo demo dataset) to my_config.yaml. The YAML is validated against every wrapper() parameter, so edit values rather than deleting keys.


Inputs

A standard scanpy AnnData file with at minimum:

  • .X — count matrix (genes for RNA, peaks for ATAC)
  • .obs['sample'] — sample column (required)
  • Optional: .obs['batch'], .obs['cell_type'], sample-level metadata file (CSV) to merge

For multi-omics, the pipeline takes two separate h5ads (RNA + ATAC) and integrates them via scGLUE; samples may be paired (1:1 cell correspondence) or unpaired.


Outputs (under output_dir)

<output_dir>/
├── rna/
│   ├── preprocess/adata_preprocessed.h5ad
│   ├── sample_embedding/sample_embedding.csv
│   ├── Sample_distance/{cosine,correlation}/*
│   ├── CCA/  or  TSCAN/                       # whichever trajectory mode
│   ├── trajectoryDEG/
│   ├── sample_cluster/{kmeans_*,proportion_test/}
│   ├── sample_association/variance_explained_sample.csv + figures/
│   └── visualization/*.png
├── atac/   (parallel structure)
├── multiomics/
│   ├── integration/glue/{rna-pp,atac-pp,guidance.graphml.gz}
│   ├── preprocess/adata_sample.h5ad           # post-GLUE merged adata with Z_comp + Z_rmd
│   ├── sample_embedding/sample_embedding.csv
│   └── (same downstream subdirs as single-omics)
└── sys_log/main_process_status.json           # which stages completed

Installation

SampleDisco is one package. The CPU install is pip-only; GPU acceleration is activated simply by installing the GPU libraries separately — the same package detects and uses them at runtime. There is no separate "GPU build" of SampleDisco.

1. Core install (CPU)

pip install sampledisco          # or `pip install -e .` from a clone

2. System prerequisite — bedtools

scGLUE (the multi-omics integrator) calls the bedtools binary, which pip cannot provide:

conda install -c bioconda bedtools

3. GPU acceleration (optional, install yourself)

The GPU functions (RAPIDS-accelerated normalization, Harmony, k-means / PCA, Leiden, scGLUE training) turn on only when the RAPIDS stack is present in your environment. RAPIDS is CUDA-driver-specific and conda-only, so you install it separately, matching your driver (the pins below target a CUDA-12.5 driver such as the cluster's GPU nodes):

conda install -c rapidsai -c conda-forge -c nvidia \
    cuml=24.12 cudf=24.12 cugraph=24.12 rmm=24.12 cuvs=24.12 cupy=13 cuda-version=12.5
pip install rapids-singlecell==0.13.1 --no-deps

Then set use_gpu: true in your config. You do not reinstall SampleDisco — once those packages are importable the GPU paths activate automatically; if they are missing or the driver is too old, SampleDisco falls back to CPU equivalents (harmonypy / linear regression, scikit-learn k-means, PyTorch CPU).

For a fully reproducible environment (including bedtools), use the provided conda files instead of the manual steps above — see INSTALL.md for the driver/version notes:

conda env create -f environment-cpu.yml      # CPU
conda env create -f environment-gpu.yml      # GPU (RAPIDS 24.12)

Metadata

Release files for sampledisco 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sampledisco 0.5.0
File Size Uploaded Provenance Actions
sampledisco-0.5.0.tar.gz 299.7 kB Without provenance Details for sampledisco-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sampledisco 0.5.0
File Interpreter ABI Platform Actions
sampledisco-0.5.0-py3-none-any.whl Python 3 none any Details for sampledisco-0.5.0-py3-none-any.whl

Total release size: 643.6 kB

Release files / sampledisco-0.5.0.tar.gz

Download URL sampledisco-0.5.0.tar.gz
Size 299.7 kB
Tags Source
SHA-256 checksum
How to use checksums
32171050e48e253291a81bf94f192e12139c5ab3ccf54efbfa4db84f75421432
BLAKE2b-256 checksum
How to use checksums
2ad3e1e712322323afd86590fd2e2fa80b0db9c4ce19a37786e910d32ebf3f2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.20

Release files / sampledisco-0.5.0-py3-none-any.whl

Download URL sampledisco-0.5.0-py3-none-any.whl
Size 343.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b20cee633466c5f1aa030698561f25bbea492a40c545e602c1f850aabee7f374
BLAKE2b-256 checksum
How to use checksums
e5402125247ad139d4af0cfcd5f34e0cb2ebdc6877b21ab594f87ddf30aee8b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.20

Security for sampledisco 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page