pysam
Über
Die pysam-Fähigkeit ermöglicht Python-Entwicklern die Arbeit mit genomischen Dateiformaten wie SAM/BAM, VCF und FASTA unter Verwendung von HTSlib-Bindungen. Sie bietet Low-Level-Streaming-Zugriff zum Lesen, Abfragen, Filtern und Schreiben von Daten, einschließlich spezialisierter Operationen wie Pileup-Analysen und Coverage-Berechnungen. Verwenden Sie diese Fähigkeit, wenn Sie programmatische Manipulation genomischer Dateien in Claudes Code-Umgebung benötigen.
Schnellinstallation
Claude Code
Empfohlennpx skills add K-Dense-AI/claude-scientific-skills -a claude-code/plugin add https://github.com/K-Dense-AI/claude-scientific-skillsgit clone https://github.com/K-Dense-AI/claude-scientific-skills.git ~/.claude/skills/pysamKopieren Sie diesen Befehl und fügen Sie ihn in Claude Code ein, um diese Fähigkeit zu installieren
Dokumentation
pysam
Overview
Use pysam for low-level, streaming access to HTSlib-supported genomic formats:
AlignmentFileandAlignedSegmentfor SAM/BAM/CRAMVariantFile,VariantHeader, andVariantRecordfor VCF/BCFFastaFilefor indexed FASTA andFastxFilefor sequential FASTA/FASTQTabixFilefor BGZF-compressed, tabix-indexed BED/GFF/GTF/custom tablespysam.samtoolsandpysam.bcftoolsfor wrapped command dispatchers
Current upstream baseline: pysam 0.24.1 (7 September 2026), wrapping
HTSlib/samtools/bcftools 1.24. Read references/sources.md before updating
version-specific guidance.
Installation
Use the pinned release for reproducible work:
uv pip install "pysam==0.24.1"
Confirm the runtime:
import pysam
print(pysam.__version__) # 0.24.1
print(pysam.__samtools_version__) # 1.24
Prebuilt wheels are available for supported macOS and Linux platforms. A
source build needs a C compiler and HTSlib build dependencies; read the
official installation guide linked from references/sources.md.
First Decide
Before writing code:
- Identify the real format, compression, sort order, and available index.
- Decide whether coordinates are numeric Python coordinates or a region string. Do not mix them.
- For CRAM, identify the exact reference assembly and FASTA.
- Prefer indexed region access; use sequential iteration only when intended.
- Preserve headers when writing and write to a new path by default.
- State filtering semantics: mapping/base quality, flags, overlap handling, duplicate handling, and pileup depth cap.
For unfamiliar files, start with the bundled read-only inspector:
python scripts/inspect_hts.py sample.bam
python scripts/inspect_hts.py cohort.vcf.gz
python scripts/inspect_hts.py reference.fa
Bundled Scripts
| Script | Purpose | Typical call |
|---|---|---|
scripts/inspect_hts.py | Metadata-only inspection for alignment, variant, FASTA, FASTQ, and tabix files | python scripts/inspect_hts.py sample.cram --reference ref.fa |
scripts/alignment_qc.py | Streaming aggregate read/QC counts as JSON | python scripts/alignment_qc.py sample.bam --max-records 100000 |
scripts/variant_summary.py | Streaming variant, FILTER, and genotype summary as JSON | python scripts/variant_summary.py cohort.vcf.gz --region chr1:1-1000000 |
scripts/filter_alignments.py | Filter SAM/BAM/CRAM without changing record order | python scripts/filter_alignments.py input.bam output.bam --exclude-secondary |
All scripts refuse to overwrite existing outputs. The filter also refuses stale
output indexes and offers --index --csi for large BAM contigs. FASTA inspection
requires an existing .fai; create it explicitly with pysam.faidx() first.
Run each with --help for coordinate, index, and privacy notes.
Examples use illustrative filenames and assay-specific thresholds. The local synthetic suite exercises these API patterns on pysam 0.24.1; remote storage and biological datasets are not part of that validation.
Coordinate Contract
Numeric coordinates accepted by pysam APIs are 0-based, half-open. This
includes numeric AlignmentFile.fetch(), VariantFile.fetch(),
FastaFile.fetch(), TabixFile.fetch(), and pileup() arguments.
Region strings are samtools-style: 1-based and inclusive.
# The same 100 bases:
bam.fetch("chr1", 99, 199) # [99, 199)
bam.fetch(region="chr1:100-199") # 1-based inclusive
VCF text uses 1-based POS, while record properties expose both systems:
record.pos # 1-based
record.start # 0-based inclusive
record.stop # 0-based exclusive
Read references/coordinates_and_indexing.md for format conversions, overlap
semantics, index choices, and contig-name checks.
Alignment Files
Use context managers and explicit modes:
import pysam
with pysam.AlignmentFile("sample.bam", "rb", threads=4) as bam:
for read in bam.fetch("chr1", 1_000, 2_000):
if (
not read.is_unmapped
and not read.is_secondary
and not read.is_supplementary
and read.mapping_quality >= 30
):
print(read.query_name, read.reference_start, read.cigarstring)
Use fetch(until_eof=True) to stream every record in file order, including
unplaced unmapped reads, without requiring an index:
with pysam.AlignmentFile("sample.bam", "rb") as bam:
for read in bam.fetch(until_eof=True):
...
Important distinctions:
fetch()returns placed alignment records overlapping a region; even an unmapped-flagged record can have a reference position. Filteris_unmapped.count()counts records and defaults toread_callback="nofilter".count_coverage()returns A/C/G/T base counts and defaults to base quality 15 plusread_callback="all".pileup()exposes per-column reads and has its own filtering, base-quality, overlap, orphan, andmax_depth=8000defaults.
For exact-region pileups, set truncate=True and explicit filters:
with pysam.FastaFile("reference.fa") as fasta, pysam.AlignmentFile(
"sample.bam", "rb"
) as bam:
for column in bam.pileup(
"chr1",
1_000,
2_000,
truncate=True,
stepper="samtools",
fastafile=fasta,
min_mapping_quality=20,
min_base_quality=20,
max_depth=100_000,
):
base_depth = sum(
not item.is_del and not item.is_refskip
and item.query_position is not None
for item in column.pileups
)
print(column.reference_pos, base_depth)
Read references/alignment_files.md for flags, CIGAR operations, tags,
modified bases, writing records, pileup details, and iterator lifetime.
Variant Files
Input format is auto-detected. Numeric fetch coordinates remain 0-based:
import pysam
with pysam.VariantFile("cohort.vcf.gz", threads=4) as variants:
for record in variants.fetch("chr1", 999_999, 2_000_000):
print(record.contig, record.pos, record.ref, record.alts)
for sample_name, call in record.samples.items():
print(sample_name, call.get("GT"))
Subset samples before retrieving records:
with pysam.VariantFile("cohort.bcf") as variants:
variants.subset_samples(["sample_A", "sample_B"])
for record in variants:
...
When changing a header, copy each record and translate it to the destination
header before assigning newly declared INFO/FORMAT/FILTER fields. Do not
manually clear and rebuild header.samples.
Read references/variant_files.md for safe headers, writing, sample
subsetting, missing genotypes, symbolic alleles, filtering, translation, and
indexing.
FASTA, FASTQ, and Tabix
Indexed FASTA uses numeric 0-based coordinates:
with pysam.FastaFile("reference.fa") as fasta:
sequence = fasta.fetch("chr1", 999, 1_099)
FastxFile is sequential. persist=False is faster but yielded records become
invalid after iteration advances:
with pysam.FastxFile("reads.fastq.gz", persist=False) as reads:
for read in reads:
qualities = read.get_quality_array()
...
Tabix input must be coordinate-sorted and BGZF-compressed, not ordinary gzip. Use a non-destructive two-step workflow:
pysam.tabix_compress("regions.bed", "regions.bed.gz")
pysam.tabix_index("regions.bed.gz", preset="bed")
with pysam.TabixFile("regions.bed.gz", parser=pysam.asBed()) as tbx:
for interval in tbx.fetch("chr1", 1_000, 2_000):
print(interval.contig, interval.start, interval.end)
Read references/sequence_files.md for FASTA/FASTQ records and safe tabix
creation.
CRAM, Remote I/O, and Threads
pysam 0.24 changed inherited HTSlib behavior:
- Newly written CRAM defaults to CRAM 3.1, not 3.0.
- HTSlib no longer contacts the EBI reference server by default.
- Prefer
reference_filename="reference.fa"for deterministic local reads and writes.
with pysam.AlignmentFile(
"sample.cram",
"rc",
reference_filename="reference.fa",
threads=4,
) as cram:
for read in cram.fetch("chr1", 1_000, 2_000):
...
Only configure REF_PATH/REF_CACHE when reference-by-MD5 lookup is
intentional. Do not assume a CRAM is self-contained. threads= accelerates
compression/decompression; it does not parallelize Python analysis.
Read references/cram_and_performance.md before CRAM conversion, remote access,
or concurrent iteration.
Wrapped samtools and bcftools
Import command modules explicitly. Pass each command-line token as a separate string:
import pysam.samtools
import pysam.bcftools
pysam.samtools.sort(
"-@", "4", "-o", "sorted.bam", "input.bam", catch_stdout=False
)
pysam.samtools.index("-@", "4", "sorted.bam", catch_stdout=False)
pysam.bcftools.index("--csi", "variants.vcf.gz", catch_stdout=False)
Dispatchers capture stdout by default. For large or binary output, use the
tool's -o option with catch_stdout=False, or save_stdout=..., rather than
returning the complete output in memory.
try:
pysam.samtools.quickcheck("-v", "sample.bam")
except pysam.SamtoolsError as error:
# The exception contains current stderr; get_messages() can be stale
# after failure in 0.24.1.
raise RuntimeError(str(error)) from error
Use the Python API for record-level logic and dispatchers for mature bulk operations such as sort, index, merge, view, and normalization. Never compose dispatcher arguments by splitting an untrusted shell command.
Writing Rules
- Copy or construct a valid header before opening output.
- Write to a new path; do not use
force=Trueunless replacement is explicit. - Preserve sort order if the output will be indexed.
- Set
query_sequencebeforequery_qualities. - Prefer
pysam.CIGAR_OPSenum members; top-level constants such aspysam.CMATCHare compatibility aliases slated for future removal. - Use
pysam.samtools.quickcheck()as a fast alignment header/EOF preflight; it does not read the middle of the file and cannot rule out internal corruption. When full readability must be established, perform a complete sequential decode with the matching CRAM reference and compare expected counts/checksums. Reopen variant/sequence outputs before downstream use. See the samtools quickcheck contract. - Use CSI rather than BAI/TBI when references or coordinates exceed legacy index limits.
Reference Map
| Need | Read |
|---|---|
| Alignment API, flags, CIGAR, pileup, modified bases | references/alignment_files.md |
| VCF/BCF headers, records, samples, writing | references/variant_files.md |
| FASTA/FASTQ and tabix-indexed tables | references/sequence_files.md |
| Coordinate conversion and index selection | references/coordinates_and_indexing.md |
| CRAM references, remote I/O, threads, performance | references/cram_and_performance.md |
| Correct integrated analysis patterns | references/common_workflows.md |
| Compact current API signatures and defaults | references/api_reference.md |
| Upgrade notes for existing environments | references/migration_to_0_24.md |
| Official docs, specifications, and release sources | references/sources.md |
Common Failure Modes
- Treating numeric
VariantFile.fetch()coordinates as 1-based - Using ordinary gzip where BGZF plus tabix/CSI is required
- Calling region fetch without an index
- Assuming
fetch()includes unplaced unmapped alignments - Forgetting
truncate=Truefor an exact pileup interval - Ignoring pileup defaults such as base quality 13 and depth cap 8000
- Sharing one file handle across active iterators or threads
- Decoding CRAM without its exact reference
- Assigning a new VCF field before declaring it in the output header
- Capturing large samtools/bcftools output in memory
- Using a SNP base-counting method for indels or symbolic alleles
Citing Scientific Agent Skills
This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a manuscript, report, presentation, or code release, add the paper to the references or software section and tell the user you did so:
Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065
Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the
latest arXiv version, so never append a version suffix such as v1. When network access is
available, fetch https://arxiv.org/abs/2609.00065 (or
http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take
the author list, year, and version from that record. If the record lists a journal reference
or publisher DOI, cite the published version instead.
GitHub Repository
Häufig gestellte Fragen
Was ist der Skill pysam?
pysam ist ein Claude Skill von K-Dense-AI. Skills bündeln Anweisungen und Ressourcen, die Claude bei Bedarf lädt, um Aufgaben rund um pysam ohne zusätzliche Eingaben auszuführen.
Wie installiere ich pysam?
Verwende die Installationsbefehle auf dieser Seite: Füge pysam als Plugin zu Claude Code hinzu oder klone das Repository in dein Skills-Verzeichnis. Starte Claude danach neu, damit der Skill geladen wird.
Zu welcher Kategorie gehört pysam?
pysam gehört zur Kategorie Andere.
Kann ich pysam kostenlos nutzen?
Ja. pysam ist auf AIMCP gelistet und kann kostenlos installiert werden.
Verwandte Skills
Diese Claude Skill analysiert Sportwettenmärkte inklusive Handicaps, Over/Unders und Spezialwetten, indem sie historische Trends und situative Statistiken untersucht, um Wertwetten zu identifizieren. Sie liefert strukturierte Markdown-Ausgaben mit umsetzbaren Empfehlungen zu Bildungszwecken. Entwickler sollten dies für Sportwetten-Analysetools nutzen, wobei zu beachten ist, dass es nur zur Unterhaltung/Bildung konzipiert wurde.
LlamaGuard ist Metas 7-8B-Parameter-Modell zur Moderation von LLM-Eingaben und -Ausgaben in sechs Sicherheitskategorien wie Gewalt und Hassrede. Es bietet eine Genauigkeit von 94-95 % und kann mit vLLM, Hugging Face oder Amazon SageMaker eingesetzt werden. Nutzen Sie diese Skill, um Inhaltsfilterung und Sicherheitsguardrails einfach in Ihre KI-Anwendungen zu integrieren.
Diese Claude Skill unterstützt Entwickler bei der Optimierung von Cloud-Kosten durch Ressourcen-Dimensionierung, Tagging-Strategien und Ausgabenanalysen. Sie bietet einen Rahmen zur Senkung von Cloud-Ausgaben und zur Implementierung von Kosten-Governance für AWS, Azure und GCP. Nutzen Sie sie, wenn Sie Infrastrukturkosten analysieren, Ressourcen richtig dimensionieren oder Budgetvorgaben einhalten müssen.
Diese Fähigkeit quantisiert LLMs auf 8-Bit- oder 4-Bit-Präzision mittels bitsandbytes und erreicht dabei eine Speicherreduzierung von 50–75 % bei minimalem Genauigkeitsverlust. Sie ist ideal für den Betrieb größerer Modelle mit begrenztem GPU-Speicher oder zur Beschleunigung von Inferenzvorgängen und unterstützt Formate wie INT8, NF4 und FP4. Die Fähigkeit integriert sich in HuggingFace Transformers und ermöglicht QLoRA-Training sowie 8-Bit-Optimierer.
