AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

pysam

Provides Python/HTSlib workflows for genomic files. Used when reading, querying, filtering, or writing SAM/BAM/CRAM, VCF/BCF, FASTA/FASTQ, or tabix data with pysam, including pileup, coverage, indexing, and CRAM references.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--pysam at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/api_reference.md

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:

| Option | Default | Meaning | |---|---:|---| | truncate | False | limit columns to exact query interval | | max_depth | 8000 | maximum depth | | stepper | "samtools" in current implementation/docs context | read filtering/processing mode | | fastafile | None | reference for BAQ/samtools behavior | | ignore_overlaps | True | adjust qualities of overlapping paired bases | | ignore_orphans | True | exclude improper paired orphans | | flag_filter | unmapped, secondary, QC-fail, duplicate | excluded flags | | flag_require | 0 | required flags | | min_base_quality | 13 | base-quality threshold | | min_mapping_quality | 0 | mapping-quality threshold | | compute_baq | True | compute BAQ when reference is available | | redo_baq | False | recompute existing BAQ |

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.