K-Dense-AI/scientific-agent-skills / skills/pysam
pysam
VerifiedProvides 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.3 KB |
| references/alignment_files.md | markdown | 13.2 KB |
| references/api_reference.md | markdown | 10.2 KB |
| references/common_workflows.md | markdown | 13.8 KB |
| references/coordinates_and_indexing.md | markdown | 8.8 KB |
| references/cram_and_performance.md | markdown | 9.4 KB |
| references/migration_to_0_24.md | markdown | 5.4 KB |
| references/sequence_files.md | markdown | 9.3 KB |
| references/sources.md | markdown | 7.5 KB |
| references/variant_files.md | markdown | 11.7 KB |
| scripts/alignment_qc.py | script | 10.6 KB |
| scripts/filter_alignments.py | script | 12.4 KB |
| scripts/inspect_hts.py | script | 14.2 KB |
| scripts/variant_summary.py | script | 11.6 KB |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |