bdCreate_diagonal_hdf5

bdCreate_diagonal_hdf5

HDF5_ALGEBRA

1 Description

Creates a diagonal matrix or vector directly in an HDF5 file using block-wise processing to minimize memory usage. This unified function replaces separate diagonal and identity matrix creation functions, providing flexible diagonal creation with automatic parameter detection.

2 Usage

bdCreate_diagonal_hdf5(filename, group, dataset, size = NULL, scalar = 1.0, diagonal_values = NULL, output_type = "matrix", block_size = 0L, compression = 6L, overwriteFile = NULL, overwriteDataset = NULL, threads = NULL)

3 Arguments

Parameter Description
filename Character. Path to HDF5 file
group Character. Group path in HDF5 file (default: “/”)
dataset Character. Name of dataset to create
size Integer. Size of diagonal (auto-detected if diagonal_values provided)
scalar Numeric. Scalar multiplier for diagonal elements (default: 1.0)
diagonal_values Numeric vector. Custom diagonal values (optional)
output_type Character. Output format: “matrix” or “vector” (default: “matrix”)
block_size Integer. Block size for processing (default: auto-estimate)
compression Integer. Compression level 0-9 (default: 6)
overwriteFile Logical. Overwrite file if exists (default: FALSE)
overwriteDataset Logical. Overwrite dataset if exists (default: FALSE)
threads Integer. Number of threads to use (default: auto-detect)

4 Value

List with components:

  • fn: Character string with the HDF5 filename
  • ds: Character string with the full dataset path to the diagonal matrix (group/dataset)

5 Details

This function provides flexible diagonal creation with two main modes: - Vector mode: Provide custom diagonal values - Size is automatically detected from vector length - Scalar acts as additional multiplier - Ideal for custom diagonal patterns - Scalar mode: Provide size and scalar value
- Creates uniform diagonal with specified scalar - scalar=1.0 creates identity matrix/vector - Ideal for identity or uniform diagonal matrices - Output formats: - “matrix”: Creates full N×N matrix (sparse, only diagonal populated) - “vector”: Creates efficient 1×N vector with diagonal values only - Performance features: - Block-wise processing for memory efficiency - Optional compression with configurable levels - Parallel processing support for large datasets - Automatic block size optimization

6 Examples

Code 
library(BigDataStatMeth)

# Create identity matrix (1M x 1M)
bdCreate_diagonal_hdf5("identity.h5", "/", "I_matrix", 
                      size = 1000000, scalar = 1.0)

# Create scaled identity vector (more efficient)
bdCreate_diagonal_hdf5("scaled_id.h5", "/", "scaled_I", 
                      size = 500000, scalar = 3.14, 
                      output_type = "vector")

# Create custom diagonal matrix
custom_diag <- runif(10000)
bdCreate_diagonal_hdf5("custom.h5", "/", "my_diag",
                      diagonal_values = custom_diag,
                      scalar = 2.0, output_type = "matrix")

# Create custom diagonal vector (most efficient)
bdCreate_diagonal_hdf5("custom_vec.h5", "/", "my_diag_vec",
                      diagonal_values = custom_diag,
                      output_type = "vector")