epyr.fair.exporters

Format-specific export functions for FAIR data conversion.

This module contains functions to export EPR data and metadata to various FAIR-compliant formats including CSV/JSON and HDF5.

Functions

`save_fair`(output_basename, x, y, pars, ...)	Save EPR data in specified FAIR formats.
`save_to_csv`(output_basename, x, y, pars, ...)	Write EPR data and a metadata header to `<basename>.csv`.
`save_to_csv_json`(output_basename, x, y, ...)	Save data to CSV and structured metadata to JSON.
`save_to_hdf5`(output_basename, x, y, pars, ...)	Write data and metadata to `<basename>.h5`.
`save_to_jpg`(output_basename, x, y, pars, ...)	Write a preview figure to `<basename>.jpg`.
`save_to_json`(output_basename, pars, ...)	Write parameter metadata to `<basename>.json`.

epyr.fair.exporters.save_to_json(output_basename, pars, original_file_path)[source]

Write parameter metadata to <basename>.json.

The output contains the source-file path, the FAIR-normalized metadata, and any unmapped Bruker keys preserved verbatim.

Parameters:

output_basename (pathlib.Path) – Base path; .json is appended.
pars (dict) – Raw Bruker parameters as returned by epyr.eprload().
original_file_path (str) – Source-file path kept as provenance.

Return type:

None

Examples

>>> from pathlib import Path
>>> from epyr import eprload
>>> from epyr.fair import save_to_json
>>> x, y, params, fp = eprload("examples/data/130406SB_CaWO4_Er_CW_5K_20.DSC")
>>> save_to_json(Path("/tmp/demo"), params, fp)

epyr.fair.exporters.save_to_csv(output_basename, x, y, pars, original_file_path)[source]

Write EPR data and a metadata header to <basename>.csv.

The header carries microwave frequency, modulation amplitude, sample name, and the path to the source file, in commented (#) lines before the column data.

Parameters:

output_basename (pathlib.Path) – Base path; .csv is appended.
x (np.ndarray, list of np.ndarray, or None) – Abscissa from epyr.eprload(). Lists (2D) are written as long-format rows.
y (np.ndarray) – Signal array.
pars (dict) – Raw Bruker parameters.
original_file_path (str) – Source-file path kept as provenance in the CSV header.

Return type:

None

Examples

>>> from pathlib import Path
>>> from epyr import eprload
>>> from epyr.fair import save_to_csv
>>> x, y, params, fp = eprload("examples/data/130406SB_CaWO4_Er_CW_5K_20.DSC")
>>> save_to_csv(Path("/tmp/demo"), x, y, params, fp)

epyr.fair.exporters.save_to_csv_json(output_basename, x, y, pars, original_file_path)[source]

Save data to CSV and structured metadata to JSON.

This function is maintained for backward compatibility and calls save_to_csv() and save_to_json() separately.

Parameters:

output_basename (Path) – Base path for output files (without extension)
x (ndarray | List[ndarray] | None) – Abscissa data array(s) or None
y (ndarray) – Intensity data array
pars (Dict[str, Any]) – Raw parameters dictionary
original_file_path (str) – Path to original data file

Return type:

None

epyr.fair.exporters.save_to_hdf5(output_basename, x, y, pars, original_file_path)[source]

Write data and metadata to <basename>.h5.

Datasets:: /intensity : signal array (y) /abscissa : abscissa array (1D) or group /axis_0,

/axis_1 (2D)

Metadata is written as attributes on the root group: the FAIR-mapped parameters, unmapped raw parameters, and the source-file path.

Parameters:

output_basename (pathlib.Path) – Base path; .h5 is appended.
x (np.ndarray, list of np.ndarray, or None) – Abscissa from epyr.eprload().
y (np.ndarray) – Signal array. Complex data is stored as two real datasets, /intensity_real and /intensity_imag.
pars (dict) – Raw Bruker parameters.
original_file_path (str) – Source path kept as an HDF5 attribute.

Returns:

A UserWarning is emitted (no exception) if h5py is not installed; the file is then not written.

Return type:

None

Examples

>>> from pathlib import Path
>>> from epyr import eprload
>>> from epyr.fair import save_to_hdf5
>>> x, y, params, fp = eprload("examples/data/Rabi2D_GdCaWO4_13dB_3057G.DSC")
>>> save_to_hdf5(Path("/tmp/demo"), x, y, params, fp)

epyr.fair.exporters.save_to_jpg(output_basename, x, y, pars, original_file_path)[source]

Write a preview figure to <basename>.jpg.

For 1D data, a single plot_1d figure. For 2D data, two files: <basename>_map.jpg and <basename>_waterfall.jpg.

Parameters:

output_basename (pathlib.Path) – Base path; the JPG suffix is appended.
x (np.ndarray, list of np.ndarray, or None) – Abscissa from epyr.eprload().
y (np.ndarray) – Signal array (1D or 2D).
pars (dict) – Raw Bruker parameters, used for axis labels.
original_file_path (str) – Source path, used as the figure title.

Returns:

Uses the Agg non-interactive backend; safe in scripts.

Return type:

None

Examples

>>> from pathlib import Path
>>> from epyr import eprload
>>> from epyr.fair import save_to_jpg
>>> x, y, params, fp = eprload("examples/data/130406SB_CaWO4_Er_CW_5K_20.DSC")
>>> save_to_jpg(Path("/tmp/demo"), x, y, params, fp)

epyr.fair.exporters.save_fair(output_basename, x, y, pars, original_file_path, formats=None)[source]

Save EPR data in specified FAIR formats.

Parameters:

output_basename (Path) – Base path for output files (without extension)
x (ndarray | List[ndarray] | None) – Abscissa data array(s) or None
y (ndarray) – Intensity data array
pars (Dict[str, Any]) – Raw parameters dictionary
original_file_path (str) – Path to original data file
formats (List[str] | None) – List of output formats. Options: ‘csv’, ‘json’, ‘hdf5’, ‘jpg’, ‘csv_json’ - ‘csv’: Save data to CSV file only - ‘json’: Save metadata to JSON file only - ‘hdf5’: Save data and metadata to HDF5 file - ‘jpg’: Save visualization plots (1D: single plot, 2D: map + waterfall) - ‘csv_json’: Save both CSV and JSON (backward compatibility) Defaults to [‘csv’, ‘json’].

Return type:

None