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 'BamViews,missing'
summarizeOverlaps(
    features, reads, mode, ignore.strand=FALSE, ..., singleEnd=TRUE, 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

Missing when a BamViews is the only argument supplied to summarizeOverlaps. reads are the files specified in bamPaths of the BamViews object.

features

A BamFileList. features are extracted from the bamRanges of the BamViews object.

Metadata from bamPaths and bamSamples are stored in the colData slot of the SummarizedExperiment object. bamExperiment metadata are in the exptData slot.

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.

singleEnd

A logical value indicating if the bam files contain single or paired-end reads.

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 metadata columns (accessed with mcols) of the returned SimpleList.

show

Compactly display the object.

Author(s)

Martin Morgan

See Also

readBamGappedAlignments. The GenomicRanges package is where the summarizeOverlaps method originates.

Examples

fls <- system.file("extdata", "ex1.bam", package="Rsamtools",
                   mustWork=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)]
mcols(aln)

##---------------------------------------------------------------------------
## summarizeOverlaps with BamViews
##

## bamSamples and bamPaths metadata are put into the colData
## and the bamExperiment metadata is put into the exptData slot
## of the resulting SummarizedExperiment.
fl <- system.file("extdata", "ex1.bam", package="Rsamtools",
                  mustWork=TRUE)
rng <- GRanges(c("seq1", "seq2"), IRanges(1, c(1575, 1584)))
bv <- BamViews(fl, bamSamples=DataFrame(info="test", row.names="ex1"),
               bamRanges=rng)
se <- summarizeOverlaps(bv, mode=Union, ignore.strand=TRUE)
colData(se)

[Package Rsamtools version 1.12.0 Index]