OverlapEncodings-class {GenomicAlignments} | R Documentation |
OverlapEncodings objects
Description
The OverlapEncodings class is a container for storing the
"overlap encodings" returned by the encodeOverlaps
function.
Usage
## -=-= OverlapEncodings getters =-=-
## S4 method for signature 'OverlapEncodings'
Loffset(x)
## S4 method for signature 'OverlapEncodings'
Roffset(x)
## S4 method for signature 'OverlapEncodings'
encoding(x)
## S4 method for signature 'OverlapEncodings'
levels(x)
## S4 method for signature 'OverlapEncodings'
flippedQuery(x)
## -=-= Coercing an OverlapEncodings object =-=-
## S4 method for signature 'OverlapEncodings'
as.data.frame(x, row.names=NULL, optional=FALSE, ...)
## -=-= Low-level encoding utilities =-=-
encodingHalves(x, single.end.on.left=FALSE, single.end.on.right=FALSE,
as.factors=FALSE)
Lencoding(x, ...)
Rencoding(x, ...)
## S4 method for signature 'ANY'
njunc(x)
Lnjunc(x, single.end.on.left=FALSE)
Rnjunc(x, single.end.on.right=FALSE)
isCompatibleWithSplicing(x)
Arguments
x |
An OverlapEncodings object. For the low-level encoding utilities, |
row.names |
|
optional |
Ignored. |
... |
Extra arguments passed to the Extra arguments passed to |
single.end.on.left , single.end.on.right |
By default the 2 halves of a single-end encoding are considered to be NAs.
If |
as.factors |
By default |
Details
Given a query
and a subject
of the same length, both
list-like objects with top-level elements typically containing multiple
ranges (e.g. IntegerRangesList objects), the "overlap
encoding" of the i-th element in query
and i-th element in
subject
is a character string describing how the ranges in
query[[i]]
are qualitatively positioned relatively to
the ranges in subject[[i]]
.
The encodeOverlaps
function computes those overlap
encodings and returns them in an OverlapEncodings object of the same
length as query
and subject
.
The topic of working with overlap encodings is covered in details
in the "OverlapEncodings" vignette located this package
(GenomicAlignments) and accessible with
vignette("OverlapEncodings")
.
OverlapEncodings getters
In the following code snippets, x
is an OverlapEncodings object
typically obtained by a call to encodeOverlaps(query, subject)
.
-
length(x)
: Get the number of elements (i.e. encodings) inx
. This is equal tolength(query)
andlength(subject)
. -
Loffset(x)
,Roffset(x)
: Get the "left offsets" and "right offsets" of the encodings, respectively. Both are integer vectors of the same length asx
.Let's denote
Qi = query[[i]]
,Si = subject[[i]]
, and [q1,q2] the range covered byQi
i.e.q1 = min(start(Qi))
andq2 = max(end(Qi))
, thenLoffset(x)[i]
is the numberL
of ranges at the head ofSi
that are strictly to the left of all the ranges inQi
i.e.L
is the greatest value such thatend(Si)[k] < q1 - 1
for allk
inseq_len(L)
. Similarly,Roffset(x)[i]
is the numberR
of ranges at the tail ofSi
that are strictly to the right of all the ranges inQi
i.e.R
is the greatest value such thatstart(Si)[length(Si) + 1 - k] > q2 + 1
for allk
inseq_len(L)
. -
encoding(x)
: Factor of the same length asx
where the i-th element is the encoding obtained by comparing each range inQi
with all the ranges intSi = Si[(1+L):(length(Si)-R)]
(tSi
stands for "trimmed Si"). More precisely, here is how this encoding is obtained:All the ranges in
Qi
are compared withtSi[1]
, then withtSi[2]
, etc... At each step (one step per range intSi
), comparing all the ranges inQi
withtSi[k]
is done withrangeComparisonCodeToLetter(compare(Qi, tSi[k]))
. So at each step, we end up with a vector ofM
single letters (whereM
islength(Qi)
).Each vector obtained previously (1 vector per range in
tSi
, all of them of lengthM
) is turned into a single string (called "encoding block") by pasting its individual letters together.All the encoding blocks (1 per range in
tSi
) are pasted together into a single long string and separated by colons (":"
). An additional colon is prepended to the long string and another one appended to it.Finally, a special block containing the value of
M
is prepended to the long string. The final string is the encoding.
-
levels(x)
: Equivalent tolevels(encoding(x))
. -
flippedQuery(x)
: Whether or not the top-level element in query used for computing the encoding was "flipped" before the encoding was computed. Note that this flipping generally affects the "left offset", "right offset", in addition to the encoding itself.
Coercing an OverlapEncodings object
In the following code snippets, x
is an OverlapEncodings object.
-
as.data.frame(x)
: Returnx
as a data frame with columns"Loffset"
,"Roffset"
and"encoding"
.
Low-level encoding utilities
In the following code snippets, x
can be an OverlapEncodings object,
or a character vector or factor containing encodings.
-
encodingHalves(x, single.end.on.left=FALSE, single.end.on.right=FALSE, as.factors=FALSE)
: Extract the 2 halves of paired-end encodings and return them as a list of 2 character vectors (or 2 factors) parallel to the input.Paired-end encodings are obtained by encoding paired-end overlaps i.e. overlaps between paired-end reads and transcripts (typically). The difference between a single-end encoding and a paired-end encoding is that all the blocks in the latter contain a
"--"
separator to mark the separation between the "left encoding" and the "right encoding".See examples below and the "Overlap encodings" vignette located in this package for examples of paired-end encodings.
-
Lencoding(x, ...)
,Rencoding(x, ...)
: Extract the "left encodings" and "right encodings" of paired-end encodings.Equivalent to
encodingHalves(x, ...)[[1]]
andencodingHalves(x, ...)[[2]]
, respectively. -
njunc(x)
,Lnjunc(x, single.end.on.left=FALSE)
,Rnjunc(x, single.end.on.right=FALSE)
: Extract the number of junctions in each encoding by looking at their first block (aka special block). If an elementxi
inx
is a paired-end encoding, thenLnjunc(xi)
,Rnjunc(xi)
, andnjunc(xi)
, returnnjunc(Lencoding(xi))
,njunc(Rencoding(xi))
, andLnjunc(xi) + Rnjunc(xi)
, respectively. -
isCompatibleWithSplicing(x)
: Returns a logical vector parallel tox
indicating whether the corresponding encoding describes a splice compatible overlap i.e. an overlap that is compatible with the splicing of the transcript.WARNING: For paired-end encodings,
isCompatibleWithSplicing
considers that the encoding is splice compatible if its 2 halves are splice compatible. This can produce false positives if for example the right end of the alignment is located upstream of the left end in transcript space. The paired-end read could not come from this transcript. To eliminate these false positives, one would need to have access and look at the position of the left and right ends in transcript space. This can be done withextractQueryStartInTranscript
.
Author(s)
Hervé Pagès
See Also
The "OverlapEncodings" vignette in this package.
The
encodeOverlaps
function for computing "overlap encodings".The
pcompare
function in the IRanges package for the interpretation of the strings returned byencoding
.The GRangesList class defined and documented in the GenomicRanges package.
Examples
## ---------------------------------------------------------------------
## A. BASIC MANIPULATION OF AN OverlapEncodings OBJECT
## ---------------------------------------------------------------------
example(encodeOverlaps) # to generate the 'ovenc' object
length(ovenc)
Loffset(ovenc)
Roffset(ovenc)
encoding(ovenc)
levels(ovenc)
nlevels(ovenc)
flippedQuery(ovenc)
njunc(ovenc)
as.data.frame(ovenc)
njunc(levels(ovenc))
## ---------------------------------------------------------------------
## B. WORKING WITH PAIRED-END ENCODINGS (POSSIBLY MIXED WITH SINGLE-END
## ENCODINGS)
## ---------------------------------------------------------------------
encodings <- c("4:jmmm:agmm:aagm:aaaf:", "3--1:jmm--b:agm--i:")
encodingHalves(encodings)
encodingHalves(encodings, single.end.on.left=TRUE)
encodingHalves(encodings, single.end.on.right=TRUE)
encodingHalves(encodings, single.end.on.left=TRUE,
single.end.on.right=TRUE)
Lencoding(encodings)
Lencoding(encodings, single.end.on.left=TRUE)
Rencoding(encodings)
Rencoding(encodings, single.end.on.right=TRUE)
njunc(encodings)
Lnjunc(encodings)
Lnjunc(encodings, single.end.on.left=TRUE)
Rnjunc(encodings)
Rnjunc(encodings, single.end.on.right=TRUE)
## ---------------------------------------------------------------------
## C. DETECTION OF "SPLICE COMPATIBLE" OVERLAPS
## ---------------------------------------------------------------------
## Reads that are compatible with the splicing of the transcript can
## be detected with a regular expression (the regular expression below
## assumes that reads have at most 2 junctions):
regex0 <- "(:[fgij]:|:[jg].:.[gf]:|:[jg]..:.g.:..[gf]:)"
grepl(regex0, encoding(ovenc)) # read4 is NOT "compatible"
## This was for illustration purpose only. In practise you don't need
## (and should not) use this regular expression, but use instead the
## isCompatibleWithSplicing() utility function:
isCompatibleWithSplicing(ovenc)