HDF5 General Library Functions

Description

These low level functions provide general general libary functions for HDF5.

Usage

H5open             ()
H5close            ()
H5garbage_collect  ()
H5get_libversion   ()

Details

These low level functions provide general general libary functions for HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Library for further details.

Value

H5open initializes the HDF5 library. H5close flushes all data to disk, closes all open identifiers, and cleans up memory. H5garbage_collect cleans up memory. H5get_libversion returns the version number of the HDF5 C-library.

Seealso

h5version , rhdf5

Author

Bernd Fischer

References

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

Examples

# test for file locking
if( !h5testFileLocking( tempdir() ) ) {
h5disableFileLocking()
}

H5open()
H5close()
H5garbage_collect()
H5get_libversion()

HDF5 Attribute Interface

Description

These functions create and manipulate attributes and information about attributes.

Usage

H5Acreate       (h5obj, name, dtype_id, h5space)
H5Aclose        (h5attribute)
H5Adelete       (h5obj, name)
H5Aexists       (h5obj, name)
H5Aget_name     (h5attribute)
H5Aget_space    (h5attribute)
H5Aget_type     (h5attribute)
H5Aopen         (h5obj, name)
H5Aopen_by_idx  (h5obj, n, objname = ".", index_type = h5default("H5_INDEX"), 
                 order = h5default("H5_ITER"))
H5Aopen_by_name (h5obj, objname = ".", name)
H5Aread         (h5attribute, buf = NULL)
H5Awrite        (h5attribute, buf)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Attributes for further details.

Value

H5Acreate , H5Aopen , H5Aopen_by_name , H5Aopen_by_idx return an object of class H5IdComponent representing a H5 attribute identifier.

H5Aget_space returns an object of class H5IdComponent representing a H5 dataspace identifier.

H5Aread returns an array with the read data.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

# create a file and write something
h5createFile("ex_H5A.h5")
h5write(1:15, "ex_H5A.h5","A")

# write an attribute 'unit' to 'A'
fid <- H5Fopen("ex_H5A.h5")
did <- H5Dopen(fid, "A")
sid <- H5Screate_simple(c(1,1))
tid <- H5Tcopy("H5T_C_S1")

H5Tset_size(tid, 10L)
aid <- H5Acreate(did, "unit", tid, sid)
aid
H5Awrite(aid, "liter")
H5Aclose(aid)
H5Sclose(sid)
H5Aexists(did, "unit")
H5Dclose(did)
H5Fclose(fid)
h5dump("ex_H5A.h5")

HDF5 Dataset Interface

Description

These functions create and manipulate dataset objects, and set and retrieve their constant or persistent properties.

Usage

H5Dcreate           (h5loc, name, dtype_id, h5space, lcpl=NULL, dcpl=NULL, dapl=NULL)
H5Dopen             (h5loc, name, dapl=NULL)
H5Dclose            (h5dataset)
H5Dget_space        (h5dataset)
H5Dget_type         (h5dataset)
H5Dget_create_plist (h5dataset)
H5Dget_storage_size (h5dataset)
H5Dread             (h5dataset, h5spaceFile = NULL, h5spaceMem = NULL,
                     buf = NULL, compoundAsDataFrame = TRUE,
                     bit64conversion, drop = FALSE)
H5Dwrite            (h5dataset, buf, h5spaceMem = NULL, h5spaceFile = NULL)
H5Dset_extent       (h5dataset, size)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Datasets for further details.

Value

H5Dcreate and H5Dopen return an object of class H5IdComponent represinting a H5 dataset identifier.

H5Dget_space returns an object of class H5IdComponent representing a H5 dataspace identifier.

H5Dread returns an array with the read data.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

# write a dataset
fid <- H5Fcreate("ex_H5D.h5")
fid
sid <- H5Screate_simple(c(10,5,3))
sid
did <- H5Dcreate(fid, "A", "H5T_STD_I32LE", sid)
did
H5Dwrite(did, 1L:150L, h5spaceMem = sid, h5spaceFile = sid)
H5Dclose(did)
H5Sclose(sid)
H5Fclose(fid)

