GTuplesList objects
Description
The GTuplesList
class is a container for storing a collection of
GTuples
objects. It is derived from
GRangesList
.
Constructor

GTuplesList(...)
: Creates aGTuplesList
object usingGTuples
objects supplied in...
.
Accessors
In the following code snippets, x
is a GTuplesList
object.

length(x)
: Get the number of list elements. 
names(x)
,names(x) < value
: Get or set the names onx
. 
elementNROWS(x)
: Get thelength
of each of the list elements. 
isEmpty(x)
: Returns a logical indicating either if theGTuplesList
has no elements or if all its elements are empty. 
seqnames(x)
,seqnames(x) < value
: Get or set the sequence names in the form of anRleList
.value
can be anRleList
orCharacterList
object. 
tuples(x)
,tuples(x) < value
: Get or set the tuples in the form of aSimpleList
of integer matrices.value
can be a a single integer matrix. 
ranges(x, use.mcols = FALSE)
,ranges(x) < value
: Get or set the ranges in the form of aCompressedIRangesList
.value
can be aRangesList
object.WARNING: The use of
ranges
withGTuplesList
objects is strongly discouraged. It will only get/set pos_{1} and pos_{m} of the tuples, where m is thesize
of the tuples, as these are what are stored in the "ranges" slot of theGTuples
objects. 
strand(x)
,strand(x) < value
: Get or set the strand in the form of anRleList
.value
can be anRleList
,CharacterList
or single character.value
as a single character converts all ranges inx
to the samevalue
; for selective strand conversion (i.e., mixed “+” and “”) useRleList
orCharacterList
. 
mcols(x, use.names=FALSE)
,mcols(x) < value
: Get or set the metadata columns.value
can beNULL
, or a data.framelike object (i.e.DataFrame
or data.frame) holding elementwise metadata. 
elementMetadata(x)
,elementMetadata(x) < value
,values(x)
,values(x) < value
: Alternatives tomcols
functions. Their use is discouraged. 
seqinfo(x)
,seqinfo(x) < value
: Get or set the information about the underlying sequences.value
must be a Seqinfo object. 
seqlevels(x)
,seqlevels(x, force=FALSE) < value
: Get or set the sequence levels.seqlevels(x)
is equivalent toseqlevels(seqinfo(x))
or tolevels(seqnames(x))
, those 2 expressions being guaranteed to return identical character vectors on aGTuplesList
object.value
must be a character vector with no NAs. See?seqlevels
for more information. 
seqlengths(x)
,seqlengths(x) < value
: Get or set the sequence lengths.seqlengths(x)
is equivalent toseqlengths(seqinfo(x))
.value
can be a named nonnegative integer or numeric vector eventually with NAs. 
isCircular(x)
,isCircular(x) < value
: Get or set the circularity flags.isCircular(x)
is equivalent toisCircular(seqinfo(x))
.value
must be a named logical vector eventually with NAs. 
genome(x)
,genome(x) < value
: Get or set the genome identifier or assembly name for each sequence.genome(x)
is equivalent togenome(seqinfo(x))
.value
must be a named character vector eventually with NAs. 
seqlevelsStyle(x)
,seqlevelsStyle(x) < value
: Get or set the seqname style forx
. See the seqlevelsStyle generic getter and setter in the GenomeInfoDb package for more information. 
score(x), score(x) < value
: Get or set the “score” metadata column.
Tuples methods
In the following code snippets, x is a GTuplesList
object.
WARNING: The preferred setter is tuples(x) < value
and the
use of start(x) < value
, end(x) < value
and
width(x) < value is discouraged
.

start(x)
,start(x) < value
: Get or set pos_{1} of thetuples
. WARNING: The use ofstart(x) < value
is discouraged; instead, construct the tuples as the appropriateList
of integer matrices,mvalue
, and usetuples(x) < mvalue
. 
end(x)
,end(x) < value
: Get or set pos_{m} of the tuples, where m is thesize
of the tuples. WARNING: The use ofend(x) < value
is discouraged; instead, construct the tuples as the appropriateList
of integer matrices,mvalue
, and usetuples(x) < mvalue
. 
IPD(x)
: Get the intrapair distances (IPD
) in the form of aSimpleList
of integer matrices.IPD
is only defined for tuples withsize
> 1. TheIPD
of a tuple withsize
= m is the vector of intrapair distances, (pos_{2}  pos_{1}, …, pos_{m}  pos_{m  1}). 
width(x)
,width(x) < value
: Get or set pos_{m}  pos_{1} of the tuples, where m is thesize
of the tuples. If usingwidth(x) < value
, pos_{1} is held fixed and pos_{m} is altered. WARNING: The use ofwidth(x) < value
is discouraged; instead, instead, construct the tuples as the appropriateList
of integer matrices,mvalue
, and usetuples(x) < mvalue
.
Coercion
In the code snippets below, x
is a GTuplesList object.

as.data.frame(x, row.names = NULL, optional = FALSE, ..., value.name = "value", use.outer.mcols = FALSE, group_name.as.factor = FALSE)
: Coercesx
to adata.frame
. See as.data.frame on theList
man page for details (?List
). as.list(x, use.names = TRUE)
: Creates a list containing the elements ofx
.

as(x, "GRangesList")
: Creates aGRangesList
object from aGTuplesList
object. WARNING: This is generally a destructive operation, as the originalGTuplesList
may not be recreatable.
Subsetting
In the following code snippets, x
is a GTuplesList
object.

