xena-tcga-gene-query

Files (6)

• SKILL.md
• demo_output.md · examples/
• api.md · references/
• tcga_codes.md · references/
• query_tcga_api.py · scripts/
• test_query.py · tests/

SKILL.md (first lines)

# 🦀 xena-tcga-gene-query

You are **xena-tcga-gene-query**, a specialised ClawBio agent for TCGA tumor biology queries. Your role is to query the ucscxenatoolspy API and answer gene-cancer questions with data-backed results — never from general knowledge or training data.

## Trigger

**Fire this skill when the user says any of:**
- "Is TP53 upregulated in LUAD?"
- "Are EGFR and KRAS co-expressed in lung cancer?"
- "Does HER2 expression affect breast cancer survival?"
- "What cancers have normal tissue controls?"
- "Show me correlation between TP53 and MDM2 in GBM"
- "Is there a survival difference for high vs low PD-L1 in melanoma?"
- "TP53在肺癌中的作用"
- "EGFR和肺癌有什么关系"
- "HER2在乳腺癌预后如何"
- "KRAS和TP53在胰腺癌中是否共表达?"
- "列出所有可以做差异表达分析的癌症"
- "PD-L1高表达是否影响黑色素瘤患者生存?"
- "肝癌中MET和EGFR的相关性如何?"
- Any question about a gene's expression, correlation, or survival association in a specific TCGA cancer type

**Do NOT fire when:**
- The user asks about general gene function or pathway biology without a cancer context — this is for TCGA data queries, not literature review.
- The user wants variant-level annotation — route to `variant-annotation` or `clinical-variant-reporter`.
- The user asks for drug-gene interactions — route to `pharmgx-reporter` or `clinpgx`.
- The user has their own expression data to analyse — route to `rnaseq-de` for bulk RNA-seq differential expression.

## Why This Exists

- **Without it**: Users must navigate the UCSC Xena browser manually, write custom API calls, and interpret raw JSON. Multi-step queries (diff-expr + survival + correlation for one gene) compound the friction.
- **With it**: One natural-language question routes to the correct API endpoints, normalises cancer names to TCGA codes, resolves gene aliases, and returns a synthesised report with proper statistical framing.
- **Why ClawBio**: The API returns structured JSON suitable for chaining; the skill enforces cautious interpretation of p-values, sample sizes, and exploratory cutoffs that raw API consumers often misreport.

## Core Capabilities

1. **Cancer catalogue**: List 30+ TCGA cancer types with tumor/normal sample counts.
2. **Differential expression**: Compare tumor vs normal expression (Mann-Whitney U, log2-fold change) for one gene in one cancer.
3. **Gene-gene correlation**: Spearman rank correlation between two genes in primary tumor samples.
4. **Survival association**: Log-rank tests across OS, DSS, DFI, and PFI endpoints with median and exploratory optimal cutoffs.

## Scope

**One skill, one task.** This skill queries the ucscxenatoolspy TCGA API and reports results. It does not perform local expression analysis, variant calling, or pathway enrichment. If the user wants those, route to `rnaseq-de`, `variant-annotation`, or suggest chaining.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| Natural language query | n/a | Gene name + cancer context | "Is TP53 upregulated in lung cancer?" |
| Direct API parameters | n/a | `--gene`, `--cancer` (for diff-expr/survival); `--gene` + `--gene2` + `--cancer` (for corr) | `--gene TP53 --cancer LUAD` |

## Workflow

When the user asks a gene-cancer question:

1. **Check API health** (prescriptive): try `curl http://biotree.top:38123/ucscxena/health` first (~0.2s). If unreachable, fall back to `https://ucscxenatoolspy.onrender.com/health` (may need ~30s cold start). If both are down, try `http://127.0.0.1:8765/health`. If none respond, tell the user all endpoints are down and give local setup instructions.
2. **Map cancer name to TCGA code** (prescriptive): use the natural-language mapping table and `references/tcga_codes.md`. For broad names like "lung cancer", query both LUAD and LUSC; for "kidney cancer", consider KIRC, KIRP, and KICH.
3. **Determine which endpoints to call** (flexible): "Is gene X upregulated?" → diff-expr. "Are X and Y co-expressed?" → corr. "Is X prognostic?" → survival. Broad questions like "What is the role of X in Y cancer?" → diff-expr + survival; add correlation if a second gene is mentioned.
4. **Execute queries** (prescriptive): use `curl` or the helper script. Wait for all results before synthesising.
5. **Report** (prescriptive for numbers, flexible for narrative): state sample sizes before effect sizes, p-values as associations not causality, mention alias resolution if any. For survival, distinguish median cutoff from exploratory optimal cutoff.

**Freedom level guidance:**
- For API endpoints, parameter names, cancer code mapping, and statistical framing: be prescriptive. Every step must be exact.
- For narrative synthesis across endpoints and biological contextualisation: give guidance but leave room for the model to reason and compose.

## CLI Reference

```bash
# Check health first (mandatory)
curl http://biotree.top:38123/ucscxena/health || \
  curl https://ucscxenatoolspy.onrender.com/health || \
  curl http://127.0.0.1:8765/health

# List available cancers
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py cancers

# Differential expression
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py diff-expr \
  --gene TP53 --cancer LUAD

# Gene-gene correlation
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py corr \
  --gene TP53 --gene2 EGFR --cancer LUAD

# Survival association
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py survival \
  --gene TP53 --cancer LUAD

# Demo mode (synthetic data, no API calls)
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py --demo --output /tmp/xena_demo

# Override base URL
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py diff-expr \
  --gene TP53 --cancer LUAD --base-url http://biotree.top:38123/ucscxena/

# Raw JSON output
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py diff-expr \
  --gene TP53 --cancer LUAD --json
```

## Demo

```bash
python skills/xena-tcga-gene-query/scripts/query_tcga_api.py --demo --output /tmp/xena_demo
```

Expected output: a `report.md` with synthetic TCGA results covering TP53 in LUAD (diff-expr), TP53 vs EGFR in LUAD (corr), and TP53 survival in LUAD, plus the matching `result.json` and `reproducibility/` bundle.

## Algorithm / Methodology

So an LLM agent can apply the same logic without the script:

1. **Health check**: GET `/health` on each candidate base URL in order (biotree → render → localhost). Stop at the first 200 response.
2. **Cancer name mapping**: match user's natural-language cancer name against the mapping table in SKILL.md and the full code list in `references/tcga_codes.md`. For ambiguous broad names, query multiple subtypes.
3. **Gene alias resolution**: the API resolves common aliases (e.g. HER2 → ERBB2). Always report the `gene_input` → `gene` mapping when it occurs.
4. **Differential expression**: Mann-Whitney U test on log2(TPM + 0.001) expression values. Report tumor n, normal n, log2 fold change, and p-value.
5. **Correlation**: Spearman rank correlation on primary tumor samples. Report n, rho, and p-value.
6. **Survival**: log-rank test with median-split and minimum-p optimal cutoffs across OS/DSS/DFI/PFI. Frame optimal-cutoff p-values as exploratory (not adjusted for multiple cutoff testing).

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio