Object-Oriented Interface

Basic Usage

To use this interface, create a file handle using h5_open(). This returns an h5 object (specifically, an environment) that maintains a reference to your file.

library(h5lite)

# Create a temporary file for this example
file <- tempfile(fileext = ".h5")

# Open the handle
h5 <- h5_open(file)

# The print method shows the file path and current internal working directory
print(h5)
#> <h5 handle>
#>   File:  C:\Users\Daniel\AppData\Local\Temp\RtmpWyee1Y\file59404719283.h5 
#>   WD:    / 
#>   Size:  195 bytes 
#>   Objects (root):  0

Once the handle is open, you can access standard h5lite functions as methods of this object. The primary benefit is that you no longer need to pass the file argument; it is handled implicitly.

# Write data using the handle
h5$write(1:10, "dataset1")
h5$write(matrix(1:9, 3, 3), "matrix_data")

# List contents
h5$ls()
#> [1] "dataset1"    "matrix_data"

# Read data back
my_data <- h5$read("dataset1")
print(my_data)
#>  [1]  1  2  3  4  5  6  7  8  9 10

Almost all standard functions map directly to methods by dropping the h5_ prefix:

• h5_write() \(\rightarrow\) h5$write()
• h5_read() \(\rightarrow\) h5$read()
• h5_ls() \(\rightarrow\) h5$ls()
• h5_attr_names() \(\rightarrow\) h5$attr_names()
• And so on (see Method Reference below).

Navigation and Working Directories

A unique feature of the h5 handle is the ability to maintain a stateful “Working Directory” (WD) inside the HDF5 file. This functions similarly to setwd() in R or cd in a shell.

By default, the WD is the root (/). You can change it using $cd() and check it using $pwd().

# Create a group structure
h5$create_group("simulations")

# Navigate into the group
h5$cd("simulations")
h5$pwd()
#> [1] "/simulations"

# Write data using relative paths (writes to /simulations/run1)
h5$write(rnorm(10), "run1")

# Verify the location
h5$ls()
#> [1] "run1"

Absolute paths (paths starting with /) always override the current working directory:

# Writes to the root, ignoring the fact that we are in /simulations
h5$write(100, "/root_dataset")

You can also use .. to navigate up the hierarchy:

h5$cd("..")
h5$pwd() # Now back at "/"
#> [1] "/"

Reference Semantics

The object returned by h5_open is an R environment. This means it follows “pass-by-reference” semantics, unlike most R objects which are “pass-by-value”.

If you assign the handle to a new variable, you are creating a new reference to the same handle. Modifying one will modify the other.

h5_alias <- h5

# Change directory in the alias
h5_alias$cd("simulations")

# The original handle is also updated
h5$pwd()
#> [1] "/simulations"

Closing the Handle

When you are finished, you can close the handle using $close().

Note: h5lite does not keep the actual HDF5 file lock open persistently (it opens and closes the file for every read/write operation to ensure safety). Therefore, $close() is a logical operation: it clears the internal file path and working directory from the handle, preventing further methods from being called on it.

h5$close()

# Further attempts to use the handle will result in an error:
# h5$ls() 
# Error: This h5 file handle has been closed.

Method Reference

The following methods are available on the h5 object: