| name | bioconductor-rsamtools |
| description | This package provides an interface to the 'samtools', 'bcftools', and 'tabix' utilities for manipulating SAM (Sequence Alignment / Map), FASTA, binary variant call (BCF) and compressed indexed tab-delimited (tabix) files. |
| when_to_use | Use when: Low-level Alignment Import: Importing and parsing BAM files directly into R lists or DataFrame objects using scanBam.; Targeted Read Extraction: Extracting specific genomic coordinates and alignment fields (e.g., read sequence, strand, position) using ScanBamParam.; BAM File Management: Managing collections of BAM files and their metadata programmatically using BamViews.; Coverage Calculation: Cal. Not for: For high-level representation of gapped alignments, use GenomicAlignments (specifically readGAlignments) because Rsamtools provides lower-level list-based outputs.; For iterating through BAM files in parallel, use GenomicFiles because it implements h |
| user-invocable | false |
Rsamtools
Dependencies & Environment
Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.
- Version: 2.28.0 · Bioconductor: 3.23 · R: ≥ 4.6
- Depends: Seqinfo, GenomicRanges, Biostrings
- Imports: BiocGenerics, S4Vectors, IRanges, XVector, bitops, BiocParallel
- System requirements: GNU make
- Install:
BiocManager::install("Rsamtools")
When to Use
- Low-level Alignment Import: Importing and parsing BAM files directly into R lists or
DataFrame objects using scanBam.
- Targeted Read Extraction: Extracting specific genomic coordinates and alignment fields (e.g., read sequence, strand, position) using
ScanBamParam.
- BAM File Management: Managing collections of BAM files and their metadata programmatically using
BamViews.
- Coverage Calculation: Calculating read coverage over specific genomic ranges using
coverage on imported BAM data.
When NOT to Use
- For high-level representation of gapped alignments, use
GenomicAlignments (specifically readGAlignments) because Rsamtools provides lower-level list-based outputs.
- For iterating through BAM files in parallel, use
GenomicFiles because it implements higher-level strategies for file iteration.
- For whole-genome manipulation and DNA sequence operations, use
Biostrings or BSgenome instead.
Data Requirements
- Input Format: BAM files (e.g.,
.bam) and their corresponding index files (.bai).
- Genomic Coordinates: Specified as
GRanges objects for targeted queries.
Key Parameters
- file: Path to the BAM file to be parsed by
scanBam.
- param: A
ScanBamParam object determining which genomic coordinates and components to input.
- which: A
GRanges object specifying the genomic ranges to extract.
- what: A character vector (e.g.,
c("rname", "pos", "qwidth")) specifying which BAM record fields to retrieve.
- flag: A filter created by
scanBamFlag (e.g., isUnmappedQuery=FALSE) to restrict reads.
- bamRanges: A
GRanges object defining the genomic rows for a BamViews instance.
Best Practices
- Always ensure a
.bai index file is available locally when querying specific ranges with the which argument.
- Restrict imported fields using the
what argument in ScanBamParam to minimize memory consumption.
- Process large BAM files in chunks (e.g., by chromosome) using summary functions to avoid memory exhaustion.
- Use
BamViews to marshal references to multiple BAM files without loading them immediately into memory.
Common Pitfalls
- Querying by range without an index: Fails because providing a
which argument to ScanBamParam requires a BAM index. Fix: Ensure the .bai file exists or create one using indexBam.
- "EOF marker is absent" warning: Occurs with some BAM files. Fix: This message can safely be ignored as noted in the vignette.
- Chromosome naming mismatches: Ensembl vs UCSC naming (e.g., "chr1" vs "1") causes empty queries. Fix: Use
seqlevels<- to map between naming schemes before querying.
Alternatives
- GenomicAlignments: Provides a more useful, higher-level representation of BAM files in R (e.g.,
GAlignments objects).
- GenomicFiles: Useful for iterating through BAM and other files, including in parallel.
- ShortRead: Better suited for I/O and quality assessment of ungapped short read alignments.
Citations
- Morgan M, Pagès H, Obenchain V, Hayden N. Rsamtools: Binary alignment (BAM), FASTA, variant call (BCF), and tabix file import. Bioconductor.
References
Run this on BioMate
This skill is the knowledge layer — when, why, and how to use rsamtools. To run this analysis on your own data with managed compute, automated QC, and reproducible outputs, use BioMate — free to start.
▶ Open rsamtools on BioMate →
