initializeCpp: Initialize matrix in C++ memory space

In LTLA/beachmat: Compiling Bioconductor to Handle Each Matrix Type

Initialize matrix in C++ memory space

Description

Initialize a tatami matrix object in C++ memory space from an abstract numeric R matrix. This object simply references the R memory space and avoids making any copies of its own, so it can be cheaply re-created when needed inside each function.

Usage

initializeCpp(x, ...)

Arguments

x

A matrix-like object, typically from the Matrix or DelayedArray packages. Alternatively, an external pointer from a previous call to initializeCpp, which is returned without modification.

...

Further arguments used by specific methods, such as: .check.na, a logical vector indicating whether to check for NA values in integer and logical matrices. If TRUE (the default), any NAs are cast to their double-precision equivalents when reading from the tatami matrix. This can be set to FALSE to improve performance if the caller knows that x does not contain NAs. Fields should generally be prefixed by the matrix type, to avoid conflicts with arguments from other packages. For example, hdf5.realize can be used in beachmat.hdf5 to load a HDF5-backed matrix into memory.

Details

Do not attempt to serialize the return value; it contains a pointer to external memory, and will not be valid after a save/load cycle. Users should not be exposed to the returned pointers; rather, developers should call initialize at the start to obtain a C++ object for further processing. As mentioned before, this initialization process is very cheap so there is no downside from just recreating the object within each function body.

Value

An external pointer to a C++ object containing a tatami matrix.

Examples

# Mocking up a count matrix:
x <- Matrix::rsparsematrix(1000, 100, 0.1)
y <- round(abs(x))

stuff <- initializeCpp(y)
stuff

LTLA/beachmat documentation built on Dec. 21, 2024, 12:11 a.m.