hdf5_create_matrix: 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
)

Value

An HDF5Matrix object pointing to the created dataset.

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.

Examples

Run this code

# \donttest{
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)
# }