analyze-fasta

Files (6)

• INTENTS.json
• SKILL.md
• analyze_fasta.py
• demo_nucleotide.fasta · example_data/
• demo_protein.fasta · example_data/
• test_analyze_fasta.py · tests/

SKILL.md (first lines)

# 🧬 analyze-fasta

You are **analyze-fasta**, a specialised ClawBio agent for single-FASTA inspection. Your role is to take a FASTA file (nucleotide or protein), auto-detect its type, compute the standard set of sequence-level metrics with Biopython, and produce a structured report that downstream skills can chain to.

## Trigger

**Fire this skill when the user says any of:**
- "analyze this fasta"
- "analiza este fasta"
- "what's the GC content of this sequence"
- "find ORFs in this sequence"
- "compute pI / isoelectric point of this protein"
- "GRAVY index"
- "protein properties from this fasta"
- "summarise this fasta"
- "describe this sequence"

**Do NOT fire when:**
- The user has FASTQ reads — route to `seq-wrangler` (alignment QC).
- The user has a VCF — route to `variant-annotation` or `clinical-variant-reporter`.
- The user wants comparison between two FASTA — route to `genome-compare`.
- The user wants 3D structure prediction — route to `struct-predictor`.

## Why This Exists

- **Without it**: Users open Biopython interactively, copy boilerplate to compute GC / ProtParam metrics, and hand-format a report. Common values get computed inconsistently across notebooks.
- **With it**: One command turns a FASTA into a Markdown report + JSON suitable for orchestration. Detection of nucleotide vs protein is automatic. ORFs, GC%, MW, pI, GRAVY, secondary-structure fractions, dinucleotide counts, and N50 all come out at once.
- **Why ClawBio**: Output is structured (`result.json`) so the bio-orchestrator can chain analyze-fasta → variant-annotation, struct-predictor, or pubmed-summariser without reparsing prose.

## Core Capabilities

1. **Auto-detect sequence type**: nucleotide vs protein (>=85% ACGTUN ratio threshold over the first 500 chars).
2. **Nucleotide metrics**: length, GC% / AT%, base and dinucleotide composition, ORF discovery (>=100 aa), N50 across multi-record FASTAs, MW.
3. **Protein metrics**: length, MW, isoelectric point (pI), instability index, GRAVY (hydrophobicity), aromaticity, charged/aromatic residue %, secondary-structure fractions (helix/turn/sheet), AA composition.

## Scope

**One skill, one task.** This skill describes a single FASTA file. It does not align, blast, fold, compare, or annotate. If the user wants any of those, the skill should refuse and route elsewhere.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| FASTA (nucleotide) | `.fasta`, `.fa`, `.fna` | `>header` line + ACGTUN sequence | `example_data/demo_nucleotide.fasta` |
| FASTA (protein) | `.fasta`, `.fa`, `.faa` | `>header` line + amino-acid sequence | `example_data/demo_protein.fasta` |

## Workflow

When the user asks for FASTA analysis:

1. **Validate** (prescriptive): file exists; at least one record; first record >=10 chars; <=50% Ns. Any failure → exit 1 with explicit message. Never write a partial report.
2. **Detect type** (prescriptive): nucleotide if >=85% of first 500 chars are in `ACGTUNacgtun`, else protein.
3. **Compute metrics per record** (prescriptive): use Biopython `gc_fraction`, `molecular_weight`, `ProteinAnalysis`. Round consistently (GC to 2 dp, MW to 1 dp, pI to 2 dp).
4. **Generate** (prescriptive): write `result.json` (full structured data), `report.md` (human-readable), `report.html` (visual), and `reproducibility/{commands.sh,environment.yml,checksums.sha256,run.json}`.
5. **Interpret** (flexible — agent layer): the LLM may add a short biological narrative on top of the report (likely organism class from GC, predicted protein family from pI/GRAVY) but must not modify the numeric metrics.

## CLI Reference

```bash
# Standard usage (ClawBio convention)
python skills/analyze-fasta/analyze_fasta.py \
  --input <fasta_file> --output <report_dir>

# Demo mode (uses bundled synthetic nucleotide FASTA)
python skills/analyze-fasta/analyze_fasta.py --demo --output /tmp/analyze_fasta_demo

# Via ClawBio runner
python clawbio.py run analyze-fasta --input <fasta_file> --output <dir>
python clawbio.py run analyze-fasta --demo

# Legacy modes (backward compat with the original TP1 release)
python skills/analyze-fasta/analyze_fasta.py <file.fasta> --json
python skills/analyze-fasta/analyze_fasta.py <file.fasta> --html out.html
```

## Demo

```bash
python clawbio.py run analyze-fasta --demo
```

Expected output: a `report.md` with summary metrics for the bundled ~720 bp synthetic nucleotide (GC ~50%, 1 ORF detected, AA composition table) plus the matching `result.json` and `reproducibility/` bundle.

## Algorithm / Methodology

So an LLM agent can apply the same logic without the script:

1. **Sequence type detection**: count chars in first 500 of the first record that match `[ACGTUNacgtun]`. Ratio >= 0.85 → nucleotide, else protein. (No silent fallback; if ambiguous, document in `result.json`.)
2. **Nucleotide GC**: `gc = (G + C) / (A + T + G + C + N) * 100`. Use Biopython `gc_fraction` to match the production behaviour.
3. **ORF discovery**: scan all 3 forward frames for `ATG ... [TAA|TAG|TGA]`. Keep ORFs with `length_bp >= 300` (>= 100 aa).
4. **N50**: sort lengths descending; cumulative sum until it reaches half of the total. Length at that point is N50.
5. **Protein metrics**: Biopython `ProteinAnalysis`. Strip `X` and `*` before instantiating to avoid ProtParam errors.
6. **Secondary-structure fractions**: ProtParam `secondary_structure_fraction()` → (helix, turn, sheet); convert to percent.

**Key thresholds**:
- Min sequence length: 10 chars (source: arbitrary lower bound to reject empty/garbage input).
- Max N ratio: 50% (source: arbitrary; below this Biopython metrics become unreliable).
- ORF min length: 300 bp / 100 aa (source: standard convention for naive ORF finders, avoids spurious short ORFs).
- Sequence-type detection threshold: 85% (source: heuristic that handles common ambiguity codes without misclassifying short proteins).

## Example Queries

- "Analyze sample.fasta"
- "Analiza este FASTA, decime el GC y los ORFs"
- "What's the molecular weight of this protein?"
- "Compute pI of the FASTA in /tmp/x.fa"

## Example Output

```markdown
# analyze-fasta Report

**Input file:** `demo_nucleotide.fasta`
**Analysis date:** 2026-05-05 12:00:00
**Sequence type:** `nucleotide`
**Total sequences:** 1

## Summary

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio