rhdf5: h5write – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

h5write

Reads and write object in HDF5 files

Description

Reads and writes objects in HDF5 files. This function can be used to read and write either full arrays/vectors or subarrays (hyperslabs) within an existing dataset.

Usage

h5read                      (file, name, index=NULL,
                             start=NULL, stride=NULL, block=NULL,
                             count=NULL, compoundAsDataFrame = TRUE,
                             callGeneric = TRUE,
                             read.attributes = FALSE, drop = FALSE,
                             ..., native = FALSE,
                             s3 = FALSE, s3credentials = NULL)
h5readAttributes            (file, name, native = FALSE)
h5write                     (obj, file, name, ...)
h5write.default             (obj, file, name, 
                             createnewfile = TRUE,
                             write.attributes = FALSE, ...,
                             native = FALSE)
h5writeDataset              (obj, h5loc, name, ...)
h5writeDataset.data.frame   (obj, h5loc, name, level=6, chunk,
                             DataFrameAsCompound = TRUE)
h5writeDataset.list         (obj, h5loc, name, level=6)
h5writeDataset.matrix       (...)
h5writeDataset.integer      (...)
h5writeDataset.double       (...)
h5writeDataset.logical      (...)
h5writeDataset.character    (...)
h5writeDataset.array        (obj, h5loc, name, index = NULL,
                             start=NULL, stride=NULL, block=NULL, count=NULL,
                             size=NULL, level=6)
h5writeAttribute            (attr, h5obj, name, ...)
h5writeAttribute.matrix     (...)
h5writeAttribute.integer    (...)
h5writeAttribute.double     (...)
h5writeAttribute.logical    (...)
h5writeAttribute.character  (...)
h5writeAttribute.array      (attr, h5obj, name, size)

Arguments

`obj`	The R object to be written.
`attr`	The R object to be written as an HDF5 attribute.
`file`	The filename (character) of the file in which the dataset will be located. For advanced programmers it is possible to provide an object of class `H5IdComponent` representing a H5 location identifier (file or group). See `H5Fcreate`, `H5Fopen`, `H5Gcreate`, `H5Gopen` to create an object of this kind.
`h5loc`	An object of class `H5IdComponent` representing a H5 location identifier (file or group). See `H5Fcreate`, `H5Fopen`, `H5Gcreate`, `H5Gopen` to create an object of this kind.
`h5obj`	An object of class `H5IdComponent` representing a H5 object identifier (file, group, or dataset). See `H5Fcreate`, `H5Fopen`, `H5Gcreate`, `H5Gopen`, `H5Dcreate`, or `H5Dopen` to create an object of this kind.
`name`	The name of the dataset in the HDF5 file. The name of the attribute for hwriteAttribute.
`index`	List of indices for subsetting. The length of the list has to agree with the dimensional extension of the HDF5 array. Each list element is an integer vector of indices. A list element equal to NULL choses all indices in this dimension. Counting is R-style 1-based.
`start`	The start coordinate of a hyperslab (similar to subsetting in R). Counting is R-style 1-based. This argument is ignored, if index is not NULL.
`stride`	The stride of the hypercube. Read the introduction http://ftp.hdfgroup.org/HDF5/Tutor/phypecont.html before using this argument. R behaves like Fortran in this example. This argument is ignored, if index is not NULL.
`block`	The block size of the hyperslab. Read the introduction http://ftp.hdfgroup.org/HDF5/Tutor/phypecont.html before using this argument. R behaves like Fortran in this example. This argument is ignored, if index is not NULL.
`count`	The number of blocks to be written. This argument is ignored, if index is not NULL.
`level`	The compression level. An integer value between 0 (no compression) and 9 (highest and slowest compression). Only used, if the dataset does not yet exist. See `h5createDataset` to create an dataset.
`chunk`	Specifies the number of items to be include in an HDF5 chunk. When writing a `data.frame` this represents the number of rows to be included in a chunk. If left unspecified the defaults is the smaller of: the total number of rows or the number of rows that fit within 4GB of memory.
`native`	An object of class `logical`. If TRUE, array-like objects are treated as stored in HDF5 row-major rather than R column-major orientation. Using `native = TRUE` increases HDF5 file portability between programming languages. A file written with `native = TRUE` should also be read with `native = TRUE`

