You're reading the documentation for a development version. For the latest released version, please have a look at v0.5.

cwepr.analysis module

Module containing the analysis steps of the cwepr package.

An analysis step, in contrast to a processing step, does not simply modify a given dataset, but extracts some characteristic of this dataset that is contained in its results property. This can be as simple as a number, e.g., in case of the signal-to-noise figure of a data trace, but as complicated as a (calculated) dataset on its own containing some measure as function of some parameter, such as the microwave frequency for each of a series of recordings, allowing to visualise drifts that may or may not impact data analysis.

Concrete analysis steps

Note to developers

Processing steps can be based on analysis steps, but not inverse! Otherwise, we get cyclic dependencies what should obviously be avoided in order to keep code working.

class cwepr.analysis.FieldCalibration

Bases: SingleAnalysisStep

Determine offset value for a magnetic field calibration.

While the microwave frequency of an EPR spectrometer can be measured with high accuracy independent of the resonator (and cryostat) used, the magnetic field values recorded are usually measured by a Hall probe or NMR teslameter away from the actual sample position. Hence, calibrating the recorded magnetic field value is necessary in case you are interested in quantitative g-value measurements or accurate comparisons between measurements.

While spectrometers without removable probeheads (typically benchtop devices) come often calibrated by the manufacturer, in the typical research setup with probeheads and cryostats changing more frequent, field calibration is typically performed by the individual researcher recording the EPR spectrum of a standard sample with known g value.

Correcting the magnetic field axis of a recorded EPR spectrum is in such cases actually a two-step process:

  1. Obtain the magnetic field offset value from the EPR spectrum of a field standard with known g value.

  2. Add the obtained value to the values of the magnetic field axis of the EPR spectrum that should be field-corrected.

This class provides the first step, obtaining the magnetic field offset value for a number of well-known standards. And in case you use another field standard, you can simply provide the g value for this standard as well. The second step, correcting the magnetic field axis of your spectrum, is taken care of by the class cwepr.processing.FieldCorrection. See the examples section below for further details.

Note

The method currently relies on the recorded spectrum of the field standard to consist of a single symmetric line accurately recorded with sufficient resolution.

Currently, the following field standards are supported:

Substance

Name

g Value

Reference

Li:LiF

LiLiF

2.002293 ± 0.000002

[1]

DPPH

DPPH

2.0036 ± 0.0002

[2]

References

[1] Stesmans and Van Gorp, Rev. Sci. Instrum. 60(1989):2949–2952.

[2] Yordanov, Appl. Magn. Reson. 10(1996):339–350.

The column “name” here refers to the value the parameter standard can take (see below). These names are case-insensitive.

parameters

All parameters necessary for this step.

standardstr

Field standard that should be applied.

For valid values, see the table above.

g_valuefloat

g value of the standard sample.

If you provide a standard by name using the standard parameter above, this is not necessary. Providing a value here overrides the value for the standard. Hence, use with care not to confuse you afterwards, when standard name and g value are inconsistent.

mw_frequencyfloat

Microwave frequency to be corrected for.

In general, this value is taken from the dataset and should therefore usually not be provided explicitly. Providing a value overrides reading from the dataset.

Type:

dict

Raises:

ValueError – Raised if no microwave frequency or g value is available.

See also

cwepr.processing.FieldCorrection

Correct magnetic field axis by a linear offset

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. The examples focus each on a single aspect.

Suppose you have recorded the spectrum of a Li:LiF field standard, and now you would like to obtain the field offset to correct your other spectra:

- kind: singleanalysis
  type: FieldCalibration
  properties:
    parameters:
      standard: LiLiF
  result: deltaB0

This result can now be used within the same recipe to perform a field correction of your other data. A more detailed example may look as follows:

datasets:
  - /path/to/LiLiF/dataset
    label: lilif
  - /path/to/my/first/dataset
    label: first
  - /path/to/my/second/dataset
    label: second

tasks:
  - kind: singleanalysis
    type: FieldCalibration
    properties:
      parameters:
        standard: LiLiF
    result: deltaB0
    apply_to: lilif

  - kind: processing
    type: FieldCorrection
    properties:
      parameters:
        offset: deltaB0
    apply_to:
      - first
      - second

Here, we start by loading three datasets, a standard (LiLiF in this case) and two actual spectra. The first task is the analysis step to obtain the field offset value, performed only on the LiLiF spectrum, and the second is a processing step performed only on the two actual spectra to correct their field axis.

Suppose you have used a standard that’s currently not supported by name. Therefore, you will want to provide both, name and g value of the standard:

- kind: singleanalysis
  type: FieldCalibration
  properties:
    parameters:
      standard: Strong pitch
      g_value: 2.0028
  result: deltaB

Of course, providing the name of the standard does not change how the field offset is calculated, but it serves as documentation for you. Note that providing a g value overrides the value stored internally. Therefore, if you provide both, standard and g value, it is your sole responsibility to ensure consistency between those two parameters.

Changed in version 0.2: Renamed to FieldCalibration, added parameter g_value

static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Field calibration can only be applied to 1D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

class cwepr.analysis.LinewidthPeakToPeak

Bases: SingleAnalysisStep

Peak to peak linewidth in derivative spectrum.

The linewidth is given in a first derivative spectrum as difference between the two extreme points. However, this is valid only for simple spectra with just one line or signal. This analysis step simply takes the difference on the magnetic field axis which is then stored in the result. The task can be used as follows:

- kind: singleanalysis
  type: LinewidthPeakToPeak
  result: linewidth
static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Line width detection can only be applied to 1D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

get_peak_to_peak_linewidth()

Calculates the peak-to-peak linewidth.

This is done by determining the distance between the maximum and the minimum in the derivative spectrum which should yield acceptable results in a symmetrical signal. Limitation: Spectrum contains only one line.

Returns:

linewidth – peak to peak linewidth

Return type:

float

class cwepr.analysis.LinewidthFWHM

Bases: SingleAnalysisStep

Full linewidth at half maximum (FWHM).

In EPR, this linewidth can be applied to integrated cwEPR spectra or spectra recorded in absorptive mode. The calculation is done by subtracting maximum/2, getting the absolute value and then determining the minima. The distance between these points corresponds to the FWHM linewidth.

Examples

Usage is quite simple as it requires no additional parameters:

- kind: singleanalysis
  type: LinewidthFWHM
  result: linewidth
static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Line width detection can only be applied to 1D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

class cwepr.analysis.SignalToNoiseRatio

Bases: SingleAnalysisStep

Get a spectrum’s signal-to-noise ratio.

This is done by comparing the absolute maximum of the spectrum to the maximum of the edge part of the spectrum (i.e. a part which is considered to not contain any signal).

parameters

All parameters necessary for this step.

percentageint

percentage of the spectrum to be considered edge part on any side (i.e. 10 % means 10 % on each side).

Default: 10 %

Type:

dict

Examples

The analysis can be applied either with or without the additional parameter “percentage”:

- kind: singleanalysis
  type: SignalToNoiseRatio
  properties:
    parameters:
        percentage: 7
  result: SNR
class cwepr.analysis.Amplitude

Bases: SingleAnalysisStep

Determine amplitude of dataset.

Depending on the dimension of the dataset, the returned value is either a scalar (1D dataset) or a vector (2D dataset) containing the amplitude of each row respectively.

Returns:

amplitude(s) row-wise, thus scalar or vector.

Return type:

result

Examples

The analysis is again called without additional parameters:

- kind: singleanalysis
  type: Amplitude
  result: amplitude
class cwepr.analysis.AmplitudeVsSqrtPower

Bases: SingleAnalysisStep

Return a calculated dataset to further analyse a power-sweep experiment.

The analysis of a power sweep results in a plot of the peak amplitude vs. the square root of the microwave power of the bridge. Both values are determined in this step and put together in a calculated dataset that can be used subsequently to perform the linear fit.

Returns:

result – Calculated Dataset where the data is the amplitude and the axis values is the root of the mw-power (in ascending order).

Return type:

aspecd.dataset.CalculatedDataset

