autodeer.DEER_analysis

Module Contents

Functions

calc_identifiability(profile)
find_longest_pulse(sequence)	Finds the longest pulse duration in a given sequence.
MNR_estimate(Vexp, t[, mask])	Estimates the Modulation to Noise Ratio (MNR) of a DEER signal without fitting.
val_in_us(Param)
DEERanalysis(dataset[, compactness, model, ROI, ...])
background_func(t, fit)
calc_correction_factor(fit_result[, aim_MNR, aim_time])	Calculate the correction factor for the number of averages required to achieve a given MNR in a given time.
DEERanalysis_plot(fit, background[, ROI, axs, fig, text])	DEERanalysis_plot Generates a figure showing both the time domain and
DEERanalysis_plot_pub(results[, ROI, fig, axs])	Generates a vertical plot of the DEER analysis results, ready for publication.
IdentifyROI(P, r[, criterion, method])	IdentifyROI Identifies the region of interest. Two methods are sypported
remove_echo(Vre, Vim, loc[, criteria, extent])	This function removes crossing echoes.
shift_pulse_freq(pulse, shift)	Shifts the frequency of a pulse by a given amount.
normalise_01(A)	Normalizes the input vector A to be between 0 and 1.
resample_and_shift_vector(A, f, shift)	Resample the vector A along axis f and shift it by shift and return on original axis f.
build__lowpass_butter_filter(cutoff)	Build a lowpass butterworth filter with a cutoff frequency of cutoff
functional(f_axis, fieldsweep, A, B[, filter, ...])	Functional for optimising the pulse positions
optimise_pulses(Fieldsweep, pump_pulse, exc_pulse[, ...])	Optimise the pulse positions to maximise the pump-exc overlap.
plot_overlap(Fieldsweep, pump_pulse, exc_pulse, ref_pulse)	Plots the pump and excitation profiles as well as the fieldsweep and filter profile.
calc_deer_settings(experiment[, CPdecay, Refocused2D, ...])	Calculates the optimal DEER settings based on the avaliable relaxation data

Attributes

log
MODULE_DIR

autodeer.DEER_analysis.log

autodeer.DEER_analysis.MODULE_DIR

autodeer.DEER_analysis.calc_identifiability(profile)

autodeer.DEER_analysis.find_longest_pulse(sequence)

Finds the longest pulse duration in a given sequence.

Args: sequence (Sequence): The sequence to analyze.

Returns: float: The duration of the longest pulse in microseconds.

autodeer.DEER_analysis.MNR_estimate(Vexp, t, mask=None)

Estimates the Modulation to Noise Ratio (MNR) of a DEER signal without fitting. This is done by applying a low pass filter to remove noise and then finding the peaks in the signal.

Parameters:

Vexpnp.ndarray

The experimental DEER signal, real part only.

tnp.ndarray

The time axis of the DEER signal, in microseconds.

masknp.ndarray, optional

The mask to apply to the data, by default None

Returns:

float

The estimated MNR of the dataset.

autodeer.DEER_analysis.val_in_us(Param)

autodeer.DEER_analysis.DEERanalysis(dataset, compactness=True, model=None, ROI=False, exp_type='5pDEER', verbosity=0, remove_crossing=True, **kwargs)

autodeer.DEER_analysis.background_func(t, fit)

autodeer.DEER_analysis.calc_correction_factor(fit_result, aim_MNR=25, aim_time=2)

Calculate the correction factor for the number of averages required to achieve a given MNR in a given time. Parameters ———- fit_result : Deerlab.FitResult

The fit result from the DEER analysis.

aim_MNRfloat, optional

The desired MNR, by default 25

aim_timefloat, optional

The desired time in hours, by default 2

Returns

float

The correction factor for the number of averages.

autodeer.DEER_analysis.DEERanalysis_plot(fit, background, ROI=None, axs=None, fig=None, text=True)

DEERanalysis_plot Generates a figure showing both the time domain and distance domain data along with extra important infomation such as the Modulation to Noise Ratio (MNR), Region of Interest (ROI) and the recommended dipolar evolution time for future experiments based upon the ROI.

Parameters:

fitDeerlab.FitResult

