# Get Started with h5lite

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')`.