Examples

For analysing a power sweep, extracting the amplitude and taking the root of the microwave power is the first step to success (see Power sweep analysis for further details) and can be done as follows without additional parameters:

- kind: singleanalysis
  type: AmplitudeVsSqrtPower
  result: power_sweep_analysis

A more complete example of a power sweep analysis including linear fit of the first n points and a graphical representation of the results may look as follows:

datasets:
  - PowerSweep
tasks:
  - kind: singleanalysis
    type: AmplitudeVsSqrtPower
    apply_to:
      - PowerSweep
    result: power_sweep_analysis
  - kind: singleanalysis
    type: FitOnData
    properties:
      parameters:
        order: 1
        points: 5
        return_type: dataset
    apply_to:
      - power_sweep_analysis
    result: fit
  - kind: multiplot
    type: PowerSweepAnalysisPlotter
    properties:
      properties:
        drawings:
          - marker: '*'
          - color: red
        grid:
          show: true
          axis: both
        axes:
          ylabel: '$EPR\\ amplitude$'
      filename: powersweepanalysis.pdf
    apply_to:
      - power_sweep_analysis
      - fit

This would result in a power saturation curve (EPR signal amplitude as a function of the square root of the microwave power, the latter usually in mW), and a linear fit covering in this case the first five data points.

Changed in version 0.5.2: rename class to reflect the processing

static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Extracting the EPR signal amplitude as function of the microwave power can only be applied to 2D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

class cwepr.analysis.AmplitudeVsPower

Bases: AmplitudeVsSqrtPower

Alias to keep the old name and avoid hard breaks.

class cwepr.analysis.FitOnData

Bases: SingleAnalysisStep

Perform polynomial fit on data and return its parameters or a dataset.

Developed tests first.

parameters

All parameters necessary for this step.

pointsint

first n points that should be taken into account

Default: 3

orderint

order of the fit.

Default: 1

return_typestr

Choose to returning the coefficients of the fit in order of increasing degree or a calculated dataset containing the curve to plot.

Default: coefficients.

Valid values: ‘coefficients’, ‘dataset’

fixed_interceptbool

Perform linear regression with fixed intercept, i.e., only fitting the slope.

To change the intercept from the origin, use the parameter offset.

Default: False.

offsetfloat

Vertical offset of the data, i.e. f(0)

Useful in cases where the model defines an intercept f(0) != 0.

Default: 0

Type:

dict

Examples

Some parameters can be chosen here, depending on the purpose and the following analysis and processing steps.

- kind: singleanalysis
  type: FitOnData
  properties:
    parameters:
        points: 5
        order: 2
        return_type: dataset
        fixed_intercept: True
  result: fit

Changed in version 0.3: Rewrite to perform fits with fixed intercept, remove parameter “add_origin”, introduced “fixed_intercept”. Return coefficients in order of increasing degree

static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Polynomial fitting can only be applied to 1D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

class cwepr.analysis.PtpVsModAmp

Bases: SingleAnalysisStep

Create calculated dataset for modulation sweep analysis.

For a modulation sweep analysis, the first step is to get the peak to peak linewidth and correlate it to the modulation amplitude, see Modulation sweep analysis for further details.

Examples

The usage is also quite simple without additional parameters necessary:

- kind: singleanalysis
  type: PtpVsModAmp
  result: calc_dataset
static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Extracting the peak-to-peak linewidth as function of the modulation amplitude can only be applied to 2D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool

class cwepr.analysis.AreaUnderCurve

Bases: SingleAnalysisStep

Make definite integration, i.e. calculate the area under the curve.

Takes no other parameters and returns a single number. However, this step does not (yet) account for baselines or noise thus that the value obtained here is to be taken with care.

Examples

- kind: singleanalysis
  type: AreaUnderCurve
  result: area
static applicable(dataset)

Check whether analysis step is applicable to the given dataset.

Calculating the area can only be applied to 1D datasets.

Parameters:

dataset (aspecd.dataset.Dataset) – Dataset to check

Returns:

applicable – Whether dataset is applicable

Return type:

bool