| Title: | Perform Complex Matrix Operations Symbolically on Sparse Matrices |
| Version: | 0.1.0 |
| Description: | Provides a framework for lazy computation on large sparse matrices. Enables lazy evaluation of normalized data matrices, preserving sparsity throughout operations without materializing dense intermediate objects. Implements statistical algorithms including LSQR for sparse least squares as described in Paige and Saunders (1982) <doi:10.1145/355984.355989> and partial singular value decomposition via the augmented implicitly restarted Lanczos bidiagonalization algorithm of Baglama and Reichel (2005) <doi:10.1137/04060593X>. |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Suggests: | bench, dplyr, ggplot2, knitr, rmarkdown, scales, testthat (≥ 3.0.0), tidyr |
| Config/testthat/edition: | 3 |
| Imports: | Matrix, methods, stats, irlba, Rcpp |
| VignetteBuilder: | knitr |
| LinkingTo: | Rcpp, RcppArmadillo |
| URL: | https://vsegersall.github.io/lazymatrix/ |
| NeedsCompilation: | yes |
| Packaged: | 2026-07-06 01:06:49 UTC; jola |
| Author: | Viktor Segersall [aut, cre, cph] |
| Maintainer: | Viktor Segersall <viktor.segersall@proton.me> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-14 16:40:07 UTC |
Matrix multiplication for vector and LazyMatrix
Description
Multiplies a LazyMatrix object by a vector.
Usage
## S4 method for signature 'ANY,LazyMatrix'
x %*% y
Arguments
x |
A numeric vector. |
y |
A |
Value
A Matrix object of class dgeMatrix.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
b <- c(1, 2)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
b %*% lazy_a
Perform the dot product between two LazyColumn vectors
Description
Computes the inner product between two LazyColumn objects.
Usage
## S4 method for signature 'LazyColumn,LazyColumn'
x %*% y
Arguments
x |
A |
y |
A |
Value
A numeric value with the resulting scalar.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
b <- rnorm(nrow(X))
lazy_col <- X[, 1]
lazy_col_2 <- X[, 2]
lazy_col %*% lazy_col_2
Perform the dot product between a LazyColumn and a numeric vector
Description
Computes the inner product of a LazyColumn object
and a numeric vector.
If y is a scalar, scalar multiplication is performed.
If y is a vector of the same length as the column, the dot product
is performed.
Usage
## S4 method for signature 'LazyColumn,numeric'
x %*% y
Arguments
x |
A |
y |
A numeric scalar or vector. |
Value
A numeric value with the resulting scalar.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
b <- rnorm(nrow(X))
lazy_col <- X[, 1]
lazy_col %*% b
Matrix multiplication for LazyMatrix and vector
Description
Multiplies a LazyMatrix object by a vector.
Usage
## S4 method for signature 'LazyMatrix,ANY'
x %*% y
Arguments
x |
A |
y |
A numeric vector. |
Value
A numeric matrix.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
b <- c(1, 2, 3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_a %*% b
Matrix multiplication for LazyMatrix and matrix-object.
Description
Multiplies a LazyMatrix object by a matrix
Usage
## S4 method for signature 'LazyMatrix,matrix'
x %*% y
Arguments
x |
A |
y |
A matrix-object. |
Value
A matrix-object with the product of the lazy and non lazy object.
Examples
mat_a <- matrix(rep(1, 6), nrow = 2, ncol = 3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
set.seed(123)
m <- matrix(rnorm(6), nrow = 3, ncol = 2)
lazy_a %*% m
Perform the dot product between a numeric vectorand a LazyColumn
Description
Computes the inner product of a numeric vector
and a LazyColumn object.
If x is a scalar, scalar multiplication is performed.
If x is a vector of the same length as the column, the dot product
is performed.
Usage
## S4 method for signature 'numeric,LazyColumn'
x %*% y
Arguments
x |
A numeric scalar or vector. |
y |
A |
Value
A numeric value with the resulting scalar.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
b <- rnorm(nrow(X))
lazy_col <- X[, 1]
b %*% lazy_col
Multiply element-wise two LazyColumn vectors
Description
Computes the element-wise multiplication of two LazyColumn objects
, preserving the lazy structure.
Usage
## S4 method for signature 'LazyColumn,LazyColumn'
e1 * e2
Arguments
e1 |
A |
e2 |
A |
Value
A numeric vector with the resulting vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- X[, 1]
lazy_col_2 <- X[, 2]
lazy_col_2 * lazy_col
Multiply a LazyColumn by a numeric scalar or vector
Description
Computes the element-wise multiplication of a LazyColumn object
with a numeric value, preserving the lazy structure.
If e2 is a scalar, scalar multiplication is performed.
If e2 is a vector of the same length as the column, element-wise
multiplication is performed.
Usage
## S4 method for signature 'LazyColumn,numeric'
e1 * e2
Arguments
e1 |
A |
e2 |
A numeric scalar or vector. |
Value
A numeric vector with the resulting vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- X[, 1]
lazy_col * 2
lazy_col * rnorm(nrow(X))
Multiply a numeric scalar or vector by a LazyColumn
Description
Computes the element-wise multiplication of a LazyColumn object
with a numeric value, preserving the lazy structure.
If e1 is a scalar, scalar multiplication is performed.
If e1 is a vector of the same length as the column, element-wise
multiplication is performed.
Usage
## S4 method for signature 'numeric,LazyColumn'
e1 * e2
Arguments
e1 |
A numeric scalar or vector. |
e2 |
A |
Value
A numeric vector with the resulting vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- X[, 1]
2* lazy_col
rnorm(nrow(X)) * lazy_col
Vector Addition between regular vector and LazyColumn
Description
Sums a regular base vector and a LazyColumn vector.
Usage
## S4 method for signature 'ANY,LazyColumn'
e1 + e2
Arguments
e1 |
A numeric vector. |
e2 |
A |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
b <- rnorm(nrow(mat_a))
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[, 2]
b + lazy_col
Vector Addition between LazyColumn and regular vector
Description
Sums a LazyColumn vector and a regular base vector.
Usage
## S4 method for signature 'LazyColumn,ANY'
e1 + e2
Arguments
e1 |
A |
e2 |
A numeric vector. |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
b <- rnorm(nrow(mat_a))
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[,2]
lazy_col + b
Vector Addition between two LazyColumn vectors.
Description
Sums two LazyColumn vectors.
Usage
## S4 method for signature 'LazyColumn,LazyColumn'
e1 + e2
Arguments
e1 |
A |
e2 |
A |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[,2]
lazy_col_2 <- lazy_a[, 3]
lazy_col_2 + lazy_col
Vector Subtraction between regular vector and LazyColumn
Description
Subtracts a LazyColumn vector from a base vector.
Usage
## S4 method for signature 'ANY,LazyColumn'
e1 - e2
Arguments
e1 |
A |
e2 |
A numeric vector. |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
b <- rnorm(nrow(mat_a))
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[, 2]
b - lazy_col
Vector subtraction between a LazyColumn vector and a regular R vector.
Description
Subtracts a numeric R vector from a LazyColumn vector.
Usage
## S4 method for signature 'LazyColumn,ANY'
e1 - e2
Arguments
e1 |
A |
e2 |
A numeric vector. |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
b <- rnorm(nrow(mat_a))
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[,2]
lazy_col - b
Vector Subtraction between two LazyColumn vectors.
Description
Subtracts a LazyColumn vector from another LazyColumn vector.
Usage
## S4 method for signature 'LazyColumn,LazyColumn'
e1 - e2
Arguments
e1 |
A |
e2 |
A |
Value
A numeric vector.
Examples
mat_a <- base::matrix(rnorm(12), nrow = 3, ncol = 4)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[, 2]
lazy_col_2 <- lazy_a[, 3]
lazy_col_2 - lazy_col
Comparison operators for LazyColumn
Description
Enables logical comparisons (>, <, >=, <=, ==, !=) on a
LazyColumn, comparing against its scaled values.
Usage
## S4 method for signature 'LazyColumn,numeric'
Compare(e1, e2)
Arguments
e1 |
A |
e2 |
A |
Value
A logical vector.
Comparison operators for LazyColumn
Description
Enables logical comparisons (>, <, >=, <=, ==, !=) on a
LazyColumn, comparing against its scaled values.
Usage
## S4 method for signature 'numeric,LazyColumn'
Compare(e1, e2)
Arguments
e1 |
A |
e2 |
A |
Value
A logical vector.
LazyColumn S4 class
Description
An S4 class to represent a column vector as a subset of a LazyMatrix-object
Value
An object of class LazyColumn with slots data (numeric vector), scale (numeric scalar), and location (numeric scalar); represents a column of a LazyMatrix (scaled via scale and location).
Slots
dataThe underlying data column vector.
scaleNumeric scalar containing column-scale parameter.
locationNumeric scalar containing the column-location parameter.
Examples
mat <- matrix(1:6, nrow = 2, ncol = 3)
lazy_mat <- LazyMatrix(mat, "sd", "mean")
lazy_column <- lazy_mat[, 2]
Constructs a LazyMatrix object.
Description
Constructs a LazyMatrix object.
Usage
LazyMatrix(data, scale = NULL, location = NULL)
Arguments
data |
a matrix object. |
scale |
optional scaling parameter. |
location |
optional location parameter. |
Value
A LazyMatrix object.
Examples
mat_a <- matrix(1:6, nrow=3, ncol=2)
lazy_a <- LazyMatrix(mat_a, scale="sd", location="mean")
lazy_a
LazyMatrix S4 class
Description
An S4 class to represent a lazily transformed matrix with scaling and location parameters.
Value
An object of class LazyMatrix with slots data (matrix, possibly sparse), col_scales, row_scales, col_locations, row_locations.
Represents the original data matrix plus stored scaling/centering parameters used for lazy operations
Slots
dataThe underlying matrix.
col_scalesNumeric vector of column scales.
row_scalesNumeric vector of row scales.
col_locationsNumeric vector of column locations.
row_locationsNumeric vector of row locations.
Examples
mat <- matrix(1:6, nrow=2, ncol=3)
obj <- LazyMatrix(mat, "sd", "mean")
Retrieve or set the row or column names of a LazyMatrix object.
Description
Retrieve or set the row or column names of a LazyMatrix object.
Usage
## S4 method for signature 'LazyMatrix'
colnames(x)
Arguments
x |
A LazyMatrix object. |
Value
A character vector of column names, or NULL if the matrix has no column names.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
colnames(lazy_a)
Crossproduct for LazyMatrix
Description
Computes the crossproduct of a LazyMatrix object as it's Gram matrix or computes the transposed matrix-vector multiplication.
Usage
## S4 method for signature 'LazyMatrix,ANY'
crossprod(x, y = NULL)
Arguments
x |
A |
y |
An optional numeric vector or matrix. If NULL, computes the Gram matrix of x. |
Value
A matrix: the Gram matrix if y is NULL, otherwise the crossproduct result.
Examples
mat_a <- matrix(rep(1, 6), nrow=2, ncol=3)
b <- c(1, 2)
lazy_a <- LazyMatrix(mat_a, scale="sd", location="mean")
crossprod(lazy_a)
crossprod(lazy_a, b)
Returns the dimension of a LazyMarix Object.
Description
Returns the dimension of a LazyMarix Object.
Usage
## S4 method for signature 'LazyMatrix'
dim(x)
Arguments
x |
A LazyMatrix object. |
Value
For an array (and hence in particular, for a matrix) dim retrieves the dim attribute of the object. It is NULL or a vector of mode integer. The replacement method changes the "dim" attribute (provided the new value is compatible) and removes any "dimnames" and "names" attributes.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
dim(lazy_a)
Fast crossprod for LazyMatrix (dense case)
Description
Fast crossprod for LazyMatrix (dense case)
Usage
lazy_crossprod_vec(x, s, c, y)
Arguments
x |
Dense matrix |
s |
Column scale inverse vector (1 / col_scales) |
c |
Column location vector (col_locations) |
y |
Vector to multiply |
Value
Vector result of t(X_tilde) * y
Fast crossprod for LazyMatrix (sparse case)
Description
Fast crossprod for LazyMatrix (sparse case)
Usage
lazy_crossprod_vec_sp(x, s, c, y)
Arguments
x |
Sparse matrix (dgCMatrix) |
s |
Column scale inverse vector (1 / col_scales) |
c |
Column location vector (col_locations) |
y |
Vector to multiply |
Value
Vector result of t(X_tilde) * y
Get the length of a LazyColumn
Description
Get the length of a LazyColumn
Usage
## S4 method for signature 'LazyColumn'
length(x)
Arguments
x |
A LazyColumn object. |
Value
An integer value containing the number of elements within the vector.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_col <- lazy_a[, 2]
length(lazy_col)
Performs least squares estimation on LazyMatrix object using the iterative lsqr algorithm.
Description
Performs least squares estimation on LazyMatrix object using the iterative lsqr algorithm.
Usage
lsqr(x, y, ...)
## S4 method for signature 'LazyMatrix'
lsqr(x, y)
Arguments
x |
A LazyMatrix object. |
y |
A response vector. |
... |
Additional arguments (currently unused). |
Value
A Matrix-object with the regression coefficients of the covariates.
Examples
set.seed(123)
mat_a <- base::matrix(rnorm(500), nrow = 50, ncol = 10)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
response_vector <- rnorm(nrow(mat_a))
lsqr(lazy_a, response_vector)
Returns the number of columns of the data matrix
Description
Returns the number of columns of the data matrix
Usage
## S4 method for signature 'LazyMatrix'
ncol(x)
Arguments
x |
A LazyMatrix object. |
Value
an integer of length 1 or NULL.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
ncol(lazy_a)
Compute the norm of a LazyMatrix or LazyColumn
Description
Dispatches to the appropriate method based on the class of x.
Usage
norm(x, ...)
Arguments
x |
A |
... |
Additional arguments passed to methods, such as |
Value
For LazyColumn, a numeric scalar containing the Euclidean norm.
For LazyMatrix, a numeric scalar containing the Frobenius norm.
Perform the norm of a LazyColumn vector
Description
Computes the norm of a LazyColumn object.
Usage
## S4 method for signature 'LazyColumn'
norm(x, type = "2")
Arguments
x |
A |
type |
A character value defining type of norm. Default is Euclidean norm. |
Value
A numeric value with the resulting scalar.
Examples
mat_a <- base::matrix(rnorm(12), nrow=3, ncol=4)
X <- LazyMatrix(mat_a, "sd", "mean")
b <- rnorm(nrow(X))
lazy_col <- X[, 1]
norm(lazy_col)
Computes the Frobenius norm of a LazyMatrix object.
Description
Computes the Frobenius norm of a LazyMatrix object.
Usage
## S4 method for signature 'LazyMatrix'
norm(x)
Arguments
x |
A |
Value
A numeric scalar representing the Frobenius norm of the matrix.
Examples
mat_a <- base::matrix(rnorm(50), nrow = 10, ncol = 5)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
norm(lazy_a)
Returns the number of rows of the data matrix
Description
Returns the number of rows of the data matrix
Usage
## S4 method for signature 'LazyMatrix'
nrow(x)
Arguments
x |
A LazyMatrix object. |
Value
an integer of length 1 or NULL.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
nrow(lazy_a)
Performs a principal component analysis on the LazyMatrix object using irlba:s sparse svd.
Description
Performs a principal component analysis on the LazyMatrix object using irlba:s sparse svd.
Usage
## S4 method for signature 'LazyMatrix'
prcomp(x, retx = TRUE, tol = NULL, rank. = NULL, ...)
Arguments
x |
a LazyMatrix object. |
retx |
a logical value indicating whether the rotated variables should be returned. |
tol |
a value indicating the magnitude below which components should be omitted. (Components are omitted if their standard deviations are less than or equal to tol times the standard deviation of the first component.) With the default null setting, no components are omitted (unless rank. is specified less than min(dim(x)).). Other settings for tol could be tol = 0 or tol = sqrt(.Machine$double.eps), which would omit essentially constant components. |
rank. |
optionally, a number specifying the maximal rank, i.e., maximal number of principal components to be used. Can be set as alternative or in addition to tol, useful notably when the desired rank is considerably smaller than the dimensions of the matrix. |
... |
Additional arguments passed to underlying methods. |
Value
A list of class \"prcomp\" containing:
sdev |
The standard deviations of the principal components (i.e., the square roots of the eigenvalues of the covariance/correlation matrix, calculated using the singular values of the data matrix). |
rotation |
The matrix of variable loadings (columns are eigenvectors). |
x |
If |
center |
The centering used, or |
scale |
The scaling applied to the data, or |
Examples
set.seed(123)
mat_a <- matrix(rnorm(500), nrow=50, ncol=10)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
pca_lazy <- prcomp(lazy_a)
Set names for a LazyColumn
Description
Assigns names to the underlying data of a LazyColumn, returning a
new LazyColumn with the same scale and location as the original.
This enables name-based subsetting via [ on LazyColumn
objects, mirroring stats::setNames() for ordinary vectors.
Usage
## S4 method for signature 'LazyColumn,character'
setNames(object = nm, nm)
Arguments
object |
A |
nm |
A character vector of names, with length equal to
|
Value
A new LazyColumn with named data, preserving the original
scale and location.
Examples
set.seed(123)
mat_a <- matrix(rnorm(500), nrow = 50, ncol = 10)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_c <- lazy_a[, 2]
lazy_named <- setNames(lazy_c[1:26], letters[1:26])
lazy_named["a"]
Subset a LazyColumn
Description
Subsets a LazyColumn object using standard R indexing rules:
positive integers, negative integers, logical vectors (with recycling),
character vectors (if named), zero, or missing (nothing).
Usage
## S4 method for signature 'LazyColumn,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]
Arguments
x |
A |
i |
Index: positive integers, negative integers, logical vector, character vector (if named), zero, or missing (nothing). |
j |
Not used for |
... |
Additional arguments (ignored). |
drop |
Logical. Currently ignored — single element extraction always returns a plain scaled numeric, consistent with vector subsetting. |
Value
A LazyColumn when multiple elements are selected, or a
scaled numeric value when a single element is selected.
Examples
set.seed(123)
mat_a <- matrix(rnorm(500), nrow = 50, ncol = 10)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_c <- lazy_a[, 2]
# Single element → plain scaled numeric
lazy_c[2]
# Multiple elements → LazyColumn
lazy_c[c(1, 3, 5)]
Subset a LazyMatrix by columns
Description
Subsets a LazyMatrix object by columns, returning either a
LazyColumn or a new LazyMatrix depending on the number
of columns selected. Row subsetting is not yet supported.
Usage
## S4 method for signature 'LazyMatrix,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]
Arguments
x |
A |
i |
Row index. Must be missing as row subsetting is not yet supported. |
j |
Column index. Either a single integer returning a |
... |
Additional arguments (ignored). |
drop |
Logical. Currently ignored. |
Value
A LazyColumn if a single column is selected, or a
LazyMatrix if multiple columns are selected.
Examples
A <- Matrix::sparseMatrix(i = c(1,2,3), j = c(1,2,3), x = c(1,2,3))
lazy_m <- LazyMatrix(A, "sd", "mean")
# Single column → LazyColumn
lazy_col <- lazy_m[, 2]
# Multiple columns → LazyMatrix
lazy_subset <- lazy_m[, 1:3]
Singular Value decomposition for LazyMatrix.
Description
Performs lazy SVD using irlba for partial Singular value decomposition on sparse matrices.
Usage
## S4 method for signature 'LazyMatrix'
svd(x, nu = min(n, p), nv = min(n, p))
Arguments
x |
A |
nu |
number of left singular vectors to estimate (defaults to nv). |
nv |
number of right singular vectors to estimate. |
Value
A list with entries:
d |
max(nu, nv) approximate singular values |
u |
nu approximate left singular vectors (only when right_only=FALSE) |
v |
nv approximate right singular vectors |
iter |
The number of Lanczos iterations carried out |
mprod |
The total number of matrix vector products carried out |
Examples
set.seed(123)
mat_a <- matrix(rnorm(500), nrow = 50, ncol = 10)
lazy_a <-LazyMatrix(mat_a, scale = "sd", location = "mean")
S <- svd(lazy_a)
# Receive singular values with
S$d
Given a LazyMatrix x, t returns the transpose of x.
Description
Given a LazyMatrix x, t returns the transpose of x.
Usage
## S4 method for signature 'LazyMatrix'
t(x)
Arguments
x |
A |
Value
A LazyMatrix object with the transposed data matrix.
Examples
mat_a <- base::matrix(rep(1, 6), nrow=2, ncol=3)
lazy_a <- LazyMatrix(mat_a, "sd", "mean")
lazy_t <- t(lazy_a)