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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/group___h5_d.html for datasets, https://docs.hdfgroup.org/hdf5/v1_10/group___h5_o.html for types and https://docs.hdfgroup.org/hdf5/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/group___h5_g.html for regular groups and https://docs.hdfgroup.org/hdf5/v1_10/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/v1_10/group___h5_d.html for regular groups and https://docs.hdfgroup.org/hdf5/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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/v1_10/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

See also

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/Rtmp0t2L4j/file3bd62a1c4a01.h5
#> Group: /testgroup
file[["testgroup/testdataset2"]] <- 1:10
# Show contents of file
file
#> Class: H5File
#> Filename: /tmp/Rtmp0t2L4j/file3bd62a1c4a01.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/Rtmp0t2L4j/file3bd62a1c4a01.h5
#> Group: /testgroup1
#> 
#> $testgroup2
#> Class: H5Group
#> Filename: /tmp/Rtmp0t2L4j/file3bd62a1c4a01.h5
#> Group: /testgroup2
#> 
#> $testgroup3
#> Class: H5Group
#> Filename: /tmp/Rtmp0t2L4j/file3bd62a1c4a01.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