Import, count, index, filter, sort, and merge `BAM' (binary alignment) files.
Import binary `BAM' files into a list structure, with facilities for selecting what fields and which records are imported, and other operations to manipulate BAM files.
scanBam(file, index=file, ..., param=ScanBamParam(what=scanBamWhat()))countBam(file, index=file, ..., param=ScanBamParam())scanBamHeader(files, ...) "scanBamHeader"(files, ...)asBam(file, destination, ...) "asBam"(file, destination, ..., overwrite=FALSE, indexDestination=TRUE)asSam(file, destination, ...) "asSam"(file, destination, ..., overwrite=FALSE)filterBam(file, destination, index=file, ...) "filterBam"(file, destination, index=file, ..., filter=FilterRules(), indexDestination=TRUE, param=ScanBamParam(what=scanBamWhat())) sortBam(file, destination, ...) "sortBam"(file, destination, ..., byQname=FALSE, maxMemory=512)indexBam(files, ...) "indexBam"(files, ...)mergeBam(files, destination, ...) "mergeBam"(files, destination, ..., region = RangedData(), overwrite = FALSE, header = character(), byQname = FALSE, addRG = FALSE, compressLevel1 = FALSE, indexDestination = FALSE)
- The character(1) file name of the `BAM' ('SAM' for
asBam) file to be processed.
- The character() file names of the `BAM' file to be
mergeBam, must satisfy
length(files) >= 2.
- The character(1) name of the index file of the 'BAM' file being processed; this is given without the '.bai' extension.
- The character(1) file name of the location where
the sorted, filtered, or merged output file will be created. For
sortBamthis is without the .bam file suffix.
- A RangedData() instance with
>= 1rows, specifying the region of the BAM files to merged.
- Additional arguments, passed to methods.
- A logical(1) indicating whether the destination can be over-written if it already exists.
FilterRulesinstance allowing users to filter BAM files based on arbitrary criteria, as described below.
- A logical(1) indicating whether the created destination file should also be indexed.
- A logical(1) indicating whether the sorted destination file should be sorted by Query-name (TRUE) or by mapping position (FALSE).
- A character(1) file path for the header information to be used in the merged BAM file.
- A logical(1) indicating whether the file name should be used as RG (read group) tag in the merged BAM file.
- A logical(1) indicating whether the merged BAM file should be compressed to zip level 1.
- A numerical(1) indicating the maximal amount of memory (in MB) that the function is allowed to use.
- An instance of
ScanBamParam. This influences what fields and which records are imported.
scanBam function parses binary BAM files; text SAM files
can be parsed using R's
scan function, especially with
what to control the fields that are parsed.
countBam returns a count of records consistent with
scanBamHeader visits the header information in a BAM file,
returning for each file a list containing elements
text, as described below. The SAM / BAM specification does not
require that the content of the header be consistent with the content
of the file, e.g., more targets may be present that are represented by
reads in the file. An optional character vector argument containing
one or two elements of
what=c("targets", "text") can be used to
specify which elements of the header are returned.
asBam converts 'SAM' files to 'BAM' files, equivalent to
samtools view -Sb file > destination. The 'BAM' file is sorted
and an index created on the destination (with extension '.bai') when
asSam converts 'BAM' files to 'SAM' files, equivalent to
samtools view file > destination.
filterBam parses records in
file. Records satisfying the
bamSimpleCigar criteria of
param are accumulated to a default of
1000000 records (change this by specifying
BamFile instance; see
BamFile-class). These records are then parsed to
DataFrame and made available for further filtering by
FilterRules. Functions in the
instance should expect a single
DataFrame argument representing
all information specified by
param. Each function must return a
logical vector equal to the number of rows of the
DataFrame. Return values are used to include (when
corresponding records in the filtered BAM file. The BAM file is
destination. An index file is created on the
indexDestination=TRUE. It is more space- and
time-efficient to filter use
bamSimpleCigar, if appropriate, than to supply
sortBam sorts the BAM file given as its first argument,
analogous to the samtools sort function.
indexBam creates an index for each BAM file specified,
analogous to the samtools index function.
mergeBam merges 2 or more sorted BAM files. As with samtools,
the RG (read group) dictionary in the header of the BAM files is not
Details of the
ScanBamParam class are provide on its help page;
several salient points are reiterated here.
contain a field
what, specifying the components of the BAM
records to be returned. Valid values of
what are available with
ScanBamParam can contain an argument
which that specifies a subset of reads to return. This requires
that the BAM file be indexed, and that the file be named following
samtools convention as
can contain an argument
tag to specify which tags will be
- qname: This is the QNAME field in SAM Spec v1.4. The query name, i.e., identifier, associated with the read.
- flag: This is the FLAG field in SAM Spec v1.4.
A numeric value summarizing details of the read. See
- rname: This is the RNAME field in SAM Spec v1.4. The name of the reference to which the read is aligned.
- strand: The strand to which the read is aligned.
- pos: This is the POS field in SAM Spec v1.4.
The genomic coordinate at the start of the alignment.
Coordinates are `left-most', i.e., at the 3' end of a
read on the '-' strand, and 1-based. The position excludes
clipped nucleotides, even though soft-clipped nucleotides are
- qwidth: The width of the query, as calculated from the
cigarencoding; normally equal to the width of the query returned in
- mapq: This is the MAPQ field in SAM Spec v1.4. The MAPping Quality.
- cigar: This is the CIGAR field in SAM Spec v1.4. The CIGAR string.
- mrnm: This is the RNEXT field in SAM Spec v1.4. The reference to which the mate (of a paired end or mate pair read) aligns.
- mpos: This is the PNEXT field in SAM Spec v1.4. The position to which the mate aligns.
- isize: This is the TLEN field in SAM Spec v1.4. Inferred insert size for paired end alignments.
- seq: This is the SEQ field in SAM Spec v1.4. The query sequence, in the 5' to 3' orientation. If aligned to the minus strand, it is the reverse complement of the original sequence.
- qual: This is the QUAL field in SAM Spec v1.4.
Phred-encoded, phred-scaled base quality score, oriented as
- groupid: This is an integer vector of unique group ids
asMates=TRUEin a BamFile object.
groupidvalues are used to create the partitioning for a
- mate_status: Returned (always) when
asMates=TRUEin a BamFile object. This is a factor indicating status (
unmated) of each record.
scanBam,character-methodreturns a list of lists. The outer list groups results from each
bamWhich(param); the outer list is of length one when
bamWhich(param)has length 0. Each inner list contains elements named after
scanBamWhat(); elements omitted from
bamWhat(param)are removed. The content of non-null elements are as follows, taken from the description in the samtools API documentation:
scanBamHeaderreturns a list, with one element for each file named in
files. The list contains two element. The
targetselement contains target (reference) sequence lengths. The
textelement is itself a list with each element a list corresponding to tags (e.g., @SQ) found in the header, and the associated tag values.
asSamreturn the file name of the destination file.
sortBamreturns the file name of the sorted file.
indexBamreturns the file name of the index file created.
filterBamreturns the file name of the destination file created.
fl <- system.file("extdata", "ex1.bam", package="Rsamtools", mustWork=TRUE) ## ## scanBam ## res0 <- scanBam(fl)[] # always list-of-lists names(res0) length(res0[["qname"]]) lapply(res0, head, 3) table(width(res0[["seq"]])) # query widths table(res0[["qwidth"]], useNA="always") # query widths derived from cigar table(res0[["cigar"]], useNA="always") table(res0[["strand"]], useNA="always") table(res0[["flag"]], useNA="always") which <- RangesList(seq1=IRanges(1000, 2000), seq2=IRanges(c(100, 1000), c(1000, 2000))) p1 <- ScanBamParam(which=which, what=scanBamWhat()) res1 <- scanBam(fl, param=p1) names(res1) names(res1[]) p2 <- ScanBamParam(what=c("rname", "strand", "pos", "qwidth")) res2 <- scanBam(fl, param=p2) p3 <- ScanBamParam( what="flag", # information to query from BAM file flag=scanBamFlag(isMinusStrand=FALSE)) length(scanBam(fl, param=p3)[]$flag) ## ## filterBam ## param <- ScanBamParam( flag=scanBamFlag(isUnmappedQuery=FALSE), what="seq") dest <- filterBam(fl, tempfile(), param=param) countBam(dest) ## 3271 records filt <- list(MinWidth = function(x) width(x$seq) > 35) dest <- filterBam(fl, tempfile(), param=param, filter=FilterRules(filt)) countBam(dest) ## 398 records res3 <- scanBam(dest, param=ScanBamParam(what="seq"))[] table(width(res3$seq)) ## ## sortBam ## sorted <- sortBam(fl, tempfile()) ## ## scanBamParam re-orders 'which'; recover original order ## gwhich <- as(which, "GRanges")[c(2, 1, 3)] # example data cnt <- countBam(fl, param=ScanBamParam(which=gwhich)) reorderIdx <- unlist(split(seq_along(gwhich), seqnames(gwhich))) cnt cnt[reorderIdx,]