Xena Tcga Gene Query

---
name: xena-tcga-gene-query
description: >-
  Query TCGA tumor biology through the ucscxenatoolspy API. Supports
  tumor-vs-normal differential expression, gene-gene correlation, survival
  association, and cancer catalogue browsing across 30+ TCGA cancer types.
license: MIT
metadata:
  version: "0.1.0"
  author: lishensuo
  domain: cancer-genomics
  tags:
    - tcga
    - gene-expression
    - survival-analysis
    - differential-expression
    - co-expression
    - cancer
    - tumor-biology
  inputs:
    - name: gene
      type: string
      format:
        - text
      description: HGNC gene symbol (e.g. TP53, EGFR, BRCA1). Aliases are resolved by the API.
      required: true
    - name: cancer
      type: string
      format:
        - text
      description: TCGA cancer abbreviation (e.g. LUAD, BRCA, GBM). See references/tcga_codes.md for the complete mapping.
      required: false
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Markdown report with query results, sample sizes, effect sizes, and interpretation notes
    - name: result
      type: file
      format:
        - json
      description: Machine-readable API response for downstream chaining
    - name: reproducibility
      type: directory
      description: Directory with commands.sh and run.json describing the exact API calls
  dependencies:
    python: ">=3.10"
  demo_data:
    - path: examples/demo_output.md
      description: Example output from running diff-expr, corr, and survival queries via demo mode
  endpoints:
    cli: python skills/xena-tcga-gene-query/scripts/query_tcga_api.py --task {task} --gene {gene} --cancer {cancer} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🦀"
    homepage: https://github.com/lishensuo/UCSCXenaToolsPy
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: ""
    trigger_keywords:
      - TCGA
      - tumor vs normal
      - differential expression
      - gene expression cancer
      - survival analysis
      - co-expression
      - prognosis
      - cancer biomarker
      - 肿瘤
      - 肺癌
      - 乳腺癌
      - 差异表达
      - 生存分析
      - 预后
---

# 🦀 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).

**Key thresholds / parameters**:
- Minimum normal samples: 3 (API returns 400 if insufficient; source: API design choice for statistical reliability).
- Expression scale: log2(TPM + 0.001) (source: UCSC Xena / Toil recompute).
- Survival endpoints: OS, DSS, DFI, PFI (source: TCGA clinical annotations).
- Optimal cutoff: minimum-p scan (source: exploratory; NOT multiple-testing corrected).

## Example Queries

- "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?"
- "TP53在肺癌中的作用是什么?"
- "列出所有可以做差异表达分析的癌症"

## Example Output

> **Demo-only output.** The report below is a synthetic example generated by `--demo`
> mode for format illustration only. The numbers are hardcoded and should not be
> interpreted as real TCGA findings.

