/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", consi