Class for interacting with HDF5 files.

H5File objects are are the main entry point to access HDF5 data from binary files. This class represents an open HDF5 File-id. It inherits all functions of the H5RefClass.

Value

Object of class H5File.

Details

HDF5 files can be opened or generated using the H5File$new() function and a specified file access mode. H5File$new() returns a H5File object which can be used to access H5Groups and Datasets (see H5D) using subsetting parameters or according class methods.

HDF5 files which have been created or opened through H5File$new() need to be closed afterwards using $close_all(). $close_all() not only closes the file itself, but also all objects that are still open inside it (such as groups or datasets). $flush() can be used to flush unwritten data to an HDF5 file.

HDF5 Files typically contain the following objects:

Groups: Similar to a file system folder, used to organize HDF5 objects in a hierarchical way, see also H5Group
Datasets: Objects to store actual data, see also H5D
Attributes: Meta data objects to store extra information about Files, Groups and Datasets, see also H5A

Methods

new(filename = NULL, mode = c("a", "r", "r+", "w", "w-", "x"), file_create_pl = h5const$H5P_DEFAULT, file_access_pl = h5const$H5P_DEFAULT, id = NULL)

Opens or creates a new HDF5 File

Parameters

filename: Name of the file
mode: How to open it. a creates a new file or opens an existing one for read/write. r opens an existing file for reading, r+ opens an existing file for read/write. w creates a file, truncating any existing ones and w-/x are synonyms, creating a file and failing if it already exists.

get_obj_count(types = h5const$H5F_OBJ_ALL)

This function implements the HDF5-API function H5Fget_obj_count. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

get_obj_ids(types = h5const$H5F_OBJ_ALL)

This function implements the HDF5-API function H5Fget_obj_ids. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

get_filesize()

This function implements the HDF5-API function H5Fget_filesize. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

file_info()

This function implements the HDF5-API function H5Fget_info2. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details. Please note that the returned information differs if HDF5 Version 1.8.16 or HDF5 Version >= 1.10.0 is being used

get_intent()

This function implements the HDF5-API function H5Fget_intent. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

close_all(close_self = TRUE)

Closes the file, flushes it and also closes all open objects that are still open in it. This is the recommended way of closing any file. If not all objects in a file are closed, the file remains open and cannot be re-opened the regular way.

print(..., max.attributes = 10, max.listing = 10)

Prints information for the file

Parameters

max.attributes: Maximum number of attribute names to print
max.listing: Maximum number of ls-items to print
...: ignored

open(name, link_access_pl = h5const$H5P_DEFAULT, dataset_access_pl = h5const$H5P_DEFAULT, type_access_pl = h5const$H5P_DEFAULT)

Opens groups, datasets or types using the appropriate HDF5-API functions. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_d.html for datasets, https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for types and https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for general objects.

