bdmove_hdf5_dataset: Move HDF5 Dataset

In BigDataStatMeth: Title: Scalable Statistical Computing with HDF5-Backed Matrices

Move HDF5 Dataset

Description

Moves an HDF5 dataset from one location to another within the same HDF5 file. This function automatically handles moving associated rownames and colnames datasets, creates parent groups if needed, and updates all internal references.

Usage

bdmove_hdf5_dataset(filename, source_path, dest_path, overwrite = FALSE)

Arguments

filename	Character string. Path to the HDF5 file
source_path	Character string. Current path to the dataset (e.g., "/group1/dataset1")
dest_path	Character string. New path for the dataset (e.g., "/group2/new_name")
overwrite	Logical. Whether to overwrite destination if it exists (default: FALSE)

Details

This function provides a high-level interface for moving datasets within HDF5 files. The operation is efficient as it uses HDF5's native linking mechanism without copying actual data.

Key features:

• Moves main dataset and associated rownames/colnames datasets

• Creates parent directory structure automatically

• Preserves all dataset attributes and properties

• Updates internal dataset references

• Efficient metadata-only operation

• Comprehensive error handling

Value

List with components. If an error occurs, all string values are returned as empty strings (""):

fn

Character string with the HDF5 filename

ds

Character string with the full dataset path to the moved dataset in its new location (group/dataset)

Behavior

• If the destination parent groups don't exist, they will be created automatically

• Associated rownames and colnames datasets are moved to the same new group

• All dataset attributes and properties are preserved during the move

• The operation is atomic - either all elements move successfully or none do

Requirements

• The HDF5 file must exist and be accessible

• The source dataset must exist

• The file must not be locked by another process

• User must have read-write permissions on the file

Author(s)

BigDataStatMeth package authors

Examples

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

# Create a dataset to move
hdf5_create_matrix(fn, "old_group/my_dataset",
                   data = matrix(rnorm(100), 10, 10))

# Move dataset to a different group
res <- bdmove_hdf5_dataset(fn,
                           source_path = "old_group/my_dataset",
                           dest_path   = "new_group/my_dataset")

# Rename dataset within the same group
hdf5_create_matrix(fn, "data/old_name",
                   data = matrix(rnorm(100), 10, 10))
res <- bdmove_hdf5_dataset(fn,
                           source_path = "data/old_name",
                           dest_path   = "data/new_name")

hdf5_close_all()
unlink(fn)

BigDataStatMeth documentation built on May 15, 2026, 1:07 a.m.