Column-Linked and Row-Linked Matrices

Description

A class that links matrix-like objects (nodes) by rows or by columns while behaving similarly to a base R matrix. Very large matrices are supported if the nodes are file-backed matrices.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Create a LinkedMatrix Object

Description

This function constructs a new ColumnLinkedMatrix or RowLinkedMatrix object from a list of matrix-like objects.

Usage

ColumnLinkedMatrix(...)

RowLinkedMatrix(...)

Arguments

Details

A matrix-like object is one that has two dimensions and implements at least dim and [. Each object needs to have the same number of rows (for ColumnLinkedMatrix) or columns (for RowLinkedMatrix) to be linked together. If no matrix-like objects are given, a single 1x1 node of type matrix filled with NA is returned. LinkedMatrix objects can be nested as long as they are conformable.

Value

Either a ColumnLinkedMatrix or a RowLinkedMatrix object.

See Also

LinkedMatrix to create an empty, prespecified LinkedMatrix object.

Examples

# Create various matrix-like objects that correspond in dimensions
m1 <- ff::ff(initdata = rnorm(50), dim = c(5, 10))
m2 <- bigmemory::big.matrix(init = rnorm(50), nrow = 5, ncol = 10)
m3 <- matrix(data = rnorm(50), nrow = 5, ncol = 10)

# Create a ColumnLinkedMatrix object
cm <- ColumnLinkedMatrix(m1, m2, m3)

# To specify the matrix-like objects as a list, use the `do.call` function
rm <- do.call(RowLinkedMatrix, list(m1, m2, m3))

A Class for Linking Matrices by Columns or Rows

Description

This class treats a list of matrix-like objects that are linked together by columns (ColumnLinkedMatrix) or rows (RowLinkedMatrix) and have the same number of rows similarly to a regular matrix by implementing key methods such as [ and [<- for extracting and replacing matrix elements, dim to retrieve dimensions, and dimnames and dimnames<- to retrieve and set dimnames. Each list element is called a node and can be extracted or replaced using [[ and [[<-. A matrix-like object is one that has two dimensions and implements at least dim and [.

Details

Internally, this class is an S4 class that contains list. Each node can be accessed using the [[ operator. lapply is also possible. ColumnLinkedMatrix and RowLinkedMatrix form a class union called LinkedMatrix.

Methods

• [

• [<-

• dim

• dimnames

• dimnames<-

• as.matrix

• is.matrix

• length

• print

• str

• cbind (for ColumnLinkedMatrix)

• rbind (for RowLinkedMatrix)

See Also

ColumnLinkedMatrix and RowLinkedMatrix to create a ColumnLinkedMatrix and RowLinkedMatrix objects from scratch. as.ColumnLinkedMatrix and as.RowLinkedMatrix to create a ColumnLinkedMatrix and RowLinkedMatrix objects from other objects. LinkedMatrix to create an empty, prespecified LinkedMatrix object. nNodes to get the number of nodes of a LinkedMatrix object.

Examples

# Create various matrix-like objects that correspond in dimensions
m1 <- ff::ff(initdata = rnorm(50), dim = c(5, 10))
m2 <- bigmemory::big.matrix(init = rnorm(50), nrow = 5, ncol = 10)
m3 <- matrix(data = rnorm(50), nrow = 5, ncol = 10)

# Link random matrices by columns
cm <- ColumnLinkedMatrix(m1, m2, m3)
dim(cm)

# Link random matrices by rows
rm <- RowLinkedMatrix(m1, m2, m3)
dim(rm)

# Get the number of nodes of each linked matrix
nNodes(cm)
nNodes(rm)

# Extract specific rows of linked matrix
cm[1, ]
cm[1:3, ]
rm[1, ]
rm[1:3, ]

# Extract specific columns of linked matrix
cm[, 1]
cm[, 1:3]
rm[, 1]
rm[, 1:3]

# Extract specific rows and columns of linked matrix
cm[1, 1]
cm[1:3, 1:3]
rm[1, 1]
rm[1:3, 1:3]

# Get a reference to one of the nodes
n <- cm[[2]]
class(n) == "big.matrix"

# LinkedMatrix objects are matrix-like and can be nested
rcm <- RowLinkedMatrix(cm, cm)

Create an Empty, Prespecified LinkedMatrix Object

Description

This function creates an empty LinkedMatrix object of a certain size, a certain number of nodes, and certain types of nodes.

Usage

LinkedMatrix(nrow, ncol, nNodes, linkedBy, nodeInitializer, ...)

Arguments

Value

A ColumnLinkedMatrix object if linkedBy is columns or a RowLinkedMatrix object if linkedBy is rows.

See Also

ColumnLinkedMatrix and RowLinkedMatrix to create ColumnLinkedMatrix and RowLinkedMatrix objects from a list of matrix-like objects.

Examples

# Create an empty 15x10 RowLinkedMatrix with 3 matrix nodes
m1 <- LinkedMatrix(nrow = 15, ncol = 10, nNodes = 3, linkedBy = "rows",
                   nodeInitializer = "matrixNodeInitializer")
dim(m1)
nNodes(m1)
all(sapply(m1, inherits, "matrix"))

# Create an empty 15x10 RowLinkedMatrix with 3 ff nodes
m2 <- LinkedMatrix(nrow = 15, ncol = 10, nNodes = 3, linkedBy = "rows",
                   nodeInitializer = "ffNodeInitializer", vmode = "byte")
dim(m2)
nNodes(m2)
all(sapply(m2, inherits, "ff_matrix"))

# Create an empty 15x10 RowLinkedMatrix with 3 big.matrix nodes
m3 <- LinkedMatrix(nrow = 15, ncol = 10, nNodes = 3, linkedBy = "rows",
                   nodeInitializer = function(nodeIndex, nrow, ncol, ...) {
                       bigmemory::big.matrix(nrow = nrow, ncol = ncol)
                   })
dim(m3)
nNodes(m3)
all(sapply(m3, inherits, "big.matrix"))

A Class Union of ColumnLinkedMatrix and RowLinkedMatrix

Description

This class is abstract and no objects can be created from it. It can be used to check whether an object is either of type ColumnLinkedMatrix or of type RowLinkedMatrix using is(x, "LinkedMatrix") and to assign methods for both ColumnLinkedMatrix and RowLinkedMatrix classes, e.g. show.

Methods

• length

• as.matrix

• show

• initialize

See Also

ColumnLinkedMatrix-class and RowLinkedMatrix-class for implementations of column-linked and row-linked matrices.

Examples

# Create an example RowLinkedMatrix from various matrix-like objects that
# correspond in dimensions
m <- RowLinkedMatrix(
    ff::ff(initdata = rnorm(50), dim = c(5, 10)),
    bigmemory::big.matrix(init = rnorm(50), nrow = 5, ncol = 10),
    matrix(data = rnorm(50), nrow = 5, ncol = 10)
)

# Test if m is an object of either type ColumnLinkedMatrix or RowLinkedMatrix
if (is(m, "LinkedMatrix")) {
    message("m is a LinkedMatrix")
}

Converts an Object to a LinkedMatrix Object

Description

Converts an Object to a LinkedMatrix Object.

Usage

as.ColumnLinkedMatrix(x, ...)

## S3 method for class 'list'
as.ColumnLinkedMatrix(x, ...)

as.RowLinkedMatrix(x, ...)

## S3 method for class 'list'
as.RowLinkedMatrix(x, ...)

Arguments

Value

A LinkedMatrix object.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Examples

m1 <- ff::ff(initdata = rnorm(50), dim = c(5, 10))
m2 <- bigmemory::big.matrix(init = rnorm(50), nrow = 5, ncol = 10)
m3 <- matrix(data = rnorm(50), nrow = 5, ncol = 10)

myList <- list(m1, m2, m3)

m <- as.ColumnLinkedMatrix(myList)

Converts a LinkedMatrix Instance to a Matrix (if Small Enough)

Description

Converts a LinkedMatrix Instance to a Matrix (if Small Enough).

Usage

## S3 method for class 'LinkedMatrix'
as.matrix(x, ...)

Arguments

Value

A matrix.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Combine Matrix-Like Objects by Columns or Rows

Description

Compared to the ColumnLinkedMatrix and RowLinkedMatrix constructor functions, nested LinkedMatrix objects that are passed via ... will not be treated as matrix-like objects, but their nodes will be extracted and merged with the new ColumnLinkedMatrix (for cbind.ColumnLinkedMatrix) or RowLinkedMatrix (for rbind.RowLinkedMatrix) object for a more compact representation.

Usage

## S3 method for class 'ColumnLinkedMatrix'
cbind(..., deparse.level = 0L)

## S3 method for class 'RowLinkedMatrix'
rbind(..., deparse.level = 1L)

Arguments

Details

cbind.ColumnLinkedMatrix currently only works for ColumnLinkedMatrix objects, rbind.RowLinkedMatrix only for RowLinkedMatrix.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Maps Each Column or Row Index of a Linked Matrix to the Column or Row Index of Its Corresponding Node

Description

If j for ColumnLinkedMatrix or i for RowLinkedMatrix is passed, it will only generate entries for the given indices. sort, which is set by default, determines whether j or i should be sorted before building the index.

Usage

index(x, ...)

Arguments

Value

A matrix.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Returns the Number of Nodes

Description

Returns the number of nodes.

Usage

nNodes(x)

Arguments

Value

The number of nodes.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.

Examples

# Create an example RowLinkedMatrix from various matrix-like objects that
# correspond in dimensions
m <- RowLinkedMatrix(
    ff::ff(initdata = rnorm(50), dim = c(5, 10)),
    bigmemory::big.matrix(init = rnorm(50), nrow = 5, ncol = 10),
    matrix(data = rnorm(50), nrow = 5, ncol = 10)
)

# Get the number of nodes of the RowLinkedMatrix
nNodes(m)

Returns the Column or Row Indexes at Which Each Node Starts and Ends

Description

Returns the column or row indexes at which each node starts and ends.

Usage

nodes(x)

Arguments

Value

A matrix.

See Also

ColumnLinkedMatrix-class, RowLinkedMatrix-class, and LinkedMatrix-class for more information on the ColumnLinkedMatrix, RowLinkedMatrix, and LinkedMatrix classes.