Installation

pip install sampledisco installs the full CPU pipeline (RNA, ATAC, and multi-omics from a pre-integrated file). GPU acceleration and training GLUE from scratch are optional, environment-specific add-ons.

Requirements

• Python ≥ 3.10, macOS or Linux. GPU acceleration is Linux + NVIDIA only.
• RAM: ≈ 8 GiB for RNA; ≈ 16 GiB for the full RNA+ATAC demo (ATAC's peak matrix is large).

1. Core install (CPU)

conda create -n sampledisco python=3.10 && conda activate sampledisco
pip install sampledisco

Verify, then drive the pipeline from a YAML config (see the Configuration guide):

python -c "import sampledisco; print(sampledisco.__version__)"
sampledisco --help

2. GPU acceleration (optional — Linux + NVIDIA)

Build the GPU environment from the repo's validated env file. (Layering conda install of RAPIDS onto the CPU env does not solve — a channel clash.)

git clone https://github.com/J041120h/SampleDisco.git && cd SampleDisco
conda env create -f environment-gpu.yml         # RAPIDS 24.12 + torch 2.5.1+cu121
conda activate sampledisco-gpu
pip install rapids-singlecell==0.13.1 --no-deps
pip install sampledisco --no-deps

Verify the stack, then set use_gpu: true in your config:

python -c "import cuml, cupy, rapids_singlecell; print('GPU OK')"

If the stack is missing, runs fall back to CPU (the backend used is recorded as gpu_available in sys_log/main_process_status.json). GPU and CPU embeddings are not identical — the k-means backends differ — so stay on one backend for reproducible results; on small data the GPU may be no faster than CPU. The 24.12 pins target a CUDA 12.0–12.5 driver; bump to RAPIDS 25.x on a newer driver.

3. Training GLUE from scratch (optional)

Only needed to build the multi-omics integration yourself (the demo starts from a pre-integrated file). scGLUE 0.3.2 needs anndata < 0.11, so use a dedicated env:

conda create -n sampledisco-glue python=3.10 && conda activate sampledisco-glue
conda install -c bioconda bedtools
pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cu121   # cu12 build first
pip install "anndata<0.11" scglue==0.3.2 harmony-pytorch
pip install sampledisco   # installs core deps; anndata stays <0.11 (already satisfied)

The torch line is Linux + NVIDIA only

The cu121 index has no macOS wheels. On macOS, drop the --index-url and just pip install torch==2.5.1 — GLUE trains fine on CPU torch there.

Do not add --no-deps to the final pip install sampledisco: scGLUE does not pull sampledisco's ~20 core runtime deps (pyensembl, harmonypy, muon, POT, pygam, leidenalg, combat, pybedtools), and skipping them makes sampledisco -m complex ImportError.

Install scGLUE from PyPI, never conda install -c bioconda scglue (that recipe caps numpy<1.22).

Reproducible env files

The repo ships exact-version environment-cpu.yml and environment-gpu.yml (creating the envs sampledisco-cpu and sampledisco-gpu respectively). The final pip install -e . --no-deps must run from inside the cloned repo:

git clone https://github.com/J041120h/SampleDisco.git && cd SampleDisco
conda env create -f environment-cpu.yml   # or environment-gpu.yml → sampledisco-gpu
conda activate sampledisco-cpu
pip install -e . --no-deps