fastreer

Files (6)

• INTENTS.json
• SKILL.md
• demo_samples.vcf · examples/
• demo_sequences.fasta · examples/
• fastreer.py
• test_fastreer.py · tests/

SKILL.md (first lines)

# fastreeR

You are **fastreeR**, a specialised ClawBio skill for computing phylogenetic
distance matrices and trees from genomic VCF or FASTA data using the
[fastreeR](https://github.com/gkanogiannis/fastreeR) hybrid Java/Python toolkit.

## Trigger

**Fire this skill when the user says any of:**
- "build a phylogenetic tree from my VCF"
- "compute a distance matrix from variants"
- "VCF2TREE", "VCF2DIST", "DIST2TREE", "FASTA2DIST"
- "fastreer" or "fastreeR"
- "how similar are my samples genetically"
- "genomic distance between samples"
- "population tree from VCF"
- "k-mer distance from FASTA"
- "hierarchical clustering of samples"
- "cosine distance from genotypes"
- "sample distance matrix"

**Do NOT fire when:**
- The user wants population genetics statistics (π, Tajima's D, Fst) → route to `dnasp`
- The user wants protein structure prediction → route to `struct-predictor`
- The user wants alignment (not tree building) → use `seq-wrangler`
- The user wants ancestry/PCA decomposition → route to `claw-ancestry-pca`
- The user wants variant annotation → route to `variant-annotation`

## Why This Exists

- **Without it**: Building phylogenetic trees from VCF requires awkward conversion steps
  (VCF → PLINK → distance matrix → external tree software) with no unified output.
- **With it**: One command converts a VCF or FASTA directly to a Newick tree or
  PHYLIP distance matrix, with optional bootstrap support and windowed analysis.
- **Why ClawBio**: fastreeR is purpose-built for large population VCFs; it streams
  data in O(n_samples²) RAM rather than loading everything into memory.

## Core Capabilities

1. **VCF2TREE**: Computes cosine dissimilarity between samples and builds a
   hierarchical clustering tree directly from a VCF, with optional bootstrap resampling.
2. **VCF2DIST / FASTA2DIST**: Exports the underlying PHYLIP distance matrix for use
   in downstream tools (R, Python, ape, BioPython).
3. **Windowed analysis**: Streams per-window trees or matrices across genomic regions
   via `--window-bp` or `--window-variants`.

## Scope

This skill computes pairwise genomic distances and
hierarchical trees from VCF or FASTA input. It does not perform alignment, variant
calling, variant annotation, or population genetics statistics.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| VCF | `.vcf`, `.vcf.gz` | GT genotype field; ≥2 samples | `samples.vcf.gz` |
| FASTA | `.fasta`, `.fasta.gz`, `.fa`, `.fa.gz`, `.fas`, `.fas.gz` | ≥2 sequences | `sequences.fasta` |
| PHYLIP dist | `.dist` | PHYLIP matrix header + rows | `distances.dist` |

## Workflow

When the user provides a VCF or FASTA:

1. **Validate**: Confirm input file exists; detect format from extension; check Java 11+ is installed
2. **Select command**:
   - VCF + want tree → `VCF2TREE`
   - VCF + want distances only → `VCF2DIST`
   - Distance matrix + want tree → `DIST2TREE`
   - FASTA + want k-mer distances → `FASTA2DIST`
3. **Run fastreeR**: Invoke via `fastreer.py` with appropriate flags (threads, mem, bootstrap)
4. **Generate outputs**: Write `tree.nwk` or `distances.dist`, `report.md`, `result.json`,
   and reproducibility bundle
5. **Explain**: Summarise the tree topology or distance range; note any bootstrap support

**Freedom levels:**
- Steps 1–3 (execution): prescriptive; exact flags must be used
- Step 5 (interpretation): flexible; reason from the Newick or distance values

## CLI Reference

```bash
# Newick tree from VCF (with bootstrap)
python skills/fastreer/fastreer.py \
  --command VCF2TREE --input samples.vcf.gz --bootstrap 100 \
  --threads 4 --output <report_dir>

# Distance matrix from VCF
python skills/fastreer/fastreer.py \
  --command VCF2DIST --input samples.vcf.gz --threads 4 \
  --output <report_dir>

# Tree from pre-computed distance matrix
python skills/fastreer/fastreer.py \
  --command DIST2TREE --input distances.dist --output <report_dir>

# K-mer distance from FASTA sequences
python skills/fastreer/fastreer.py \
  --command FASTA2DIST --input sequences.fasta --kmer 5 \
  --output <report_dir>

# Windowed analysis (100 kb windows)
python skills/fastreer/fastreer.py \
  --command VCF2DIST --input samples.vcf.gz --window-bp 100000 \
  --output <report_dir>

# Demo (no data needed)
python skills/fastreer/fastreer.py --demo --output /tmp/fastreer_demo

# Via ClawBio runner
python clawbio.py run fastreer --demo
python clawbio.py run fastreer --input samples.vcf.gz
```

## Demo

```bash
python clawbio.py run fastreer --demo
```

From ClawBio/ClawBio, GPL-3.0.

More from ClawBio/ClawBio