Celltype Specificity Profiler

🎯 Cell-Type Specificity Profiler

You are Cell-Type Specificity Profiler, a specialised ClawBio agent for single-cell analysis. Your role is to quantify, for a single gene, how cell-type-specific its expression is across an annotated atlas.

Trigger

Fire this skill when the user says any of:

• "how cell-type-specific is <gene>?"
• "compute the tau specificity index for <gene>"
• "is <gene> a broad or restricted marker?"
• "which cell types express <gene>, and is its expression bimodal?"
• "expression specificity / bimodality coefficient for my target"
• "profile target specificity (optionally with the trial-success prior)"

Do NOT fire when:

• The user wants to build the embedding / integrate batches / cluster cells → that is scrna-embedding or scrna-orchestrator.
• The user wants differential expression between conditions → that is rnaseq-de / proteomics-de.
• The user wants generic target evidence (GWAS, tractability, known drugs) rather than a single-cell specificity metric → that is omics-target-evidence-mapper / target-validation-scorer.

Design note: This skill consumes an already-annotated matrix and returns one focused metric set. It does not fetch, embed, or cluster.

Why This Exists

Target prioritization, off-target safety triage, and marker-gene discovery all hinge on cell-type specificity. ClawBio's existing single-cell skills (scrna-embedding, omics-target-evidence-mapper) embed and annotate cells, but none return a per-gene specificity metric.

• Without it: Users hand-roll pseudobulk aggregation and ad-hoc specificity scores, with no standard tau / bimodality contract for downstream skills.
• With it: One command returns a clean specificity profile (tau, bimodality_coefficient, ranked cell types) plus a tidy table, ready for target-validation-scorer and clinical-trial-finder.
• Why ClawBio: It is a pure analytic transform — it does not fetch data. Data access stays upstream (scrna-embedding pulls real atlases from CELLxGENE Census); this skill computes metrics on the matrix it is handed, keeping it a clean, chainable citizen rather than a competing data connector, and preserves the reproducibility-bundle contract.

It implements the two complementary single-cell features from The Virtual Biotech (Zhang et al., 2026): cell-type-specific targets progress further in clinical trials with fewer adverse events. The bimodality coefficient is a cross-domain transfer from psychometrics, only moderately correlated with tau (ρ≈0.54), so the two carry complementary signal. The paper's trial-success scoring is an optional layer (--trial-prior), so the core capability is not locked to one preprint's coefficients.

Core Capabilities

1. Tau Specificity Index: Yanai et al. 2005 index over pseudobulk per-cell-type means, in [0, 1] (0 = ubiquitous → 1 = single-cell-type restricted).
2. Bimodality Coefficient: Sarle's BC (bias-corrected skewness/kurtosis) over expressing cells — an "on/off" expression signal.
3. Cell-Type Ranking: Top expressing cell types with mean expression and fraction expressing, plus full per-cell-type stats.
4. Optional Trial Prior: With --trial-prior, attach the published Zhang et al. 2026 odds ratios (labelled, correlational).
5. Reproducibility Bundle: Emit commands.sh, environment.yml, and SHA-256 checksums.

Scope

One skill, one task. This skill computes per-gene cell-type specificity metrics from an annotated matrix and nothing else. It does not fetch data, embed, cluster, annotate, or run differential expression — those belong to other skills.

Input Formats

In the chain, the .h5ad is the output of upstream scrna-embedding, not fetched here.

Workflow

1. Load: Read the .h5ad (or --demo); resolve the cell-type obs column (--cell-type-key, auto-detected from common names).
2. Resolve gene: Map the symbol against the atlas var index (small alias map, e.g. CD276 ↔ B7-H3); fail loudly on a genuinely missing symbol rather than returning zeros. (Prescriptive.)
3. Subset: If --tissue is given, restrict to that label; error if absent. (Prescriptive.)
4. Aggregate & score: Pseudobulk mean expression per cell type → tau; bimodality coefficient over expressing cells; set low_expression when the gene is expressed in <1% of cells. (Prescriptive.)
5. Generate: Write profile.json, per_celltype.csv, and the reproducibility bundle; if --trial-prior, attach the labelled odds ratios. (Prescriptive.)

CLI Reference

# Standard usage — profile a gene against your own atlas
python skills/celltype-specificity-profiler/profiler.py \
  --gene CD276 --atlas lung_atlas.h5ad --output <report_dir>

# Restrict to a tissue and attach the paper's trial-success prior
python skills/celltype-specificity-profiler/profiler.py \
  --gene CD276 --atlas lung_atlas.h5ad --tissue lung --trial-prior --output <report_dir>

# Demo mode (real scanpy-bundled pbmc3k; default gene MS4A1)
python skills/celltype-specificity-profiler/profiler.py --demo --output <report_dir>

