pyepri.io

Basic functions for loading datasets (in Bruker BES3T format or pickle Python format).

The functions of this module related to BES3T format were adapted from the open source MIT licensed DIVE package (v0.2.1), as detailed below:

  • read_bruker_description_file() is a copy of the read_description_file() function coded into the file deerload.py of the DIVE package (with the slight modification of variable naming (l -> L) to avoid ruff ambiguous-variable-name error (E741))

  • read_bruker_bes3t_dataset() was adapted from the deerload() function of coded deerload.py of the DIVE package.

We provide below the copy of the license file of the DIVE package (v.0.2.1), in accordance with the rules of the MIT license.

MIT License

Copyright (c) 2024 Sarah Sweger, Julian Cheung, Lukas Zha, Stephan Pribitzer,
Stefan Stoll

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Attributes

read_bruker_best3_dataset

Functions

read_bruker_description_file(→ dict)

Retrieves the parameters from a .DSC files as a dictionary.

read_bruker_bes3t_dataset(name[, squeeze, stack, ...])

Read Bruker data from a .DSC or .DTA file.

load(path[, backend, dtype])

load a dataset stored in BES3T (.DSC or .DTA) or Python pickle (.PKL) format.

Module Contents

pyepri.io.read_bruker_description_file(name: str) → dict[source]

Retrieves the parameters from a .DSC files as a dictionary.

Parameters:

name (str) – The filename to be read, including the .DSC extension.

Returns:

Parameters – A dictionary of the parameters in the .DSC file.

Return type:

dict

pyepri.io.read_bruker_bes3t_dataset(name, squeeze=True, stack=True, dtype=None, backend=None)[source]

Read Bruker data from a .DSC or .DTA file.

Read files in BES3T format (Bruker EPR Standard for Spectrum Storage and Transfer) which is used on Bruker ELEXSYS and EMX machines.

The BES3T format consists of at least two files, a data file with extension .DTA and a descriptor file with extension .DSC. This code assumes that the .DSC file and the .DTA file are both stored in the same directory.

Code based on BES3T version 1.2 (Xepr >= 2.1), and adapted from the deerload() function of the open source MIT licensed DIVE package (v0.2.1).

This code is restricted to real datasets with regular sampling grids.

Parameters:

  • name (str) – The full filename of the .DSC or .DTA file (including the .DSC or .DTA extension). Both the .DSC and the .DAT files must be stored in the same folder.

  • squeeze (bool, optional) – When squeeze is True, axes with lenght one will be removed from the output data array.

  • stack (bool, optional) – When the input dataset contain more than one datapoint along the Z axis, set stack = True to keep the original data shape, or use stack = False to reshape the data (Z-axis signals are stacked vertically along the first axis).

  • dtype (str, optional) – Desired datatype (given in str format) for the loaded data arrays (spectrum or projections, field gradient vector coordinates, etc.).

  • backends (<class 'pyepri.backends.Backend'> or None, optional) –

    A numpy, cupy or torch backend (see pyepri.backends module).

    When backend is None, a numpy backend is instantiated.

Returns:

  • B (ndarray) – Monodimensional array containing the sampling nodes of the projections (homogeneous magnetic field), stored as a monodimensional array.

  • data (ndarray) – Multidimensional array containing the measurements.

  • parameters (dict) – Retrieved additional parameters.

pyepri.io.read_bruker_best3_dataset
pyepri.io.load(path, backend=None, dtype='float32')[source]

load a dataset stored in BES3T (.DSC or .DTA) or Python pickle (.PKL) format.

In case of a BES3T dastaset, both the .DSC file and the .DTA file must be stored in the same directory.

Otherwise, when the dataset is stored in .PKL format, it is assumed to contain the following key-values content:

  • ‘DAT’: the spectrum or projections measurements;

  • ‘B’: a monodimensional array containing the homogeneous magnetic field intensities sampling nodes;

Additionally, when the dataset contains projections, it must also contain the following key-value:

  • ‘FGRAD’: an two dimensional array containing the coordinates of the sequence of field gradient vectors associated to the measured projections (first row = first coordinate, second row = second coordinate, etc).

Parameters:

  • path (str) – The full filename of the dataset (including the .DSC or .DTA or .PKL extension). If the dataset is provided in BES3T format, the user may supply either the .DSC or .DTA file path; both are accepted interchangeably (remind however that the two files must be stored in the same folder).

  • backends (<class 'pyepri.backends.Backend'> or None, optional) –

    A numpy, cupy or torch backend (see pyepri.backends module).

    When backend is None, a numpy backend is instantiated.

  • dtype (str, optional) – Desired datatype for the loaded data arrays (spectrum or projections, field gradient vector coordinates, etc.).

Returns:

out – A dictionary containing the retrieved data, with the same key-value as those described above for .PKL input dataset.

Return type:

dict