SkillAgentSearch skills...

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-annotation

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

91/100

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
11/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
popv-cell-annotation (this skill)by jaechang-hits913673mo agoSKILL.md
taste-skillby Leonxlnx100118.9k11d agoCLAUDE.md
hyperframesby heygen-com10087.1ktodayCLAUDE.md
ai-job-searchby ai-job-search-dev10072.6ktodayCLAUDE.md
claude-howtoby luongnv8910047.5k5d agoCLAUDE.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.

name: "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_agreement score)
  • 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 in obs, and an unlabeled query (adata_query). Both must be from the same species and have overlapping gene sets. Raw counts in adata.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

View on GitHub
GitHub Stars367
CategoryDevelopment
Updated2mo ago
Forks36

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium