Skip to main content

Genomic alignments and intervals

IterableData reads common genomics interval and alignment formats as dictionaries. SAM, BAM, and CRAM have their own pages; this page covers BED, GFF3, and GTF.

Compressed text (.bed.gz, .gff3.zst, and similar) uses the usual filename codec detection.

CRAM​

CRAM is a reference-compressed alignment format with its own page: CRAM.

BED​

BED3–BED12 interval tables with 0-based, half-open coordinates (start/end). Optional fields map to name, score, strand, thick coordinates, RGB, and blocks. Extra columns are stored in extra. Writes are supported.

from iterable import open_iterable

with open_iterable("peaks.bed") as source:
for row in source:
print(row["chrom"], row["start"], row["end"])

with open_iterable("out.bed", mode="w") as dest:
dest.write({"chrom": "chr1", "start": 100, "end": 200, "name": "peak1"})

Parameters (BED)​

ParameterTypeDefaultRequiredDescription
headerslist[str][]NoOptional collected track/browser/# header lines (also filled while reading)

Invalid coordinates (end < start, mismatched block counts) raise ValueError.

GFF3 and GTF​

GFF3 and GTF are tab-separated annotations with 1-based, closed coordinates. Directives and comments are collected on metadata. Attributes are parsed into an ordered map; set attribute_mode="lossless" to also keep the raw attribute string.

FASTA tail policy: a ##FASTA directive ends feature reading — the directive is kept in metadata (or yielded as a directive record with include_comments=True) and iteration stops; sequence lines after it are never parsed as feature rows and are never loaded eagerly.

from iterable import open_iterable

with open_iterable("genes.gff3", iterableargs={"attribute_mode": "parsed"}) as source:
for row in source:
print(row["seqid"], row["start"], row["end"], row["attributes"])

with open_iterable("genes.gtf", iterableargs={"include_comments": True}) as source:
for row in source:
print(row)

Parameters (GFF3 / GTF)​

ParameterTypeDefaultRequiredDescription
attribute_mode"parsed" or "lossless""parsed"NoParse attributes, or also keep the raw string as attributes_raw
include_commentsboolFalseNoYield directive/comment lines as {"record_type": "directive", "value": ...}

GFF3 and GTF support writing. Install: no extra for BED/GFF3/GTF (plain text).

Error Handling​

Format errors identify the file and line: filename.bed:line 4: ... (or line 4: ... for streams).

  • ValueError (BED): Fewer than three columns, end < start, or block_count mismatch
  • ValueError (GFF3/GTF): Wrong column count, invalid coordinates, bad attribute_mode, or malformed GFF3 attributes
  • FileNotFoundError: Path is wrong or the file is missing

See Troubleshooting for more help.

Limitations​

  1. BED vs GFF/GTF coordinates differ (0-based half-open vs 1-based closed); values are not converted
  2. .vcf is not this page — genomic VCF/BCF is genomic_vcf; vCard is VCF