# read a dataset
fid <- H5Fopen("ex_H5D.h5")
fid
did <- H5Dopen(fid, "A")
did
sid <- H5Dget_space(did)
sid
B <- H5Dread(did)
B
H5Dclose(did)
H5Sclose(sid)
H5Fclose(fid)

# write a subarray
fid <- H5Fopen("ex_H5D.h5")
fid
did <- H5Dopen(fid, "A")
did
sid <- H5Dget_space(did)
sid
H5Sselect_index(sid, list(1:3,2:4,2))
sidmem <- H5Screate_simple(c(3,3,1))
sidmem
A = array(-801:-809,dim=c(3,3,1))
H5Dwrite(did, A, h5spaceMem = sidmem, h5spaceFile = sid)
H5Dread(did)
H5Sclose(sid)
H5Dclose(did)
H5Sclose(sidmem)
H5Fclose(fid)

HDF5 File Interface

Description

These functions are designed to provide file-level access to HDF5 files.

Usage

H5Fcreate           (name, flags = h5default("H5F_ACC"), fcpl = NULL,
                     fapl = NULL, native = FALSE)
H5Fopen             (name, flags = h5default("H5F_ACC_RD"), native = FALSE)
H5Fclose            (h5file)
H5Fflush            (h5file, scope = h5default("H5F_SCOPE"))
H5Fis_hdf5          (name, showWarnings = TRUE)
H5Fget_filesize     (h5file)
H5Fget_name         (h5obj)
H5Fget_create_plist (h5file)
H5Fget_access_plist (h5file)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Files for further details.

Value

H5Fcreate and H5Fopen return an object of class H5IdComponent representing a H5 file identifier.

H5Fis_hdf5 returns TRUE, if the file is an HDF5 file, or FALSE otherwise. In the case the file doesn't exist, NA is returned.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

fid <- H5Fcreate("ex_H5F.h5")
fid
H5Fclose(fid)
fid2 <- H5Fopen("ex_H5F.h5")
fid2
H5Fclose(fid2)

HDF5 Group Interface

Description

The Group interface functions create and manipulate groups of objects in an HDF5 file.

Usage

H5Gcreate      (h5loc, name)
H5Gcreate_anon (h5loc)
H5Gopen        (h5loc, name)
H5Gclose       (h5group)
H5Gget_info    (h5loc)
H5Gget_info_by_idx  (h5loc, n, group_name = ".", 
                       index_type = h5default("H5_INDEX"), 
               order = h5default("H5_ITER"))
H5Gget_info_by_name (h5loc, group_name)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Groups for further details.

Value

H5Gcreate , H5Gcreate_anon , and H5Gopen return an object of class H5IdComponent representing a H5 group identifier.

H5Gget_info , H5Gget_info_by_idx , and H5Gget_info_by_name return a list with the group information.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

fid <- H5Fcreate("ex_H5G.h5")
gid <- H5Gcreate(fid, "foo")
gid
H5Gget_info(gid)
H5Gclose(gid)

H5Gget_info_by_idx(fid,1)
H5Gget_info_by_name(fid,"foo")

H5Fclose(fid)

HDF5 Identifier Interface

Description

These functions provides tools for working with object identifiers and object names.

Usage

H5Iget_type(h5identifier)
H5Iget_name(h5obj)
H5Iis_valid(h5identifier)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Identifiers for further details.

Value

H5Iget_type returns the type of the H5 identifier, H5Iget_name the name of the object, and H5Iis_valid checks if the object is a valid H5 identifier.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

# create an hdf5 file and write something
h5createFile("ex_H5I.h5")
h5createGroup("ex_H5I.h5","foo")
B = array(seq(0.1,2.0,by=0.1),dim=c(5,2,2))
h5write(B, "ex_H5I.h5","foo/B")

# reopen file and dataset and get object info
fid <- H5Fopen("ex_H5I.h5")
oid = H5Oopen(fid, "foo")
H5Iget_type(oid)
H5Oclose(oid)
H5Fclose(fid)

Class "H5IdComponent"

Description

A class representing a HDF5 identifier handle. HDF5 identifiers represent open files, groups, datasets, dataspaces, attributes, and datatypes.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

showClass("H5IdComponent")

HDF5 Link Interface

Description

The Link interface, H5L, functions create and manipulate links in an HDF5 group. This interface includes functions that enable the creation and use of user-defined link classes.

Usage

H5Lcreate_external (target_file_name, target_obj_name, link_loc, link_name)
H5Lexists          (h5loc, name)
H5Lget_info        (h5loc, name)
H5Ldelete          (h5loc, name)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Links for further details.

If name consists of a relative path containing group names, the function H5Lexists checks recursively if the links exists which is a different behaviour to the C-function.

Value

H5Lexists returns boolean TRUE if the link exists and FALSE otherwise.

H5Lget_info returns a list with the entries of the C-structure H5L_info_t .

Seealso

rhdf5

Author

Bernd Fischer, Mike Smith

References

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

Examples

# create an hdf5 file and a group
h5createFile("ex_H5L.h5")
h5createGroup("ex_H5L.h5","foo")

# reopen file and get link info
fid <- H5Fopen("ex_H5L.h5")
H5Lexists(fid, "foo")
H5Lexists(fid, "baa")
H5Lget_info(fid, "foo")

H5Ldelete(fid, "foo")
H5Lexists(fid, "foo")

H5Fclose(fid)

HDF5 Object Interface

Description

The Object interface, H5O, functions manipulate objects in an HDF5 file. This interface is designed to be used in conjunction with the Links interface (H5L).

Usage

H5Oopen  (h5loc, name)
H5Oclose (h5obj)
H5Oget_num_attrs(h5obj)
H5Oget_num_attrs_by_name(h5loc, name)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Objects for further details.

Value

H5Oopen opens an object (a file, group, or dataset) and returns an object of class H5IdComponent . H5Oclose closed the object again. H5Oget_num_attrs and H5Oget_num_attrs_by_name return the number of attributes of an object.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

# create an hdf5 file and write something
h5createFile("ex_H5O.h5")
h5createGroup("ex_H5O.h5","foo")
B = array(seq(0.1,2.0,by=0.1),dim=c(5,2,2))
h5write(B, "ex_H5O.h5","foo/B")

# reopen file and dataset and get object info
fid <- H5Fopen("ex_H5O.h5")
oid = H5Oopen(fid, "foo")
H5Oget_num_attrs(oid)
H5Oclose(oid)
H5Fclose(fid)

HDF5 Property List Interface

Description

The functions, macros, and subroutines listed here are used to manipulate property list objects in various ways, including to reset property values. With the use of property lists, HDF5 functions have been implemented and can be used in applications with many fewer parameters than would be required without property lists.

Usage

H5Pcreate            (type = h5default("H5P"), native = FALSE)
H5Pcopy              (h5plist)
H5Pget_class         (h5plist)
H5Pclose             (h5plist)
H5Pclose_class       (h5plistclass)
H5Pequal             (h5plistclass1, h5plistclass2)
H5Pset_libver_bounds (h5plist, 
                      libver_low = "H5F_LIBVER_EARLIEST", 
                      libver_high = "H5F_LIBVER_LATEST")
H5Pget_libver_bounds (h5plist)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Property+Lists for further details.

Value

H5Pcreate and H5Pcopy return an object of class H5IdComponent representing a H5 property list identifier.

H5Pget_class returns an object of class H5IdComponent representing a H5 property list class identifier.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5 , H5P_DATASET_CREATE

Author

Bernd Fischer

References

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

Examples

pid <- H5Pcreate()
pid2 <- H5Pcopy(pid)
pclid <- H5Pget_class(pid)
H5Pclose_class(pclid)
H5Pclose(pid)
H5Pclose(pid2)

HDF5 Dataset Access Property List Interface

Description

