epyr.fair.conversion

Main conversion functions and workflows for Bruker EPR to FAIR format conversion.

This module provides the high-level interface for converting Bruker EPR data to FAIR-compliant formats using the EPyR Tools package.

Functions

batch_convert_directory(input_directory[, ...])

Convert every Bruker file in a directory to FAIR formats.

convert_bruker_to_fair(input_file[, ...])

Load a Bruker file and convert it to FAIR-compliant formats.

save_fair(output_basename, x, y, params, ...)

Write already-loaded EPR data to one or more FAIR formats.

validate_conversion(fair_json_file[, ...])

Validate a FAIR conversion by checking the JSON metadata file.
epyr.fair.conversion.convert_bruker_to_fair(input_file, output_dir=None, formats=None, include_metadata=True, scaling='')[source]

Load a Bruker file and convert it to FAIR-compliant formats.

End-to-end pipeline: epyr.eprload() -> parameter normalization -> writing one or more output files next to the input.

Parameters:

  • input_file (str or pathlib.Path) – Path to a Bruker data file (.dta, .dsc, .spc, .par).

  • output_dir (str or pathlib.Path, optional) – Where to write the converted files. Defaults to the input file’s directory. Created if missing.

  • formats (list of str, optional) –

    Subset of ['csv', 'json', 'hdf5', 'jpg']. Default ['csv', 'json'].

    • csv : data array

    • json : metadata only

    • hdf5 : data + metadata in one file

    • jpg : preview figure (1D plot or 2D map + waterfall)

  • include_metadata (bool, optional) – Whether CSV files should carry the parameter dictionary as commented header lines. Default True.

  • scaling (str, optional) – Scaling code passed through to epyr.eprload(). Default "".

Returns:

True on success, False if loading or writing failed (errors are logged, not raised).

Return type:

bool

Examples

>>> from epyr.fair import convert_bruker_to_fair
>>> ok = convert_bruker_to_fair(
...     "examples/data/130406SB_CaWO4_Er_CW_5K_20.DSC",
...     output_dir="/tmp/epyr_out",
...     formats=["json", "hdf5"],
... )
>>> ok
True
epyr.fair.conversion.save_fair(output_basename, x, y, params, original_file_path, output_formats=None)[source]

Write already-loaded EPR data to one or more FAIR formats.

Use this when data is already in memory (e.g., after processing) and you want to write outputs without re-reading the Bruker file.

Parameters:

  • output_basename (str or pathlib.Path) – Base path (no extension); each format appends its own.

  • x (np.ndarray, list of np.ndarray, or None) – Abscissa as returned by epyr.eprload().

  • y (np.ndarray) – Signal data.

  • params (dict) – Parameter dictionary from the original file.

  • original_file_path (str) – Full path of the source file, kept as provenance in the outputs.

  • output_formats (list of str, optional) – Subset of ['csv', 'json', 'hdf5', 'jpg', 'csv_json']. Default ['csv', 'json'].

Returns:

Outputs are written to disk under output_basename.

Return type:

None

Examples

>>> import numpy as np
>>> from epyr.fair import save_fair
>>> x = np.linspace(3300, 3400, 100)
>>> y = np.random.randn(100)
>>> save_fair("/tmp/demo", x, y, {"MWFQ": 9.4e9},
...           "demo.dsc", ["json"])
epyr.fair.conversion.batch_convert_directory(input_directory, output_directory=None, file_extensions=None, scaling='', output_formats=None, recursive=False)[source]

Convert every Bruker file in a directory to FAIR formats.

Parameters:

  • input_directory (str or pathlib.Path) – Directory to scan.

  • output_directory (str or pathlib.Path, optional) – Where to write the converted files. Defaults to alongside each input file. Created if missing.

  • file_extensions (list of str, optional) – Which extensions count as Bruker files. Default ['.dsc', '.spc', '.par'].

  • scaling (str, optional) – Scaling code passed through to epyr.eprload().

  • output_formats (list of str, optional) – Subset of ['csv', 'json', 'hdf5', 'jpg']. Default ['csv', 'json'].

  • recursive (bool, optional) – Also descend into subdirectories. Default False.

Returns:

Progress and a final per-file summary are logged.

Return type:

None

Examples

>>> from epyr.fair import batch_convert_directory
>>> batch_convert_directory(
...     "examples/data",
...     output_directory="/tmp/epyr_batch",
...     output_formats=["json"],
... )
epyr.fair.conversion.validate_conversion(fair_json_file, original_data_file=None)[source]

Validate a FAIR conversion by checking the JSON metadata file.

Parameters:

  • fair_json_file (str | Path) – Path to the JSON metadata file from FAIR conversion.

  • original_data_file (str | Path | None) – Path to original data file for comparison (optional).

Returns:

Dictionary with validation results including warnings and statistics.

Return type:

Dict[str, Any]