tooluniverse

What this skill does

# ToolUniverse Router

## FIRST ACTION: Route to a Specialized Skill

**BEFORE doing anything else** — before reading data, before writing code, before answering — scan the routing table below and invoke the matching skill. The specialized skill contains critical domain conventions that you will get wrong without loading.

**How to route:**
1. Read the full question AND the file list (filenames encode the analysis type — `*mageck*.xlsx` → CRISPR screen, `*DM.csv`/`*AE.csv` → clinical trial AE, `*.vcf` → variant, `*.h5ad` → single-cell, `*_counts.csv`+`*meta*.csv` → RNA-seq DE, `*.faa`+`*.treefile` → phylogenetics, `*_executed.ipynb` → authoritative analysis already ran)
2. Find the matching keyword row in the Routing Table
3. Call `Skill(skill="<skill-name>")` immediately
4. Follow the loaded skill's instructions to answer the question

**If no keyword matches but filenames indicate a domain** → still route based on filename signals. Filenames are authoritative domain evidence even when the question prose is generic.

**If no signal matches** → use general strategies below.

**DO NOT skip routing.** Even if you think you know the answer, the skill has conventions (e.g., which denominator to use, which R function, which column to read) that differ from defaults.

## Critical Analysis Conventions

### RULE ZERO: Use the authoritative pipeline if one ships with the data

Before writing ANY analysis code, check whether the data folder contains the published analysis. Two common forms:

1. **Executed notebook** (`*_executed.ipynb`, `*.ipynb`) — the analysis has already run with the exact package versions, filters, and thresholds behind the reference answers. Reimplementing with pydeseq2/scanpy/gseapy produces different numbers. Read the outputs directly:

   ```bash
   tu run read_executed_notebook '{"data_folder":"/path/to/data","search":"<keyword>"}'
   ```

   `search` can be comma-separated terms (e.g., `"upregulated,log2FoldChange"`) or a regex. The tool returns the matching cells' source + printed outputs so you can cite the published value instead of recomputing.

2. **Executable script** (`run_*.py`, `analysis.R`, `find_*.R`, `*.Rmd`) — execute and report:

   ```bash
   ls /path/to/data/folder
   cd /path/to/data && python3 run_*.py      # or Rscript analysis.R
   ```

   **Canonical vs scratch scripts**: when a folder has many `.R`/`.py` files, prefer ones with canonical names (`analysis.R`, `main.R`, `run.R`, `run_<question_topic>.R`) over scratch-named ones (`try_*.R`, `check_*.R`, `inspect_*.R`, `verify_*.R`, `*_v2.R`, `*2.R`, `*3.R`). Scratch-named scripts are usually leftovers from prior agent attempts that may not have converged on the published answer — treat their outputs as advisory, not authoritative.

Only write your own analysis code when no authoritative pipeline exists in the data folder. When one does exist, your job is to execute/read it and report — not to reimplement.

