hdf5_create_matrix: Create an HDF5 dataset and return an HDF5Matrix object

In BigDataStatMeth: Title: Scalable Statistical Computing with HDF5-Backed Matrices

Create an HDF5 dataset and return an HDF5Matrix object

Description

Creates a new HDF5 dataset (optionally writing data) and returns an HDF5Matrix object pointing to it.

Usage

hdf5_create_matrix(
  filename,
  dataset,
  nrow = NULL,
  ncol = NULL,
  data = NULL,
  dtype = c("double", "integer", "logical"),
  overwrite = FALSE,
  compression = NULL
)

Arguments

filename	Character. Path to the HDF5 file (created if it does not exist).
dataset	Character. Full path inside the HDF5 file in "group/dataset" or "group/subgroup/dataset" format.
nrow	Integer or NULL. Number of rows. Required when data = NULL.
ncol	Integer or NULL. Number of columns. Required when data = NULL.
data	Numeric matrix, integer matrix, or numeric vector, or NULL. When non-NULL, the data are written to the new dataset. When NULL, an empty (zero-filled) dataset of size nrow x ncol is created.
dtype	Character. Element type: "double" (default), "integer", or "logical".
overwrite	Logical. If TRUE, an existing dataset is replaced.
compression	Integer (0-9) or NULL. gzip compression level. NULL uses the global option set by hdf5matrix_options (default 6). Use 0 to disable compression.

Details

Replaces the legacy bdCreate_hdf5_matrix() / bdCreate_hdf5_emptyDataset() calls in the R6+S3 interface. The legacy functions remain available for backward compatibility.

Row and column names stored in the dimnames attribute of data are written to the HDF5 file automatically.

Value

An HDF5Matrix object pointing to the created dataset.

See Also

hdf5matrix_options to set global compression default.

Examples

tmp <- tempfile(fileext = ".h5")

# Create from matrix data
mat <- matrix(rnorm(200), nrow = 20, ncol = 10)
X <- hdf5_create_matrix(tmp, "data/X", data = mat)
dim(X)  # 20 x 10

# Create empty dataset
Y <- hdf5_create_matrix(tmp, "data/Y", nrow = 1000, ncol = 500)
dim(Y)  # 1000 x 500

# No compression (useful for benchmarks or intermediate results)
Z <- hdf5_create_matrix(tmp, "data/Z", data = mat, compression = 0)

X$close(); Y$close(); Z$close()
unlink(tmp)

BigDataStatMeth documentation built on May 15, 2026, 1:07 a.m.