h5_read: Read an HDF5 Object or Attribute

Description

Reads a dataset, a group, or a specific attribute from an HDF5 file into an R object.

Usage

h5_read(file, name = "/", attr = NULL, as = "auto")

Value

An R object corresponding to the HDF5 object or attribute. Returns NULL if the object is skipped via as = "null".

Arguments

file

The path to the HDF5 file.

name

The full path of the dataset or group to read (e.g., "/data/matrix").

attr

The name of an attribute to read.

If NULL (default), the function reads the object specified by name (and attaches its attributes to the result).
If provided (string), the function reads only the specified attribute from name.

as

The target R data type.

Global: "auto" (default), "integer", "double", "logical", "bit64", "null".
Specific: A named vector mapping names or type classes to R types (see Section "Type Conversion").

Type Conversion (<code>as</code>)

You can control how HDF5 data is converted to R types using the as argument.

1. Mapping by Name:

as = c("data_col" = "integer"): Reads the dataset/column named "data_col" as an integer.
as = c("@validated" = "logical"): When reading a dataset, this forces the attached attribute "validated" to be read as logical.

2. Mapping by HDF5 Type Class: You can target specific HDF5 data types using keys prefixed with a dot (.). Supported classes include:

Integer: .int, .int8, .int16, .int32, .int64
Unsigned: .uint, .uint8, .uint16, .uint32, .uint64
Floating Point: .float, .float16, .float32, .float64

Example: as = c(.uint8 = "logical", .int = "bit64")

3. Precedence & Attribute Config:

Attributes vs Datasets: Attribute type mappings take precedence over dataset mappings. If you specify as = c(.uint = "logical", "@.uint" = "integer"), unsigned integer datasets will be read as logical, but unsigned integer attributes will be read as integer.
Specific vs Generic: Specific keys (e.g., .uint32) take precedence over generic keys (e.g., .uint), which take precedence over the global default (.).

Examples

Run this code

file <- tempfile(fileext = ".h5")

# --- Write Data ---
h5_write(c(10L, 20L), file, "ints")
h5_write(I(TRUE),     file, "ints", attr = "ready")
h5_write(c(10.5, 18), file, "floats")
h5_write(I("meters"), file, "floats", attr = "unit")

# --- Read Data ---
# Read dataset
x <- h5_read(file, "ints")
print(x)

# Read dataset with attributes
y <- h5_read(file, "floats")
print(attr(y, "unit"))

# Read a specific attribute directly
unit <- h5_read(file, "floats", attr = "unit")
print(unit)

# --- Type Conversion Examples ---

# Force integer dataset to be read as numeric (double)
x_dbl <- h5_read(file, "ints", as = "double")
class(x_dbl)

# Force attached attribute to be read as logical
# Note the "@" prefix to target the attribute
z <- h5_read(file, "ints", as = c("@ready" = "logical"))
print(z)

unlink(file)