BigMatrix-class: Class '"BigMatrix"'

In bigmemoryExtras: An extension of the bigmemory package with added safety, convenience, and a factor class

Description

This package defines a "BigMatrix" ReferenceClass which adds safety and convenience features to the filebacked.big.matrix class from the bigmemory package. BigMatrix protects against segfaults by monitoring and gracefully restoring the connection to on-disk data. We provide utilities for using BigMatrix-derived classes as assayData matrices within the Biobase package's eSet family of classes. BigMatrix provides some optimizations related to attaching to, and indexing into, file-backed matrices with dimnames.

A big.matrix object is backed by two files, a data file (backingfile) and a text metadata file (descriptor file). BigMatrix replaces the text metadata file with a binary "rds" file, for faster access. The location of this file is stored in the descpath field. The data in the metadata file is used to "attach" a big.matrix object its on-disk data. BigMatrix stores the big.matrix object and checks for a valid connection to the on-disk data each time it is necessary to access the big.matrix object. Re-attachment, using the attach method and the descpath field is performed as necessary. This avoids a segfault caused by accessing what could otherwise be a nil pointer. For example, A nil pointer occurs when a big.matrix data is saved and loaded using save() and load().

Reference classes are a relatively new and unused feature of R. They represent a new object model that is quite similar to OOP you might have seen in java or python. The ?ReferenceClasses help page is an excellent resource on this topic. As ReferenceClasses are an extension of R's S4 class system, S4-style methods can also be defined. In order to give the familiar matrix API, BigMatrix's ReferenceClass methods have a corresponding S4-style method. Please see the examples below.

Extends

All reference classes extend and inherit methods from "envRefClass".

Methods

S4-style methods supplement ReferenceClass methods to provide a standard matrix API.

[

signature(x = "BigMatrix", i = "ANY", j = "ANY", drop = "ANY"): Access matrix data.

[<-

signature(x = "BigMatrix", i = "ANY", j = "ANY"): Set matrix data.

[<-

signature(x = "BigMatrix", i = "ANY", j = "ANY", NA = "ANY"): Set matrix data

annotatedDataFrameFrom

signature(object = "BigMatrix"): Used in creation of a Biobase eSet with a BigMatrix as an assayDataElement.

coerce

signature(from = "BigMatrix", to = "matrix"): Coerce BigMatrix to a base matrix.

as.matrix

signature(x = "BigMatrix"): Coerce BigMatrix to a base matrix.

dim

signature(x = "BigMatrix"): Get dimensions of the matrix.

dimnames

signature(x = "BigMatrix"): Get dimension names of the matrix.

dimnames<-

signature(x = "BigMatrix", value = "ANY"): Set dimension names

length

signature(x = "BigMatrix"): Get length of the vector used as a matrix (nrow * ncol).

ncol

signature(x = "BigMatrix"): Get the number of columns in the matrix.

nrow

signature(x = "BigMatrix"): Get the number of rows in the matrix.

apply

signature(X = "BigMatrix"): Apply a function over one margin of the data in a BigMatrix, borrowing from biganalytics.

Fields

bigmat:

Object of class activeBindingFunction Public access to the big.matrix object.

datapath:

Object of class activeBindingFunction Full file path the big.matrix backing file.

descpath:

Object of class character Full file path the big.matrix metadata file.

.bm:

Object of class big.matrix Private storage of the big.matrix object.

Class-Based Methods

save():

Saves metadata about big.matrix in .bm field to file at location given by descpath field.

colnames

signature(x = "BigMatrix"): Get column names of the matrix.

rownames

signature(x = "BigMatrix"): Get row names of the matrix.

dimnames

signature(x = "BigMatrix"): Get dimension names of the matrix.

dim

signature(x = "BigMatrix"): Get the dimensions of the matrix.

nrow

signature(x = "BigMatrix"): Get the number of rows in the matrix.

ncol

signature(x = "BigMatrix"): Get the number of columns in the matrix.

length

signature(x = "BigMatrix"): Get the number of cells in the matrix.

setValues(i, j, value):

Setter for on-disk data.

getValues(i, j, drop):

Getter for on-disk data.

attach():

Uses path from descpath field to connect object to on-disk data. 'force' argument will force re-attachment of an object that is already attached.

Author(s)

Peter M. Haverty

See Also

See Also ReferenceClasses, BigMatrix, BigMatrixFactor, makeActiveBinding,filebacked.big.matrix

Examples

showClass("BigMatrix")
back.file = tempfile()
x = matrix(1:9,ncol=3,dimnames=list(letters[1:3],LETTERS[1:3]))
ds = BigMatrix(x,back.file)
ds[1,3]
ds[3,3] = 5
as(ds,"matrix")
ds[,]
rownames(ds)
ds$rownames()
colnames(ds)
ds$colnames()
dimnames(ds)
ds$dimnames()
dim(ds)
ds$dim()
nrow(ds)
ds$nrow()
ncol(ds)
ds$ncol()

bigmemoryExtras documentation built on Nov. 8, 2020, 5:17 p.m.