_description_

backgroundbool

Should the background fit be plotted.

ROItuple, optional

The minimum and maximum of the Region of Interest (ROI), by default None

Returns:

Figure

A Matplotlib Figure object of the figure.

Parameters:

background (bool)

autodeer.DEER_analysis.DEERanalysis_plot_pub(results, ROI=None, fig=None, axs=None)

Generates a vertical plot of the DEER analysis results, ready for publication.

Parameters:

resultsDeerlab.FitResult

The results of the DEER analysis.

ROItuple, optional

The minimum and maximum of the Region of Interest (ROI), by default None

figmatplotlib.figure.Figure, optional

The figure to plot the results on. If None, a new figure is created.

axsmatplotlib.axes.Axes, optional

The axes to plot the results on. If None, a new axes is created.

autodeer.DEER_analysis.IdentifyROI(P, r, criterion=0.99, method='gauss')

IdentifyROI Identifies the region of interest. Two methods are sypported

Methods

1. Gaussian fitting (“gauss”):

2. Intergration (“int”):

Parameters:

Pnp.ndarray

The distance distribution.

rnp.ndarray

The distance axis

criterionfloat, optional

The fraction of the distance distribution that must be in the ROI, by default 0.99

method: str, optional

The method used to calculate region of interest.

Parameters:

• P (numpy.ndarray)

• r (numpy.ndarray)

• criterion (float)

• method (str)

autodeer.DEER_analysis.remove_echo(Vre, Vim, loc, criteria=4, extent=3)

This function removes crossing echoes. Parameters ———- Vre : np.ndarray

The real part of the phase corrected signal.

Vimnp.ndarray

The imaginary part of the phase corrected signal.

locint

The approximate location of the crossing echo, +- 30 data points

criteriafloat, optional

The detection criteria, in multiples of the std deviation, by default 4

extentint, optional

How many data points either side to remove, by default 3.

Returns:

np.ndarray

The mask of points to be ignored.

Parameters:

• Vre (numpy.ndarray)

• Vim (numpy.ndarray)

• loc (int)

• criteria (float)

• extent (int)

Return type:

numpy.ndarray

autodeer.DEER_analysis.shift_pulse_freq(pulse, shift)

Shifts the frequency of a pulse by a given amount.

Args:

pulse: The pulse whose frequency should be shifted. shift: The amount by which to shift the frequency.

Returns:

The pulse with the shifted frequency.

autodeer.DEER_analysis.normalise_01(A)

Normalizes the input vector A to be between 0 and 1.

Parameters: A (numpy.ndarray): Input vector to be normalized.

Returns: numpy.ndarray: Normalized vector between 0 and 1.

autodeer.DEER_analysis.resample_and_shift_vector(A, f, shift)

Resample the vector A along axis f and shift it by shift and return on original axis f.

Parameters: A (numpy.ndarray): The input vector to be resampled and shifted. f (numpy.ndarray): The axis along which to resample the vector. shift (float): The amount by which to shift the resampled vector.

Returns: numpy.ndarray: The resampled and shifted vector.

autodeer.DEER_analysis.build__lowpass_butter_filter(cutoff)

Build a lowpass butterworth filter with a cutoff frequency of cutoff

Args:

cutoff (float): cutoff frequency in GHz

autodeer.DEER_analysis.functional(f_axis, fieldsweep, A, B, filter=None, A_shift=0, B_shift=0)

Functional for optimising the pulse positions

Parameters:

f_axisnp.ndarray

The frequency axis of the field sweep in GHz

fieldsweepad.FieldSweepAnalysis

The FieldSweep analysis object

Anp.ndarray

The pump pulse profile

Bnp.ndarray

The effective excitation pulse profile

filternp.ndarray, optional

The filter profile if applicable, by default None

A_shiftint, optional

The shift in pump pulse in GHz, by default 0

B_shiftint, optional

The shift in effective exciatation pulse in GHz, by default 0

Returns:

_type_

_description_

autodeer.DEER_analysis.optimise_pulses(Fieldsweep, pump_pulse, exc_pulse, ref_pulse=None, filter=None, verbosity=0, method='brute', nDEER=False, num_ref_pulses=2, full_output=False, resonator=None, **kwargs)

