Skip to contents

combine_matrices_fast

Source: R/fastReseg_full_pipeline.R
combine_matrices_fast.Rd

Efficiently combines a list of matrices by aligning along the necessary axis and then binding.

Usage

combine_matrices_fast(
  matrix_list,
  bind = c("cbind", "rbind"),
  fill = 0,
  output_type = c("auto", "dense", "sparse")
)

Arguments

matrix_list

A list of matrices to combine. All matrices must have non-NULL dimension names. Matrices can be either sparse (Matrix::sparseMatrix) or dense (base::matrix). Mixed inputs are supported according to output_type.

bind

Character string, "cbind" or "rbind". Controls the bind direction:

  • "cbind": align rows (union of rownames) then column-bind. Rownames must be unique; colnames may be duplicated.

  • "rbind": align columns (union of colnames) then row-bind. Colnames must be unique; rownames may be duplicated.

fill

Value to fill missing entries introduced by alignment. Default 0.

  • If output_type = "sparse" (or all inputs are sparse) and fill = NA, the function sets fill = 0 with a warning.

  • If fill != 0 and sparse output is requested, the function converts to dense and warns.

output_type

One of "auto", "dense", "sparse". Controls the output class.

  • "auto": all sparse → sparse; all dense → dense; mixed → sparse only when fill == 0, otherwise dense.

  • "dense": convert any sparse inputs to dense and return a dense matrix.

  • "sparse": convert any dense inputs to sparse and return a sparse matrix. If fill != 0, converts to dense with warning.

Value

A combined matrix:

  • If output_type resolves to sparse, returns a Matrix::sparseMatrix (typically dgCMatrix).

  • If output_type resolves to dense, returns a base R matrix.

Details

  • Alignment is performed on the axis specified by bind, and names on the aligned axis must be unique for correctness.

  • The non-aligned axis may contain duplicated names, which are preserved through binding.

  • Missing rows/columns introduced by alignment are filled with fill. For sparse outputs, missing entries are zeros.

  • If fill = NA and sparse output is selected, fill is replaced by 0 with a warning. If fill != 0 and sparse output is requested, the function converts to dense (with a warning) to represent non-zero fills.

Examples

## --- Dense matrices, rbind ---
A2 <- matrix(11, 2, 2, dimnames = list(c("ra","rb"), c("u","v")))   
B2 <- matrix(22, 2, 3, dimnames = list(c("rc","rd"), c("v","w","x")))
out_r_dense <- combine_matrices_fast(list(A2, B2), bind = "rbind", fill = NA)
stopifnot(is.matrix(out_r_dense), identical(dim(out_r_dense), c(4L,4L)))

## --- Sparse matrices, cbind: duplicated colnames allowed ---
S1 <- Matrix::rsparsematrix(3, 2, 0.5)
dimnames(S1) <- list(c("r1","r2","r3"), c("sA","sA")) # duplicate colnames
S2 <- Matrix::rsparsematrix(2, 3, 0.5)
dimnames(S2) <- list(c("r2","r4"), c("sB","sA","sC")) # another "sA"
out_c_sparse <- combine_matrices_fast(list(S1, S2), bind = "cbind", fill = 0)
stopifnot(inherits(out_c_sparse, "sparseMatrix"), identical(dim(out_c_sparse), c(4L,5L)))

## --- Mixed inputs, nonzero fill forces dense ---
Mx <- matrix(1, 2, 2, dimnames = list(c("a","b"), c("x","y"))) 
Sy <- Matrix::rsparsematrix(2, 1, 1); dimnames(Sy) <- list(c("b","c"), "z")
out_mixed <- combine_matrices_fast(list(Mx, Sy), bind = "cbind", fill = NA, output_type = "auto")
stopifnot(is.matrix(out_mixed))  # dense result due to nonzero 'fill'

## --- Mixed inputs, 3 matrices, zero fill, sparse preserved ---
Td <- matrix(5, 1, 1, dimnames = list("a", "zz"))
out_mixed3 <- combine_matrices_fast(list(Mx, Sy, Td), bind = "cbind", fill = 0, output_type = "auto")
stopifnot(inherits(out_mixed3, "sparseMatrix"), identical(dim(out_mixed3), c(3L,4L)))