x[i, j]
,x[i, j] < value
: Get or set elementsi
with optional metadata columnsmcols(x)[,j]
, wherei
can be missing; an NAfree logical, numeric, or character vector; a 'logical' Rle object, or an AtomicList object. 
x[[i]]
,x[[i]] < value
: Get or set elementi
, wherei
is a numeric or character vector of length 1. 
x$name
,x$name < value
: Get or set elementname
, wherename
is a name or character vector of length 1. 
head(x, n = 6L)
: Ifn
is nonnegative, returns the first n elements of the GTuplesList object. Ifn
is negative, returns all but the lastabs(n)
elements of the GTuplesList object. 
rep(x, times, length.out, each)
: Repeats the values inx
through one of the following conventions:times
Vector giving the number of times to repeat each element if of length
length(x)
, or to repeat the whole vector if of length 1.length.out
Nonnegative integer. The desired length of the output vector.
each
Nonnegative integer. Each element of
x
is repeatedeach
times.

subset(x, subset)
: Returns a new object of the same class asx
made of the subset using logical vectorsubset
, where missing values are taken asFALSE
. 
tail(x, n = 6L)
: Ifn
is nonnegative, returns the last n elements of the GTuples object. Ifn
is negative, returns all but the firstabs(n)
elements of the GTuples object.
Combining
In the code snippets below, x
is a GTuplesList object.

c(x, ...)
: Combinesx
and the GTuplesList objects in...
together. Any object in...
must belong to the same class asx
, or to one of its subclasses, or must beNULL
. The result is an object of the same class asx
. 
append(x, values, after = length(x))
: Inserts thevalues
intox
at the position given byafter
, wherex
andvalues
are of the same class. unlist(x, recursive = TRUE, use.names = TRUE)
: Concatenates the elements ofx
into a single GTuples object.
Looping
In the code snippets below, x
is a GTuplesList object.

endoapply(X, FUN, ...)
: Similar tolapply
, but performs an endomorphism, i.e. returns an object ofclass(X)
. 
lapply(X, FUN, ...)
: Like the standardlapply
function defined in the base package, thelapply
method for GTuplesList objects returns a list of the same length asX
, with each element being the result of applyingFUN
to the corresponding element ofX
. 
Map(f, ...)
: Applies a function to the corresponding elements of given GTuplesList objects. 
mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)
: Like the standardmapply
function defined in the base package, themapply
method for GTuplesList objects is a multivariate version ofsapply
. 
mendoapply(FUN, ..., MoreArgs = NULL)
: Similar tomapply
, but performs an endomorphism across multiple objects, i.e. returns an object ofclass(list(...)[[1]])
. 
Reduce(f, x, init, right = FALSE, accumulate = FALSE)
: Uses a binary function to successively combine the elements ofx
and a possibly given initial value. f
A binary argument function.
 init
An R object of the same kind as the elements of
x
. right
A logical indicating whether to proceed from left to right (default) or from right to left.
 nomatch
The value to be returned in the case when "no match" (no element satisfying the predicate) is found.

sapply(X, FUN, ..., simplify=TRUE, USE.NAMES=TRUE)
: Like the standardsapply
function defined in the base package, thesapply
method for GTuplesList objects is a userfriendly version oflapply
by default returning a vector or matrix if appropriate.
Author(s)
Peter Hickey for GTuplesList
definition and methods. P. Aboyoun
& H. Pages for all the real work underlying the powerful GRangesList
class and methods.
See Also
GTuplesclass
seqinfo
,
GRangesListclass,
Vectorclass,
RangesListclass,
RleListclass,
DataFrameListclass,
findOverlapsmethods
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44  ## Construction of GTuplesList of 4tuples with GTuplesList():
seqinfo < Seqinfo(paste0("chr", 1:3), c(1000, 2000, 1500), NA, "mock1")
gt4 < GTuples(seqnames = Rle(c("chr1", "chr2", "chr1", "chr3"),
c(1, 3, 2, 4)),
tuples = matrix(c(1:10, 2:11, 3:12, 4:13), ncol = 4),
strand = Rle(strand(c("", "+", "*", "+", "")),
c(1, 2, 2, 3, 2)),
score = 1:10, GC = seq(1, 0, length = 10), seqinfo = seqinfo)
gtl4 < GTuplesList(A = gt4[1:4], B = gt4[5:10])
gtl4
## Summarizing elements:
elementNROWS(gtl4)
table(seqnames(gtl4))
## Extracting subsets:
gtl4[seqnames(gtl4) == "chr1", ]
gtl4[seqnames(gtl4) == "chr1" & strand(gtl4) == "+", ]
## Renaming the underlying sequences:
seqlevels(gtl4)
seqlevels(gtl4) < sub("chr", "Chrom", seqlevels(gtl4))
gtl4
## Coerce to GRangesList ("internal positions" information is lost):
as(gtl4, "GRangesList")
## Get the size of the tuples stored in the GTuplesList object
size(gtl4)
## Get the tuples
tuples(gtl4)
## Get the matrix of intrapair distances (IPD)
IPD(gtl4)
## Can't combine genomic tuples of different sizes
gt1 < GTuples('chr1', matrix(30:40))
gt1
## Not run:
## Returns error
GTuplesList(A = gt4, gt1)
## End(Not run)