```markdown
# Xena TCGA Gene Query Report

**Date**: 2026-07-06
**API base URL**: http://biotree.top:38123/ucscxena/
**Mode**: demo (synthetic data — no live API calls)
**Queries**: diff-expr (TP53 in LUAD), corr (TP53 vs EGFR in LUAD), survival (TP53 in LUAD)

---

## 1. Differential Expression — TP53 in LUAD

**Gene**: TP53
**Cancer**: LUAD (Lung Adenocarcinoma)
**Tumor samples**: n = 515
**Normal samples**: n = 59

| Metric | Value |
|--------|-------|
| Tumor mean (log2) | 5.12 |
| Normal mean (log2) | 4.87 |
| log2 Fold Change | 0.25 |
| Mann-Whitney p | 0.0034 |

**Interpretation**: TP53 expression is modestly higher in LUAD tumor vs normal tissue
(p = 0.0034). The difference (~0.25 log2 units) is statistically significant but
biologically small.

---

## 2. Gene-Gene Correlation — TP53 vs EGFR in LUAD

**Genes**: TP53, EGFR
**Cancer**: LUAD (Lung Adenocarcinoma)
**Primary tumor samples**: n = 508

| Metric | Value |
|--------|-------|
| Spearman r | 0.18 |
| p-value | 4.2e-05 |

**Interpretation**: TP53 and EGFR show a weak positive rank correlation in LUAD primary
tumors (Spearman r = 0.18, p = 4.2e-05). The correlation is statistically detectable
but explains little variance.

---

## 3. Survival Association — TP53 in LUAD

**Gene**: TP53
**Cancer**: LUAD (Lung Adenocarcinoma)

| Endpoint | n (total) | Events | Median-cutoff p | Optimal-cutoff p (exploratory) |
|----------|-----------|--------|-----------------|-------------------------------|
| OS | 504 | 189 | 0.042 | 0.0081 |
| DSS | 494 | 142 | 0.11 | 0.021 |
| DFI | 312 | 84 | 0.67 | 0.13 |
| PFI | 504 | 218 | 0.031 | 0.0056 |

Optimal-cutoff results are exploratory and not adjusted for multiple cutoff testing.

**Interpretation**: Higher TP53 expression is associated with worse overall survival (OS)
and progression-free interval (PFI) at the median split (OS p = 0.042, PFI p = 0.031).
Disease-specific survival (DSS) and disease-free interval (DFI) do not reach
significance at the median cutoff. These are statistical associations; they do not
prove TP53 is a causal driver of outcome.

---

*ClawBio is a research and educational tool. It is not a medical device and does not
provide clinical diagnoses. Consult a healthcare professional before making any
medical decisions.*
```

## Output Structure

```
<output_dir>/
├── report.md              # Primary markdown report
├── result.json            # Machine-readable results (API responses)
└── reproducibility/
    ├── commands.sh        # Exact curl commands to reproduce
    └── run.json           # Run metadata (timestamps, base URL, API version)
```

## Dependencies

**Required**:
- Python >= 3.10 (stdlib only; no external packages required).

**Optional**:
- None. The helper script uses only `urllib` from stdlib for maximum portability.

## Gotchas

- **The model will want to answer gene-cancer questions from training data instead of calling the API.** Do not. This skill exists precisely because training-data answers are often outdated, lack sample sizes, and miss alias resolution. Always call the API and report what the data shows — even if it contradicts "common knowledge."
- **The model will treat p-values as proof of biological importance.** Do not. A small p-value with a tiny effect size (e.g. log2FC = 0.1 with n = 500) is a precise estimate of a negligible difference, not a "significant finding." Always report sample sizes and effect sizes alongside p-values.
- **The model will report optimal-cutoff survival p-values without caveats.** Do not. The optimal cutoff is a minimum-p scan across candidate thresholds — p-values are not adjusted for multiple cutoff testing. Frame them as exploratory and hypothesis-generating only.
- **The model will map broad cancer names to a single TCGA code without checking.** "Lung cancer" should map to both LUAD and LUSC unless the user specifies a subtype. "Kidney cancer" maps to KIRC, KIRP, and KICH. When in doubt, query multiple codes and explain the heterogeneity.
- **The model will skip the health check and go straight to queries.** Do not. Always run the health check first in the order: biotree (primary, fast) → render.com (fallback, cold-start) → localhost (last resort). Remember which URL worked and use it for all subsequent queries.

## Safety

- **Author-hosted API service**: This skill sends gene symbols and cancer type codes to an author-hosted UCSCXenaToolsPy API endpoint (default: `http://biotree.top:38123/ucscxena/`, fallback: `https://ucscxenatoolspy.onrender.com`). The service queries public TCGA/UCSC Xena-derived datasets and computes summary statistics (fold change, p-values, survival associations) server-side. No patient-level input data are uploaded by the user, but returned numerical results depend on the hosted service implementation and dataset version.
- **Disclaimer**: every `report.md` includes the standard ClawBio research-tool disclaimer.
- **Audit trail**: every run writes `reproducibility/commands.sh` with the exact curl commands and `reproducibility/run.json` with metadata including the mode (demo vs live).
- **No hallucinated science**: all gene-cancer associations come from the API response, not from the model's training data. P-value thresholds and effect-size framing follow this SKILL.md.

