BigDataStatMeth (version 2.0.3)

bdmove_hdf5_dataset: 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)

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)

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)

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

BigDataStatMeth package authors

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

Examples

# \donttest{
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)
# }