Analyze Fasta

🧬 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

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

# 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

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

# analyze-fasta Report

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

## Summary

| Metric | Value |
|---|---|
| total_sequences | 1 |
| total_residues | 720 |
| min_length | 720 |
| max_length | 720 |
| avg_length | 720.0 |
| n50 | 720 |
| avg_gc_content | 50.42 |
| total_orfs | 1 |

## Per-sequence metrics

### 1. synthetic_demo_orf

- **Description:** synthetic_demo_orf | Synthetic E. coli-like ORF
- **Length:** 720 bp
- **GC content:** 50.42%
- **AT content:** 49.58%
- **ORFs (>=100 aa):** 1

---

_ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions._

Output Structure

<output_dir>/
├── report.md              # Primary markdown report
├── report.html            # Standalone visual report
├── result.json            # Machine-readable results
└── reproducibility/
    ├── commands.sh        # Portable replay command ($CLAWBIO_ROOT / $OUTPUT_DIR)
    ├── environment.yml    # Conda recipe (biopython)
    ├── checksums.sha256   # SHA-256 of every output file
    └── run.json           # Run metadata (versions, timestamps, input size)