## Agent Boundary

The agent (LLM) maps user intent to API endpoints, normalises cancer names to TCGA codes, synthesises multi-endpoint results into a coherent narrative, and adds cautious biological interpretation. The skill (Python helper script) handles HTTP transport, JSON formatting, and summary computation. The agent must NOT fabricate gene-cancer associations from training data, override API results, or report p-values without sample sizes and caveats.

## Integration with Bio Orchestrator

**Trigger conditions**: the orchestrator routes here when the query mentions a gene symbol alongside a cancer type or TCGA keyword, or when the user asks about tumor-vs-normal expression, gene-gene correlation in cancer, or survival/prognosis.

**Chaining partners**:
- `pubmed-summariser`: take gene + cancer pair from this skill's output and find recent literature for biological context.
- `rnaseq-de`: if the user has their own expression data, route there instead for local differential expression.
- `variant-annotation`: if the user asks about specific mutations in the queried gene, chain to variant annotation for ClinVar/gnomAD data.

> Output is JSON with stable keys (`gene`, `cancer`, `log2_fold_change`, `p_value`, etc.), so it composes cleanly into pipelines.

## Maintenance

- **Review cadence**: re-evaluate quarterly or when the upstream API (`ucscxenatoolspy`) releases a new version.
- **Staleness signals**: API endpoint URLs change, new TCGA cancer types are added, or the expression data is recomputed against a newer reference.
- **Deprecation**: archive to `skills/_deprecated/xena-tcga-gene-query/` if the ucscxenatoolspy API is shut down or a more comprehensive TCGA query skill replaces it.

## Natural Language Cancer Mapping

When users use common Chinese or broad cancer names, map them to TCGA cancer codes before querying:

| User term | English | TCGA code(s) |
|-----------|---------|-------------|
| 肺癌 / lung cancer | Lung cancer | LUAD, LUSC |
| 肺腺癌 / lung adenocarcinoma | Lung adenocarcinoma | LUAD |
| 肺鳞癌 / lung squamous | Lung squamous cell carcinoma | LUSC |
| 乳腺癌 / breast cancer | Breast cancer | BRCA |
| 结肠癌 / colon cancer | Colon cancer | COAD |
| 结直肠癌 / colorectal cancer | Colorectal cancer | COAD, READ |
| 肝癌 / liver cancer | Liver cancer | LIHC |
| 胃癌 / gastric cancer | Gastric cancer | STAD |
| 前列腺癌 / prostate cancer | Prostate cancer | PRAD |
| 胰腺癌 / pancreatic cancer | Pancreatic cancer | PAAD |
| 胶质母细胞瘤 / glioblastoma | Glioblastoma | GBM |
| 低级别胶质瘤 / low-grade glioma | Lower-grade glioma | LGG |
| 肾癌 / kidney cancer | Kidney cancer | KIRC, KIRP, KICH |
| 黑色素瘤 / melanoma | Melanoma | SKCM |
| 卵巢癌 / ovarian cancer | Ovarian cancer | OV |

For complete TCGA abbreviations, read `references/tcga_codes.md` when the cancer name is uncommon, ambiguous, or not covered above.

## Citations

- [UCSC Xena](https://xena.ucsc.edu/) — TCGA expression data and clinical annotations.
- [ucscxenatoolspy](https://github.com/lishensuo/UCSCXenaToolsPy) — Python toolkit and API for UCSC Xena data access.
- [Toil recompute](https://toil.xenahubs.net/) — uniformly reprocessed TCGA/TARGET/GTEx expression compendium.
- [TCGA](https://www.cancer.gov/tcga) — The Cancer Genome Atlas, source of the underlying data.