MSP: Multi-Sample Pipeline

Find recurring noise and annotate cell types across samples.

Why MSP   ·   Workflow   ·   Get started   ·   Results   ·   Documentation

MSP uses cross-sample integration to identify recurring noisy populations and annotate cell types in single-cell RNA-seq data. It combines Harmony, cluster structure, and QC evidence in a browser report, with optional AI agents for inspection and annotation. Start from OSP outputs or your own compatible H5AD files.

Why review samples together?

Outliers are scarce within one sample, but similar noisy cells can recur across many samples. After integration, they can accumulate into dense groups, separating from the main populations while retaining traces of their cell-type identity. This repeated core-and-satellite pattern, or fractal structure, makes noise that was scattered within samples easier to locate and assess together. Recurrence across samples can therefore reveal shared technical effects as well as shared biology.

From structure to noise filtering

MSP locates separated fragments within broad cell populations and compares their QC profiles with core cells. Contamination, doublet, stress, mitochondrial, and inherited QC evidence contribute removal candidates. AI inspection checks markers, sample composition, and cluster structure; annotation applies removals and records their sources. A detached group needs supporting evidence before being interpreted as noise.

How it works

Integration builds the shared map and finds fragments. Inspection reviews quality and biological evidence. Annotation assigns broad and fine labels, merges groups judged to represent the same population, and writes a filtered dataset. The report brings the structures, evidence, and decisions together.

Get started

1. Install

Use Python 3.10 or newer in a separate environment. Install from PyPI with AI support; omit [agent] if you only need integration. No GPU or torch is needed: Harmony runs on the CPU through harmonypy 2.

python -m pip install "msp-sc[agent]"

For the development version, install from GitHub instead:

python -m pip install "msp-sc[agent] @ git+https://github.com/chansigit/msp.git"

2. Prepare your samples

Provide one H5AD per sample, with raw counts in layers["counts"] and a sample column in obs. Files must share the same genes in the same order, and cell IDs must be unique across files. Replace the paths and sample_id below with your own; see the user guide for details.

3. Run the analysis

This command integrates samples and creates msp_out/report.html without an API key. To include AI inspection and annotation, follow the example below it.

python -m msp A/clustered.h5ad B/clustered.h5ad \
    --batch-col sample_id --species human --outdir msp_out

export ARK_API_KEY="YOUR_ARK_API_KEY"
python -m msp A/clustered.h5ad B/clustered.h5ad \
    --batch-col sample_id --species human --outdir msp_out \
    --annotate --harness openai --model doubao-seed-2-1-turbo-260628

Find and understand your results

Open msp_out/report.html in your browser; download it first if you ran on a server. Start with sample composition and cell maps, then compare flagged groups against their markers and QC. Review the proposed labels, merges, and removals before downstream analysis. The HTML embeds its plots and can be shared as one file.

FAQ

Documentation

Read the user guide for input preparation, report reading, and reruns, or the developer guide for APIs, data fields, and stage contracts. A folder-based example runs MSP over OSP outputs. Questions and problems belong in GitHub Issues. MSP uses the MIT license.