Experiment¶

This section gives an overview of modules to handle and plot experimental EPR data. It contains two modules: experiment.xepr_dataset defines classes to read, write, manipulate and plot Xepr datasets from Bruker’s BES3T file format. mode_picture_dataset.xepr_dataset defines classes to read, write and plot cavity mode pictures.

This page documents the main classes available from experiment. The full API is documented in the pages for the respective submodules:

class experiment.XeprData(path: Optional[str] = None)[source]¶

Holds a Bruker EPR measurement result, including all measurement parameters. Supports importing and exporting to the Bruker BES3T file format (‘.DSC’, ‘.DTA’ and possible associated ‘.XGF’, ‘.YGF’ and ‘.ZGF’ files) in the 1.2 specification currently used by Xepr. Parameters are stored in the following attributes and are grouped after the associated functional unit (e.g., ‘mwBridge’, ‘fieldCtrl’) or type (e.g., ‘Documentational Text’).

Variables

desc – DescriptorLayer instance holding the parameters from the ‘.DSC’ file that describe content and parsing of corresponding data files (‘.DTA’ etc).
spl – StandardParameterLayer instance holding all mandatory EPR parameters, such as the microwave power.
dsl – DeviceSpecificLayer instance holding the EPR measurement parameters specific to the instrument and type of measurement, i.e., the measurement temperature, sample angles, integration time, etc.
mhl – ManipulationHistoryLayer instance holding all parameters that describe manipulations performed on the data set (e.g., baseline correction, scaling, …).
pars – Dictionary-like object giving direct access to all measurement parameters. Allows for quickly reading and setting parameter values.
pulse_sequence – PulseSequence instance which describes the pulse sequence used to acquire the data (in case of pulsed experiments). This object is constructed from the pulse channel tables “Psd1”, “Psd2”, etc, in the descriptor layer.

Setting the value of an existing parameter will automatically update it in the appropriate parameter layer. Setting a new parameter value will add it to a ‘customXepr’ device group in the DeviceSpecificLayer.

The actual data is accessible as numpy arrays x, y, z and o. Only the the ordinate data may be changed and the new data must have the same size and format as o. It is not currently possible to change the x/y/z-axis data.

Warning

Changing the parameters in the Descriptor Layer may result in inconsistencies between the parameter file (DSC) and the actual data files (DTA, XGF, YGF, ZGF) and therefore may result in corrupted files.

Examples

Read a data file and get some information about the device specific parameters:

>>> from customxepr import XeprData, XeprParam
>>> dset = XeprData("/path/to/file.DSC")
>>> dset.dsl.groups
{"fieldCtrl": <ParamGroupDSL(fieldCtrl)>,
 "fieldSweep": <ParamGroupDSL(fieldSweep)>,
 "freqCounter": <ParamGroupDSL(freqCounter)>,
 "mwBridge": <ParamGroupDSL(mwBridge)>,
 "recorder": <ParamGroupDSL(recorder)>,
 "signalChannel": <ParamGroupDSL(signalChannel)>}
>>> dset.dsl.groups["mwBridge"].pars
{"AcqFineTuning": <XeprParam(Never)>,
 "AcqScanFTuning": <XeprParam(Off)>,
 "AcqSliceFTuning": <XeprParam(Off)>,
 "BridgeCalib": <XeprParam(50.5)>,
 "Power": <XeprParam(0.002 mW)>,
 "PowerAtten": <XeprParam(50.0 dB)>,
 "QValue": <XeprParam(5900)>}

Change the value of an existing parameter:

>>> dset.pars["ModAmp"].value = 2

Add a new parameter without an associated group (it will be added to a “CustomXepr” group in the DSL layer):

>>> dset.pars["NewParam"] = XeprParam("NewParam", 1234)

Add a new parameter to the microwave bridge device group:

>>> dset.dsl.groups["mwBridge"].add_param(XeprParam("QValue", 6789))

Add a new parameter group for a temperature controller, with two parameters:

>>> pars = [
...    XeprParam("Temperature", 290, "K"),
...    XeprParam("AcqWaitTime", 120, "s")
...    ]
>>> new_group = ParamGroupDSL("tempCtrl", pars)
>>> dset.dsl.groups["tempCtrl"] = new_group

Save the modified data set:

