Skip to content

API Overview

Aligner

The Aligner orchestrates the alignment process.

It encapsulates the alignment configuration and the index to map query sequences against reference targets.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)
>>> for mapping in aligner.map(b"query1", b"ATGC..."):
...     print(mapping.score)

options property

Get the current mapping options.

Returns:

Name Type Description
MapOptions MapOptions

A copy of the current mapping options.

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

from_fasta(path, preset=Ellipsis) staticmethod

Create an aligner from a FASTA file.

Parameters:

Name Type Description Default
path PathLike

The file path to the FASTA file.

 required
preset Preset

The preset configuration (e.g. Preset.MapOnt). Defaults to Preset.MapOnt.

 Ellipsis

Returns:

Name Type Description
Aligner Aligner

The initialized aligner object.

from_index(path, preset=Ellipsis) staticmethod

Create an aligner from an index file.

Parameters:

Name Type Description Default
path PathLike

The file path to the saved index file.

 required
preset Preset

The preset configuration (e.g. Preset.MapOnt). Defaults to Preset.MapOnt.

 Ellipsis

Returns:

Name Type Description
Aligner Aligner

The initialized aligner object.

load_junctions_bed(path) method descriptor

Load splice junctions from a BED file.

Parameters:

Name Type Description Default
path PathLike | str

Path to the BED file.

 required

load_junctions_spsc(path, scale=None) method descriptor

Load splice junctions from a SPSC file.

Parameters:

Name Type Description Default
path PathLike | str

Path to the SPSC file.

 required
scale float | None

Optional scaling factor.

 None

map(query_name, query_seq) method descriptor

Maps a single query sequence sequentially to the targets.

Parameters:

Name Type Description Default
query_name bytes

The name of the query sequence.

 required
query_seq bytes

The query sequence.

 required

Returns:

Name Type Description
MappingIterator MappingIterator

An iterator over the generated mappings.

map_batch(queries) method descriptor

Performs highly parallelized batch alignments mapping over multiple queries.

Bypasses the GIL to utilize multiple threads for parallelism (via Rayon).

Parameters:

Name Type Description Default
queries list[tuple[bytes, bytes]]

A list of tuples containing (name, sequence) as bytes.

 required

Returns:

Type Description
list[MappingIterator]

list[MappingIterator]: A list of iterators, one for each query sequence.

seq(name, start=None, end=None) method descriptor

Returns the sequence for a given target name.

Parameters:

Name Type Description Default
name str

The name of the target sequence.

 required
start int

The 0-based start coordinate. Defaults to 0.

 None
end int

The 0-based end coordinate. Defaults to the end of the sequence.

 None

Returns:

Name Type Description
str str

The requested sequence.

Raises:

Type Description
ValueError

If the sequence name is not found in the index.

CigarElement

Structured CIGAR operation element (length and operation type).

Attributes:

Name Type Description
len int

Operation length.
op CigarOp

Operation type enum.

CigarOp

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

B = CigarOp.B class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

D = CigarOp.D class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

EQ = CigarOp.EQ class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

H = CigarOp.H class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

I = CigarOp.I class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

M = CigarOp.M class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

N = CigarOp.N class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

P = CigarOp.P class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

S = CigarOp.S class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

X = CigarOp.X class-attribute

BAM CIGAR operation encodings as a Python Enum.

The values correspond to the official BAM specification.

__eq__(value) method descriptor

Return self==value.

__ge__(value) method descriptor

Return self>=value.

__gt__(value) method descriptor

Return self>value.

__int__() method descriptor

int(self)

__le__(value) method descriptor

Return self<=value.

__lt__(value) method descriptor

Return self<value.

__ne__(value) method descriptor

Return self!=value.

__repr__() method descriptor

Return repr(self).

FastaStreamer

Streaming FASTA parser. Push bytes via push; pop completed (name, seq) pairs via next_record; flush the in-flight record (if any) at end-of-input via finalize.

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

finalize() method descriptor

Flush the trailing partial line + the in-flight record. Call once after the last push. The flushed record (if any) is appended to the queue — drain with next_record.

next_record() method descriptor

Pop a completed record from the internal queue.

push(chunk) method descriptor

Feed a chunk of bytes. Records that complete inside this chunk are queued for next_record.

FastqStreamer

Streaming FASTQ parser. 4-line records: @name, sequence, +, quality. Quality scores are consumed and discarded; only (name, seq) is yielded.

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

finalize() method descriptor

Flush the trailing partial line + the in-flight record.

next_record() method descriptor

Pop a completed record from the internal queue.

push(chunk) method descriptor

Feed a chunk of bytes.

FastxReader