# Via ClawBio runner
python clawbio.py run celltype-specificity-profiler --demo

Demo

python clawbio.py run celltype-specificity-profiler --demo

The demo runs on scanpy's bundled, real pbmc3k 10x dataset (2,638 cells, annotated cell types) — no synthetic data. The default gene MS4A1 is a canonical B-cell marker, so it scores as highly cell-type-specific. A reference of this output ships at examples/expected_demo_profile.json.

Algorithm / Methodology

1. Load atlas; resolve gene against var (with alias map) and subset (and --tissue if given).
2. Aggregate to pseudobulk mean expression per cell type (expects log-normalized, non-negative input).
3. tau = Σᵢ(1 − xᵢ/x_max) / (n − 1) over n cell types; xᵢ = mean expression in cell type i. NaN for n < 2. Following Zhang et al. 2026, cell types with fewer than 20 cells are excluded from the tau computation (their pseudobulk means are unreliable and, via the max-normalization, can distort tau); they remain in per_celltype_stats, and the profile records n_cell_types_used_for_tau / n_cell_types_excluded_small.
4. Bimodality coefficient = (g1² + 1) / (g2 + 3·(n−1)²/((n−2)(n−3))), g1/g2 = bias-corrected sample skewness/excess kurtosis over expressing cells. NaN for n < 4 or zero variance.
5. Rank cell types by mean expression; if --trial-prior, label tau against tau_threshold and attach the published ORs.

Key thresholds / parameters:

• TAU_THRESHOLD = 0.69 — tau > 0.69 → "cell-type-specific". This is not a universal constant: Zhang et al. 2026 (Extended Methods) derived it as the midpoint of a K-means (k=2) split of their trial-level tau distribution, so it is cohort-specific. Treat continuous tau as the real output and recalibrate the cut on your own distribution if you binarize.
• MIN_CELLS_FOR_TAU = 20 — cell types with <20 cells are dropped from the tau computation (source: Zhang et al. 2026).
• LOW_EXPRESSION_FRACTION = 0.01 — gene expressed in <1% of cells flags an unreliable BC.
• Trial-prior odds ratios: phase I→II OR 1.27 (95% CI 1.22–1.33), primary-endpoint OR 1.11 (95% CI 1.09–1.14) — verified verbatim against Zhang et al. 2026 Results.

Example Queries

• "How cell-type-specific is CD276 in this lung atlas?"
• "Compute the tau specificity index for MS4A1"
• "Which cell types express B7-H3, and is its expression bimodal?"
• "Profile this gene's specificity and give me the trial-success prior"

Example Output

profile.json (demo, --demo --trial-prior, abbreviated):

{
  "skill": "celltype-specificity-profiler",
  "gene": "MS4A1",
  "atlas": "pbmc3k (10x, real; scanpy bundled)",
  "tau": 0.956,
  "tau_threshold": 0.69,
  "tau_threshold_note": "cohort-specific K-means(k=2) midpoint of the trial-level tau distribution in Zhang et al. 2026 (tau=0.69); an interpretive default, not a universal cutoff",
  "n_cell_types_used_for_tau": 7,
  "n_cell_types_excluded_small": 1,
  "bimodality_coefficient": 0.4936,
  "interpretation": "cell-type-specific (tau > 0.69)",
  "low_expression": false,
  "top_cell_types": [
    {"cell_type": "B cells", "mean_expr": 0.993, "pct_expressing": 0.8596},
    {"cell_type": "FCGR3A+ Monocytes", "mean_expr": 0.0601, "pct_expressing": 0.0867}
  ],
  "trial_prior": {
    "note": "Odds ratios from Zhang et al. 2026 (bioRxiv 10.64898/2026.02.23.707551)",
    "phase_I_to_II_OR": 1.27,
    "primary_endpoint_OR": 1.11,
    "lower_AE_rate": true
  }
}

per_celltype.csv:

cell_type,mean_expr,median_expr,pct_expressing,n_cells
B cells,0.993,1.0986,0.8596,342
FCGR3A+ Monocytes,0.0601,0.0,0.0867,150

ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses.

Output Structure

output_directory/
├── profile.json              # specificity contract: tau, bimodality, ranked + per-cell-type stats, optional trial_prior
├── per_celltype.csv          # tidy per-cell-type table
└── reproducibility/
    ├── commands.sh            # exact command to reproduce
    ├── environment.yml        # pip/conda environment snapshot
    └── checksums.sha256       # SHA-256 of the outputs

Dependencies

Required:

• scanpy; load atlas / bundled demo dataset
• anndata >= 0.9; .h5ad I/O
• numpy >= 1.23; tau / bimodality math
• scipy >= 1.9; distribution statistics
• pandas >= 2.0; tabular output

No network access required in --demo mode after pbmc3k is cached on first fetch.