Authoritative Sources

Last researched: 2026-10-01

Skill baseline: pysam 0.24.1, released 2026-09-07, wrapping HTSlib/samtools/bcftools 1.24.

Use these sources in priority order when refreshing this skill. Do not assume that the newest standalone HTSlib release is the version embedded in the current pysam wheel.

Pysam Release and Package Metadata

• pysam on PyPI — current published version, release date, wheels, release history, and provenance attestations
• Pysam release notes — 0.24 CRAM changes, Python support, bundled component versions, bug fixes, and deprecations
• pysam-developers/pysam — upstream source and current development state
• pysam 0.24.1 source tag — version-specific implementation and tests

As of the research date, PyPI identifies 0.24.1 as latest. The 0.24 release notes state:

• tested Python versions: 3.9 through 3.15 (RC2)
• wheels: macOS and Linux, ARM and x86-64
• bundled HTSlib/samtools/bcftools: 1.24
• default newly written CRAM: 3.1
• implicit EBI CRAM reference fetching: removed
• format_options: Python str values work as documented
• top-level CIGAR constants remain compatibility aliases; prefer pysam.CIGAR_OPS

Re-check all of these before changing the version pin.

Official Pysam Documentation

• Documentation index
• Installation
• Usage guide
• API reference
• FAQ
• Release notes
• Glossary

Use the API reference for signatures and documented defaults. Use the FAQ for iterator lifetime, threading, coordinate, pileup, and quality-editing behavior. Where prose in the older usage guide conflicts with the current API, verify against the 0.24 source/tests and installed runtime.

One known example: a real Python file object exposing fileno() works with AlignmentFile, while io.BytesIO does not. The API constructor documents file-object support; the usage guide's broad statement about "true python file objects" is too general.

Bundled Tool Manuals

Pysam 0.24 wraps the 1.24 tool line. Consult manuals matching that line when using dispatchers:

• samtools 1.24 manual
• bcftools 1.24 manual
• tabix 1.24 manual
• bgzip 1.24 manual
• faidx 1.24 format/manual
• HTSlib documentation index

Pysam dispatchers emulate command-line subcommands but capture stdout/stderr. The pysam usage guide, not only the tool manual, defines catch_stdout, save_stdout, split_lines, get_messages(), and SamtoolsError.

CRAM References

• Pysam 0.24 release notes — CRAM 3.1 default and removal of implicit EBI lookup
• Samtools reference-sequence guidance — CRAM reference search order and REF_PATH/REF_CACHE
• Using CRAM within Samtools — reference-based compression, M5 tags, local caches, and workflow concepts

The older CRAM workflow page describes historical fallback to EBI. For pysam 0.24/HTSlib 1.24 behavior, the 0.24 release notes and matching samtools manual take precedence: implicit EBI lookup is no longer the default.

Canonical Format Specifications

• HTS format specifications index
• SAM/BAM and BAI specification
• SAM optional tags specification
• CRAM 3 specification
• VCF 4.5 specification
• BCF 2 quick reference
• Tabix index specification
• CSI specification
• BED 1 specification

Use format specifications for coordinate fields, flags, tags, header semantics, binary encodings, and index limits. Use pysam documentation for how those concepts are translated into Python properties.

Source and Runtime Discrepancies Verified in 0.24.1

The current release notes, API, installation guide, usage guide, FAQ, 1.24 manuals, and the tagged Cython implementation were reviewed. Key source files:

• Alignment iteration, coverage, CRAM and pileup
• CIGAR, sequence orientation and pileup columns
• Variants, headers, fetch and write modes
• FASTA/FASTQ index and bounds behavior
• Tabix constructor, indexes and parsers
• Dispatcher error and message handling

Native synthetic tests on macOS/Python 3.13.3 confirmed:

• Alignment fetch can return placed unmapped records; no-region variant fetch rewinds and streams without an index.
• get_num_aligned() includes D/N entries; actual base depth needs exclusions.
• count_coverage sizes arrays from numeric start/stop, clips at the contig, and does not derive array bounds from region/end aliases.
• CRAI index counters are unavailable, not observed zero-read counts.
• FastaFile can create an implicit index; explicit index paths prevent it. End overruns clip rather than reliably raising.
• Tabix CSI requires index=; the loaded path is filename_index, and the 0.24.1 implementation resets threads to 1.
• wbu raises; wb0 is level-zero BGZF BCF. Appending a fileformat meta-line to a fresh VariantHeader duplicates the version line.
• get_messages() may be stale after a dispatcher exception; use the exception.

The per-skill tests generate tiny SAM/BAM/CRAM, VCF/BCF, FASTA/FASTQ and BGZF/tabix fixtures. No clinical or other biological result is validated. Linux networking-library loading, authenticated remote storage, institutional reference caches, and Cython extension ABI builds were not executed. The example.org remote-I/O URLs are explicitly illustrative, not service APIs.

Refresh Checklist

When updating:

1. Check PyPI for the newest published pysam.
2. Read all release notes since the pinned version.
3. Record the embedded HTSlib/samtools/bcftools version.
4. Verify supported Python versions and wheel platforms.
5. Re-check CRAM defaults and reference lookup.
6. Compare API signatures in api.html and the tagged source.
7. Run bundled scripts against the new version.
8. Re-run Agent Skills validation and the security scanner.