`compoundAsDataFrame`	If true, a compound datatype will be coerced to a data.frame. This is not possible, if the dataset is multi-dimensional. Otherwise the compound datatype will be returned as a list. Nested compound data types will be returned as a nested list.
`DataFrameAsCompound`	If true, a data.frame will be saved as a compound data type. Otherwise it is saved like a list. The advantage of saving a data.frame as a compound data type is that it can be read as a table from python or with a struct-type from C. The disadvantage is that the data has to be rearranged on disk and thus can slow down I/O. If fast reading is required, DataFrameAsCompound=FALSE is recommended.
`callGeneric`	If TRUE a generic function h5read.classname will be called if it exists depending on the dataset's class attribute within the HDF5 file. This function can be used to convert the standard output of h5read depending on the class attribute. Note that h5read is not a S3 generic function. Dispatching is done based on the HDF5 attribute after the standard h5read function.
`size`	The length of string data type. Variable lengt strings are not yet supported.
`createnewfile`	If TRUE, a new file will be created if necessary.
`read.attributes`	(logical) If TRUE, the HDF5 attributes are read and attached to the respective R object.
`drop`	(logical) If TRUE, the HDF5 object is read as a vector with NULL dim attributes.
`write.attributes`	(logical) If TRUE, all R-attributes attached to the object `obj` are written to the HDF5 file.
`s3`	Logical value indicating whether the file argument should be treated as a URL to an Amazon S3 bucket, rather than a local file path.
`s3credentials`	A list of length three, providing the credentials for accessing files in a private Amazon S3 bucket.
`...`	Further arguments passed to `H5Dread`.

Details

Read/writes an R object from/to an HDF5 file. If neither of the arguments start, stride, block, count is specified, the dataset has the same dimension in the HDF5 file and in memory. If the dataset already exists in the HDF5 file, one can read/write subarrays, so called hyperslabs from/to the HDF5 file. The arguments start, stride, block, count define the subset of the dataset in the HDF5 file that is to be read/written. See these introductions to hyperslabs: https://support.hdfgroup.org/HDF5/Tutor/selectsimple.html, https://support.hdfgroup.org/HDF5/Tutor/select.html and http://ftp.hdfgroup.org/HDF5/Tutor/phypecont.html. Please note that in R the first dimension is the fastest changing dimension.

When viewing the HDF5 datasets with any C-program (e.g. HDFView), the order of dimensions is inverted. In the R interface counting starts with 1, whereas in the C-programs (e.g. HDFView) counting starts with 0.

Value

h5read returns an array with the data read.

h5readAttributes returns a list of all HDF5 attributes of object name.

h5write returns 0 if successful.

Author(s)

Bernd Fischer

References

https://portal.hdfgroup.org/display/HDF5

Examples

h5createFile("ex_hdf5file.h5")

# write a matrix
B = array(seq(0.1,2.0,by=0.1),dim=c(5,2,2))
attr(B, "scale") <- "liter"
h5write(B, "ex_hdf5file.h5","B")

# read a matrix
E = h5read("ex_hdf5file.h5","B")

# write and read submatrix
h5createDataset("ex_hdf5file.h5", "S", c(5,8), storage.mode = "integer", chunk=c(5,1), level=7)
h5write(matrix(1:5,nr=5,nc=1), file="ex_hdf5file.h5", name="S", index=list(NULL,1))
h5read("ex_hdf5file.h5", "S")
h5read("ex_hdf5file.h5", "S", index=list(NULL,2:3))

# Read a subset of an hdf5 file in a public S3 bucket

h5read('https://rhdf5-public.s3.eu-central-1.amazonaws.com/rhdf5ex_t_float_3d.h5', 
      s3 = TRUE, name = "a1", index = list(NULL, 3, NULL))

rhdf5

R Interface to HDF5

v2.34.0

Artistic-2.0

Authors

Bernd Fischer [aut], Mike Smith [aut, cre] (<https://orcid.org/0000-0002-7800-3848>), Gregoire Pau [aut], Martin Morgan [ctb], Daniel van Twisk [ctb]

Initial release