R: Views into a set of BAM files

BamViews {Rsamtools}

R Documentation

Views into a set of BAM files

Description

Use BamViews() to reference a set of disk-based BAM files to be processed (e.g., queried using scanBam) as a single ‘experiment’.

Usage


## Constructor
BamViews(bamPaths=character(0),
     bamIndicies=bamPaths,
     bamSamples=DataFrame(row.names=make.unique(basename(bamPaths))),
     bamRanges, bamExperiment = list(), ...)
## S4 method for signature 'missing'
BamViews(bamPaths=character(0),
     bamIndicies=bamPaths,
     bamSamples=DataFrame(row.names=make.unique(basename(bamPaths))),
     bamRanges, bamExperiment = list(), ..., auto.range=FALSE)
## Accessors
bamPaths(x)
bamSamples(x)
bamSamples(x) <- value
bamRanges(x)
bamRanges(x) <- value
bamExperiment(x)

## S4 method for signature 'BamViews'
names(x)
## S4 replacement method for signature 'BamViews'
names(x) <- value
## S4 method for signature 'BamViews'
dimnames(x)
## S4 replacement method for signature 'BamViews,ANY'
dimnames(x) <- value

bamDirname(x, ...) <- value

## Subset
## S4 method for signature 'BamViews,ANY,ANY'
x[i, j, ..., drop=TRUE]
## S4 method for signature 'BamViews,ANY,missing'
x[i, j, ..., drop=TRUE]
## S4 method for signature 'BamViews,missing,ANY'
x[i, j, ..., drop=TRUE]

## Input
## S4 method for signature 'BamViews'
scanBam(file, index = file, ...,
    param = ScanBamParam(what=scanBamWhat()))
## S4 method for signature 'BamViews'
countBam(file, index = file, ..., param = ScanBamParam())
## S4 method for signature 'BamViews'
readBamGappedAlignments(file, index=file, use.names=FALSE, param=NULL)

## Show
## S4 method for signature 'BamViews'
show(object)

## Counting
## S4 method for signature 'GRanges,BamViews'
summarizeOverlaps(
    features, reads, mode, ignore.strand = FALSE, ..., param = ScanBamParam())

Arguments

`bamPaths`	A character() vector of BAM path names.
`bamIndicies`	A character() vector of BAM index file path names, without the ‘.bai’ extension.
`bamSamples`	A `DataFrame` instance with as many rows as `length(bamPaths)`, containing sample information associated with each path.
`bamRanges`	A `GRanges`, `RangedData` or missing instance with ranges defined on the spaces of the BAM files. Ranges are not validated against the BAM files.
`bamExperiment`	A list() containing additional information about the experiment.
`auto.range`	If `TRUE` and all `bamPaths` exist, populate the ranges with the union of ranges returned in the `target` element of `scanBamHeader`.
`...`	Additional arguments.
`x`	An instance of `BamViews`.
`object`	An instance of `BamViews`.
`value`	An object of appropriate type to replace content.
`i`	During subsetting, a logical or numeric index into `bamRanges`.
`j`	During subsetting, a logical or numeric index into `bamSamples` and `bamPaths`.
`drop`	A logical(1), ignored by all `BamViews` subsetting methods.

`file`	An instance of `BamViews`.
`index`	A character vector of indices, corresponding to the `bamPaths(file)`.
`param`	An optional `ScanBamParam` instance to further influence scanning or counting.
`use.names`	Construct the names of the returned object from the query template names (QNAME field)? If not (the default), then the returned object has no names.
`reads`	A BamFileList that represents the data to be counted by summarizeOverlaps.
`features`	A GRanges or a GRangesList object of genomic regions of interest. When a GRanges is supplied, each row is considered a feature. When a GRangesList is supplied, each higher list-level is considered a feature. This distinction is important when defining an overlap between a read and a feature. See examples for details.
`mode`	A function that defines the method to be used when a read overlaps more than one feature. Pre-defined options are "Union", "IntersectionStrict", or "IntersectionNotEmpty" and are designed after the counting modes available in the HTSeq package by Simon Anders (see references). "Union" : (Default) Reads that overlap any portion of exactly one feature are counted. Reads that overlap multiple features are discarded. "IntersectionStrict" : A read must fall completely "within" the feature to be counted. If a read overlaps multiple features but falls "within" only one, the read is counted for that feature. If the read is "within" multiple features, the read is discarded. "IntersectionNotEmpty" : A read must fall in a unique disjoint region of a feature to be counted. When a read overlaps multiple features, the features are partitioned into disjoint intervals. Regions that are shared between the features are discarded leaving only the unique disjoint regions. If the read overlaps one of these remaining regions, it is assigned to the feature the unique disjoint region came from.
`ignore.strand`	A logical value indicating if strand should be considered when matching.

