pysam

Overview

Use pysam for low-level, streaming access to HTSlib-supported genomic formats:

• AlignmentFile and AlignedSegment for SAM/BAM/CRAM
• VariantFile, VariantHeader, and VariantRecord for VCF/BCF
• FastaFile for indexed FASTA and FastxFile for sequential FASTA/FASTQ
• TabixFile for BGZF-compressed, tabix-indexed BED/GFF/GTF/custom tables
• pysam.samtools and pysam.bcftools for wrapped command dispatchers

Current upstream baseline: pysam 0.24.1 (7 September 2026), wrapping HTSlib/samtools/bcftools 1.24. Read references/sources.md before updating version-specific guidance.

Installation

Use the pinned release for reproducible work:

uv pip install "pysam==0.24.1"

Confirm the runtime:

import pysam

print(pysam.__version__)           # 0.24.1
print(pysam.__samtools_version__)  # 1.24

Prebuilt wheels are available for supported macOS and Linux platforms. A source build needs a C compiler and HTSlib build dependencies; read the official installation guide linked from references/sources.md.

First Decide

Before writing code:

1. Identify the real format, compression, sort order, and available index.
2. Decide whether coordinates are numeric Python coordinates or a region string. Do not mix them.
3. For CRAM, identify the exact reference assembly and FASTA.
4. Prefer indexed region access; use sequential iteration only when intended.
5. Preserve headers when writing and write to a new path by default.
6. State filtering semantics: mapping/base quality, flags, overlap handling, duplicate handling, and pileup depth cap.

For unfamiliar files, start with the bundled read-only inspector:

python scripts/inspect_hts.py sample.bam
python scripts/inspect_hts.py cohort.vcf.gz
python scripts/inspect_hts.py reference.fa

Bundled Scripts

All scripts refuse to overwrite existing outputs. The filter also refuses stale output indexes and offers --index --csi for large BAM contigs. FASTA inspection requires an existing .fai; create it explicitly with pysam.faidx() first. Run each with --help for coordinate, index, and privacy notes.

Examples use illustrative filenames and assay-specific thresholds. The local synthetic suite exercises these API patterns on pysam 0.24.1; remote storage and biological datasets are not part of that validation.

Coordinate Contract

Numeric coordinates accepted by pysam APIs are 0-based, half-open. This includes numeric AlignmentFile.fetch(), VariantFile.fetch(), FastaFile.fetch(), TabixFile.fetch(), and pileup() arguments.

Region strings are samtools-style: 1-based and inclusive.

# The same 100 bases:
bam.fetch("chr1", 99, 199)          # [99, 199)
bam.fetch(region="chr1:100-199")    # 1-based inclusive

VCF text uses 1-based POS, while record properties expose both systems:

record.pos    # 1-based
record.start  # 0-based inclusive
record.stop   # 0-based exclusive

Read references/coordinates_and_indexing.md for format conversions, overlap semantics, index choices, and contig-name checks.

Alignment Files

Use context managers and explicit modes:

import pysam

with pysam.AlignmentFile("sample.bam", "rb", threads=4) as bam:
    for read in bam.fetch("chr1", 1_000, 2_000):
        if (
            not read.is_unmapped
            and not read.is_secondary
            and not read.is_supplementary
            and read.mapping_quality >= 30
        ):
            print(read.query_name, read.reference_start, read.cigarstring)

Use fetch(until_eof=True) to stream every record in file order, including unplaced unmapped reads, without requiring an index:

with pysam.AlignmentFile("sample.bam", "rb") as bam:

…