ptyrad.io.provenance

ptyrad.io.provenance#

Reconstruction provenance handling (load/save)

Functions

collect_provenance(init_params)

Initializes the provenance tracking dictionary for a new run.

export_hdf5_provenance_to_json(h5_path[, ...])

Extracts provenance history from an HDF5 file and saves it as JSON.

generate_provenance_json(current_provenance, ...)

Appends the current run details to the provenance timeline and serializes it.

load_provenance_from_h5(file_path)

Reads and parses the provenance history from an HDF5 file.

save_provenance_to_hdf5(hdf5_path, ...)

Saves the serialized provenance JSON string to an HDF5 file attribute.

Classes

SafeJSONEncoder(*[, skipkeys, ensure_ascii, ...])

Sanitizes scientific types into JSON-safe formats.
class ptyrad.io.provenance.SafeJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]#

Bases: JSONEncoder

Sanitizes scientific types into JSON-safe formats.

This custom encoder ensures that NumPy numerical types, arrays, pathlib Path objects, and stray PyTorch tensors can be cleanly serialized into the provenance JSON string without throwing TypeErrors.

default(obj)[source]#

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)
ptyrad.io.provenance.collect_provenance(init_params)[source]#

Initializes the provenance tracking dictionary for a new run.

This function scans the initialization parameters to determine the origin of the probe, object, positions, and tilts. It handles file loading (including inheriting provenance from older PtyRAD HDF5 files), simulations, and in-memory custom arrays.

Parameters:

init_params (dict) – The initialization parameters for the reconstruction.

Returns:

A dictionary mapping component names (‘probe’, ‘pos’, ‘obj’, ‘tilt’) to a list of provenance entry dictionaries representing their history.

Return type:

dict

ptyrad.io.provenance.generate_provenance_json(current_provenance, params, output_filename='current_run')[source]#

Appends the current run details to the provenance timeline and serializes it.

This safely deepcopies the existing provenance history, appends the current run’s configuration to every component’s timeline, and encodes the entire history into a JSON string using SafeJSONEncoder.

Parameters:

  • current_provenance (dict) – The inherited provenance dictionary.

  • params (dict) – The configuration parameters for the current run.

  • output_filename (str or Path, optional) – The filename or path identifying this specific run. Defaults to “current_run”.

Returns:

A JSON-formatted string of the complete provenance history.

Return type:

str

ptyrad.io.provenance.save_provenance_to_hdf5(hdf5_path, provenance_json_str)[source]#

Saves the serialized provenance JSON string to an HDF5 file attribute.

Parameters:

  • hdf5_path (str or Path) – The path to the target HDF5 file.

  • provenance_json_str (str) – The JSON string representing the history.

ptyrad.io.provenance.load_provenance_from_h5(file_path)[source]#

Reads and parses the provenance history from an HDF5 file.

Extracts the ‘provenance_json’ attribute from the root of the specified HDF5 file and parses it back into a Python dictionary.

Parameters:

file_path (str or Path) – The path to the HDF5 file.

Returns:

The lineage dictionary (e.g., {‘probe’: […], ‘obj’: […]}). Returns an empty dict {} if the attribute is missing or corrupted.

Return type:

dict

Raises:

FileNotFoundError – If the specified HDF5 file does not exist.

ptyrad.io.provenance.export_hdf5_provenance_to_json(h5_path, output_json_path=None)[source]#

Extracts provenance history from an HDF5 file and saves it as JSON.

Parameters:

  • h5_path (str or Path) – The path to the source .h5 file.

  • output_json_path (str, optional) – The destination path for the .json file. If None, it defaults to ‘<h5_filename>_provenance.json’ in the same directory. Defaults to None.

Returns:

The path to the generated JSON output file.

Return type:

str

Contents