I/O Facade

High-level HDF5 I/O with schema validation, connection pooling, and consistent error handling.

Overview

The xpcsviewer.io module provides the HDF5Facade class, a unified interface for reading and writing validated XPCS data. It sits above the lower-level xpcsviewer.fileIO module and returns schema-validated objects from xpcsviewer.schemas.

Quick Start

from xpcsviewer.io import HDF5Facade

facade = HDF5Facade()

# Read with schema validation
qmap = facade.read_qmap("data.hdf5")
print(f"Q-map shape: {qmap.sqmap.shape}")
print(f"Units: {qmap.sqmap_unit}")

# Read G2 correlation data
g2_data = facade.read_g2_data("data.hdf5")
print(f"Delay points: {g2_data.g2.shape[0]}, Q-bins: {g2_data.g2.shape[1]}")

# Read geometry metadata
geometry = facade.read_geometry_metadata("data.hdf5")
print(f"Beam center: ({geometry.bcx}, {geometry.bcy})")

HDF5Facade

class xpcsviewer.io.HDF5Facade(pool=None, validate=True)[source]

Bases: object

Unified facade for HDF5 I/O operations with schema validation.

This facade provides a single entry point for all HDF5 file operations, with built-in: - Schema validation using dataclasses - Connection pooling for performance - Consistent error handling - Logging and monitoring

Parameters:

  • pool (HDF5ConnectionPool | None)

  • validate (bool)

pool

Connection pool for managing HDF5 file handles

Type:

HDF5ConnectionPool

validate

Whether to perform schema validation

Type:

bool

__init__(pool=None, validate=True)[source]

Initialize HDF5 facade.

Parameters:

  • pool (HDF5ConnectionPool, optional) – Connection pool to use. If None, uses global pool.

  • validate (bool, optional) – Enable schema validation, by default True

read_qmap(file_path, group='/xpcs/qmap')[source]

Read Q-map from HDF5 file with schema validation.

Parameters:

  • file_path (str or Path) – Path to HDF5 file

  • group (str, optional) – HDF5 group containing Q-map data, by default “/xpcs/qmap”

Returns:

Validated Q-map data

Return type:

QMapSchema

Raises:

  • HDF5ValidationError – If Q-map data fails schema validation

  • FileNotFoundError – If file does not exist

  • KeyError – If required datasets are missing

write_mask(file_path, mask_schema, group='/simplemask/mask', compression='gzip', compression_opts=4)[source]

Write mask to HDF5 file with versioning.

Parameters:

  • file_path (str or Path) – Path to HDF5 file

  • mask_schema (MaskSchema) – Validated mask schema to write

  • group (str, optional) – HDF5 group to write to, by default “/simplemask/mask”

  • compression (str, optional) – Compression algorithm, by default “gzip”

  • compression_opts (int, optional) – Compression level (1-9), by default 4

Raises:

ValueError – If mask_schema validation fails

Return type:

None

write_partition(file_path, partition_schema, group='/simplemask/partition', compression='gzip', compression_opts=4)[source]

Write partition to HDF5 file with versioning.

Parameters:

  • file_path (str or Path) – Path to HDF5 file

  • partition_schema (PartitionSchema) – Validated partition schema to write

  • group (str, optional) – HDF5 group to write to, by default “/simplemask/partition”

  • compression (str, optional) – Compression algorithm, by default “gzip”

  • compression_opts (int, optional) – Compression level (1-9), by default 4

Raises:

ValueError – If partition_schema validation fails

Return type:

None

read_g2_data(file_path, q_idx=None, group='/xpcs/g2')[source]

Read G2 correlation data from HDF5 file with schema validation.

Parameters:

  • file_path (str or Path) – Path to HDF5 file

  • q_idx (int, optional) – If provided, read only this Q-bin index. Otherwise read all.

  • group (str, optional) – HDF5 group containing G2 data, by default “/xpcs/g2”

Returns:

Validated G2 correlation data

Return type:

G2Data

Raises:

  • HDF5ValidationError – If G2 data fails schema validation

  • KeyError – If required datasets are missing

read_geometry_metadata(file_path, group='/xpcs/metadata')[source]

Read geometry metadata from HDF5 file with schema validation.

Parameters:

  • file_path (str or Path) – Path to HDF5 file

  • group (str, optional) – HDF5 group containing metadata, by default “/xpcs/metadata”

Returns:

Validated geometry metadata

Return type:

GeometryMetadata

Raises:

  • HDF5ValidationError – If metadata fails schema validation

  • KeyError – If required fields are missing

get_pool_stats()[source]

Get connection pool statistics.

Returns:

Connection pool statistics including cache hits, pool size, etc.

Return type:

dict

clear_pool()[source]

Clear the connection pool.

Use this to force close all pooled connections, for example after major changes or before application shutdown.

Return type:

None

HDF5ValidationError

class xpcsviewer.io.HDF5ValidationError[source]

Bases: Exception

Raised when HDF5 data fails schema validation.

Raised when HDF5 data fails schema validation during read operations.

from xpcsviewer.io import HDF5Facade, HDF5ValidationError

facade = HDF5Facade()
try:
    qmap = facade.read_qmap("corrupted.hdf5")
except HDF5ValidationError as e:
    print(f"Validation failed: {e}")

Writing Data

The facade provides write methods for masks and partitions:

import numpy as np
from xpcsviewer.schemas import MaskSchema, GeometryMetadata

metadata = GeometryMetadata(
    bcx=256.0, bcy=256.0,
    det_dist=5000.0, lambda_=1.0,
    pix_dim=0.075, shape=(512, 512),
)

mask = MaskSchema(
    mask=np.ones((512, 512), dtype=np.int32),
    metadata=metadata,
    description="Clean mask",
)

facade = HDF5Facade()
facade.write_mask("output.hdf5", mask)

Connection Pool

The facade uses an internal connection pool for HDF5 file handles, reducing overhead for repeated reads from the same file.

# Check pool statistics
stats = facade.get_pool_stats()
print(f"Pool size: {stats}")

# Clear the pool (e.g., before shutdown)
facade.clear_pool()

See Also

  • Schemas - Data structure schemas returned by the facade

  • File I/O - Lower-level HDF5 reading utilities

  • Backends - Backend-aware I/O adapters