| GAlignmentsList-class {GenomicRanges} | R Documentation |
The GAlignmentsList class is a container for storing a collection of GAlignments objects.
A GAlignmentsList object contains a list of GAlignments objects.
The majority of operations on this page are described in more detail
on the GAlignments man page, see ?GAlignments.
GAlignmentsList(...):
Creates a GAlignmentsList from a list of GAlignments objects.
readGAlignmentsList(file, format="BAM", use.names=FALSE, ...):
Read a file containing aligned reads as a GAlignmentsList object.
Note that this function is just a front-end that delegates to the
readGAlignmentsListFromBam function defined
in the Rsamtools package.
See ?readGAlignmentsListFromBam for
more information.
The param described on the
readGAlignmentsListFromBam man page fine tunes
which records are returned and how they are grouped. param is
specified by the standard ScanBamParam() options.
makeGAlignmentsListFromFeatureFragments(seqnames=Rle(factor()),
fragmentPos=list(),
fragmentCigar=list(),
strand=character(0),
sep=","):
Constructs a GAlignmentsList from a list of fragmented features.
In the code snippets below, x is a GAlignmentsList object.
length(x):
Return the number of elements in x.
names(x), names(x) <- value:
Get or set the names of the elements of x.
seqnames(x), seqnames(x) <- value:
Get or set the name of the reference sequences of the
alignments in each element of x.
rname(x), rname(x) <- value:
Same as seqnames(x) and seqnames(x) <- value.
strand(x), strand(x) <- value:
Get or set the strand of the alignments in each element
of x.
cigar(x):
Returns a character list of length length(x)
containing the CIGAR string for the alignments in
each element of x.
qwidth(x):
Returns an integer list of length length(x)
containing the length of the alignments in each element of
x *after* hard clipping (i.e. the length of the
query sequence that is stored in the corresponding SAM/BAM record).
start(x), end(x):
Returns an integer list of length length(x)
containing the "start" and "end" (respectively) of the
alignments in each element of x.
width(x):
Returns an integer list of length length(x) containing
the "width" of the alignments in each element of x.
ngap(x):
Returns an integer list of length x containing the number
of gaps (i.e. N operations in the CIGAR) for the alignments
in each element of x.
seqinfo(x), seqinfo(x) <- value:
Get or set the information about the underlying sequences in each
element of x. value must be a list of Seqinfo
objects.
seqlevels(x), seqlevels(x) <- value:
Get or set the sequence levels of the alignments in each element
of x.
seqlengths(x), seqlengths(x) <- value:
Get or set the sequence lengths for each element of x.
seqlengths(x) is equivalent to seqlengths(seqinfo(x)).
value can be a named non-negative integer or numeric vector
eventually with NAs.
isCircular(x), isCircular(x) <- value:
Get or set the circularity flags for the alignments in each
element in x. value must be a named logical list
eventually with NAs.
genome(x), genome(x) <- value:
Get or set the genome identifier or assembly name for the alignments
in each element of x. value must be a named character
list eventually with NAs.
seqnameStyle(x):
Get or set the seqname style for alignments in each element of x.
In the code snippets below, x is a GAlignmentsList object.
granges(x, ignore.strand=FALSE),
ranges(x):
Return either a GRanges or a IRanges
object of length length(x). Note this coercion IGNORES
the cigar information. The resulting ranges span the entire
range, including any gaps or spaces between paired-end reads.
granges coercion supports ignore.strand to allow
ranges of opposite strand to be combined (see examples). All
ranges in the resulting GRanges will have strand ‘*’.
grglist(x, ignore.strand=FALSE),
rglist(x):
Return either a GRangesList or a IRangesList
object of length length(x). This coercion RESPECTS the cigar
information. The resulting ranges are fragments of the original ranges
that do not include gaps or spaces between paired-end reads.
grglist coercion supports ignore.strand to allow
ranges of opposite strand to be combined (see examples). All
ranges in the resulting GRangesList will have strand ‘*’.
as(x, "GRangesList"), as(x, "GRanges"),
as(x, "RangesList"), as(x, "Ranges"):
Alternate ways of doing grglist(x), granges(x),
rglist(x), ranges(x), respectively.
as(x, "GALignmentsList"): Return a GAlignmentsList object of
length length(x) where the i-th list element represents the ranges
of the i-th alignment pair in x.
In the code snippets below, x is a GAlignmentsList object.
x[i], x[i] <- value:
Get or set list elements i. i can be a numeric
or logical vector. value must be a GAlignments.
x[[i]], x[[i]] <- value:
Same as x[i], x[i] <- value.
x[i, j], x[i, j] <- value:
Get or set list elements i with optional metadata columns
j. i can be a numeric, logical or missing.
value must be a GAlignments.
c(...):
Concatenates the GAlignmentsList objects in ....
In the code snippets below, x is a GAlignmentsList object.
qnarrow(x, start=NA, end=NA, width=NA):
Return a new GAlignmentsList object of the same length as x
describing how the narrowed query sequences align to the reference.
The start/end/width arguments describe how
to narrow the query sequences. They must be vectors of integers.
NAs and negative values are accepted and "solved" according to the
rules of the SEW (Start/End/Width) interface (see
?solveUserSEW for the details).
Valerie Obenchain <vobencha@fhcrc.org
http://samtools.sourceforge.net/
gal1 <- GAlignments(
seqnames=Rle(factor(c("chr1", "chr2", "chr1", "chr3")),
c(1, 3, 2, 4)),
pos=1:10, cigar=paste0(10:1, "M"),
strand=Rle(strand(c("-", "+", "*", "+", "-")), c(1, 2, 2, 3, 2)),
names=head(letters, 10), score=1:10)
gal2 <- GAlignments(
seqnames=Rle(factor(c("chr2", "chr4")), c(3, 4)), pos=1:7,
cigar=c("5M", "3M2N3M2N3M", "5M", "10M", "5M1N4M", "8M2N1M", "5M"),
strand=Rle(strand(c("-", "+")), c(4, 3)),
names=tail(letters, 7), score=1:7)
galist <- GAlignmentsList(noGaps=gal1, Gaps=gal2)
## ---------------------------------------------------------------------
## A. BASIC MANIPULATION
## ---------------------------------------------------------------------
length(galist)
names(galist)
seqnames(galist)
strand(galist)
head(cigar(galist))
head(qwidth(galist))
head(start(galist))
head(end(galist))
head(width(galist))
head(ngap(galist))
seqlevels(galist)
## Rename the reference sequences:
seqlevels(galist) <- sub("chr", "seq", seqlevels(galist))
seqlevels(galist)
grglist(galist) # a GRangesList object
rglist(galist) # an IRangesList object
## ---------------------------------------------------------------------
## B. SUBSETTING
## ---------------------------------------------------------------------
galist[strand(galist) == "-"]
gaps <- sapply(galist, function(x) any(grepl("N", cigar(x), fixed=TRUE)))
galist[gaps]
## Different ways to subset:
galist[2] # a GAlignments object of length 1
galist[[2]] # a GAlignments object of length 1
grglist(galist[2]) # a GRangesList object of length 1
rglist(galist[2]) # a NormalIRangesList object of length 1
## ---------------------------------------------------------------------
## C. mcols()/elementMetadata()
## ---------------------------------------------------------------------
## Metadata can be defined on the individual GAlignment elements
## and the overall GAlignmentsList object. By default, 'level=between'
## extracts the GALignmentsList metadata. Using 'level=within'
## will extract the metadata on the individual GAlignments objects.
mcols(galist) ## no metadata on the GAlignmentsList object
mcols(galist, level="within")
## ---------------------------------------------------------------------
## D. readGAlignmentsListFromBam()
## ---------------------------------------------------------------------
library(Rsamtools)
library(pasillaBamSubset)
## 'file' as character.
fl <- untreated3_chr4()
galist1 <- readGAlignmentsList(fl)
galist1[1:3]
length(galist1)
table(elementLengths(galist1))
## When 'file' is a BamFile, 'asMates' must be TRUE. If FALSE,
## the data are treated as single-end and each list element of the
## GAlignmentsList will be of length 1. For single-end data
## use readGAlignments() instead of readGAlignmentsList().
bf <- BamFile(fl, yieldSize=3, asMates=TRUE)
readGAlignmentsList(bf)
## Use a 'param' to fine tune the results.
param <- ScanBamParam(flag=scanBamFlag(isProperPair=TRUE))
galist2 <- readGAlignmentsList(fl, param=param)
length(galist2)
## ---------------------------------------------------------------------
## E. COERCION
## ---------------------------------------------------------------------
## The granges() and grlist() coercions support 'ignore.strand' to
## allow ranges from different strand to be combined. In this example
## paired-end reads aligned to opposite strands were read into a
## GAlignmentsList. If the desired operation is to combine these ranges,
## reguardless of gaps or the space between pairs, 'ignore.strand' must be TRUE.
granges(galist[1])
granges(galist[1], ignore.strand=TRUE)
## grglist() splits ranges by gap and the space between list elements.
galist <- GAlignmentsList(noGaps=gal1, Gaps=gal2)
grglist(galist)
grglist(galist, ignore.strand=TRUE)