Assays objects

Description

The Assays virtual class and its methods provide a formal abstraction of the assays slot of SummarizedExperiment objects.

SimpleListAssays and ShallowSimpleListAssays are concrete subclasses of Assays with the latter being currently the default implementation of Assays objects. Other implementations (e.g. disk-based) could easily be added.

Note that these classes are not meant to be used directly by the end-user and the material in this man page is aimed at package developers.

Details

Assays objects have a list-like semantics with elements having matrix- or array-like semantics (e.g., dim, dimnames).

The Assays API consists of:

• (a) The Assays() constructor function.

• (b) Lossless back and forth coercion from/to SimpleList. The coercion method from SimpleList doesn't need (and should not) validate the returned object.

• (c) length, names, `names<-`, [[, `[[<-`, dim, [, `[<-`, rbind, cbind.

An Assays concrete subclass needs to implement (b) (required) plus, optionally any of the methods in (c).

IMPORTANT: Methods that return a modified Assays object (a.k.a. endomorphisms), that is, [ as well as replacement methods names<-, [[<-, and [<-, must respect the copy-on-change contract. With objects that don't make use of references internally, the developer doesn't need to take any special action for that because it's automatically taken care of by R itself. However, for objects that do make use of references internally (e.g. environments, external pointers, pointer to a file on disk, etc...), the developer needs to be careful to implement endomorphisms with copy-on-change semantics. This can easily be achieved (and is what the default methods for Assays objects do) by performaing a full (deep) copy of the object before modifying it instead of trying to modify it in-place. Note that the full (deep) copy is not always necessary in order to achieve copy-on-change semantics: it's enough (and often preferrable for performance reasons) to copy only the parts of the objects that need to be modified.

Assays has currently 3 implementations which are formalized by concrete subclasses SimpleListAssays, ShallowSimpleListAssays, and AssaysInEnv. ShallowSimpleListAssays is the default. AssaysInEnv is a broken alternative to ShallowSimpleListAssays that does NOT respect the copy-on-change contract. It is only provided for illustration purposes (see source file Assays-class.R for the details).

A little more detail about ShallowSimpleListAssays: a small reference class hierarchy (not exported from the GenomicRanges name space) defines a reference class ShallowData with a single field data of type ANY, and a derived class ShallowSimpleListAssays that specializes the type of data as SimpleList, and contains=c("ShallowData", "Assays"). The assays slot of a SummarizedExperiment object contains an instance of ShallowSimpleListAssays.

Author(s)

Martin Morgan, mtmorgan@fhcrc.org

See Also

• SummarizedExperiment objects.

• SimpleList objects in the S4Vectors package.

Examples

## ---------------------------------------------------------------------
## DIRECT MANIPULATION OF Assays OBJECTS
## ---------------------------------------------------------------------
m1 <- matrix(runif(24), ncol=3)
m2 <- matrix(runif(24), ncol=3)
a <- Assays(SimpleList(m1, m2))
a

as(a, "SimpleList")

length(a)
a[[2]]
dim(a)

b <- a[-4, 2]
b
length(b)
b[[2]]
dim(b)

names(a)
names(a) <- c("a1", "a2")
names(a)
a[["a2"]]

rbind(a, a)
cbind(a, a)

## ---------------------------------------------------------------------
## COPY-ON-CHANGE CONTRACT
## ---------------------------------------------------------------------

## ShallowSimpleListAssays objects have copy-on-change semantics but not
## AssaysInEnv objects. For example:
ssla <- as(SimpleList(m1, m2), "ShallowSimpleListAssays")
aie <- as(SimpleList(m1, m2), "AssaysInEnv")

## No names on 'ssla' and 'aie':
names(ssla)
names(aie)

ssla2 <- ssla
aie2 <- aie
names(ssla2) <- names(aie2) <- c("A1", "A2")

names(ssla)  # still NULL (as expected)

names(aie)   # changed! (because the names<-,AssaysInEnv method is not
             # implemented in a way that respects the copy-on-change
             # contract)

Results

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(SummarizedExperiment)
Loading required package: GenomicRanges
Loading required package: BiocGenerics
Loading required package: parallel

Attaching package: 'BiocGenerics'

The following objects are masked from 'package:parallel':

    clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
    clusterExport, clusterMap, parApply, parCapply, parLapply,
    parLapplyLB, parRapply, parSapply, parSapplyLB

The following objects are masked from 'package:stats':

    IQR, mad, xtabs

The following objects are masked from 'package:base':

    Filter, Find, Map, Position, Reduce, anyDuplicated, append,
    as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
    get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
    match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
    rbind, rownames, sapply, setdiff, sort, table, tapply, union,
    unique, unsplit

Loading required package: S4Vectors
Loading required package: stats4

Attaching package: 'S4Vectors'

The following objects are masked from 'package:base':

    colMeans, colSums, expand.grid, rowMeans, rowSums

Loading required package: IRanges
Loading required package: GenomeInfoDb
Loading required package: Biobase
Welcome to Bioconductor

    Vignettes contain introductory material; view with
    'browseVignettes()'. To cite Bioconductor, see
    'citation("Biobase")', and for packages 'citation("pkgname")'.

> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/SummarizedExperiment/Assays-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Assays-class
> ### Title: Assays objects
> ### Aliases: class:Assays Assays-class Assays length,Assays-method
> ###   names,Assays-method names<-,Assays-method [[,Assays,ANY,ANY-method
> ###   [[<-,Assays,ANY,ANY-method dim,Assays-method [,Assays,ANY-method
> ###   [<-,Assays,ANY,ANY,ANY-method arbind acbind arbind,array-method
> ###   acbind,array-method rbind,Assays-method cbind,Assays-method
> ###   class:SimpleListAssays SimpleListAssays-class SimpleListAssays
> ###   class:ShallowData ShallowData-class ShallowData
> ###   class:ShallowSimpleListAssays ShallowSimpleListAssays-class
> ###   ShallowSimpleListAssays
> ###   coerce,SimpleList,ShallowSimpleListAssays-method
> ###   coerce,ShallowSimpleListAssays,SimpleList-method class:AssaysInEnv
> ###   AssaysInEnv-class AssaysInEnv length,AssaysInEnv-method
> ###   names,AssaysInEnv-method names<-,AssaysInEnv-method
> ###   [[,AssaysInEnv,ANY,ANY-method [[<-,AssaysInEnv,ANY,ANY-method
> ###   coerce,SimpleList,AssaysInEnv-method
> ###   coerce,AssaysInEnv,SimpleList-method
> 
> ### ** Examples
> 
> ## ---------------------------------------------------------------------
> ## DIRECT MANIPULATION OF Assays OBJECTS
> ## ---------------------------------------------------------------------
> m1 <- matrix(runif(24), ncol=3)
> m2 <- matrix(runif(24), ncol=3)
> a <- Assays(SimpleList(m1, m2))
> a
Reference class object of class "ShallowSimpleListAssays"
Field "data":
List of length 2
> 
> as(a, "SimpleList")
List of length 2
> 
> length(a)
[1] 2
> a[[2]]
          [,1]      [,2]      [,3]
[1,] 0.8969100 0.8064294 0.6404711
[2,] 0.3811800 0.4482868 0.1611052
[3,] 0.9512826 0.2666290 0.2779076
[4,] 0.2171420 0.2992164 0.3482419
[5,] 0.7452323 0.5795820 0.6792952
[6,] 0.2148887 0.7573322 0.8440750
[7,] 0.7772717 0.5209488 0.5949137
[8,] 0.7405961 0.9202665 0.2437869
> dim(a)
[1] 8 3
> 
> b <- a[-4, 2]
> b
Reference class object of class "ShallowSimpleListAssays"
Field "data":
List of length 2
> length(b)
[1] 2
> b[[2]]
          [,1]
[1,] 0.8064294
[2,] 0.4482868
[3,] 0.2666290
[4,] 0.5795820
[5,] 0.7573322
[6,] 0.5209488
[7,] 0.9202665
> dim(b)
[1] 7 1
> 
> names(a)
NULL
> names(a) <- c("a1", "a2")
> names(a)
[1] "a1" "a2"
> a[["a2"]]
          [,1]      [,2]      [,3]
[1,] 0.8969100 0.8064294 0.6404711
[2,] 0.3811800 0.4482868 0.1611052
[3,] 0.9512826 0.2666290 0.2779076
[4,] 0.2171420 0.2992164 0.3482419
[5,] 0.7452323 0.5795820 0.6792952
[6,] 0.2148887 0.7573322 0.8440750
[7,] 0.7772717 0.5209488 0.5949137
[8,] 0.7405961 0.9202665 0.2437869
> 
> rbind(a, a)
Reference class object of class "ShallowSimpleListAssays"
Field "data":
List of length 2
names(2): a1 a2
> cbind(a, a)
Reference class object of class "ShallowSimpleListAssays"
Field "data":
List of length 2
names(2): a1 a2
> 
> ## ---------------------------------------------------------------------
> ## COPY-ON-CHANGE CONTRACT
> ## ---------------------------------------------------------------------
> 
> ## ShallowSimpleListAssays objects have copy-on-change semantics but not
> ## AssaysInEnv objects. For example:
> ssla <- as(SimpleList(m1, m2), "ShallowSimpleListAssays")
> aie <- as(SimpleList(m1, m2), "AssaysInEnv")
> 
> ## No names on 'ssla' and 'aie':
> names(ssla)
NULL
> names(aie)
NULL
> 
> ssla2 <- ssla
> aie2 <- aie
> names(ssla2) <- names(aie2) <- c("A1", "A2")
> 
> names(ssla)  # still NULL (as expected)
NULL
> 
> names(aie)   # changed! (because the names<-,AssaysInEnv method is not
[1] "A1" "A2"
>              # implemented in a way that respects the copy-on-change
>              # contract)
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>