popv-cell-annotation
Consensus cell type annotation: runs 10+ algorithms (KNN-Harmony/BBKNN/Scanorama/scVI, CellTypist, ONCLASS, Random Forest, SCANVI, SVM, XGBoost) on a labeled reference and transfers labels via majority voting. Outputs per-method labels, consensus, agreement score
Install / Use
npx skills add jaechang-hits/SciAgent-Skills --skill popv-cell-annotationInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of popv-cell-annotation
popv-cell-annotation scores 91/100 on our quality scale, 1182nd of 4,716 Development & Engineering skills we index (top 26%).
Its SKILL.md is 27 KB long, well organised into 72 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
It has 367 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so popv-cell-annotation is actively maintained.
- Our last check on 2026-11-20 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
popv-cell-annotation compared with similar skills
All 4 of these similar skills score higher than popv-cell-annotation; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| popv-cell-annotation (this skill)by jaechang-hits | 91 | 367 | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 118.9k | 11d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 87.1k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.6k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.5k | 5d ago | CLAUDE.md |
Frequently asked questions
- How do I install popv-cell-annotation?
- Run
npx skills add jaechang-hits/SciAgent-Skills --skill popv-cell-annotation. The install tabs above show the steps for each supported agent. - Which AI agents does popv-cell-annotation work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is popv-cell-annotation safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is popv-cell-annotation still maintained?
- The repository was last updated about 3 months ago, so popv-cell-annotation is actively maintained.
Skill content
View source on GitHubname: "popv-cell-annotation" description: "Consensus cell type annotation: runs 10+ algorithms (KNN-Harmony/BBKNN/Scanorama/scVI, CellTypist, ONCLASS, Random Forest, SCANVI, SVM, XGBoost) on a labeled reference and transfers labels via majority voting. Outputs per-method labels, consensus, agreement score. Use when single-method annotation is insufficient or you need ensemble uncertainty for novel states." license: "BSD-3-Clause"
popV Multi-Method Cell Type Transfer
Overview
popV (Population Voting for single-cell annotation) annotates a query scRNA-seq dataset by running 10+ independent classification algorithms against a labeled reference atlas and aggregating results via majority voting. Each method produces its own label; the final popv_prediction is the consensus across all methods, and the popv_agreement score quantifies how many methods agree. This ensemble strategy is robust to individual method failures on unusual datasets and provides a principled uncertainty estimate: low agreement highlights novel cell states or annotation gaps.
When to Use
- Annotating a query dataset by transferring labels from a well-curated reference atlas when you want a consensus rather than a single model's judgment
- Identifying novel or ambiguous cell states as cells where methods disagree (low
popv_agreementscore) - Benchmarking annotation reliability by comparing per-method labels to detect systematic disagreements
- Annotating large atlas datasets (>100k cells) where batch effects between reference and query are substantial
- Producing annotation for downstream analyses that require high-confidence labels (clinical data, regulatory submissions)
- Use omics-plotting SKILL for confidence bar charts and method-agreement heatmaps from exported tables (UMAPs stay in scanpy
sc.pl.*) - Use CellTypist (celltypist-cell-annotation) instead when speed matters and a pre-trained model matches your tissue; popV is slower because it trains multiple models on your reference
- Use scANVI (scvi-tools-single-cell) instead when you need a single probabilistic deep generative model with formal uncertainty quantification and do not require the ensemble
Prerequisites
- Python packages:
popv>=0.6,scanpy>=1.9,anndata,scvi-tools>=1.0,harmonypy,bbknn,celltypist - Data requirements: Two AnnData objects — a labeled reference (
adata_ref) with cell type labels inobs, and an unlabeled query (adata_query). Both must be from the same species and have overlapping gene sets. Raw counts inadata.X(popV applies its own normalization internally) - Environment: Python 3.9+; GPU recommended for scVI/SCANVI methods (falls back to CPU); 32 GB RAM recommended for >200k reference cells
pip install popv scvi-tools harmonypy bbknn celltypist
Pre-flight Interview
Settle these with the user before writing any analysis code.
decisions:
- id: D1
param: annotationStrategy
kind: required
source: user
ask: "Name cell types from canonical markers by hand over the clusters, transfer them from an annotated reference by ensemble consensus, or do both and compare the two?"
default: "ensemble transfer, then confirm against markers"
- id: D2
param: tissueContext
kind: required
source: user
ask: "Which tissue is this, and in what state - healthy adult, fetal or developmental, diseased, or perturbed?"
default: null
- id: D3
param: referenceAtlas
kind: required
source: literature
depends_on: [D2]
ask: "Which annotated reference matches that tissue AND that state?"
default: null
- id: D4
param: referenceLabelColumn
kind: required
source: data
depends_on: [D3]
ask: "Which column of the reference holds the cell type labels, and at what granularity?"
default: null
- id: D5
param: markerValidation
kind: required
source: user
depends_on: [D1]
ask: "Should the consensus labels be checked against canonical marker expression before they are accepted?"
default: "checked - method agreement measures consistency, not correctness"
- id: D6
param: validationMarkerPanel
kind: required
source: literature
depends_on: [D2, D5]
ask: "Which canonical markers should the consensus types be confirmed against?"
default: null
skip_if: "marker validation declined"
- id: D7
param: consensusThreshold
kind: required
source: user
ask: "How many of the annotation methods must agree before a label is trusted?"
default: "80% agreement"
- id: D8
param: methodSubset
kind: required
source: user
ask: "Run the full method panel, or drop the slow model-based ones?"
default: "all methods"
- id: D9
param: variableGeneCount
kind: optional
source: user
ask: "How many variable genes should the embedding and nearest-neighbour methods use?"
default: 4000
- id: D10
param: trainingEpochs
kind: optional_conditional
source: data
depends_on: [D8]
ask: "Do the model-based methods need longer training for a large or complex query?"
default: "50 unsupervised, 20 semi-supervised"
skip_if: "model-based methods excluded"
- id: D11
param: gpuUse
kind: never_ask
source: data
reason: "Falls back to CPU automatically; affects runtime only"
default: true
D1 is asked even though the user has arrived at an ensemble annotator, because
the alternative is not visible from here: manual marker naming and reference
transfer fail in opposite directions. If the answer is manual only, this skill
is not the tool — see single-cell-annotation-guide.
D5 matters more here than it looks. The agreement score in D7 measures whether the methods concur, not whether they are right — several methods sharing one unsuitable reference agree with each other confidently. Markers are the only outside check. D4 sets the granularity of every downstream comparison: a reference labelled at lineage level cannot produce subtype calls.
Quick Start
Minimal pipeline from labeled reference and unlabeled query to annotated result:
import popv
import scanpy as sc
# Load reference (labeled) and query (unlabeled) AnnData objects
adata_ref = sc.read_h5ad("reference_atlas.h5ad") # adata_ref.obs["cell_type"] exists
adata_query = sc.read_h5ad("query_dataset.h5ad")
# Prepare combined object with popV preprocessing
adata = popv.preprocessing.Process_Query(
adata_ref,
adata_query,
ref_labels_key="cell_type",
ref_batch_key="batch",
query_batch_key="batch",
unknown_celltype_label="unknown",
save_path_trained_models="./popv_models/",
n_epochs_unsupervised=50,
)
# Run all annotation methods
popv.annotation.annotate_data(adata)
# Inspect consensus results for query cells
query_mask = adata.obs["_dataset"] == "query"
print(adata[query_mask].obs[["popv_prediction", "popv_agreement"]].head(10))
Core API
Module 1: Reference and Query Data Setup
Both AnnData objects must share a gene space and have required metadata columns. popV will subset to the intersection of genes automatically.
import anndata as ad
import scanpy as sc
import numpy as np
# Reference: must have cell type labels and (optionally) batch metadata
adata_ref = sc.read_h5ad("reference_atlas.h5ad")
print(f"Reference: {adata_ref.n_obs} cells x {adata_ref.n_vars} genes")
print(f"Cell types: {adata_ref.obs['cell_type'].nunique()} unique labels")
print(f"Reference cell type counts:\n{adata_ref.obs['cell_type'].value_counts().head(10)}")
# Query: no labels required; batch metadata optional
adata_query = sc.read_h5ad("query_dataset.h5ad")
print(f"\nQuery: {adata_query.n_obs} cells x {adata_query.n_vars} genes")
# Check gene overlap (popV will handle subsetting but >70% overlap is recommended)
shared_genes = adata_ref.var_names.intersection(adata_query.var_names)
pct_shared = len(shared_genes) / adata_ref.n_vars
print(f"\nShared genes: {len(shared_genes)} ({pct_shared:.1%} of reference genes)")
if pct_shared < 0.5:
print("WARNING: <50% gene overlap — annotation quality may be reduced")
# Verify required fields before popV setup
assert "cell_type" in adata_ref.obs.columns, "Reference needs cell type labels"
# Add batch column if absent (popV requires it even for single-batch data)
if "batch" not in adata_ref.obs.columns:
adata_ref.obs["batch"] = "ref_batch"
if "batch" not in adata_query.obs.columns:
adata_query.obs["batch"] = "query_batch"
print("Reference obs columns:", adata_ref.obs.columns.tolist())
print("Query obs columns: ", adata_query.obs.columns.tolist())
Module 2: POPV Object Creation (Process_Query)
Process_Query combines reference and query, normalizes counts, selects HVGs, and prepares the joint embedding needed by all annotation methods.
import popv
# Create processed combined AnnData
adata = popv.preprocessing.Process_Query(
adata_ref,
adata_query,
ref_labels_key="cell_type", # obs column with reference labels
ref_batch_key="batch", # obs column with reference batch info
query_batch_key="batch", # obs column with query batch info
unknown_celltype_label="unknown",# label to use for query cells before annotation
save_path_trained_models="./popv_models/", # directory for scVI/SCANVI model checkpoints
n_epochs_unsupervised=50, # scVI training epochs (increase to 100–200 for large datasets)
n_epochs_semisupervised=20, # scANVI fine-tuning epochs
use_gpu=True, # GPU for scVI/SCANVI (falls back to CPU if unavailable)
hvg=4000, # number of highly variable genes to use
)
print(f"Combined object: {adata.n_obs} cells x {adata.n_vars} genes")
print(f"Dataset labels: {adata.obs['_dataset'].value_counts().to_dict()}")
# Expected: {'ref': N_ref, 'query': N_query}
Module 3: Running the Method Ensemble
annotate_data runs all selected methods sequentially and adds per-method label columns plus the consensus to adata.obs.
import popv
# Run annotation with default set of methods
popv.annotation.annotate_data(
adata,
methods=[
"knn_harmony", # KNN on Harmony-corrected embedding
"knn_bbknn", # KNN on BBKNN cross-batch graph
"knn_scvi", # KNN on scVI latent space
"scanvi_popv", # Semi-supervised scANVI label transfer
"celltypist_popv",# CellTypist logistic regression
"rf", # Random Forest on HVG expression
"xgboost", # XGBoost classifier
"svm", # Support Vector Machine
"onclass", # ONCLASS (ontology-guided)
],
)
# Inspect per-method result columns (all end in "_popv")
query_mask = adata.obs["_dataset"] == "query"
popv_cols = adata.obs.filter(like="_popv").columns.tolist()
print(f"Per-method columns: {popv_cols}")
print(adata[query_mask].obs[popv_cols + ["popv_prediction", "popv_agreement"]].head(10))
Module 4: Consensus Results and Agreement Scoring
popv_prediction is the majority-vote consensus; popv_agreement is the fraction of methods that agreed on the winning label.
import pandas as pd
query_mask = adata.obs["_dataset"] == "query"
query_obs = adata[query_mask].obs.copy()
# Consensus label distribution
print("Consensus cell type distribution:")
print(query_obs["popv_prediction"].value_counts().head(15))
# Agreement score statistics
print(f"\npopv_agreement statistics:")
print(query_obs["popv_agreement"].describe())
# agreement = 1.0 → all methods agree; agreement = 0.2 → only 2/10 methods agree
# Cells with high confidence (>80% method agreement)
high_conf = query_obs["popv_agreement"] >= 0.8
print(f"\nHigh-confidence cells (agreement >= 0.8): {high_conf.sum()} ({high_conf.mean():.1%})")
# Cells with low confidence — candidate novel states or annotation gaps
low_conf =
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
118.9kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
hyperframes
87.1kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ai-job-search
72.6kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.5kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