open_by_idx(n, group_name = ".", index_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Oopen_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

ls(recursive = FALSE, detailed = FALSE, index_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT, dataset_access_pl = h5const$H5P_DEFAULT, type_access_pl = h5const$H5P_DEFAULT)

Returns the contents of a file or group as a data.frame.

exists(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lexists. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

path_valid(path, check_object_valid = TRUE)

This function implements the HDF5-API function H5LTpath_valid. Please see the documentation at https://support.hdfgroup.org/HDF5/doc/HL/RM_H5LT.html#H5LTpath_valid for details.

link(obj, new_link_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Olink. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

obj_copy_to(dst_loc, dst_name, src_name, object_copy_pl = h5const$H5P_DEFAULT, link_create_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Ocopy. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

obj_copy_from(src_loc, src_name, dst_name, object_copy_pl = h5const$H5P_DEFAULT, link_create_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Ocopy. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

obj_info_by_idx(n, group_name = ".", index_field = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, remove_internal_use_only = TRUE)

This function implements the HDF5-API function H5Oget_info_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

obj_info_by_name(object_name, remove_internal_use_only = TRUE)

This function implements the HDF5-API function H5Oget_info_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

group_info()

This function implements the HDF5-API function H5Gget_info. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_g.html for details.

group_info_by_name(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Gget_info_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_g.html for details.

group_info_by_idx(n, group_name = ".", index_field = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Gget_info_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_g.html for details.

create_group(name, link_create_pl = h5const$H5P_DEFAULT, group_create_pl = h5const$H5P_DEFAULT, group_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Gcreate2 and H5Gcreate_anon (if name is NULL). Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_g.html for regular groups and https://docs.hdfgroup.org/hdf5/develop/group___h5_g.html for anonymous groups for details.

create_dataset(name, robj = NULL, dtype = NULL, space = NULL, dims = NULL, chunk_dims = "auto", gzip_level = 4, link_create_pl = h5const$H5P_DEFAULT, dataset_create_pl = h5const$H5P_DEFAULT, dataset_access_pl = h5const$H5P_DEFAULT)

This function is the main interface to create a new dataset. Its parameters allow for customization of the default behavior, i.e. in order to get a specific datatype, a certain chunk size or dataset dimensionality. Also note that this function implements the HDF5-API function H5Dcreate2 and H5Dcreate_anon (if name is NULL). Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_d.html for regular groups and https://docs.hdfgroup.org/hdf5/develop/group___h5_d.html for anonymous groups for details.

Parameters

name: The name of the new dataset. If missing, an anonymous dataset is created
robj: An R-object to take as a template for creating the dataset. Either robj or both dtype and space have to be provided
dtype: The datatype to use for the creation of the object. Can be null if robj is given.
space: The space to use for the object creation. Can be null if robj is given. Otherwise an object of type H5S which specifies the dimensions of the dataset.
dims: Dimension of the new dataset; used if space is NULL. overwrite the dimension guessed from robj if robj is given.
chunk_dims: Size of the chunk. Has to have the same length as the dataset dimension. If "auto" then the size of each chunk is estimated so that each chunk is roughly as large in bytes as the value in the hdf5r.chunk_size option. See also guess_chunks for a more detailed explanation. If set to NULL, then no chunking is used, unless explicitly set in dataset_create_pl.
gzip_level: Only if chunk_dims is not null. If given, then the dataset_create_pl is set to enable zipping at the level given here. If set to NULL, then gzip is not set (but could be set otherwise in dataset_create_pl
link_create_pl: Link creation property list. See H5P_LINK_CREATE
dataset_create_pl: Dataset creation property list. See H5P_DATASET_CREATE
dataset_access_pl: Dataset access property list. See H5P_DATASET_ACCESS

commit(name, dtype, link_create_pl = h5const$H5P_DEFAULT, type_create_pl = h5const$H5P_DEFAULT, type_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Tcommit2. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_t.html for details.

link_create_hard(obj_loc, obj_name, link_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lcreate_hard. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_create_soft(target_path, link_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lcreate_soft. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_create_external(target_filename, target_obj_name, link_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lcreate_external. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_exists(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lexists. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_move_from(src_loc, src_name, dst_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lmove. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_move_to(dst_loc, dst_name, src_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lmove. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_copy_from(src_loc, src_name, dst_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lcopy. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_copy_to(dst_loc, dst_name, src_name, link_create_pl = h5const$H5P_DEFAULT, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lcopy. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_delete(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Ldelete. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_delete_by_idx(n, group_name = ".", index_field = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Ldelete_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_info(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lget_info. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_info_by_idx(n, group_name = ".", index_field = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lget_info_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_value(name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lget_val. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_value_by_idx(n, group_name = ".", index_field = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lget_val_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

link_name_by_idx(n, group_name, idx_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Lget_name_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_l.html for details.

mount(name, child)

This function implements the HDF5-API function H5Fmount. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

unmount(name)

This function implements the HDF5-API function H5Funmount. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

create_reference(name = ".", space = NULL)

This function implements the HDF5-API function H5Rcreate. If space=NULL then a H5R_OBJECT reference is created, otherwise a H5R_DATASET_REGION reference Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_r.html for details.

obj_info(remove_internal_use_only = TRUE)

This function implements the HDF5-API function H5Oget_info. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_o.html for details.

get_obj_name()

This function implements the HDF5-API function H5Iget_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_i.html for details.

create_attr(attr_name, robj = NULL, dtype = NULL, space = NULL)

This function implements the HDF5-API function H5Acreate2. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_open(attr_name)

This function implements the HDF5-API function H5Aopen. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

create_attr_by_name(attr_name, obj_name, robj = NULL, dtype = NULL, space = NULL, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Acreate_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_open_by_name(attr_name, obj_name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aopen_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_open_by_idx(n, obj_name, idx_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aopen_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_exists_by_name(attr_name, obj_name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aexists_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_exists(attr_name)

This function implements the HDF5-API function H5Aexists. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_rename_by_name(old_attr_name, new_attr_name, obj_name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Arename_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_rename(old_attr_name, new_attr_name)

This function implements the HDF5-API function H5Arename. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_delete(attr_name)

This function implements the HDF5-API function H5Adelete. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_delete_by_name(attr_name, obj_name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Adelete_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_delete_by_idx(n, obj_name, idx_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Adelete_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_info_by_name(attr_name, obj_name, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aget_info_by_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_info_by_idx(n, obj_name, idx_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aget_info_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_name_by_idx(n, obj_name, idx_type = h5const$H5_INDEX_NAME, order = h5const$H5_ITER_NATIVE, link_access_pl = h5const$H5P_DEFAULT)

This function implements the HDF5-API function H5Aget_name_by_idx. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_a.html for details.

attr_get_number()

This function implements the HDF5-API function H5Aget_num_attrs. Please see the documentation at https://support.hdfgroup.org/HDF5/doc/RM/RM_H5A.html#Annot-NumAttrs for details.

flush(scope = h5const$H5F_SCOPE_GLOBAL)

This function implements the HDF5-API function H5Fflush. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

get_filename()

This function implements the HDF5-API function H5Fget_name. Please see the documentation at https://docs.hdfgroup.org/hdf5/develop/group___h5_f.html for details.

names(link_access_pl = h5const$H5P_DEFAULT)

Returns the names of the items in the group or at the root of the file

Parameters

link_access_pl: The link-access property list. See https://docs.hdfgroup.org/hdf5/develop/group___l_a_p_l.html for more detail.

Extract/List File Contents

The following functions are defined to extract HDF5 file contents:

list.groups: List HDF5 groups in file.
list.datasets: List HDF5 datasets in file.
names: List all items in a file or group (applicable for H5File and H5Group)
list.attributes: List Attributes of HDF5 object (file, group or dataset).
h5attr_names: Attribute names of an HDF5 object; similar to list.attributes

Author

Holger Hoefling, Mario Annau

Examples

# The following examples generates a HDF5 file with the different HDF5 
# Objects and shows its contents:
fname <- tempfile(fileext = ".h5")
file <- H5File$new(fname, mode = "a")
file[["testdataset"]] <- 1:10
h5attr(file, "testattrib") <- LETTERS[1:10]
file$create_group("testgroup")
#> Class: H5Group
#> Filename: /tmp/RtmpXkJRwA/file11d9ef098b2c.h5
#> Group: /testgroup
file[["testgroup/testdataset2"]] <- 1:10
# Show contents of file
file
#> Class: H5File
#> Filename: /tmp/RtmpXkJRwA/file11d9ef098b2c.h5
#> Access type: H5F_ACC_RDWR
#> Attributes: testattrib
#> Listing:
#>         name    obj_type dataset.dims dataset.type_class
#>  testdataset H5I_DATASET           10        H5T_INTEGER
#>    testgroup   H5I_GROUP         <NA>               <NA>
# Close file and delete
file$close_all()

# The following example shows hdf5 file contents and how to use them to iterate over HDF5 elements:
file <- h5file(fname, mode = "a")
sapply(c("testgroup1", "testgroup2", "testgroup3"), file$create_group)
#> $testgroup1
#> Class: H5Group
#> Filename: /tmp/RtmpXkJRwA/file11d9ef098b2c.h5
#> Group: /testgroup1
#> 
#> $testgroup2
#> Class: H5Group
#> Filename: /tmp/RtmpXkJRwA/file11d9ef098b2c.h5
#> Group: /testgroup2
#> 
#> $testgroup3
#> Class: H5Group
#> Filename: /tmp/RtmpXkJRwA/file11d9ef098b2c.h5
#> Group: /testgroup3
#> 
file[["testgroup1/testset1"]] <- 1:10
file[["testgroup2/testset2"]] <- 11:20
file[["testgroup3/testset3"]] <- 21:30

# Extract first 3 elements from each dataset and combine result to matrix
sapply(list.datasets(file, recursive = TRUE), function(x) file[[x]][1:3])
#>      testdataset testgroup/testdataset2 testgroup1/testset1 testgroup2/testset2
#> [1,]           1                      1                   1                  11
#> [2,]           2                      2                   2                  12
#> [3,]           3                      3                   3                  13
#>      testgroup3/testset3
#> [1,]                  21
#> [2,]                  22
#> [3,]                  23
# Close file
file$close_all()
file.remove(fname)
#> [1] TRUE

Class for interacting with HDF5 files.

Value

Details

Methods

Extract/List File Contents

See also

Author

Examples