The functions, macros, and subroutines listed here are used to manipulate dataset access property list objects in various ways, including to reset property values. With the use of property lists, HDF5 functions have been implemented and can be used in applications with many fewer parameters than would be required without property lists.

Usage

H5Pset_chunk_cache                 ( h5plist, rdcc_nslots, rdcc_nbytes, rdcc_w0 )
% H5Pget_chunk_cache                 ( dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0 )

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Dataset+Access+Properties for further details. See H5P for documentation of more functions to manupulate property lists of other property list classes.

Value

The functions return the standard return value from their respective C-functions.

Seealso

rhdf5 , H5P

Author

Bernd Fischer

References

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

Examples

pid <- H5Pcreate("H5P_DATASET_ACCESS")
H5Pset_chunk_cache( pid, 100, 10000, 0.5)
H5Pclose(pid)

HDF5 Dataset Create Property List Interface

Description

The functions, macros, and subroutines listed here are used to manipulate dataset creation property list objects in various ways, including to reset property values. With the use of property lists, HDF5 functions have been implemented and can be used in applications with many fewer parameters than would be required without property lists.

Usage

H5Pset_layout                      ( h5plist, layout = h5default("H5D") )
H5Pget_layout                      ( h5plist )
H5Pset_chunk                       ( h5plist, dim )
H5Pget_chunk                       ( h5plist )
H5Pset_deflate                     ( h5plist, level )
H5Pset_fill_value                  ( h5plist, value )
% H5Pget_fill_value                  ( plist_id, type_id, value )H5Pfill_value_defined              ( h5plist )
H5Pset_fill_time                   ( h5plist, fill_time = h5default("H5D_FILL_TIME") )
H5Pget_fill_time                   ( h5plist )
H5Pset_alloc_time                  ( h5plist, alloc_time = h5default("H5D_ALLOC_TIME") )
H5Pget_alloc_time                  ( h5plist )
% H5Pset_filter                      ( plist_id, filter_id, flags, cd_nelmts, cd_values[] )% H5Pall_filters_avail               ( plist_id )% H5Pget_nfilters                    ( plist )% H5Pget_filter1                     ( plist_id, idx, flags, cd_nelmts, cd_values, namelen, name[] )% H5Pget_filter2                     ( plist_id, idx, flags, cd_nelmts, cd_values[], namelen, name[], filter_config )% H5Pget_filter_by_id1               ( plist_id, filter_id, flags, cd_nelmts, cd_values[], namelen, name[] )% H5Pget_filter_by_id2               ( plist_id, filter_id, flags, cd_nelmts, cd_values[], namelen, name[], filter_config )% H5Pmodify_filter                   ( plist_id, filter_id, flags, cd_nelmts, cd_values[] )% H5Premove_filter                   ( plist_id, filter )% H5Pset_fletcher32                  ( plist_id )% H5Pset_nbit                        ( plist_id )% H5Pset_scaleoffset                 ( plist_id, scale_type, scale_factor )% H5Pset_shuffle                     ( plist_id )% H5Pset_szip                        ( plist, options_mask, pixels_per_block )% H5Pset_external                    ( plist, *name, offset, size )% H5Pget_external_count              ( plist )% H5Pget_external                    ( plist, idx, name_size, *name, *offset, *size )

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Dataset+Creation+Properties for further details. See H5P for documentation of more functions to manupulate property lists of other property list classes.

Value

The functions return the standard return value from their respective C-functions.

Seealso

rhdf5 , H5P

Author

Bernd Fischer

References

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

Examples

pid <- H5Pcreate("H5P_DATASET_CREATE")
H5Pset_fill_time( pid, "H5D_FILL_TIME_ALLOC" )
H5Pset_chunk(pid, c(1000,1,1))
H5Pset_deflate(pid, 6)

H5Pget_layout( pid )
H5Pfill_value_defined( pid )
H5Pget_fill_time( pid )
H5Pget_alloc_time( pid )
H5Pget_chunk( pid)

H5Pclose(pid)

HDF5 Link Create Property List Interface

Description

