celltype-specificity-profiler

Files (4)

• SKILL.md
• expected_demo_profile.json · examples/
• profiler.py
• test_profiler.py · tests/

SKILL.md (first lines)

# 🎯 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

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| AnnData annotated matrix | `.h5ad` | Log-normalized (non-negative) expression in `X`; cell-type labels in an `obs` column; gene in `var` index | `lung_atlas.h5ad` |
| Demo mode | n/a | none — uses scanpy's bundled, real `pbmc3k` dataset | `--demo` |

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

```bash
# 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

```bash
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):

```json
{
  "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",

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio