h5WriteDataset {hdf5r.Extra}

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")
stopifnot(!x)

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

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")
stopifnot(identical(x, "ABC"))

# 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")
stopifnot(identical(x, x1))

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")
stopifnot(identical(x, x1))

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")
stopifnot(identical(x, x1))

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)