>>> dset.save("/path/to/file.DSC")

property x: numpy.ndarray¶: Returns x-axis data as numpy array.

property y: numpy.ndarray¶: Returns y-axis data as numpy array.

property z: numpy.ndarray¶: Returns z-axis data as numpy array.

property o: numpy.ndarray¶: Returns ordinate data as numpy array or as a tuple of arrays containing all ordinate data sets. If real and imaginary parts are present, they will be combined to a complex numpy array.

load(path: str) → None[source]¶

Loads data and parameters from a ‘.DSC’ file and accompanying data files.

Parameters: path (str) – Path to ‘.DSC’ file or accompanying data files to load. Any of those file paths can be given, the other files belonging to the same data set will be found automatically if in the same directory.

save(path: str) → None[source]¶

Saves data and parameters to a ‘.DSC’ file and accompanying data files.

Parameters: path (str) – Path to ‘.DSC’ file or accompanying data files to save. Any of those file paths can be given, the other file names will be generated as necessary.

print_dsc() → str[source]¶

Parses all parameters as ‘.DSC’ file content and returns the result as a string.

Returns: String containing all parameters in ‘.DSC’ file format.
Return type: str

plot() → None[source]¶: Plots all recorded spectra / sweeps as 2D or 3D plots. Requires matplotlib.

class experiment.XeprParam(name: str, value: Optional[Union[float, bool, str, numpy.ndarray]] = None, unit: str = '', comment: str = '')[source]¶

Holds a Bruker measurement parameter in the BES3T file format.

Parameters

value – The parameter value.
unit – String containing the unit. Defaults to an empty string.
comment – Defaults to an empty string.

to_string() → str[source]¶

Prints a parameter as string in the Bruker BES3T format.

Returns: Parsed parameter.

from_string(string: str) → None[source]¶

Parses a parameter from string given in the Bruker BES3T format.

Parameters: string (str) – String to parse.

class experiment.ModePicture(input_path_or_data, freq=9.385, metadata=None)[source]¶

Class to store mode pictures. It provides methods to calculate Q-values, and save and load mode picture data from and to .txt files.

If several mode pictures with different zoom factors are given, ModePicture will rescale and combine the data into a single mode picture.

Parameters

input_path_or_data (dict) – Dict with zoom factors as keys and respective mode picture data sets as values or path to file with saved mode picture data.
freq (float) – Cavity resonance frequency in GHz as float.
metadata (dict) – Optional dictionary with metadata to save in the file header.

Variables

x_data_mhz – Numpy array with x-axis data of mode picture in MHz.
x_data_points – Numpy array with x-axis data of mode picture in pts.
y_data – Mode picture y-axis data (absorption of cavity).
freq0 – Center frequency of cavity resonance.
qvalue – Fitted Q-Value.
qvalue_stderr – Standard error of Q-Value from fitting.

combine_data(mode_pic_data)[source]¶

Rescales mode pictures from different zoom factors and combines them to one.

Parameters: mode_pic_data (dict) – Dict with zoom factors as keys and respective mode picture curves as values.
Returns: (x_axis_mhz_comb, x_axis_points_comb, mode_pic_comb) where x_axis_mhz_comb and x_axis_points_comb are the combined x-axis values of all mode pictures in mhz and points, respectively, and mode_pic_comb is the combines y-axis data in a.u..

fit_qvalue(x_data, y_data, zoom_factor=1)[source]¶

Least square fit of Lorentzian and polynomial background to mode picture.

Parameters

x_data – Iterable containing x-data of mode picture in points.
y_data – Iterable containing y-data of mode picture in a.u..
zoom_factor – Zoom factor (scaling factor of x-axis).

Returns

(q_value, fit_result) where fit_result is a

get_qvalue_stderr()[source]¶

Determines 1 sigma confidence bounds for Q-value.

Returns: Standard error of Q-value from fitting.
Return type: float

plot()[source]¶: Plots mode picture and the least squares fit used to determine the Q-value. Requires matplotlib.

save(filepath)[source]¶

Saves mode picture data as a text file with headers. If no file path is given, the user is prompted to select a location and name through a user interface.

Parameters: filepath (str) – Absolute file path.

load(path)[source]¶

Loads mode picture data from text file and determines the resulting Q-factor.

Parameters: path (str) – Path of file.