celltypist
Use CellTypist for single-cell RNA-seq cell type annotation, model management, custom classifier training, CLI usage, and result visualization workflows.
- License 许可
- MIT
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- celltypist
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Use CellTypist for single-cell RNA-seq cell type annotation, model management, custom classifier training, CLI usage, and result visualization workflows.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/cli-and-containers.md3.0 KB
- 参考文档references/repo-provenance.md1.7 KB
- 参考文档references/repo-routing-metadata.json337 B
- 参考文档references/troubleshooting.md3.9 KB
- 脚本scripts/celltypist_cli_smoke.py3.0 KB
03 SKILL.md 正文
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-memoryAnnData, 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, anddownsample_adata. - Use visualization-and-results for
AnnotationResulttables, Excel export, AnnData insertion, confidence scores, UMAP plot files, andcelltypist.dotplotcomparisons 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
celltypistcommand 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.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).