MACS3.IO.Parser module

BAM/BAMPE and FRAG parsers share an internal compiled byte stream in MACS3.IO.BAMStream. Public parser imports and methods remain in MACS3.IO.Parser. The stream owns decompression, native workers and compressed/decompressed buffers; its internal Cython declarations describe the buffer lifetime and serial-fallback contracts. Parser retains format decoding, FRAG interning, fragment batches and track assembly. Extracting those FRAG components is deferred because they share native callback layouts and track emission logic.

Input parsers used across MACS3 for reading alignment-like formats.

This code is free software; you can redistribute it and/or modify it under the terms of the BSD License (see the file LICENSE included with the distribution).

class MACS3.IO.Parser.BAMPEParser

Bases: BAMParser

Parser for paired-end BAM files that yields fragment spans.

Track loaders raise EOFError for incomplete alignment size fields or bodies. After a failed append, discard the partially modified track. Invalid template lengths, mate references and positions are skipped. Input with no accepted fragments raises ValueError.

n: Total number of fragments.

d: Average fragment length.

append_petrack(petrack)

Append inferred fragments to an existing PETrackI.

Parameters:: petrack – Existing paired-end track to append to.
Returns:: The updated track instance.
Return type:: PETrackI

Examples

from MACS3.IO.Parser import BAMPEParser
parser = BAMPEParser("reads.bam")
petrack = parser.build_petrack()
# Later, append more fragments from another file:
parser2 = BAMPEParser("more_reads.bam")
petrack = parser2.append_petrack(petrack)

build_petrack()

Return a PETrackI populated with inferred fragments.

Returns:: Paired-end track populated from BAM pairs.
Return type:: PETrackI

Examples

from MACS3.IO.Parser import BAMPEParser
parser = BAMPEParser("reads.bam")
petrack = parser.build_petrack()

class MACS3.IO.Parser.BAMParser

Bases: GenericParser

Parser for BAM binary alignment files.

Track loaders raise EOFError for incomplete alignment size fields or bodies. After a failed append, discard the partially modified track.

append_fwtrack(fwtrack): Append uniquely mapped reads to an existing FWTrack.

build_fwtrack(): Append uniquely mapped reads to an existing FWTrack.

get_references(): Return (references, lengths) extracted from the BAM header.

sniff(): Return True if the file begins with the BAM magic string.

tsize()

Average query length over up to ten records, stopping at clean EOF.

Use query-consuming CIGAR operations when SEQ is missing (l_seq=0). Raise ValueError for empty inputs or unusable lengths, and EOFError for incomplete alignment size fields or bodies.

Refer to: http://samtools.sourceforge.net/SAM1.pdf

class MACS3.IO.Parser.BEDPEParser

Bases: GenericParser

Parser for three-column BEDPE-style fragments (chrom, left, right).

append_petrack(petrack)

Append fragments from the stream to an existing PETrackI.

The last record may omit its newline. An empty load preserves this parser’s existing statistics; if it has no prior fragments, it raises ValueError. Statistics describe this parser, not the supplied track.

build_petrack()

Return a PETrackI constructed from the entire stream.

The last record may omit its newline. Input with no accepted fragments, including empty/header-only input, raises ValueError.

Returns:: Paired-end track populated from the input stream.
Return type:: PETrackI

Examples

from MACS3.IO.Parser import BEDPEParser
parser = BEDPEParser("fragments.bedpe")
petrack = parser.build_petrack()

class MACS3.IO.Parser.BEDParser

Bases: GenericParser

Parser for standard BED records with optional strand column.

class MACS3.IO.Parser.BowtieParser

Bases: GenericParser

Parser for Bowtie or Maqview single-end map files.

class MACS3.IO.Parser.ELANDExportParser

Bases: GenericParser

Parser for ELAND export tab-delimited files.

class MACS3.IO.Parser.ELANDMultiParser

Bases: GenericParser

Parser for ELAND multi-hit reports (s_N_eland_multi format).

class MACS3.IO.Parser.ELANDResultParser

Bases: GenericParser

Parser for single-end ELAND result tables.

class MACS3.IO.Parser.FragParser

Bases: GenericParser

Parser for scATAC fragment TSV files with barcode counts.

append_petrack(petrack, max_count=0)

Append barcode-aware fragments to an existing PETrackI.

The last record may omit its newline. An empty load preserves this parser’s existing statistics; if it has no prior fragments, it raises ValueError. Statistics describe this parser, not the supplied track.

Parameters:

petrack – Existing paired-end track to append to.
max_count – Optional cap applied to per-fragment count values.

Returns:

The updated track instance.

Return type:

PETrackII

Examples

from MACS3.IO.Parser import FragParser
parser = FragParser("fragments.tsv.gz")
petrack = parser.build_petrack()
parser2 = FragParser("more_fragments.tsv.gz")
petrack = parser2.append_petrack(petrack, max_count=10)

build_petrack(max_count=0)

Return a PETrackII populated with fragments and barcodes.

The last record may omit its newline. Empty/header-only input or input with no accepted fragments raises ValueError.

Parameters:: max_count – Optional cap applied to per-fragment count values.
Returns:: Paired-end track with barcode and count metadata.
Return type:: PETrackII

Examples

from MACS3.IO.Parser import FragParser
parser = FragParser("fragments.tsv.gz")
petrack = parser.build_petrack(max_count=10)

class MACS3.IO.Parser.GenericParser

Bases: object

Base parser with helpers for streaming alignment-like text files.

filename: Path to the input file.

gzipped: Whether the input stream is gzipped. (bool)

tag_size: tag size.

fhd: Open file handle for the input stream.

buffer_size: Buffer size for streaming reads.

append_fwtrack(fwtrack): Append parsed locations to an existing FWTrack.

build_fwtrack(): Create a new FWTrack populated from the underlying stream.

close(): Close the underlying file handle.

execution_policy

is_gzipped(): Report whether the underlying input stream is gzip compressed.

sniff(): Return True when the input appears compatible with this parser.

tsize(): Estimate tag length from a sample of valid alignments.

class MACS3.IO.Parser.SAMParser

Bases: GenericParser

Parser for SAM alignment text files with standard SAM flags.

MACS3.IO.Parser.guess_parser(fname, buffer_size=100000, execution_policy=None, threads=None)

Return the first parser that recognises fname as a supported format.

Parameters:

fname – Path to inspect.
buffer_size (cython.long) – Buffer size handed to candidate parser constructors.

Returns:

Parser instance configured for the detected format.

Raises:

Exception – If no parser can identify the file structure.