The functions, macros, and subroutines listed here are used to manipulate link creation property list objects in various ways, including to reset property values. With the use of property lists, HDF5 functions have been implemented and can be used in applications with many fewer parameters than would be required without property lists.

Usage

H5Pset_char_encoding               ( h5plist, encoding  = h5default("H5T_CSET"))
H5Pget_char_encoding               ( h5plist )
H5Pset_create_intermediate_group   ( h5plist, crt_intermed_group )
H5Pget_create_intermediate_group   ( h5plist )

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Attribute+and+Link+Creation+Properties for further details. See H5P for documentation of more functions to manupulate property lists of other property list classes.

Value

The functions return the standard return value from their respective C-functions.

Seealso

rhdf5 , H5P

Author

Bernd Fischer

References

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

Examples

pid <- H5Pcreate("H5P_LINK_CREATE")
H5Pset_char_encoding( pid, "H5T_CSET_ASCII")
H5Pget_char_encoding( pid)
H5Pset_create_intermediate_group(pid, TRUE)
H5Pget_create_intermediate_group(pid)
H5Pclose(pid)

HDF5 Dataspace Interface

Description

These functions create and manipulate the dataspace in which to store the elements of a dataset.

Usage

H5Screate                 (type = h5default("H5S"), native = FALSE)
H5Screate_simple          (dims, maxdims, native = FALSE)
H5Scopy                   (h5space)
H5Sclose                  (h5space)
H5Sis_simple              (h5space)
H5Sget_simple_extent_dims (h5space)
H5Sset_extent_simple      (h5space, dims, maxdims)
H5Sselect_hyperslab       (h5space, op = h5default("H5S_SELECT"), 
                           start = NULL, stride = NULL, count = NULL,
                           block = NULL)
H5Sselect_index           (h5space, index)
H5Sunlimited              ()

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Dataspaces for further details.

As an introduction to use hyperslabs see these tutorials: 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.

H5Sselect_index is not part of the standard HDF5 C interface. It performes an iterative call to H5select_points by iterating through the given index positions. This function avoids a for loop in R. If a list element is NULL, all elements of the respective dimension are considered.

Value

H5Screate , H5Screate_simple , and H5Scopy return an object of class H5IdComponent representing a dataspace.

H5Sis_simple returns a boolean.

H5Sget_simple_extent_dims returns an integer vector.

H5Sunlimited is a simple macro to return the constant H5S_UNLIMITED that can be provided to the maxdims arguments of H5Screate_simple to create and extensible dataspace.

The other functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

sid <- H5Screate_simple(c(10,5,3))
sid
H5Sis_simple(sid)
H5Sget_simple_extent_dims(sid)

# select a subarray (called hyperslab in the hdf5 community).
# The next h5write can use this to write a subarray
H5Sselect_index(sid, list(1:3,2:4,2))

# always close dataspaces after usage to free recources
H5Sclose(sid)
sid

HDF5 Datatype Interface

Description

These functions create and manipulate the datatype which describes elements of a dataset.

Usage

H5Tcopy     (dtype_id = h5default(type = "H5T"))
H5Tset_size (dtype_id = h5default(type = "H5T"), size)

Arguments

Details

Interface to the HDF5 C-library libhdf5. See https://portal.hdfgroup.org/display/HDF5/Datatypes for further details.

Value

The functions return the standard return value from their respective C-functions.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

# create character datatype with string length 10
tid <- H5Tcopy("H5T_C_S1")
H5Tset_size(tid, 10L)

# List all predefined types implemented in the R-interface
h5const("H5T")

# List all available type classes (not all of them are implemented)
h5const("H5T_CLASS")

Close all open HDF5 handles

Description

Occasionally references to HDF5 files, groups, datasets etc can be created and not closed correctly. This function identifies all open handles and closes them. It replaces the functionality previously supplied by H5close .

Usage

h5closeAll()

Author

Mike Smith

Examples

## create an empty file and then re-open it
h5createFile("ex_h5closeAll.h5")
H5Fopen("ex_h5closeAll.h5")