A reader for parsing FASTA/FASTQ files.

The FastxReader allows parsing of uncompressed or gzip-compressed FASTA/FASTQ files and acts as a Python iterator, yielding sequence records.

Examples:

>>> from rammappy import FastxReader
>>> reader = FastxReader("test.fa")
>>> for record in reader:
...     print(f"{record.name}: {record.sequence}")

__iter__() method descriptor

Implement iter(self).

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

__next__() method descriptor

Implement next(self).

read_batch(batch_size) method descriptor

Read sequences until cumulative bases exceed batch_size. Returns (seqs, is_eof). Caller can call again for the next batch.

Index

The Index object represents a genomic sequence index.

It holds the internal Rust Index for alignment. You can construct an index from a collection of sequences, or load it from a previously saved file.

Examples:

>>> from rammappy import Index
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> index.save("my_index.mmi")
>>> loaded_index = Index.load("my_index.mmi")

seq_names property

Returns the sequence names in the index.

Returns:

Type Description
list[str]

list[str]: The list of sequence names.

build(seqs, w=10, k=15, is_hpc=False, max_occ=50000) staticmethod

Build an index from target sequences.

Parameters:

Name Type Description Default
seqs list[tuple[bytes, bytes]]

A list of tuples containing (name, sequence) as bytes.

 required
w int

Window size. Defaults to 10.

 10
k int

K-mer size. Defaults to 15.

 15
is_hpc bool

Homopolymer compressed. Defaults to False.

 False
max_occ int

Maximum occurrences. Defaults to 50000.

 50000

Returns:

Name Type Description
Index Index

The built index.

load(path) staticmethod

Load an index from file.

Parameters:

Name Type Description Default
path PathLike

The file path to load the index from.

 required

Returns:

Name Type Description
Index Index

The loaded index.

save(path) method descriptor

Save the index to a file.

Parameters:

Name Type Description Default
path PathLike

The file path to save the index to.

 required

seq(name, start=None, end=None) method descriptor

Returns the sequence for a given target name.

Parameters:

Name Type Description Default
name str

The name of the target sequence.

 required
start int

The 0-based start coordinate. Defaults to 0.

 None
end int

The 0-based end coordinate. Defaults to the end of the sequence.

 None

Returns:

Name Type Description
str str

The requested sequence.

Raises:

Type Description
ValueError

If the sequence name is not found in the index.

strip_sequences() method descriptor

Strip sequences from the index to save memory.

This removes the actual sequence bytes from memory, which is useful when you only need to perform mapping and do not need base-level alignment (CIGAR).

Examples:

>>> index.strip_sequences()

Mapping

Python representation of an alignment Mapping.

Mappings are lazily evaluated: the actual Rust-level objects are preserved until accessed via the Python properties.

Attributes:

Name Type Description
target_name bytes

The name of the target sequence.
target_id int

Target sequence numeric index.
target_len int

Target sequence length.
target_start int

Start coordinate on the target.
target_end int

End coordinate on the target.
query_start int

Start coordinate on the query.
query_end int

End coordinate on the query.
strand Strand

Orientation of the alignment.
score int

Alignment score.
mapq int

Mapping quality (0-255).
is_primary bool

True if this is the primary alignment.
is_supplementary bool

True if this is a supplementary alignment.
is_spliced bool

True if this alignment contains splice junctions.
trans_strand Strand | None

Transcript strand for splice alignments, if known.
matches int

Number of matching bases.
block_len int

Alignment block length.
edit_distance int

Edit distance (NM tag).
divergence float

Sequence divergence (0.0 = identical).
cigar bytes | None

The CIGAR string, if requested during alignment.
cigar_ops list[CigarElement] | None

Structured CIGAR operations, if requested.
cs bytes | None

CS tag string, if requested.
md bytes | None

MD tag string, if requested.

cigar property

Returns the optional CIGAR string as a lazy byte array.

cigar_ops property

Returns the structured CIGAR operations.

cs property

Returns the optional cs string as a lazy byte array.

md property

Returns the optional MD string as a lazy byte array.

target_name property

Return the target name as Python bytes.

__repr__() method descriptor

Return repr(self).

__str__() method descriptor

Return str(self).

MappingIterator

A lazy iterator that provides Mapping objects.

Instead of allocating a list, we hold an iterator of Rust mappings and materialize Python wrapper objects only when requested via next().

__iter__() method descriptor

Implement iter(self).

__next__() method descriptor

Implement next(self).

Minimizer

Represents a k-mer sketch (minimizer, syncmer, etc.).

Contains the genomic coordinate and the hash value.

Attributes:

Name Type Description
x int

