Annotation and state scoring
The immune_annotation pipeline labels immune cells, transfers labels from a reference marker atlas, and scores immune state programs.
Outputs
| Output | Description |
|---|---|
labels | Immune hierarchy label counts and proportions |
reference_labels | Reference-atlas label counts and proportions |
reference_confidence | Counts for high, medium, ambiguous, below-threshold, or out-of-reference assignments |
reference_atlas | Atlas labels, marker counts, provenance, organism metadata, and query/atlas gene-overlap compatibility |
groups | Group-level label summaries |
state_programs | Mean scores for immune gene programs |
cells_preview | Per-cell preview with hierarchy label, reference label, probability, confidence, competing labels, matched genes, and state scores |
run_record | Gene set source, reference atlas versions, annotation parameters, and CellTypist model field |
Reference atlas input
The optional reference atlas table can include:
| Column | Purpose |
|---|---|
label or cell_type | Fine immune label |
broad_label | Broad immune compartment |
markers or marker_genes | Comma-, semicolon-, or pipe-separated marker genes |
organism | Atlas organism metadata |
reference | Atlas/source name |
version or model_version | Atlas/model version |
If no atlas is supplied, the pipeline uses the built-in immune marker atlas. The result records marker overlap and organism warnings so users can detect gene-ID or species mismatches.
Built-in programs
- exhaustion
- activation
- effector function
- cytotoxicity
- regulatory suppression
CellTypist gate
The pipeline detects whether CellTypist is available and records CellTypist status. Concrete CellTypist model execution still requires configured model assets. Until then, celltypist_model_version is logged as null, while the native reference-atlas label-transfer output remains available.
Interpretation
AI summaries cite computed labels and state scores only. They do not infer clinical immune status or treatment response.