Optimise the pulse positions to maximise the pump-exc overlap.

Parameters:

Fieldsweepad.FieldSweepAnalysis

The FieldSweep analysis object

pump_pulsead.Pulse

The pump pulse object

exc_pulsead.Pulse

The excitation pulse object

ref_pulsead.Pulse, optional

The refocusing pulse object, by default None

filterstr or number or list, optional

The filter profile if applicable, by default None. If it is a number a filter is generated with this cutoff frequency. If the string ‘Matched’ is used a matched filter is used. If a list is used the optimisation is performed for each filter and the best is returned.

verbosityint, optional

The verbosity, by default 0

methodstr, optional

What search optimisation is used, by default ‘grid’

nDEERbool, optional

Is the sequence an nDEER sequrence, by default False. If True then the refocusing pulse is not optimised.

num_ref_pulsesint, optional

The total number of refocusing pulses, by default 2

full_outputbool, optional

Return the full output, by default False

resonatorad.ResonatorProfile, optional

The resonator profile, by default None

Returns

——-

ad.Pulse

The optimised pump pulse

ad.Pulse

The optimised excitation pulse

ad.Pulse

The optimised refocusing pulse

str or number

The best filter, only if a list of filters is provided

float

The functional value after optimisation, only if full_output is True

tuple

The grid of the optimisation, only if full_output is True

tuple

The output of the optimisation, only if full_output is True

autodeer.DEER_analysis.plot_overlap(Fieldsweep, pump_pulse, exc_pulse, ref_pulse, filter=None, respro=None, num_ref_pulses=2, axs=None, fig=None)

Plots the pump and excitation profiles as well as the fieldsweep and filter profile.

Parameters:

Fieldsweepad.FieldSweepAnalysis

The FieldSweep analysis object

pump_pulsead.Pulse

The pump pulse object

exc_pulsead.Pulse

The excitation pulse object

ref_pulsead.Pulse, optional

The refocusing pulse object, by default None

filterstr or number, optional

The filter profile if applicable, by default None. If it is a number a filter is generated with this cutoff frequency. If the string ‘Matched’ is used a matched filter is used.

resproad.ResonatorProfileAnalysis, optional

The resonator profile for fitting, by default None. The resonator profile must include the fit.

num_ref_pulsesint, optional

The total number of refocusing pulses, by default 2

axsmatplotlib.axes, optional

The axes to plot on, by default None

figmatplotlib.figure, optional

The figure to plot on, by default None

autodeer.DEER_analysis.calc_deer_settings(experiment, CPdecay=None, Refocused2D=None, target_time=2, target_MNR=20, waveform_precision=2)

Calculates the optimal DEER settings based on the avaliable relaxation data

Parameters:

experimentstr

Type of DEER experiment, either ‘auto’, ‘4pDEER’ or ‘5pDEER’

CPdecayad.CarrPurcellAnalysis

Carr-Purcell relaxation data

Refocused2Dad.RefocusedEcho2DAnalysis, optional

Refocused 2D data required for ‘4pDEER’, by default None

target_timeint, optional

Target time for the DEER experiment in hours, by default 2

target_MNRfloat, optional

Target modulation to noise ratio, by default 20

waveform_precisionint, optional

Precision of the waveform in ns, by default 2

Returns:

dict

DEER settings, with keys:

-‘ExpType’: ‘4pDEER’ or ‘5pDEER’ -‘tau1’: in us -‘tau2’: in us -‘tau3’: in us, only for 5pDEER -‘AimTime’: in hours

Parameters:

experiment (str)

Notes

This function will calcate the optimal DEER settings based on the avaliable relaxation data, depending on the experiment type. For 4pDEER, the optimal tau1 and tau2 are calculated based on the refocused 2D data, and for 5pDEER, the optimal tau2 is calculated based on the CPdecay data or refocused 2D if CP decay data is not availiable. If the optimal tau2 for 5pDEER is less than 1.5us, the function will calculate the optimal tau1 and tau2 for 4pDEER instead. This is only possible if the refocused 2D data is availiable, otherwise a non optimal tau1 of 0.4us is used.