h5WriteDataset: Write array-like data into an existing H5 dataset

In hdf5r.Extra: Extensions for 'HDF5' R Interfaces

Write array-like data into an existing H5 dataset

Description

Low-level helper function to write atomic R data into an existing H5 dataset. All data written will be treated as array for HDF5.

Usage

h5WriteDataset(x, robj, ...)

## S3 method for class 'H5D'
h5WriteDataset(
  x,
  robj,
  idx_list = NULL,
  transpose = FALSE,
  block_size = 5000L,
  verbose = TRUE,
  ...
)

## S3 method for class 'H5Group'
h5WriteDataset(
  x,
  robj,
  name,
  idx_list = NULL,
  transpose = FALSE,
  block_size = 5000L,
  verbose = TRUE,
  ...
)

## S3 method for class 'H5File'
h5WriteDataset(
  x,
  robj,
  name,
  idx_list = NULL,
  transpose = FALSE,
  block_size = 5000L,
  verbose = TRUE,
  ...
)

## S3 method for class 'character'
h5WriteDataset(
  x,
  robj,
  name,
  idx_list = NULL,
  transpose = FALSE,
  block_size = 5000L,
  verbose = TRUE,
  ...
)

Arguments

x	An H5File, H5Group, H5D or a path name of HDF5 file.
robj	An R array.
...	Arguments passed to H5D$write().
idx_list	The indices for each dimension of name to subset given as a list. If NULL, the entire dataset will be use. Passed to H5D$write(args)
transpose	Whether or not to transpose the input matrix. Only works for a 2-dimension array-like object.
block_size	Default size for number of columns to transpose in a single writing. Increasing block_size may speed up but at an additional memory cost.
verbose	Print progress.
name	Name of the HDF5 dataset to be written.

Value

This is an operation function and no return. Any failure should raise an error.

Note

If you want to write robj into scalar space, you should use h5WriteScalar.

Examples

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

# Scalar (will be written into array space for HDF5) ##########
h5CreateDataset(
  tmp.file, 
  name = "test/bool", 
  dims = 1, 
  storage.mode = logical()
) # Must create the dataset first
h5WriteDataset(tmp.file, FALSE, name = "test/bool")
x <- h5Read(tmp.file, name = "test/bool")
x

h5CreateDataset(tmp.file, name = "test/num", dims = 1)
h5WriteDataset(tmp.file, 100.0, name = "test/num")
x <- h5Read(tmp.file, name = "test/num")
x

h5CreateDataset(
  tmp.file, 
  name = "test/string", 
  dims = 1, 
  storage.mode = character()
)
h5WriteDataset(tmp.file, "ABC", name = "test/string")
x <- h5Read(tmp.file, name = "test/string")
x

# Vector (1d array) ##########
x1 <- rep(FALSE, 10)
h5CreateDataset(
  tmp.file, 
  name = "vec/bool", 
  dims = 10, 
  storage.mode = logical()
)
h5WriteDataset(tmp.file, x1, name = "vec/bool")
x <- h5Read(tmp.file, name = "vec/bool")
x

x1 <- rep(1.1, 10)
h5CreateDataset(
  tmp.file, 
  name = "vec/num", 
  dims = 10
)
h5WriteDataset(tmp.file, x1, name = "vec/num")
x <- h5Read(tmp.file, name = "vec/num")
x

x1 <- rep(2.0, 5)
h5WriteDataset(
  tmp.file, 
  x1, 
  name = "vec/num", 
  idx_list = list(c(1, 3, 5, 7, 9)) # Set each indices to be written
)
x <- h5Read(tmp.file, name = "vec/num")
stopifnot(identical(x, rep(c(2.0, 1.1), 5)))

# matrix ##########
x1 <- matrix(1.0, 7, 5)
h5CreateDataset(
  tmp.file, 
  name = "mat/num", 
  dims = dim(x1)
)
h5WriteDataset(
  tmp.file, 
  x1, 
  name = "mat/num"
)
x <- h5Read(tmp.file, name = "mat/num")
x

x1 <- matrix(2.0, 3, 4)
h5WriteDataset(
  tmp.file, 
  x1, 
  name = "mat/num",
  idx_list = list(2:4, 1:4)
)
x <- h5Read(tmp.file, name = "mat/num")
print(x)

h5WriteDataset(
  tmp.file, 
  x1, 
  name = "mat/num",
  idx_list = list(1:4, 2:4),  # idx_list must match the transposed matrix
  transpose = TRUE
)
x <- h5Read(tmp.file, name = "mat/num")
print(x)

hdf5r.Extra documentation built on Oct. 18, 2024, 9:06 a.m.