Start with a human or mouse count-bearing AnnData file, Cell Ranger output directory, standalone 10x H5 or Matrix Market matrix, or a CSV/TSV sample sheet. For gene-family QC, use gene symbols in var_names. Install the base package on
Linux, macOS or WSL. Installation guide.
cellquorum init my_study --input /path/to/study.h5adFor several libraries, use one row per library. Paths are relative to the sheet. Use a biological replicate ID consistently across repeated measurements.
sample_id,path,donor,condition,metadata_path
D1_normal,D1_normal/outs,D1,normal,D1_normal/cells.csv
D1_tumor,D1_tumor/outs,D1,tumor,D1_tumor/cells.csvmetadata_path is optional. Its table has a barcode column and one row for every barcode in the filtered library. Add your cell labels there. Additional sheet fields are library-level metadata. For AnnData entries with transformed X, declare counts_layer. Recognized sidecars include raw_matrix_path, loom_path, bam_path and gtf_path. A matrix-only study can run expression analyses and DPT as its design allows. Velocity needs splice evidence. For a sample sheet, run cellquorum init my_study --input samples.csv. It writes the reusable configuration, merged counts and normalized manifest into the new study directory.
Choose the question you want to answer.
| Choice | What to supply | What to open first |
|---|---|---|
discovery |
Counts plus the study design, label sources, reference resources and biological questions the available evidence supports | Manuscript gallery, exclusions and study report |
questions |
Selected question families and their inputs. Replicated comparisons can also request leave-one-donor-out abundance sensitivity | Panels, donor tables, resolved settings and inferred program results |
explore |
Raw counts, organism and preparation | The cluster UMAP and QC figures in the HTML report |
abundance |
The same inputs plus existing cell-type labels, biological replicate IDs and two conditions | The composition figure and results/da_proportion_ttest.csv |
The prompts list the count matrices and observation columns in your file. Specify whole cells,
nuclei or mixed preparation so QC can interpret nuclear-retained signal appropriately. Give
a library ID column if you have one. For a mixed study with several values identifying
nuclei, add them to qc_evidence.graded.nuclei_values in the saved config.
For abundance, choose the biological replicate, such as a mouse or a patient. In a study measuring
the same people before and after treatment, choose the patient ID, set the reference to the
baseline condition, and choose paired. The setup shows the number of replicates in each arm
and how many appear in both. A paired test requires at least two complete pairs and uses the
donors with both measurements. For groups of different individuals choose independent.
Open my_study/config.yaml. The input and output paths are absolute, so the same config works
from another directory on the same machine. The stages block lists the analyses selected.
The baseline QC applies floors of 200 detected genes per cell and three cells per gene.
Review those thresholds for the assay. Ambient correction and doublet detection are off in
both starters.
For abundance, check design.donor_col, design.condition_col, design.control, design.case
and design.paired. An effect of +5 percentage points means that the cell type accounts for
five more percentage points of the sampled cells, on average, in the comparison condition.
Check the donor counts and adjusted p-values alongside the effect. The test measures relative
composition.
plan validates the YAML and lists the stages enabled in your configuration
alongside the available backends.
cellquorum plan -c my_study/config.yamlDataset and method checks run during execution. Inspect the report for their
outcomes. Add --json to the plan command for machine-readable output.
cellquorum run -c my_study/config.yamlThe engine creates the standardized run directory, executes each enabled stage
in dependency order, validates the AnnData at every stage boundary, and
records provenance as it goes. Useful flags:
| Flag | Effect |
|---|---|
-o, --output-dir |
Where the run directory is written. |
--bootstrap-only |
Create the run structure and resolve the plan without executing stages. |
--json |
Print the run summary as JSON. |
-q, --quiet |
Suppress progress output. |
Every run writes the same directory contract, so you always know where to look:
my_study/run/
├── reports/ # human-readable HTML + Markdown report — start here
├── figures/ # generated figures (QC, embeddings, DE, …)
├── results/ # machine-readable result tables (CSV/TSV)
├── objects/ # intermediate AnnData objects (.h5ad checkpoints)
├── provenance/ # resolved config, execution plan, backend status,
│ # environment/version stamp, artifact manifest
└── logs/ # execution logs and per-stage warnings
Open reports/report.html and expand an analysis under Analysis outputs to
open its registered figures and tables. Keep the run directory together when sharing it
so the links continue to work. The provenance/ directory
captures the exact resolved config, the plan that ran, which backends were
present, and the software/environment versions — so a run can be re-created or
audited later.
Download the Kang AnnData file
and run cellquorum init kang --input kang_2018.h5ad. Select abundance, X, human
and cells. Leave the library field empty. Choose cell_type for the annotation,
replicate for the donor and label for the condition. Select ctrl as the reference,
stim as the comparison and paired for the design. Dataset description.
Run cellquorum run -c kang/config.yaml. The tested file contained 24,673 cells from
eight donors. With the starter settings, 24,562 cells cleared the QC floors and all eight
cell types had results from eight paired donors. This file contains no mitochondrial
gene names matching MT-, so mitochondrial percentage is unavailable.
Edit the saved configuration to extend a study.
- Rename the cohort keys to match your obs columns — nothing downstream hardcodes them.
- Enable more stages in the
stagesblock as their backends become available (differential expression and multicellular programs need the R env; cell–cell communication and trajectory benefit from the GPU env — see Backends & environments). - Restrict to a lineage with
input.subset(e.g. run the whole pipeline on fibroblasts only) without splitting your object by hand. - Drop a cluster with
input.exclude(e.g. an ambient-RNA artifact cluster found bycellquorum.stats.cluster_artifact_audit) — the direction a subset cannot express, since a subset names what to keep. Both rules compose, and both record what they removed in provenance. See Configuration.
- Configuration — every top-level section and per-stage block, and how a method is selected per stage.
- Architecture — how validation, planning, the executor, and provenance fit together.
- Backends & environments — the R/Rscript bridge, the GPU env, and the isolated backend environments.
- Python API — drive the same pipeline from a notebook with
cellquorum.run_pipeline.