Split a large HDF5 spectral map by metadata category

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.

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.

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; the source-wide mosaic is omitted because its geometry may refer to regions stored in other split files.

Examples

if (FALSE) { # \dontrun{
split_h5("large_map.h5")
split_h5("large_map.h5", field = "particle_id", output_dir = "regions",
         format = "rds")
} # }