/celltype-specificity-profiler

name: celltype-specificity-profiler
description: Given a gene and a single-cell atlas, compute how cell-type-specific its expression is — the tau specificity index, Sarle's expression bimodality coefficient, and the cell types that drive the signal; a pure analytic transform that chains downstream of scrna-embedding.
license: MIT
metadata:
  version: "0.1.0"
  author: Jacky Siu
  domain: single-cell
  tags:
    - scrna
    - single-cell
    - specificity
    - tau
    - bimodality
    - target-prioritization
    - marker-gene
    - h5ad
  inputs:
    - name: atlas
      type: file
      format:
        - h5ad
      description: Annotated single-cell expression matrix (log-normalized X; cell-type labels in an obs column). In the chain, this is the output of upstream scrna-embedding.
      required: false
    - name: gene
      type: string
      format:
        - txt
      description: HGNC gene symbol to profile (e.g. CD276). Required unless --demo.
      required: false
  outputs:
    - name: profile
      type: file
      format:
        - json
      description: Specificity profile — tau, bimodality coefficient, ranked cell types, per-cell-type stats, optional trial prior.
    - name: per_celltype
      type: file
      format:
        - csv
      description: Tidy per-cell-type expression table for plotting.
  dependencies:
    python: ">=3.10"
    packages:
      - scanpy
      - anndata
      - numpy>=1.23
      - scipy>=1.9
      - pandas>=2.0
  demo_data:
    - path: examples/expected_demo_profile.json
      description: Reference output of `--demo` on scanpy's bundled real pbmc3k dataset (gene MS4A1).
  endpoints:
    cli: python skills/celltype-specificity-profiler/profiler.py --gene {gene} --atlas {atlas} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🎯"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: uv
        package: scanpy
      - kind: uv
        package: anndata
      - kind: uv
        package: numpy
      - kind: uv
        package: scipy
      - kind: uv
        package: pandas
    trigger_keywords:
      - cell-type specificity
      - cell type specificity
      - specificity index
      - tau index
      - tau specificity
      - bimodality
      - bimodality coefficient
      - cell-type-specific expression
      - expression specificity
      - marker gene specificity

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