## list all open identifiers
h5listIdentifier()

## close all open identifiers and verify
h5closeAll()
h5listIdentifier()

HDF5 library constants.

Description

Access to HDF5 constants.

Usage

h5const     (type = "")
h5default   (type = "")
h5constType ()

Arguments

Details

These functions provide a list of HDF5 constants that are defined in the R package. h5constType provides a list of group names and h5const gives the constants defined within a group. h5default gives the default choice for each group.

Value

A character vector with names of HDF5 constants or groups.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

h5constType()[1]
h5const(h5constType()[1])

Create HDF5 attribute

Description

R function to create an HDF5 attribute and defining its dimensionality.

Usage

h5createAttribute (obj, attr, dims, maxdims = dims, file, 
                   storage.mode = "double", H5type = NULL, size=NULL,
                   native = FALSE)

Arguments

Details

Creates a new attribute and attaches it to an existing HDF5 object. The function will fail, if the file doesn't exist or if there exists already another attribute with the same name for this object.

You can use h5writeAttribute immediately. It will create the attribute for you.

Value

Returns TRUE is attribute was created successfully and FALSE otherwise.

Seealso

h5createFile , h5createGroup , h5createDataset , h5read , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_createAttribute.h5")
h5write(1:1, "ex_createAttribute.h5","A")
fid <- H5Fopen("ex_createAttribute.h5")
did <- H5Dopen(fid, "A")
h5createAttribute (did, "time", c(1,10))
H5Dclose(did)
H5Fclose(fid)

Create HDF5 dataset

Description

R function to create an HDF5 dataset and defining its dimensionality and compression behaviour.

Usage

h5createDataset (file, dataset, 
        dims, maxdims = dims, 
        storage.mode = "double", H5type = NULL, 
        size = NULL, chunk = dims, level = 6,
        fillValue, showWarnings, native = FALSE)

Arguments

Details

Creates a new dataset. in an existing HDF5 file. The function will fail, if the file doesn't exist or if there exists already another dataset with the same name within the specified file.

Value

Returns TRUE is dataset was created successfully and FALSE otherwise.

Seealso

h5createFile , h5createGroup , h5read , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_createDataset.h5")

# create dataset with compression
h5createDataset("ex_createDataset.h5", "A", c(5,8), storage.mode = "integer", chunk=c(5,1), level=7)

# create dataset without compression
h5createDataset("ex_createDataset.h5", "B", c(5,8), storage.mode = "integer")
h5createDataset("ex_createDataset.h5", "C", c(5,8), storage.mode = "double")

# create a dataset of strings & define size to include null terminator
ex_strings <- c('long', 'longer', 'longest')
h5createDataset("ex_createDataset.h5", "D",
storage.mode = "character", chunk = 3, level = 6,
dims = length(ex_strings), size = max(nchar(ex_strings)) + 1)


# write data to dataset
h5write(matrix(1:40,nr=5,nc=8), file="ex_createDataset.h5", name="A")
# write second column
h5write(matrix(1:5,nr=5,nc=1), file="ex_createDataset.h5", name="B", index=list(NULL,2))
# write character vector
h5write(ex_strings, file = "ex_createDataset.h5", name = "D")

h5dump("ex_createDataset.h5")

Create HDF5 file

Description

R function to create an empty HDF5 file.

Usage

h5createFile (file)

Arguments

Details

Creates an empty HDF5 file.

Value

Returns TRUE is file was created successfully and FALSE otherwise.

Seealso

h5createGroup , h5createDataset , h5read , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_createFile.h5")

# create groups
h5createGroup("ex_createFile.h5","foo")
h5createGroup("ex_createFile.h5","foo/foobaa")

h5ls("ex_createFile.h5")

Create HDF5 group

Description

Creates a group within an HDF5 file.

Usage

h5createGroup (file, group)

Arguments

Details

Creates a new group within an HDF5 file.

Value

Returns TRUE is group was created successfully and FALSE otherwise.

Seealso

