CellTypist Repo Skill

Use this skill when a task involves CellTypist, automated scRNA-seq cell type annotation, CellTypist model downloads or local model pickles, celltypist.annotate, the celltypist CLI, custom CellTypist classifier training, or CellTypist result exports and plots.

Quick Start

Install CellTypist from PyPI or conda, then verify the import and CLI:

pip install celltypist
python -c "import celltypist; print(celltypist.__version__)"
celltypist --help

CellTypist uses scanpy, anndata, scikit-learn, pandas, numpy, openpyxl, click, requests, and leidenalg. GPU paths are optional: rapids-singlecell affects over-clustering during majority voting, and cuml affects GPU logistic regression training.

Route by Task

• Use annotation-workflows for prediction with celltypist.annotate, count tables, Matrix Market input, .h5ad, in-memory AnnData, CLI annotation, best-match vs probability-match modes, majority voting, and table export.
• Use model-management for built-in model download/cache behavior, offline model pickles, CELLTYPIST_FOLDER, Model.load, Model.write, marker extraction, model conversion, model subsetting, and tiny offline model fixtures.
• Use training-and-custom-models for celltypist.train, training matrix/label/gene validation, logistic regression vs SGD vs mini-batch, feature selection, sparse-memory settings, GPU training caveats, and downsample_adata.
• Use visualization-and-results for AnnotationResult tables, Excel export, AnnData insertion, confidence scores, UMAP plot files, and celltypist.dotplot comparisons against manual labels or clusters.

Common Workflows

Annotate Query Cells

Prefer an explicit local model path when the user needs offline behavior. Built-in model names and model=None can consult the CellTypist model cache and may need network access if the cache is empty.

import celltypist

predictions = celltypist.annotate(
    "query_counts.csv",
    model="local_model.pkl",
    mode="best match",
)
predictions.to_table(folder="results", prefix="query_")

For CLI usage, create the output directory first:

mkdir -p results
celltypist --indata query_counts.csv --model local_model.pkl --outdir results --prefix query_ --quiet

Work Offline With Local Models

Use the model-management helpers to avoid accidental downloads:

python sub-skills/model-management/scripts/model_cache_check.py --verify-model ./local_model.pkl
python sub-skills/model-management/scripts/tiny_model_factory.py --output tiny_model.pkl --write-query-csv tiny_query.csv

Then pass ./local_model.pkl or an absolute path to Model.load() or celltypist.annotate().

Train or Preflight Custom Models

Before expensive training, validate the matrix/label/gene shape and algorithm feasibility:

python sub-skills/training-and-custom-models/scripts/training_data_check.py \
  --matrix reference.csv --labels labels.txt --genes genes.txt

Use with_mean=False for sparse data that should not be densified, and use check_expression=False only when the user intentionally trains on a subset such as highly variable genes that cannot satisfy whole-transcriptome normalization checks.

Export and Plot Results

Use the visualization sub-skill when the user already has an AnnotationResult:

adata = predictions.to_adata(insert_labels=True, insert_conf=True, insert_prob=True)
predictions.to_table(folder="results", prefix="query_", xlsx=True)

For celltypist.dotplot(), remember that the default prediction column is majority_voting; use use_as_prediction="predicted_labels" when majority voting was not run.

Shared References and Checks

• Read troubleshooting for install/import issues, model-cache/network surprises, optional GPU package behavior, data-format problems, and workflow routing.
• Read CLI and containers for command patterns, Docker/Singularity notes, and safe smoke checks.
• Read repo provenance before deciding whether this skill matches a current CellTypist checkout or needs refresh.
• Run celltypist_cli_smoke.py to check that the installed celltypist command exposes expected options without running downloads or annotation.

Safety and Self-Containment

• Do not rely on original repository notebooks, docs, or source files at runtime; this skill bundles distilled references and safe helper scripts.
• Do not call model download APIs in offline or restricted environments unless the user explicitly wants network access.
• Treat built-in model files and remote model indexes as runtime data dependencies, not as part of this skill.
• Use local model paths with ./ or absolute paths for strict offline loading; bare filenames can trigger built-in inventory checks.