The 64-bit integer combining the genomic coordinate and other metadata.
y int

The 64-bit hash value of the k-mer.

MinimizerSketcher

A sketcher that extracts minimizers from sequences.

Minimizers are the lexicographically smallest k-mers in a sliding window of size w.

Examples:

>>> from rammappy.sketch import MinimizerSketcher
>>> sketcher = MinimizerSketcher(k=15, w=10)
>>> sketcher.sketch(b"ATGCGTACGATCGATC")
[<Minimizer object at ...>, ...]

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

sketch(seq) method descriptor

Extract minimizers from a byte string sequence.

Parameters:

Name Type Description Default
seq bytes

The sequence to sketch.

 required

Returns:

Type Description
list[Minimizer]

list[Minimizer]: A list of minimizer objects.

Preset

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

Asm10 = Preset.Asm10 class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

Asm20 = Preset.Asm20 class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

Asm5 = Preset.Asm5 class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

MapHifi = Preset.MapHifi class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

MapOnt = Preset.MapOnt class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

MapPb = Preset.MapPb class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

Splice = Preset.Splice class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

Sr = Preset.Sr class-attribute

The mapping presets available in rammappy.

These presets configure the aligner for different sequencing technologies and use cases, tuning heuristics and scoring.

Examples:

>>> from rammappy import Index, Aligner, Preset
>>> index = Index.build([(b"target1", b"ATGC...")])
>>> aligner = Aligner(index, preset=Preset.MapOnt)

__eq__(value) method descriptor

Return self==value.

__ge__(value) method descriptor

Return self>=value.

__gt__(value) method descriptor

Return self>value.

__int__() method descriptor

int(self)

__le__(value) method descriptor

Return self<=value.

__lt__(value) method descriptor

Return self<value.

__ne__(value) method descriptor

Return self!=value.

__repr__() method descriptor

Return repr(self).

RandstrobeSketcher

A sketcher that extracts randstrobes from sequences.

Randstrobes are combinations of k-mers that provide more resilient matching.

Examples:

>>> from rammappy.sketch import RandstrobeSketcher
>>> sketcher = RandstrobeSketcher(k=15, w_min=10, w_max=30)
>>> sketcher.sketch(b"ATGCGTACGATCGATC")
[<Minimizer object at ...>, ...]

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

sketch(seq) method descriptor

Extract randstrobes from a byte string sequence.

Parameters:

Name Type Description Default
seq bytes

The sequence to sketch.

 required

Returns:

Type Description
list[Minimizer]

list[Minimizer]: A list of randstrobe objects.

Record

A sequence record from a FASTA or FASTQ file.

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

__repr__() method descriptor

Return repr(self).

Strand

Strand orientation of an alignment.

Represents whether the query mapped to the forward or reverse strand of the target.

Attributes:

Name Type Description
Forward

The forward strand.
Reverse

The reverse complement strand.

Forward = Strand.Forward class-attribute

Strand orientation of an alignment.

Represents whether the query mapped to the forward or reverse strand of the target.

Attributes:

Name Type Description
Forward

The forward strand.
Reverse

The reverse complement strand.

Reverse = Strand.Reverse class-attribute

Strand orientation of an alignment.

Represents whether the query mapped to the forward or reverse strand of the target.

Attributes:

Name Type Description
Forward

The forward strand.
Reverse

The reverse complement strand.

__eq__(value) method descriptor

Return self==value.

__ge__(value) method descriptor

Return self>=value.

__gt__(value) method descriptor

Return self>value.

__int__() method descriptor

int(self)

__le__(value) method descriptor

Return self<=value.

__lt__(value) method descriptor

Return self<value.

__ne__(value) method descriptor

Return self!=value.

__repr__() method descriptor

Return repr(self).

SyncmerSketcher

A sketcher that extracts syncmers from sequences.

Syncmers provide a more evenly spaced sampling of sequences compared to minimizers.

Examples:

>>> from rammappy.sketch import SyncmerSketcher
>>> sketcher = SyncmerSketcher(k=15, s=5)
>>> sketcher.sketch(b"ATGCGTACGATCGATC")
[<Minimizer object at ...>, ...]

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

sketch(seq) method descriptor

Extract syncmers from a byte string sequence.

Parameters:

Name Type Description Default
seq bytes

The sequence to sketch.

 required

Returns:

Type Description
list[Minimizer]

list[Minimizer]: A list of syncmer objects.

parse_fasta_bytes(data) builtin

Parse FASTA from a byte slice (works with mmap or regular buffers) Returns a list of (name, sequence) pairs.

read_fasta(path) builtin

Read all sequences from a FASTA file into memory. Returns a list of (name, sequence) pairs.