Objects from the Class

Objects are created by calls of the form BamViews().

Slots

bamPaths: A character() vector of BAM path names.
bamIndicies: A character() vector of BAM index path names.
bamSamples: A DataFrame instance with as many rows as length(bamPaths), containing sample information associated with each path.
bamRanges: A GRanges instance with ranges defined on the spaces of the BAM files. Ranges are not validated against the BAM files.
bamExperiment: A list() containing additional information about the experiment.

Functions and methods

See 'Usage' for details on invocation.

Constructor:

BamViews:: Returns a BamViews object.

Accessors:

bamPaths: Returns a character() vector of BAM path names.
bamIndicies: Returns a character() vector of BAM index path names.
bamSamples: Returns a DataFrame instance with as many rows as length(bamPaths), containing sample information associated with each path.
bamSamples<-: Assign a DataFrame instance with as many rows as length(bamPaths), containing sample information associated with each path.
bamRanges: Returns a GRanges instance with ranges defined on the spaces of the BAM files. Ranges are not validated against the BAM files.
bamRanges<-: Assign a GRanges instance with ranges defined on the spaces of the BAM files. Ranges are not validated against the BAM files.
bamExperiment: Returns a list() containing additional information about the experiment.
names: Return the column names of the BamViews instance; same as names(bamSamples(x)).
names<-: Assign the column names of the BamViews instance.
dimnames: Return the row and column names of the BamViews instance.
dimnames<-: Assign the row and column names of the BamViews instance.

Methods:

"[": Subset the object by bamRanges or bamSamples.
scanBam: Visit each path in bamPaths(file), returning the result of scanBam applied to the specified path. bamRanges(file) takes precedence over bamWhich(param).
countBam: Visit each path in bamPaths(file), returning the result of countBam applied to the specified path. bamRanges(file) takes precedence over bamWhich(param).
readBamGappedAlignments: Visit each path in bamPaths(file), returning the result of readBamGappedAlignments applied to the specified path. When index is missing, it is set equal to bamIndicies(file). Only reads in bamRanges(file) are returned (if param is supplied, bamRanges(file) takes precedence over bamWhich(param)). The return value is a SimpleList, with elements of the list corresponding to each path. bamSamples(file) is available as elementMetadata of the returned SimpleList.
show: Compactly display the object.

Author(s)

Martin Morgan

Examples


fls <- list.files(system.file("extdata", package="Rsamtools"),
                  "\\.bam$", full=TRUE)
rngs <- GRanges(seqnames = Rle(c("chr1", "chr2"), c(9, 9)),
                ranges = c(IRanges(seq(10000, 90000, 10000), width=500),
                           IRanges(seq(100000, 900000, 100000), width=5000)),
                Count = seq_len(18L))
v <- BamViews(fls, bamRanges=rngs)
v
v[1:5,]
bamRanges(v[c(1:5, 11:15),])
bamDirname(v) <- getwd()
v

bv <- BamViews(fls,
               bamSamples=DataFrame(info="test", row.names="ex1"),
               auto.range=TRUE)
aln <- readBamGappedAlignments(bv)
aln
aln[[1]]
aln[colnames(bv)]
elementMetadata(aln)

##---------------------------------------------------------------------------##
## How to use summarizeOverlaps with a BamViews object.
fls = list.files(system.file("extdata",package="GenomicRanges"),
                 recursive=TRUE, pattern="*bam$", full=TRUE)
bfs <- BamViews(fls)

## "features" will be the argument for an "annotations" object (GRanges
## or GRangesList object.
group_id <- c("A", "B", "C", "C", "D", "D", "E", "F", "G", "H", "H")
features <- GRanges(
    seqnames = Rle(c("chr2L", "chr2R", "chr2L", "chr2R", "chr2L", "chr2R", 
        "chr2L", "chr2R", "chr2R", "chr3L", "chr3L")),
    strand = strand(rep("+", length(group_id))),
    ranges = IRanges(
        start=c(1000, 2000, 3000, 3600, 7000, 7500, 4000, 4000, 3000, 5000, 5400),
        width=c(500, 900, 500, 300, 600, 300, 500, 900, 500, 500, 500)),
   DataFrame(group_id)
)
## Then call the method:
summarizeOverlaps(features, bfs, mode = Union, ignore.strand=TRUE)

[Package Rsamtools version 1.6.3 Index]