BigDataStatMeth (version 1.0.3)

bdCreate_diagonal_hdf5: Create Diagonal Matrix or Vector in HDF5 File

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.

Usage

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

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)

Arguments

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)

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

Examples

if (FALSE) {
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")
}