playnano.analysis.utils.common module

Common utility functions for analysis.

class playnano.analysis.utils.common.NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Custom JSON encoder for serializing NumPy ndarray and scalar objects.

This encoder converts NumPy arrays to native Python lists and NumPy scalar types (e.g., float32, int64) to their native Python equivalents so they can be serialized by the standard json module. It can be used with json.dump or json.dumps by passing it as the cls argument.

Example

json.dump(data, file, cls=NumpyEncoder)

default(obj)

Override default method to convert NumPy arrays and scalar types.

Convert NumPy arrays ad scalar types to JSON-serializable forms.

Parameters:

obj (Any) – The object to be serialized.

Returns:

A JSON-serializable version of the object. If the object is a NumPy ndarray, it is converted to a list. If the object is a NumPy scalar (e.g., np.float32, np.int64), it is converted to the equivalent Python scalar. Otherwise, the superclass’s default method is used.

Raises:

TypeError – If the object cannot be serialized by the superclass.

playnano.analysis.utils.common.export_to_hdf5(record: Mapping[str, Any], out_path: Path, dataset_name: str = 'analysis_record') → None

Save a nested dict/list/array structure to HDF5 with full breakdown.

• Dicts become groups.

• Lists of primitives become datasets.

• Lists of complex objects become subgroups item_0, item_1, etc.

• NumPy arrays become datasets.

playnano.analysis.utils.common.load_analysis_from_hdf5(file_path: str | Path, dataset_name: str = 'analysis_record') → dict

Load a nested dict/list/NumPy array structure from an HDF5 file.

This exactly reverses export_to_hdf5. Automatically converts integer-valued NumPy floats to Python ints recursively for use as list indices.

Parameters:

• file_path (str or Path) – Path to the HDF5 file containing the saved analysis dictionary.

• dataset_name (str) – Name of the top-level group in the HDF5 file where the dictionary is stored. Default is ‘analysis_record’.

Returns:

record – Nested dictionary reconstructed from the HDF5 file. The structure preserves: - dicts as dicts - lists as lists - NumPy arrays as np.ndarray - strings as str - empty lists as [] - primitive values stored in attributes - integer-valued floats converted to Python int recursively

Return type:

dict

Raises:

KeyError – If dataset_name is not found in the HDF5 file.

playnano.analysis.utils.common.make_json_safe(record: dict) → dict

Make a AnalysisRecord safe for export through JSON dumping.

Prepare an AnalysisRecord for JSON dumping by stripping out or summarizing any non-JSON-serializable entries.

Parameters:

record (dict) – The full AnalysisRecord returned by AnalysisPipeline.run().

Returns:

A new dict with the same top-level keys (“environment”, “analysis”, “provenance”), but with each value run through your sanitizers so that they contain only numbers, strings, lists, and dicts.

Return type:

dict

playnano.analysis.utils.common.safe_json_dumps(obj)

Serialize an object to JSON safely, falling back to str() on failure.

playnano.analysis.utils.common.sanitize_analysis_for_logging(obj, path='root', _depth=0, _max_depth=6)

Return a JSON-safe version of any object, printing any functions it finds.