h5createFile , h5createDataset , h5read , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_createGroup.h5")

# create groups
h5createGroup("ex_createGroup.h5","foo")
h5createGroup("ex_createGroup.h5","foo/foobaa")

h5ls("ex_createGroup.h5")

Delete contents of HDF5 file

Description

Deletes the specfied group or dataset from within an HDF5 file.

Usage

h5delete( file, name )

Arguments

Author

Mike Smith

handling of HDF5 error messages

Description

Sets the options for handling HDF5 error messages.

Usage

h5errorHandling (type="normal")

Arguments

Details

Sets the options for HDF5 error hanlding.

Value

Returns 0 if options are set successfully.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

h5errorHandling("normal")

Test and set file locking for HDF5

Description

HDF5 1.10 uses file locking by default. On some file systems this is not available, and the HDF5 library will throw an error if the user attempts to create or access a file located on such a file system. These functions help identify if file locking is available without throwing an error, and allow the locking to be disabled for the duration of the R session if needed.

Usage

h5testFileLocking(location)
h5disableFileLocking()
h5enableFileLocking()

Arguments

Details

h5testFileLocking will create a temporary file and then attempt to apply a file lock using the appropriate function within the HDF5 library. The success or failure of the locking is then recorded and the temporary file removed. Even relatively low level functions such as H5Fcreate will fail inelegantly if file locking fails.

h5disableFileLocking will set the environment variable RHDF5_USE_FILE_LOCKING=FALSE , which is the recommended was to disable this behaviour if file locking is not supported. This will only persist within the current R session. You can set the environment variable outside of R if this is a more general issue on your system.

h5enableFileLocking will unset the RHDF5_USE_FILE_LOCKING .

More discussion of HDF5's use of file locking can be found online e.g. https://forum.hdfgroup.org/t/hdf5-1-10-0-and-flock/3761/4 or https://forum.hdfgroup.org/t/hdf5-files-on-nfs/3985/5

Value

h5testFileLocking returns TRUE if a file can be successfully locked at the specified location, or FALSE otherwise.

h5disableFileLocking and h5enableFileLocking set are called for the side effect of setting or unsetting the environment variable HDF5_USE_FILE_LOCKING and do not return anything.

Author

Mike Smith

Examples

## either a file name or directory can be tested
file <- tempfile()
dir <- tempdir()

h5testFileLocking(dir)
h5testFileLocking(file)

## we can check for file locking, and disable if needed
if( !h5testFileLocking(dir) ) {
h5disableFileLocking()
}

list all valid H5 identifier.

Description

A list of all valid H5 identifier. H5 objects should be closed after usage to release resources.

Usage

h5listIdentifier()
h5validObjects(native = FALSE)

Arguments

Value

h5validObjects returns a list of H5IdComponent objects. h5listIdentifier prints the valid identifiers on screen and returns NULL.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_list_identifier.h5")

# create groups
h5createGroup("ex_list_identifier.h5","foo")

h5listIdentifier()
h5validObjects()

List the content of an HDF5 file.

Description

Lists the content of an HDF5 file.

Usage

h5ls   (file,
        recursive = TRUE,
    all = FALSE, 
    datasetinfo = TRUE,
    index_type = h5default("H5_INDEX"),
    order = h5default("H5_ITER"), native = FALSE)
h5dump (file,
        recursive = TRUE,
    load = TRUE,
    all = FALSE,
        index_type = h5default("H5_INDEX"),
        order = h5default("H5_ITER"), ..., native = FALSE)

Arguments

Details

h5ls lists the content of an HDF5 file including group structure and datasets. It returns the content as a data.frame. You can use h5dump(file="myfile.h5", load=FALSE) to obtain the dataset information in a hierarchical list structure. Usually the datasets are loaded individually with h5read , but you have the possibility to load the complete content of an HDF5 file with h5dump

Value

h5ls returns a data.frame with the file content.

h5dump returns a hierarchical list structure representing the HDF5 group hierarchy. It either returns the datasets within the list structure ( load=TRUE ) or it returns a data.frame for each datset with the dataset header information load=FALSE .

