Normalize sparse rows or columns without densifying — sparse

Each selected row or column is divided by its sum and multiplied by scale_factor. Optionally, log1p() is applied to stored non-zero values. The operation preserves sparse structure and dimension labels. The native CUDA backend retains normalized storage on the device and updates the public host COO mirror from metadata already held by the object. It does not download the normalized values or the complete margin-sum vector; only a small device-validation flag crosses back before the result is returned. Native results share immutable sparse index storage with their source while retaining independent value storage and release-safe ownership.

Usage

sparse_normalize(
  x,
  margin = c("rows", "columns"),
  scale_factor = 1,
  log1p = FALSE
)

Arguments

x: A non-negative cudasparse matrix.
margin: Normalize "rows" or "columns".
scale_factor: Positive target sum before the optional log transform.
log1p: Whether to apply log1p() to normalized stored values.

Value

A cudasparse matrix on the same device as x.

Examples

x <- cuda_sparse(matrix(c(1, 0, 3, 2), 2), device = "cpu")
sparse_normalize(x, margin = "rows", scale_factor = 1)
#> <cudasparse[2x2] nnz=3 format=csr device=cpu backend=Matrix>
#> 2 x 2 sparse Matrix of class "dgCMatrix"
#>               
#> [1,] 0.25 0.75
#> [2,] .    1.00