Fastreer

fastreeR

You are fastreeR, a specialised ClawBio skill for computing phylogenetic distance matrices and trees from genomic VCF or FASTA data using the 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

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

# 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

python clawbio.py run fastreer --demo

Expected output: VCF2TREE run on a synthetic 5-sample / 20-SNP VCF. Produces a Newick tree (tree.nwk), report.md with sample list and interpretation, and a reproducibility bundle. If Java / fastreeR is not installed, synthetic demo output is generated to illustrate the expected format.

Algorithm / Methodology

VCF2TREE / VCF2DIST (cosine dissimilarity from genotypes):

1. For each sample pair (i, j), compute the cosine dissimilarity over all biallelic variant sites as: d(i,j) = 1 - cosine_similarity(gt_vector_i, gt_vector_j) where genotypes are encoded as allele dosages (0/0→0, 0/1→1, 1/1→2).
2. Build an N×N PHYLIP distance matrix; emit to .dist file.
3. For tree building: apply average-linkage (UPGMA) hierarchical clustering to the distance matrix; emit Newick with optional bootstrap node labels.

FASTA2DIST (D2S k-mer distance):

1. For each sequence, compute k-mer frequency vectors (default k=4).
2. Apply the D2S statistic (Reinert et al. 2009) to compute pairwise distances.
3. Emit PHYLIP matrix.

Key parameters:

• --threads: parallelism for distance computation (default: 1)
• --mem: JVM heap in MB (default: 256; increase for >500 samples)
• --bootstrap: streaming bootstrap replicates from VCF (VCF2TREE only)
• --kmer: k-mer size for FASTA2DIST (default: 4; range 3–8 typical)

Example Queries

• "Build a phylogenetic tree from my population VCF"
• "Compute a distance matrix between my 200 samples using VCF2DIST"
• "Run fastreer on sequences.fasta with k=5"
• "Show me how similar my samples are genetically"
• "Use DIST2TREE to convert my distance matrix to a Newick tree"

Example Output

# fastreeR Report

**Command**: `VCF2TREE`
**Input**: `demo_samples.vcf` (5 samples, 20 variants)
**Date**: 2026-05-11

## Samples (5)
  - SAMPLE1
  - SAMPLE2
  - SAMPLE3
  - SAMPLE4
  - SAMPLE5

## Phylogenetic Tree

**Output format**: Newick
**File**: `tree.nwk`

((SAMPLE1:0.120,SAMPLE2:0.098):0.045,
 (SAMPLE3:0.110,(SAMPLE4:0.087,SAMPLE5:0.132):0.062):0.038);

SAMPLE1 and SAMPLE2 cluster together (distance 0.12), suggesting greater
genomic similarity relative to SAMPLE3–5. SAMPLE4 and SAMPLE5 are the
second closest pair (distance 0.087).

Output Structure

output_directory/
├── report.md              # Summary: samples, tree/matrix preview, interpretation
├── result.json            # Machine-readable: command, samples, paths, metadata
├── tree.nwk               # Newick tree (VCF2TREE / DIST2TREE)
├── distances.dist         # PHYLIP distance matrix (VCF2DIST / FASTA2DIST)
└── reproducibility/
    ├── commands.sh        # Portable replay command ($CLAWBIO_ROOT / $OUTPUT_DIR)
    ├── environment.yml    # Conda recipe (fastreer + openjdk)
    ├── environment.txt    # Java version + pip fastreer version
    └── checksums.sha256   # SHA-256 of every output file

Dependencies

Required:

• fastreer >= 2.2.0 (install with pip install fastreer)
• Java 11+: the Python package wraps a Java backend; install via sudo apt install default-jre (Linux) or brew install openjdk@17 (macOS)

Optional:

• matplotlib, for tree/heatmap visualisation in future versions