Data Space

Data space for organizing, loading, and working with hierarchical data from multiple file sources.

Installation

pip install vcti-dataspace>=1.0.0

With HDF5 export support:

pip install vcti-dataspace[hdf5-export]>=1.0.0

Quick Start

import numpy as np
from pathlib import Path
from vcti.dataspace import FilesProject

# Context manager ensures clean resource cleanup
with FilesProject("Analysis", registry=registry) as project:
    # Add file sources (auto-loads, creates immutable source DataSpaces)
    project.add_path_source("sim", Path("results.h5"))

    # Access source DataSpace (immutable, mirrors file)
    sim = project.get_path_source("sim")
    tree = sim.dataspace.tree
    info = sim.dataspace.get_node_info_all()

    # Open workspace and create user DataSpace (mutable)
    ws = project.open_workspace()
    user_space = ws.create_dataspace("output")

    # Copy data from source, add custom groups and datasets
    user_space.copy_node_from(sim.dataspace, node_id=5)
    grp = user_space.create_group("custom")
    user_space.create_dataset("values", np.array([1.0, 2.0]), parent_id=grp)

    # Delete nodes when no longer needed
    user_space.delete_node(grp, recursive=True)

    # Export to HDF5
    user_space.export_hdf5(Path("output.h5"))

Error Handling

All exceptions inherit from DataSpaceError, so you can catch broadly or narrowly:

from vcti.dataspace import DataSpaceError, ImmutableDataSpaceError, NodeNotFoundError

try:
    space.delete_node(999)
except NodeNotFoundError:
    print("Node does not exist")
except DataSpaceError:
    print("Catch-all for any DataSpace error")

Core API

DataSpace

PathSource, Workspace, FilesProject

Dependencies

• numpy (>=1.24)
• vcti-fileloader (>=1.0.0)
• vcti-array-tree (>=1.0.0) — DataNode
• h5py — optional, for HDF5 export