Read Structure

The ReadStructure dataclass describes the geometry of a sequencing read (offsets, stagger, swap). Returned by heuristic_discover() and used by count_barcodes().

protocol

ReadStructure dataclass — what discovery produces.

Defines the immutable ReadStructure that barcode discovery produces.

ReadStructure dataclass

ReadStructure(barcode_offset: int, orientation: str, left_flank: str | None, right_flank: str | None, need_swap: bool, barcode_length: int, chunks_sampled: int, diversity_satisfied: bool, reverse_offset: int | None = None, reverse_left_flank: str | None = None, reverse_right_flank: str | None = None)

What the discovery phase learns about the reads.

All fields are populated by the discoverer and consumed by the counter. Frozen so it can be safely passed between pipeline stages.

Parameters:

Name	Type	Description	Default
barcode_offset	int	Position of barcode within forward reads.	required
orientation	str	"forward" or "reverse" — dominant barcode orientation in the primary reads file.	required
left_flank	str | None	Constant sequence left of barcode, or None.	required
right_flank	str | None	Constant sequence right of barcode, or None.	required
need_swap	bool	Whether paired-end files need swapping (the file labeled R1 actually contains the reverse reads).	required
barcode_length	int	Length of barcodes in the library.	required
chunks_sampled	int	Number of chunks processed during discovery.	required
diversity_satisfied	bool	Whether diversity criteria were met.	required
reverse_offset	int | None	Position of barcode in reverse reads (paired-end), or None for single-end.	None
reverse_left_flank	str | None	Left flank in reverse reads, or None.	None
reverse_right_flank	str | None	Right flank in reverse reads, or None.	None

Examples:

>>> ReadStructure(
...     barcode_offset=6, orientation="forward",
...     left_flank="AACCGG", right_flank="TTAACC",
...     need_swap=False, barcode_length=20,
...     chunks_sampled=3, diversity_satisfied=True,
... )
ReadStructure(barcode_offset=6, ...)