Write/read the dimnames of an HDF5 dataset
h5writeDimnames and h5readDimnames can be used to
write/read the dimnames of an HDF5 dataset to/from the HDF5 file.
Note that h5writeDimnames is used internally by
writeHDF5Array(x, ..., with.dimnames=TRUE)
to write the dimnames of x to the HDF5 file together
with the array data.
set_h5dimnames and get_h5dimnames are low-level
utilities that can be used to attach existing HDF5 datasets
along the dimensions of a given HDF5 dataset, or to retrieve
the names of the HDF5 datasets that are attached along the
dimensions of a given HDF5 dataset.
h5writeDimnames(dimnames, filepath, name, group=NA, h5dimnames=NULL) h5readDimnames(filepath, name, as.character=FALSE) set_h5dimnames(filepath, name, h5dimnames, dry.run=FALSE) get_h5dimnames(filepath, name)
dimnames |
The dimnames to write to the HDF5 file. Must be supplied as a list
(possibly named) with one list element per dimension in the HDF5 dataset
specified via the |
filepath |
For For |
name |
For For |
group |
Except when |
h5dimnames |
For If set to For |
as.character |
Even though the dimnames of an HDF5 dataset are usually stored as
datasets of type |
dry.run |
When set to |
h5writeDimnames and set_h5dimnames return nothing.
h5readDimnames returns a list (possibly named) with one list
element per dimension in HDF5 dataset name and containing its
dimnames retrieved from the file.
get_h5dimnames returns a character vector containing the names
of the HDF5 datasets that are currently set as the dimnames of the
dataset specified in name. The vector has one element per
dimension in dataset name. NAs in the vector indicate dimensions
along which nothing is set.
writeHDF5Array for a high-level function to write
an array-like object and its dimnames to an HDF5 file.
h5write in the rhdf5 package that
h5writeDimnames uses internally to write the dimnames
to the HDF5 file.
h5mread in this package (HDF5Array) that
h5readDimnames uses internally to read the dimnames
from the HDF5 file.
h5ls in the rhdf5 package.
HDF5Array objects.
## ---------------------------------------------------------------------
## BASIC EXAMPLE
## ---------------------------------------------------------------------
library(rhdf5) # for h5write() and h5ls()
m0 <- matrix(1:60, ncol=5)
colnames(m0) <- LETTERS[1:5]
h5file <- tempfile(fileext=".h5")
h5write(m0, h5file, "M0") # h5write() ignores the dimnames
h5ls(h5file)
h5writeDimnames(dimnames(m0), h5file, "M0")
h5ls(h5file)
get_h5dimnames(h5file, "M0")
h5readDimnames(h5file, "M0")
## Reconstruct 'm0' from HDF5 file:
m1 <- h5mread(h5file, "M0")
dimnames(m1) <- h5readDimnames(h5file, "M0")
stopifnot(identical(m0, m1))
## Create an HDF5Array object that points to HDF5 dataset M0:
HDF5Array(h5file, "M0")
## Sanity checks:
stopifnot(identical(dimnames(m0), h5readDimnames(h5file, "M0")))
stopifnot(identical(dimnames(m0), dimnames(HDF5Array(h5file, "M0"))))
## ---------------------------------------------------------------------
## SHARED DIMNAMES
## ---------------------------------------------------------------------
## If a collection of HDF5 datasets share the same dimnames, the
## dimnames only need to be written once in the HDF5 file. Then they
## can be attached to the individual datasets with set_h5dimnames():
h5write(array(runif(240), c(12, 5:4)), h5file, "A1")
set_h5dimnames(h5file, "A1", get_h5dimnames(h5file, "M0"))
get_h5dimnames(h5file, "A1")
h5readDimnames(h5file, "A1")
HDF5Array(h5file, "A1")
h5write(matrix(sample(letters, 60, replace=TRUE), ncol=5), h5file, "A2")
set_h5dimnames(h5file, "A2", get_h5dimnames(h5file, "M0"))
get_h5dimnames(h5file, "A2")
h5readDimnames(h5file, "A2")
HDF5Array(h5file, "A2")
## Sanity checks:
stopifnot(identical(dimnames(m0), h5readDimnames(h5file, "A1")[1:2]))
stopifnot(identical(dimnames(m0), h5readDimnames(h5file, "A2")))
## ---------------------------------------------------------------------
## USE h5writeDimnames() AFTER A CALL TO writeHDF5Array()
## ---------------------------------------------------------------------
## After calling writeHDF5Array(x, ..., with.dimnames=FALSE) the
## dimnames on 'x' can still be written to the HDF5 file by doing the
## following:
## 1. Write 'm0' to the HDF5 file and ignore the dimnames (for now):
writeHDF5Array(m0, h5file, "M2")
## 2. Use h5writeDimnames() to write 'dimnames(m0)' to the file and
## associate them with the "M2" dataset:
h5writeDimnames(dimnames(m0), h5file, "M2")
## 3. Use the HDF5Array() constructor to make an HDF5Array object that
## points to the "M2" dataset:
HDF5Array(h5file, "M2")
## Note that at step 2. you can use the extra arguments of
## h5writeDimnames() to take full control of where the dimnames
## should be stored in the file:
writeHDF5Array(m0, h5file, "M3")
h5writeDimnames(dimnames(m0), h5file, "M3",
group="a_secret_place", h5dimnames=c("NA", "M3_dim2"))
h5ls(h5file)
## h5readDimnames() and HDF5Array() still "finds" the dimnames:
h5readDimnames(h5file, "M3")
HDF5Array(h5file, "M3")
## Sanity checks:
stopifnot(identical(dimnames(m0), h5readDimnames(h5file, "M3")))
stopifnot(identical(dimnames(m0), dimnames(HDF5Array(h5file, "M3"))))
## ---------------------------------------------------------------------
## STORE THE DIMNAMES AS NON-CHARACTER TYPES
## ---------------------------------------------------------------------
writeHDF5Array(m0, h5file, "M4")
dimnames <- list(1001:1012, as.raw(11:15))
h5writeDimnames(dimnames, h5file, "M4")
h5ls(h5file)
h5readDimnames(h5file, "M4")
h5readDimnames(h5file, "M4", as.character=TRUE)
## Sanity checks:
stopifnot(identical(dimnames, h5readDimnames(h5file, "M4")))
dimnames(m0) <- dimnames
stopifnot(identical(
dimnames(m0),
h5readDimnames(h5file, "M4", as.character=TRUE)
))Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.