Single-cell RNA Analysis

Use this workflow for human or mouse 10x GEX scRNA-seq or snRNA-seq after cell calling. It preserves raw counts, keeps descriptive cluster markers separate from condition inference, and treats annotations as evidence until the user confirms them.

Before running

1. Read the input contract, select exactly one analysis_mode, and resolve every input path. Use descriptive only for a single h5ad without a valid condition contrast; otherwise use comparative.
2. Run preflight(config). Do not proceed when status is invalid.
3. Show the user warnings about ambient RNA, confounding, annotation evidence, or insufficient donor replication before interpreting results.
4. Harmony is opt-in only. Never infer a batch key or silently replace a confounded one.

Call the workflow

The directory contains hyphens, so import it with importlib:

import importlib

single_cell = importlib.import_module("single-cell-rna-analysis.kernel")
config = {
    "schema_version": 1,
    "analysis_mode": "comparative",
    "organism": "human",
    "modality": "scrna",
    "input": {"mode": "sample_sheet", "path": "samples.csv"},
    "reference": {
        "gene_id_type": "symbol",
        "genome_build": "GRCh38",
        "annotation_release": "GENCODE 46",
    },
    "design": {
        "tested": "stim",
        "reference": "control",
        "condition_key": "condition",
        "donor_key": "donor_id",
        "paired": True,
        "covariates": [],
    },
    "integration": {"method": "none", "batch_keys": []},
}

check = single_cell.preflight(config)
result = single_cell.run(config, "single-cell-run")

For a single h5ad with no donor or condition metadata, use descriptive mode:

config = {
    "schema_version": 1,
    "analysis_mode": "descriptive",
    "organism": "human",
    "modality": "scrna",
    "input": {
        "mode": "h5ad",
        "path": "pbmc3k.h5ad",
        "counts_layer": "X",
        "sample_id": "pbmc3k",
    },
    "reference": {
        "gene_id_type": "symbol",
        "genome_build": "hg19",
        "annotation_release": "GENCODE 19",
    },
    "integration": {"method": "none", "batch_keys": []},
}

Descriptive mode never invents donor/condition labels, performs integration, or emits inferential DE/DA. It runs raw-count validation, within-sample QC, embedding, resolution-sweep clustering, descriptive markers and optional evidence-assisted annotation.

run() and resume() return status, run_dir, featured_files, warnings, annotation_status, statistics_status, and manifest. Save every featured file as an Artifact:

for featured_file in result["featured_files"]:
    host.save_artifact(featured_file)

If a run was interrupted, call:

resumed = single_cell.resume("single-cell-run")

Resume validates the resolved configuration and input hashes. A changed source invalidates dependent checkpoints instead of mixing results from different inputs.

Stage routing

• Input ambiguity or validation failure: use the input contract.
• QC, Scrublet, representation, Harmony, clustering, and marker questions: use the scientific workflow.
• Marker panels, reference evidence, Unknown, or confirmed labels: use the annotation contract.
• Pseudobulk DE, pairing, donor replication, or Milo DA: use the statistics contract.
• Checkpoints, statuses, manifest, or Artifact delivery: use the output contract.

Non-negotiable interpretation rules

• A normalized-only matrix is not valid input for formal analysis.
• Multiple samples do not imply that integration is appropriate.
• UMAP appearance does not establish an optimal clustering resolution.
• Cluster markers are descriptive and are not condition DE.
• Descriptive mode cannot support condition, donor, treatment or causal claims.
• Cells are not biological replicates. Inferential DE/DA requires at least three independent donors in each contrast level.
• Candidate labels, including reference transfer, are not ground truth.
• scVI, scGPT, GPU, remote compute, ambient correction, FASTQ processing and downstream specialty analyses require a separate, explicit workflow.