Seealso

h5read , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

h5createFile("ex_ls_dump.h5")

# create groups
h5createGroup("ex_ls_dump.h5","foo")
h5createGroup("ex_ls_dump.h5","foo/foobaa")

# 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_ls_dump.h5","foo/B")

# list content of hdf5 file
h5ls("ex_ls_dump.h5",all=TRUE)
h5dump("ex_ls_dump.h5")

Saves a series of objects to an HDF5 file.

Description

Saves a number of R objects to an HDF5 file.

Usage

h5save(..., file, name = NULL, createnewfile = TRUE, native = FALSE)

Arguments

Details

The objects will be saved to the HDF5 file. If the file does not exists it will be created. The data can be read again by either h5dump or individually for each dataset by h5read .

Value

Nothing returned.

Seealso

h5ls , h5write , rhdf5

Author

Bernd Fischer

References

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

Examples

A = 1:7;  B = 1:18; D = seq(0,1,by=0.1)
h5save(A, B, D, file="ex_save.h5")
h5dump("ex_save.h5")

Set a new dataset extension

Description

Set a new dataset extension to an existing dataset in an HDF5 file

Usage

h5set_extent(file, dataset, dims, native = FALSE)

Arguments

Value

Returns 0 if the dimension of the dataset was changed successfully and a negative value otherwise.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

tmpfile <- tempfile()
h5createFile(file=tmpfile)
h5createDataset(tmpfile, "A", c(10,12), c(20,24))
h5ls(tmpfile, all=TRUE)[c("dim", "maxdim")]
h5set_extent(tmpfile, "A", c(20,24))
h5ls(tmpfile, all=TRUE)[c("dim", "maxdim")]

rhdf5 and libhdf5 version numbers

Description

Returns the version number of the Bioconductor package rhdf5 and the C-library libhdf5.

Usage

h5version()

Value

A list of major, minor and release number.

Seealso

rhdf5

Author

Bernd Fischer

References

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

Examples

h5version()

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)
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=7, chunk,
                             DataFrameAsCompound = TRUE)
h5writeDataset.list         (obj, h5loc, name, level=7)
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=7)
h5writeAttribute            (attr, h5obj, name, ...)
h5writeAttribute.matrix     (...)
h5writeAttribute.integer    (...)
h5writeAttribute.double     (...)
h5writeAttribute.logical    (...)
h5writeAttribute.character  (...)
h5writeAttribute.array      (attr, h5obj, name, size)

Arguments

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.

Seealso

h5ls , h5createFile , h5createDataset , rhdf5

Author

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))

# list content of hdf5 file
h5ls("ex_hdf5file.h5")

Methods for Function & in Package rhdf5

Description

Methods for function & in package rhdf5 .

Methods for Function $ in Package rhdf5

Description

Methods for function $ in package rhdf5 .

~~ Methods for Function $<- in Package rhdf5 ~~

Description

Methods for function $<- in package rhdf5 .

Methods for Function [ in Package rhdf5

Description

Methods for function [ in package rhdf5 .

Methods for Function [<- in Package rhdf5

Description

Methods for function [<- in package rhdf5 .

Package overview

Description

rhdf5 is an interface to the HDF5 library. The R-package contains the complete HDF5 library, thus no further installation of external packages is necessary.

There are a number of high level R functions that provide a convinient way of accessing HDF5 file as well as R interfaces to a number of functions in the C-library.

Examples

h5createFile("ex_hdf5file.h5")

# create groups
h5createGroup("ex_hdf5file.h5","foo")
h5createGroup("ex_hdf5file.h5","foo/foobaa")

# 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","foo/B")

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

# list content of hdf5 file
h5ls("ex_hdf5file.h5")

# write and read submatrix
h5createDataset("ex_hdf5file.h5", "foo/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="foo/S", index=list(NULL,1))
h5read("ex_hdf5file.h5", "foo/S")
h5read("ex_hdf5file.h5", "foo/S", index=list(2:3,2:3))