Realize an object in memory or on disk

realize() is an S4 generic function.

The default realize() method handles the array case. It will realize the array-like object (typically a DelayedArray object) in memory or on disk, depending on the realization backend specified via its BACKEND argument,

Usage

realize(x, ...)

# S4 method for class 'ANY'
realize(x, BACKEND=getAutoRealizationBackend())

Arguments

x

An array-like object (typically a DelayedArray object) for the default method.

Other types of objects can be supported via additional methods. For example, the SummarizedExperiment package defines a method for SummarizedExperiment objects (see ?`realize,SummarizedExperiment-method`).

...

Additional arguments passed to methods.

BACKEND

NULL or a single string specifying the name of a realization backend. By default, the automatic realization backend will be used. This is the backend returned by getAutoRealizationBackend().

Details

The default realize() method realizes an array-like object x in memory if BACKEND is NULL, otherwise on disk.

Note that, when BACKEND is not NULL, x gets realized as a "pristine" DelayedArray object (e.g. an HDF5Array object), that is, as a DelayedArray object that carries no delayed operations. This means that, if x is itself a DelayedArray object, then the returned object is another DelayedArray object semantically equivalent to x where the delayed operations carried by x have been realized.

Value

A "pristine" DelayedArray object if BACKEND is not NULL.

Otherwise, an ordinary matrix or array, or a SparseArray object.

Examples

## ---------------------------------------------------------------------
## In-memory realization
## ---------------------------------------------------------------------

a <- array(1:24, dim=4:2)
realize(a, BACKEND=NULL)  # no-op
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]    1    5    9
#> [2,]    2    6   10
#> [3,]    3    7   11
#> [4,]    4    8   12
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3]
#> [1,]   13   17   21
#> [2,]   14   18   22
#> [3,]   15   19   23
#> [4,]   16   20   24
#> 

A <- DelayedArray(a)
realize(log(A), BACKEND=NULL)  # same as 'as.array(log(A))'
#> , , 1
#> 
#>           [,1]     [,2]     [,3]
#> [1,] 0.0000000 1.609438 2.197225
#> [2,] 0.6931472 1.791759 2.302585
#> [3,] 1.0986123 1.945910 2.397895
#> [4,] 1.3862944 2.079442 2.484907
#> 
#> , , 2
#> 
#>          [,1]     [,2]     [,3]
#> [1,] 2.564949 2.833213 3.044522
#> [2,] 2.639057 2.890372 3.091042
#> [3,] 2.708050 2.944439 3.135494
#> [4,] 2.772589 2.995732 3.178054
#> 

## Sanity checks:
stopifnot(identical(realize(a, BACKEND=NULL), a))
stopifnot(identical(realize(log(A), BACKEND=NULL), log(a)))

## ---------------------------------------------------------------------
## On-disk realization
## ---------------------------------------------------------------------

library(HDF5Array)

realize(log(A), BACKEND="HDF5Array")  # same as 'as(log(A), "HDF5Array")'
#> <4 x 3 x 2> HDF5Array object of type "double":
#> ,,1
#>           [,1]      [,2]      [,3]
#> [1,] 0.0000000 1.6094379 2.1972246
#> [2,] 0.6931472 1.7917595 2.3025851
#> [3,] 1.0986123 1.9459101 2.3978953
#> [4,] 1.3862944 2.0794415 2.4849066
#> 
#> ,,2
#>          [,1]     [,2]     [,3]
#> [1,] 2.564949 2.833213 3.044522
#> [2,] 2.639057 2.890372 3.091042
#> [3,] 2.708050 2.944439 3.135494
#> [4,] 2.772589 2.995732 3.178054
#> 

## ---------------------------------------------------------------------
## Omitting the 'BACKEND' argument
## ---------------------------------------------------------------------

## When 'BACKEND' is not specified, the "automatic realization backend"
## is used. This backend is controlled via setAutoRealizationBackend().

toy_h5 <- system.file("extdata", "toy.h5", package="HDF5Array")
h5ls(toy_h5)
#>   group name       otype dclass         dim
#> 0     /   M1 H5I_DATASET  FLOAT 10000 x 150
#> 1     /   M2 H5I_DATASET  FLOAT   150 x 200
M1 <- HDF5Array(toy_h5, "M1")
M2 <- HDF5Array(toy_h5, "M2")
M3 <- rbind(log(M1), t(M2)) + 0.5
M3
#> <10200 x 150> DelayedMatrix object of type "double":
#>                 [,1]        [,2]        [,3] ...      [,149]      [,150]
#>     [1,] -0.32063951 -3.27093524 -1.64652267   .  0.09725242  0.48588437
#>     [2,] -1.16688823  0.32936878 -1.60756820   . -0.74252354 -0.79065419
#>     [3,]  0.49229739 -0.97294529 -1.06073618   . -0.23686236  0.15580764
#>     [4,] -0.14185832 -1.36833326 -0.33740987   .  0.36255690 -0.03265512
#>     [5,]  0.02789916 -0.78652688 -0.11567117   . -0.67687460 -0.72776874
#>      ...           .           .           .   .           .           .
#> [10196,]  13.2122663   3.5340890  -0.9169923   .   7.4245396   3.4911944
#> [10197,]  -0.6921119  12.6553961  10.8398257   .  14.0414241  11.2321084
#> [10198,]  11.7522507   6.7994228   1.3515161   .   4.1392227  -2.2872102
#> [10199,]   4.7025030  15.3541228   1.0208430   .  14.0904518   0.4925605
#> [10200,]   7.7127450   3.9810124   9.3763231   .   2.6347528   7.6645148

## Set the "automatic realization backend" to NULL for in-memory
## realization (as ordinary array or SparseArray object):
setAutoRealizationBackend(NULL)
m3 <- realize(M3)  # in-memory realization

registeredRealizationBackends()
#>        BACKEND      package  
#> 1     RleArray DelayedArray  
#> 2    HDF5Array    HDF5Array  
#> 3   TENxMatrix    HDF5Array  

setAutoRealizationBackend("RleArray")
realize(M3)  # realization as RleArray object
#> <10200 x 150> RleMatrix object of type "double":
#>                 [,1]        [,2]        [,3] ...      [,149]      [,150]
#>     [1,] -0.32063951 -3.27093524 -1.64652267   .  0.09725242  0.48588437
#>     [2,] -1.16688823  0.32936878 -1.60756820   . -0.74252354 -0.79065419
#>     [3,]  0.49229739 -0.97294529 -1.06073618   . -0.23686236  0.15580764
#>     [4,] -0.14185832 -1.36833326 -0.33740987   .  0.36255690 -0.03265512
#>     [5,]  0.02789916 -0.78652688 -0.11567117   . -0.67687460 -0.72776874
#>      ...           .           .           .   .           .           .
#> [10196,]  13.2122663   3.5340890  -0.9169923   .   7.4245396   3.4911944
#> [10197,]  -0.6921119  12.6553961  10.8398257   .  14.0414241  11.2321084
#> [10198,]  11.7522507   6.7994228   1.3515161   .   4.1392227  -2.2872102
#> [10199,]   4.7025030  15.3541228   1.0208430   .  14.0904518   0.4925605
#> [10200,]   7.7127450   3.9810124   9.3763231   .   2.6347528   7.6645148

setAutoRealizationBackend("HDF5Array")
realize(M3)  # on-disk realization (as HDF5Array object)
#> <10200 x 150> HDF5Matrix object of type "double":
#>                 [,1]        [,2]        [,3] ...      [,149]      [,150]
#>     [1,] -0.32063951 -3.27093524 -1.64652267   .  0.09725242  0.48588437
#>     [2,] -1.16688823  0.32936878 -1.60756820   . -0.74252354 -0.79065419
#>     [3,]  0.49229739 -0.97294529 -1.06073618   . -0.23686236  0.15580764
#>     [4,] -0.14185832 -1.36833326 -0.33740987   .  0.36255690 -0.03265512
#>     [5,]  0.02789916 -0.78652688 -0.11567117   . -0.67687460 -0.72776874
#>      ...           .           .           .   .           .           .
#> [10196,]  13.2122663   3.5340890  -0.9169923   .   7.4245396   3.4911944
#> [10197,]  -0.6921119  12.6553961  10.8398257   .  14.0414241  11.2321084
#> [10198,]  11.7522507   6.7994228   1.3515161   .   4.1392227  -2.2872102
#> [10199,]   4.7025030  15.3541228   1.0208430   .  14.0904518   0.4925605
#> [10200,]   7.7127450   3.9810124   9.3763231   .   2.6347528   7.6645148

setAutoRealizationBackend()  # restore default (NULL)

Usage

Arguments

Details

Value

See also

Examples