fastasma

A modular toolkit for FASTA file processing, built around a pipeline of composable operations.

Installation

pip install fastasma

Core concepts

All modules implement the SequenceSource protocol — an iterable that yields Sequence objects (header, sequence, annotation). This allows arbitrary chaining:

output = LastStep(Step2(Step1(ImportFasta("input.fasta"))))

Quick start

import fastasma

source = fastasma.ImportFasta("input.fasta")
source = fastasma.DropAnnotationKeys(source, keys_to_remove=["length"])
source = fastasma.AddAnnotationToHeader(source, annotation_key="organism", position="suffix")
source = fastasma.Head(source, n=10)
fastasma.WriteFasta(source, output_path="output.fasta")

Modules

Importers

Annotators

Transform sequence annotations or headers.

Mutators

Filter, sample, or rename sequences in the stream.

Filters

Boolean conditions testable on a single Sequence. Used standalone or combined with Group.

Filter examples

# Sequences containing a motif
fastasma.ContainsMotif("ATTG")

# Sequences with organism annotation set to "Homo sapiens"
fastasma.HasAnnotation("organism", "Homo sapiens")

# Sequences whose header starts with "seq"
fastasma.HeaderMatches(r"^seq")

# Sequences longer than 200 bp
fastasma.SequenceLength(is_="greater", length=200)

# Short sequences (less than 100 bp) containing a motif
fastasma.And(fastasma.ContainsMotif("ATTG"), fastasma.SequenceLength(is_="less", length=100))

# Sequences that do NOT contain a stop codon
fastasma.Not(fastasma.ContainsMotif("TAG"))

Groups

Group splits a SequenceSource into matched and unmatched subsets based on a Filter, then lets you apply operations only to the matched subset before reuniting them.

Any class that accepts a SequenceSource as first argument (Annotators, Mutators, Writers, even another Group) can be used with .then().

Group examples

# Find sequences containing "ATTG" and add a suffix to their header
result = (fastasma.Group(fastasma.ImportFasta("input.fasta"),
                         fastasma.ContainsMotif("ATTG"))
          .then(fastasma.AddAnnotationToHeader, annotation_key="organism",
                separator="_", position="suffix")
          .ungroup())
fastasma.WriteFasta(result, output_path="output.fasta")

# Chain multiple operations on the matched group
result = (fastasma.Group(source, fastasma.SequenceLength(is_="greater", length=200))
          .then(fastasma.DeduplicateHeaders, separator="_")
          .then(fastasma.DropAnnotationKeys, keys_to_remove=["length"])
          .ungroup())

# Use Group as a simple filter (no transforms)
source = fastasma.Group(
    fastasma.ImportFasta("input.fasta"),
    fastasma.Or(fastasma.ContainsMotif("ATTG"), fastasma.ContainsMotif("CGGT"))
).matched
fastasma.WriteFasta(source, output_path="filtered.fasta")

Writers

Write sequences to files or databases.