Pysam 0.24 API Quick Reference

This is a compact navigation aid, not a replacement for the official API documentation. Signatures and defaults below are for pysam 0.24.1.

Alignment Files

Constructor

pysam.AlignmentFile(
    filepath_or_object,
    mode=None,  # pass the remaining options by keyword
    template=None,
    reference_names=None,
    reference_lengths=None,
    text=None,
    header=None,
    add_sq_text=True,
    add_sam_header=True,
    check_header=True,
    check_sq=True,
    reference_filename=None,
    index_filename=None,
    filepath_index=None,
    require_index=False,
    duplicate_filehandle=True,
    ignore_truncation=False,
    format_options=None,
    threads=1,
)

Core methods:

AlignmentFile.fetch(
    contig=None,
    start=None,
    stop=None,
    region=None,
    tid=None,
    until_eof=False,
    multiple_iterators=False,
    reference=None,  # compatibility alias
    end=None,        # compatibility alias
)

AlignmentFile.count(
    contig=None,
    start=None,
    stop=None,
    region=None,
    until_eof=False,
    read_callback="nofilter",
    reference=None,
    end=None,
)

AlignmentFile.count_coverage(
    contig,
    start=None,
    stop=None,
    region=None,
    quality_threshold=15,
    read_callback="all",
    reference=None,
    end=None,
)

AlignmentFile.pileup(
    contig=None,
    start=None,
    stop=None,
    region=None,
    reference=None,
    end=None,
    **kwargs,
)

Important pileup kwargs/defaults:

For count_coverage, pass numeric contig, start, stop within contig bounds; the accepted region/end aliases do not size its arrays correctly in 0.24.1.

Always pass important pileup semantics explicitly rather than depending on defaults. get_num_aligned() is a quality-filtered pileup-entry count in 0.24.1 and can include D/N entries. Count non-deletion/non-refskip entries explicitly for observed base depth.

Other useful methods/properties:

• write(read)
• has_index() / check_index()
• get_index_statistics()
• get_reference_name(tid) / get_tid(name)
• get_reference_length(name)
• find_introns(read_iterator)
• head(n, multiple_iterators=True)
• references, lengths, nreferences
• mapped, unmapped, nocoordinate when index statistics support them; CRAI returns zeros because it stores no such counts

AlignedSegment

Construction:

read = pysam.AlignedSegment(header=None)

Prefer passing the destination AlignmentHeader.

Frequently used attributes:

• identity: query_name, query_sequence, query_qualities
• query spans: query_length, query_alignment_start, query_alignment_end, query_alignment_length
• reference: reference_id, reference_name, reference_start, reference_end, reference_length
• mapping: mapping_quality, cigarstring, cigartuples
• mate: next_reference_id, next_reference_name, next_reference_start, template_length
• flags: flag and is_* boolean properties

Methods:

• get_tag(tag, with_value_type=False)
• set_tag(tag, value, value_type=None, replace=True)
• has_tag(tag)
• get_tags(with_value_type=False)
• set_tags(tags)
• get_aligned_pairs(matches_only=False, with_seq=False, with_cigar=False)
• get_blocks()
• get_reference_positions(full_length=False)
• get_reference_sequence() (requires MD)
• get_forward_sequence() / get_forward_qualities()
• infer_query_length() / infer_read_length()

Modified-base properties:

• modified_bases
• modified_bases_forward

They return mappings from (canonical_base, strand, modification) to (query_position, quality) calls.

Pileup Objects

PileupColumn:

• reference_id, reference_name, reference_pos
• nsegments
• pileups
• get_num_aligned()
• get_query_sequences(...)
• get_query_qualities()
• get_mapping_qualities()

PileupRead:

• alignment
• query_position
• query_position_or_next
• is_del
• is_refskip
• indel
• level

Read column values before the iterator advances; the buffer is reused. PileupRead.level is exposed but is not currently computed.

Variant Files

Constructor

pysam.VariantFile(
    filename,
    mode=None,
    index_filename=None,
    header=None,
    drop_samples=False,
    duplicate_filehandle=True,
    ignore_truncation=False,
    threads=1,
)

Core methods:

VariantFile.fetch(
    contig=None,
    start=None,
    stop=None,
    region=None,
    reopen=False,
    end=None,
    reference=None,
)

VariantFile.subset_samples(include_samples)
VariantFile.new_record(*args, **kwargs)
VariantFile.write(record)

Numeric fetch coordinates are 0-based, half-open. reopen=True supports multiple simultaneous iterators. Use contig, not the legacy reference alias: without contig or region, 0.24.1 selects the sequential-rewind path before interpreting that alias.

VariantHeader:

header.copy()
header.add_meta(key, value=None, items=None)
header.add_line(line)
header.add_sample(sample)
header.new_record(
    contig=None,
    start=0,
    stop=0,
    alleles=None,
    id=None,
    qual=None,
    filter=None,
    info=None,
    samples=None,
    **kwargs,
)

Metadata collections:

• contigs
• samples
• filters
• info
• formats
• records

VariantRecord:

• location: contig, chrom, pos, start, stop, rlen
• alleles: ref, alts, alleles, alleles_variant_types
• metadata: id, qual, filter, info
• samples: samples
• methods: copy(), translate(destination_header)

FASTA and FASTX

pysam.FastaFile(
    filename,
    filepath_index=None,
    filepath_index_compressed=None,
)

FastaFile.fetch(
    reference=None,
    start=None,
    end=None,
    region=None,
)

FastaFile.get_reference_length(reference)

Properties: references, lengths, nreferences.

pysam.FastxFile(filename, persist=True)

Yielded records expose:

• name
• comment
• sequence
• quality
• get_quality_array()

persist=False is faster but returns temporary read-only proxies.

Tabix

pysam.TabixFile(
    filename,
    mode="r",
    parser=None,
    index=None,
    encoding="ascii",
    threads=1,
)

TabixFile.fetch(
    reference=None,
    start=None,
    end=None,
    region=None,
    parser=None,
    multiple_iterators=False,
)

Properties: contigs, header, filename, filename_index. Do not use the inherited index_filename to discover the loaded tabix index (it is None in the tested release). Supply index="data.gz.csi" for CSI; the default looks only for data.gz.tbi. Although accepted, threads= is reset to 1 by the 0.24.1 TabixFile implementation; do not promise tabix parallel decoding.

Compression and indexing:

pysam.tabix_compress(
    filename_in,
    filename_out,
    force=False,
)

pysam.tabix_index(
    filename,
    force=False,
    seq_col=None,
    start_col=None,
    end_col=None,
    preset=None,
    meta_char="#",
    line_skip=0,
    zerobased=False,
    min_shift=-1,
    index=None,
    keep_original=False,
    csi=False,
)

Parsers:

• pysam.asTuple()
• pysam.asBed()
• pysam.asGTF()
• pysam.asGFF3()
• pysam.asVCF() (its .pos is 0-based, unlike VariantRecord.pos)

Wrapped Commands

Explicit imports:

import pysam.samtools
import pysam.bcftools

Each dispatcher has:

command(
    *args: str,
    catch_stdout=True,
    save_stdout=None,
    split_lines=False,
)

command.get_messages()
command.usage()

• command-line tokens are separate strings
• stdout is returned by default
• save_stdout=path writes captured stdout to a file
• catch_stdout=False discards stdout and avoids overriding a command's -o
• after success, stderr is available from get_messages(); after failure, use the raised exception because 0.24.1 can leave that cache unchanged
• a nonzero exit raises pysam.SamtoolsError

Top-level samtools aliases such as pysam.sort exist, but explicit module imports make provenance clearer. Bcftools should be explicitly imported as pysam.bcftools.

Convenience Functions

• pysam.qualitystring_to_array(text)
• pysam.array_to_qualitystring(values)
• pysam.index(*samtools_args, **dispatcher_kwargs)
• pysam.faidx(*samtools_args, **dispatcher_kwargs)
• pysam.tabix_compress(...)
• pysam.tabix_index(...)
• pysam.set_verbosity(level)
• pysam.reverse_complement(sequence) (new in 0.24.1; preserves input type)
• pysam.reverse_complement_inplace(bytearray_sequence) (new in 0.24.1)

Pysam 0.24 substantially optimized array_to_qualitystring().

Exceptions

Expect and handle narrowly:

• ValueError: invalid coordinates, header/record errors, unusable index
• OSError / IOError: file, compression, and HTSlib I/O problems
• IndexError: some invalid coordinates and sequence access; FASTA end overruns can instead clip or return an empty string, so validate bounds
• KeyError: missing headers, samples, tags, or fields when accessed directly
• pysam.SamtoolsError: wrapped command failure

Do not use ignore_truncation=True as general error suppression.

Compatibility Names to Avoid in New Code

Prefer:

• AlignmentFile, not Samfile
• AlignedSegment, not AlignedRead
• FastxFile, not FastqFile
• get_tag() / set_tag(), not opt() / setTag()
• get_reference_name() / get_tid(), not old PEP8-incompatible names
• pysam.CIGAR_OPS.CMATCH and related enum members, not top-level aliases

Compatibility aliases can remain in 0.24 but are poor foundations for new work.