Xepr data module¶

@author: Sam Schott (ss2151@cam.ac.uk)

(c) Sam Schott; This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 2.0 UK: England & Wales License.

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

Bases: object

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.xepr_dataset.ParamGroup(name: str = '', pars: Optional[List[experiment.xepr_dataset.XeprParam]] = None)[source]¶

Bases: object

Class to hold an Xepr experiment parameter group, which is part of a layer.

Variables

HEADER_FMT – Format of parameter group header.
CELL_LENGTH – Length of cell containing the parameter name.
DELIM – Delimiter between parameter name and value.

Parameters

name – The parameter group’s name.
pars – Dictionary containing all XeprParam instances belonging to the group.

to_string() → str[source]¶: Prints a parameter group as string.

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

Parses a parameter group from given string.

Parameters: string – Parameter group string from Bruker .DSC file.

class experiment.xepr_dataset.ParamGroupDESC(name: str = '', pars: Optional[List[experiment.xepr_dataset.XeprParam]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamGroup

Class to hold an Xepr experiment parameter group which forms a section of the Descriptor Layer (DESC).

class experiment.xepr_dataset.ParamGroupSPL(name: str = '', pars: Optional[List[experiment.xepr_dataset.XeprParam]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamGroup

Class to hold an Xepr experiment parameter group associated with a functional unit, part of the Standard Parameter Layer (SPL).

HEADER_FMT = None¶

class experiment.xepr_dataset.ParamGroupDSL(name: str = '', pars: Optional[List[experiment.xepr_dataset.XeprParam]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamGroup

Class to hold an Xepr experiment parameter group associated with a functional unit, part of the Device Specific Layer (DSL).

class experiment.xepr_dataset.ParamGroupMHL(name: str = '', pars: Optional[List[experiment.xepr_dataset.XeprParam]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamGroup

Class to hold an Xepr experiment parameter group which forms a section of the Manipulation History Layer (MHL).

class experiment.xepr_dataset.ParamLayer(groups: Optional[List[experiment.xepr_dataset.ParamGroup]] = None)[source]¶

Bases: object

Parameter layer object. Contains a top level parameter section of a Bruker BES3T file. This should be subclassed, depending on the actual parameter layer type.

Variables

TYPE – Parameter layer type. Can be ‘DESC’ for a Descriptor Layer, ‘SPL’ for a Standard Parameter Layer, ‘DSL’ for a Device Specific Layer or ‘MHL’ for a Manipulation History Layer.
NAME – Parameter layer name.
VERSION – Parameter layer version. This identifies the implemented BES3T file format specification used when parsing the information.
HEADER_FMT – Header format for the parameter layer.
END – Characters to indicate the end of layer in ‘.DSC’ file.

GROUP_CLASS¶: alias of experiment.xepr_dataset.ParamGroup

to_string() → str[source]¶

Prints the parameter layer as string.

Returns: Parameter layer string in as found in ‘.DSC’ file.
Return type: str

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

Parses parameter layer string to contained parameters

Parameters: string (str) – Parameter layer string in as found in ‘.DSC’ file.

class experiment.xepr_dataset.DescriptorLayer(groups: Optional[List[experiment.xepr_dataset.ParamGroup]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamLayer

Descriptor Layer class.

GROUP_CLASS¶: alias of experiment.xepr_dataset.ParamGroupDESC

class experiment.xepr_dataset.StandardParameterLayer(groups: Optional[List[experiment.xepr_dataset.ParamGroup]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamLayer

Standard Parameter Layer class.

GROUP_CLASS¶: alias of experiment.xepr_dataset.ParamGroupSPL

from_string(string)[source]¶

Parses parameter layer string to contained parameters

Parameters: string (str) – Parameter layer string in as found in ‘.DSC’ file.

class experiment.xepr_dataset.DeviceSpecificLayer(groups: Optional[List[experiment.xepr_dataset.ParamGroup]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamLayer

Device Specific Parameter Layer class.

GROUP_CLASS¶: alias of experiment.xepr_dataset.ParamGroupDSL

class experiment.xepr_dataset.ManipulationHistoryLayer(groups: Optional[List[experiment.xepr_dataset.ParamGroup]] = None)[source]¶

Bases: experiment.xepr_dataset.ParamLayer

Manipulation History Parameter Layer class.

GROUP_CLASS¶: alias of experiment.xepr_dataset.ParamGroupMHL

class experiment.xepr_dataset.Pulse(position: int, length: int, position_increment: int = 0, length_increment: int = 0)[source]¶

Bases: object

Object representing a single pulse.

Parameters

position – Pulse position in ns.
length – Pulse length in ns.
position_increment – Increment in pulse position between subsequent measurements in ns.
length_increment – Increment in pulse length between subsequent measurements in ns.

class experiment.xepr_dataset.PulseChannel(par: experiment.xepr_dataset.XeprParam)[source]¶

Bases: object

On object representing a pulse channel in a pulsed ESR experiment. Pulse channels can be for microwave pulses and acquisition (e.g., “+x”, “+y”, “AWG Trigger”, “Acquisition trigger”) which are manually set by the user or for instrument control pulses which are automatically determined (e.g., “TWT”, “”Receiver Protection”).

Every pulse channel can hold up to 1024 pulses, represented by Pulse instances.

Variables

N_PULSES_DEFAULT – Default number of programmable pulses: 400.
N_PULSES_MAX – Maximum number of programmable pulses 1024.
channel_descriptions – Verbose descriptions of pulse channels in a data file (otherwise designated by numbers Psd1 to Psd34 only).

Parameters

par – XeprParam holding the pulse channel table.

property name: str¶: Name of pulse channel, e.g., ‘Psd6’.

property number: int¶: Number of pulse channel, e.g., 6.

property description: str¶: Description of pulse channel, e.g., ‘+x’.

property pulses: List[experiment.xepr_dataset.Pulse]¶: List of pulses in this channel.

class experiment.xepr_dataset.PulseSequence(dset: experiment.xepr_dataset.XeprData)[source]¶

Bases: object

Object which hold information about the pulse sequence used to acquire the dataset (in case of pulsed experiments). This object is constructed from the pulse channel tables “Psd1”, “Psd2”, etc, in the descriptor layer.

property pulse_channels: List[experiment.xepr_dataset.PulseChannel]¶: Returns a list of pulse channels present in the instrument.

plot() → None[source]¶

Plots the pulse sequence used to acquire the data.

Raises: RuntimeError if the experiment is not pulsed.
Raises: ImportError if matplotlib is not installed.

class experiment.xepr_dataset.ParamDict(layers: Dict[str, experiment.xepr_dataset.ParamLayer])[source]¶

Bases: collections.abc.MutableMapping

Object to allow attribute access to all measurement parameters.

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

Bases: object

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.