split_h5: Split a large HDF5 spectral map by metadata category

In OpenSpecy: Analyze, Process, Identify, and Share Raman and (FT)IR Spectra

Split a large HDF5 spectral map by metadata category

Description

split_h5() groups an H5 or HDF5 spectral map by a metadata field. The default region-to-H5 path discovers region groups directly and copies them without hashing the complete source, building a per-pixel index, or loading spectral values into R. Other metadata fields use a file-backed FileSpecs descriptor. format = "rds" reads and saves one category at a time; each RDS category must fit in memory.

Usage

split_h5(
  file,
  field = "region",
  output_dir = dirname(file),
  format = c("h5", "rds")
)

Arguments

file	path to one .h5 or .hdf5 file.
field	metadata field used to group spectra. Defaults to "region".
output_dir	directory in which to save the output files. Defaults to the source file's directory.
format	output format. "h5" (the default) uses native HDF5 object copies for whole-region categories. "rds" materializes one category as an OpenSpecy object before saving it.

Details

Output files are named ⁠<input stem>_<field category>.<format>⁠. Characters that are not valid in Windows file names are replaced with underscores. Existing output files are never overwritten. Native H5 output requires each category to contain complete source regions because the source schema stores spectra as three-dimensional regional grids. Use format = "rds" for a field that divides pixels within a region. File-level metadata and selected region groups are retained in H5 outputs. When registered mosaic metadata is available, each H5 output also retains the intersecting image tiles and their corresponding centers so visual-image registration remains self-contained.

Value

Invisibly, a named character vector of output paths. Names are the original field-category labels. H5 outputs remain readable by read_h5() and open_specs(); each RDS file contains one OpenSpecy object.

See Also

open_specs(), decompress_spec()

Examples

## Not run: 
split_h5("large_map.h5")
split_h5("large_map.h5", field = "particle_id", output_dir = "regions",
         format = "rds")

## End(Not run)

OpenSpecy documentation built on Oct. 6, 2026, 1:07 a.m.