Skip to content

K-Dense-AI/scientific-agent-skills / 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.

references/api_reference.md

View on GitHub
# 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

```python
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:

```python
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:

```python
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

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

Core methods:

```python
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`:

```python
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

```python
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`.

```python
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

```python
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:

```python
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:

```python
import pysam.samtools
import pysam.bcftools
```

Each dispatcher has:

```python
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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall