Get Started with h5lite

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

The h5lite package provides a simplified, user-friendly interface for interacting with HDF5 files in R. While HDF5 is a complex hierarchical data format, h5lite is designed to feel familiar to R users by mapping HDF5 concepts directly to R’s native data structures.

HDF5 for R Users

If you are new to HDF5, the easiest way to understand it is through R analogues. HDF5 files function like a file system within a single file, containing “groups” (folders) and “datasets” (files).

R Concept	HDF5 Concept	Description
List	Group	A container that holds other objects (datasets or other groups).
Vector / Matrix	Dataset	A multidimensional array of data (numeric, character, etc.).
Data Frame	Compound Dataset	A table where each column can have a different data type.
Attribute	Attribute	Metadata attached to a specific object (e.g., units, timestamps).
Factor	Enum	An integer vector with associated string labels.

Basic Usage

The package uses two primary functions: h5_write() to save data and h5_read() to load it.

Writing Numeric Data

You can write standard R arrays and vectors directly to an HDF5 file. h5lite automatically handles dimensions.

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

# 1. 1D Array (Vector)
vec <- c(1.5, 2.3, 4.2)
h5_write(vec, file, "examples/vector")

# 2. 2D Array (Matrix)
mat <- matrix(1:9, nrow = 3, ncol = 3)
h5_write(mat, file, "examples/matrix")

# 3. 3D Array
arr <- array(1:24, dim = c(4, 3, 2))
h5_write(arr, file, "examples/array_3d")

# 4. Scalar
# By default, R treats length-1 vectors as arrays. 
# Wrap in I() to write a true HDF5 scalar.
val <- I(42)
h5_write(val, file, "examples/scalar")

Note: While h5lite supports preserving row and column names for matrices and vectors, these examples omit them for simplicity. See vignette('attributes-in-depth') for details on how dimension names are stored.

Reading Data

Data is read back into its native R format.

x <- h5_read(file, "examples/matrix")
print(x)
#>      [,1] [,2] [,3]
#> [1,]    1    4    7
#> [2,]    2    5    8
#> [3,]    3    6    9

Data Type Mapping

h5lite automatically selects the appropriate HDF5 data type based on the content of your R objects.

R Data Type	HDF5 Equivalent	Description
Numeric	variable	Selects optimal type: `int8`, `float32`, etc.
Logical	`H5T_STD_U8LE`	Stored as 0 (FALSE) or 1 (TRUE) (`uint8`).
Character	`H5T_STRING`	Variable or fixed-length UTF-8 strings.
Complex	`H5T_COMPLEX`	Native HDF5 2.0+ complex numbers.
Raw	`H5T_OPAQUE`	Raw bytes / binary data.
Factor	`H5T_ENUM`	Integer indices with label mapping.
integer64	`H5T_STD_I64LE`	64-bit signed integers via `bit64` package.
POSIXt	`H5T_STRING`	ISO 8601 string (`YYYY-MM-DDTHH:MM:SSZ`).
List	`H5O_TYPE_GROUP`	Recursive container structure.
Data Frame	`H5T_COMPOUND`	Table of mixed types.
NULL	`H5S_NULL`	Creates a placeholder.

You can use the as argument to explicitly set the HDF5 data type for numeric, logical, and character vectors. See vignette('data-types') for details.

Complex Data Structures

Lists as Groups

R lists are naturally hierarchical, making them perfect for creating HDF5 groups.

my_list <- list(
  config = list(id = 1L, status = "active"),
  data   = runif(10)
)
# Creates a group "/experiment" containing "config" (group) and "data" (dataset)
h5_write(my_list, file, "experiment")

Data Frames as Compound Datasets

Data frames are written as native HDF5 compound datasets, allowing efficient storage of tabular data with mixed types.

df <- data.frame(
  id = 1:5,
  val = c(1.1, 2.2, 3.3, 4.4, 5.5)
)
h5_write(df, file, "study_data")

For more details on these structures, including how to handle factors and nested lists, refer to vignette('data-frames').

Attributes

Attributes are small pieces of metadata attached to objects. h5lite writes R attributes (like units or description) as HDF5 attributes.

# Write a dataset
h5_write(1:10, file, "measurements")

# Attach an attribute to it
h5_write("meters", file, "measurements", attr = "units")

See vignette('attributes-in-depth') for information on reading specific attributes and how special R attributes like dimnames are handled.

File Inspection

You can inspect the contents of an HDF5 file without reading the data into memory using h5_ls() and h5_str().

# List contents
h5_ls(file)
#>  [1] "examples"                 "examples/vector"         
#>  [3] "examples/matrix"          "examples/array_3d"       
#>  [5] "examples/scalar"          "experiment"              
#>  [7] "experiment/config"        "experiment/config/id"    
#>  [9] "experiment/config/status" "experiment/data"         
#> [11] "study_data"               "measurements"

# Print structure tree (like R's str())
h5_str(file)
#> /
#> ├── examples/
#> │   ├── vector <float64 × 3>
#> │   ├── matrix <uint8 × 3 × 3>
#> │   ├── array_3d <uint8 × 4 × 3 × 2>
#> │   └── scalar <uint8 scalar>
#> ├── experiment/
#> │   ├── config/
#> │   │   ├── id <uint8 × 1>
#> │   │   └── status <utf8[6] × 1>
#> │   └── data <float64 × 10>
#> ├── study_data <compound[2] × 5>
#> │   ├── $id <uint8>
#> │   └── $val <float64>
#> └── measurements <uint8 × 10>
#>     └── @units <utf8[6] × 1>

For advanced file operations, including moving, deleting, and verifying objects, refer to vignette('data-organization').

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.