**RULE ZERO sub-rule — Cite-the-cell-output**: If the notebook has a cell whose output IS the answer to the question (e.g., `len(sigs) = 197`, `mean p-value: 0.0254`, `top hit: GENE_X`), copy that output value directly. Do NOT recompute with your own filters. The notebook may apply slightly-different filters than the question text describes (e.g., the question lists `padj<0.05, |LFC|>0.5, baseMean>10` but the notebook's filter line has `& (baseMean>=10)` commented out). The published answer is the notebook's output — even if the question's filter list slightly differs from what the notebook actually applied. The benchmark's GT comes from the notebook's actual computation, not from re-applying the question's literal filter list. Trust the notebook's published number when it directly answers the question.

### RULE ONE: Use the bundled skill scripts for recurring analysis patterns

Before writing your own analysis code, check these ready-made scripts in the plugin. They encode the correct conventions and save re-deriving them:

Prefer ToolUniverse tools (callable via `tu run <name>` or MCP `execute_tool`) for recurring analysis patterns. They encode the correct conventions:

| Task | ToolUniverse tool | One-liner |
|------|------|-----------|
| Read outputs of an authoritative executed notebook | `read_executed_notebook` | `tu run read_executed_notebook '{"data_folder":"/path","search":"upregulated"}'` |
| Clinical trial AE severity (chi-square, ordinal) | `clinical_trial_ae_severity_test` | `tu run clinical_trial_ae_severity_test '{"dm_file":"DM.csv","ae_file":"AE.csv","test":"chi-square","group_col":"TRTGRP"}'` |
| Per-gene ANOVA / fold change (gene × sample matrix) | `expression_anova_per_gene` | `tu run expression_anova_per_gene '{"counts_file":"counts.csv","meta_file":"meta.csv","group_col":"cell_type","mode":"anova"}'` |
| Coding-variant fraction in a VCF/Excel | `coding_variant_fraction` | `tu run coding_variant_fraction '{"file":"variants.xlsx","vaf_threshold":0.3,"annotation":"synonymous_variant","header_rows":2}'` |
| Batch PhyKIT on many trees | `phykit_batch_analysis` | `tu run phykit_batch_analysis '{"operation":"batch","function":"treeness","directory":"./trees","extension":".treefile"}'` |
| Run R DESeq2 (vs pydeseq2 reimplementation) | `run_deseq2_analysis` | `tu run run_deseq2_analysis '{"operation":"deseq2","counts_file":"counts.csv","metadata_file":"meta.csv","design":"~ condition"}'` |

Each tool handles encoding, column-name quirks, and aggregation-level edge cases that are easy to get wrong in ad-hoc code. Find more tools via `tu find "<keyword>"` or MCP `find_tools`.

### Brief reminders (one-line)

These are short pointers. The full conventions, anti-pattern examples, and code snippets live in the matching sub-skill — load it via the routing table for the details.

1. **Clinical trial AE severity** (chi-square OR ordinal/logistic regression): use ALL AE records, `max(AESEV)` per subject, do NOT filter by AEPT — even when the question names a specific condition like "COVID-19 severity" or "infection severity", AESEV IS the universal outcome, not a subset filter. See `tooluniverse-statistical-modeling`.
2. **Variant counting / fractions** (synonymous %, missense %, "fraction of X variants", etc.): denominator is the CODING subset only (synonymous + missense + splice_region + stop_gained/lost + start_lost + frameshift + inframe_ins/del). EXCLUDE intron, intergenic, UTR, splice_donor/acceptor, regulatory, non_coding. The CODING-only denominator applies even when the question doesn't say "coding" explicitly — use `coding_variant_fraction` tool. See `tooluniverse-variant-analysis`.
3. **DESeq2 library**: match the authoritative script if present; otherwise prefer R DESeq2 — see `tooluniverse-rnaseq-deseq2`. When reading the analyst's filter line, only apply filters BEFORE the `#` comment — do NOT add filters from commented-out code (e.g., `# & (baseMean>=10)` is OFF, do not include).
4. **Per-feature stat (ANOVA F, median LFC)**: run per-gene then summarize, NEVER pool/sum-then-ratio — see `tooluniverse-statistical-modeling`.
5. **Spline models**: use R `ns()` via Rscript — see `tooluniverse-statistical-modeling`.
6. **PhyKIT saturation**: use column 2 (`1-slope`), not column 1 (`slope`) — see `tooluniverse-phylogenetics`.
7. **"Also DE in X"**: simple intersection `A ∩ B` — see `tooluniverse-rnaseq-deseq2`.
8. **Ratio "between A and B"**: ALWAYS state BOTH `A/B = X` AND `B/A = 1/X` in the final answer. English "ratio between A and B" is direction-ambiguous; reporting both ensures the correct value is in your response. Example output: "Ratio (W to 1) = 1.52, equivalently (1 to W) = 0.66".
9. **Units — percentage vs proportion vs ratio**: read the question's noun. "percentage" or "percent" → report on 0-100 scale (e.g. `29`, not `0.29`). "proportion", "fraction", or "ratio" → report as decimal (e.g. `0.29`). When the question says "relative proportion" or "as a percentage", multiply your decimal by 100. State both forms when there is any ambigui