Skip to main content

Crate antisequence

Crate antisequence 

Source
Expand description

Rust stream processing library for sequencing reads.

§Overview

ANTISEQUENCE provides efficient and composable operations for manipulating fastq records.

This is useful for:

  • Processing reads for custom sequencing protocol development
  • Unifying read formats from various sequencing protocols
  • Writing fastq processing tools
  • Debugging sequencing pipelines

§Computation graph API

To use ANTISEQUENCE, first add operations (read from FASTQ, transform, filter, output, and so on) to a GraphBuilder. Compiling it produces a structurally immutable CompiledGraph for execution. Graph is retained as the legacy mutable construction API.

See graph for all supported operations.

use antisequence::graph::{GraphBuilder, InputFastqOp, NullOutputOp};
use antisequence::trace::NoTrace;
use std::io::Cursor;

let input = b"@read\nACGT\n+\nIIII\n";
let mut builder = GraphBuilder::<NoTrace>::new();
builder.add(InputFastqOp::from_reader(Cursor::new(input))?);
builder.add(NullOutputOp::new());
let graph = builder.compile()?;
graph.run()?;

Each operation declares its requirements and effects through an allocation-free OperationDescriptor. Missing requirements use an explicit MissingInputPolicy: strict error, per-read rejection, or compatibility skip.

§Reads

Here’s an example fastq record:

@read6
AATTCCGGAATTCCCAAAAG
+
01234567890123456789

The first, second, and fourth lines are the name, sequence, and quality scores, respectively.

ANTISEQUENCE stores that record as an internal Read data structure:

name1:
 *     |---|
 str:  read6
 from: record 5 in file: "example_data/match.fastq"
seq1:
 *        |------------------|  adapter=AAAA
 template |-------------|
 adapter                 |---|
 str:     AATTCCGGAATTCCCAAAAG
 qual:    01234567890123456789
 from:    record 5 in file: "example_data/match.fastq"

Each Read is a set of strings of different types. Types help indicate whether the string is a read sequence (seq1) or read name (name1).

Each string has associated labeled intervals in the string. For example, the region where an adapter is found in the read sequence can be labeled. All strings start with an interval labeled *, which spans the whole string. You can refer to an interval with seq1.*, seq1.adapter, name1.*, etc.

An interval can contain attributes that hold arbitrary metadata. This may include a boolean for whether to filter the read, or the name of the pattern that the read matches. You can refer to an attribute with seq1.*.adapter, etc.

For efficiency and simplicity, most ANTISEQUENCE operations only manipulate the intervals and attributes. You can choose to modify the underlying strings afterwards.

§Transform expressions

Transform expressions allow you to specify the names of the inputs and outputs for an operation. For example, to cut an interval and create two new intervals, you can use tr!(seq1.* -> seq1.left, seq1.right).

§Expressions

Expressions are useful for doing arbitrary computation on reads. Here are some examples:

  • label_exists("seq1.label").and(attr_exists("seq1.*.attribute"))
  • Expr::from(label("seq1.label")).slice(..3)
  • Expr::from(label("seq1.label")).len().in_bounds(10..20)

Supported data types are: byte string, int, float, and boolean.

§Format expressions

Format expressions allow you to contruct new strings from intervals and attributes, and they are similar to Rust’s formatting syntax. For example, you can use fmt_expr("{seq1.a}_{seq1.b}") to concatenate the substrings corresponding to mappings a and b, separated by an underscore. They also preserve quality scores, making rearranging regions in a read easy.

§Note

To apply the same transformations to the quality score, the same expression is evaluated by simply substituting in quality scores when needed when a label() is used. If this is not desired, then break up the expression by storing intermediate results as attributes, which will always have the same value (not substituted by quality scores).

Re-exports§

pub use End::*;

Modules§

errors
expr
graph
matcher
Orthogonal matcher semantics and observable backend planning.
trace

Macros§

tr
Create a transform expression.

Structs§

Mapping
A labeled mapping that corresponds to an interval/region in a string.
Patterns
Read
A fastq read.
StrMappings
A string and its correspondings mappings.

Enums§

AmbiguityPolicy
Determines how an equal-best match against multiple distinct patterns is handled.
CompiledSimdBackend
SIMD implementation compiled into ANTISEQUENCE’s alignment backend.
Data
Data types.
End
Left or right end.
Intersection
Origin
Pattern
PositionAmbiguityPolicy
Determines how equal-best placements of the same pattern are handled in search and bounded-search scopes. This is deliberately separate from AmbiguityPolicy, which resolves ties between distinct patterns.
ReadProjectionPart
One source in a terminal read projection.
StrType
Valid types of strings.

Functions§

compiled_simd_backend
Return the alignment SIMD backend selected by Cargo features for this build.

Type Aliases§

FastqRecord
A FASTQ record as (name, sequence, quality) byte slices.