deernet.m
Uses pre-trained neural networks to extract background signals, modulation depths, and distance distributions from DEER data. See our papers:
https://doi.org/10.1126/sciadv.aat5218 https://doi.org/10.1073/pnas.2016917118 https://doi.org/10.1016/j.jmr.2022.107186
for further information.
Syntax
dataset=deernet(input_traces,input_axis,options)
Parameters
Required parameters:
input_traces - experimental DEER trace(s), phased into pure absor-
ption and cropped on the left to make the first po-
int correspond to the echo modulation maximum; for
sparsely sampled data, the missing points should be
set to NaN. If multiple traces are supplied as col-
umns of a matrix, they will be processed assuming
common background dimension and decay rate.
input_axis - experimental time axis in seconds, a column vector
that must start at zero, have a uniform time step,
and no NaN elements in it - even when the data is
sparsely sampled
Optional parameters (using new Matlab option syntax, literally as below):
expt='ridme' - requests RIDME type background, the default
is DEER type background function
bg_dim_range=[a b] - constrains background signal dimension to
the interval [a b], default is [3.0,3.5],
the training range was [2.0,3.5]; this op-
tion only applies to expt='deer'.
do_jacobian=true - requests Jacobian calculation; the run time
will become much longer
Outputs
Either a figure (if there are no output parameters), or a data struccture with the following fields:
input_traces - DEER/RIDME trace(s), as supplied by the user
input_axis - time axis, as supplied by the user
ntraces - number of DEER/RIDME traces in the input
nsmpls - number of non-NaN elements in the input DEER
or RIDME trace
net_type - 'net' for uniformly sampled input data, 'vet'
for sparsely sampled input data
resamp_axis - time axis resampled to match DEERNet input dimen-
sion, same as the input time axis for sparsely
sampled inputs; this axis is used by background
and retrocalculation outputs
resamp_traces - DEER/RIDME trace(s) resampled to match DEERNet
input dimensions, same as the input trace for
sparsely sampled inputs
nnets - number of networks in the netset that did the
processing and the statistics
expt - background model selected at input
bg_rates - (DEER only) background decay rate returned by
the retrofit of the data from each network
bg_dims - (DEER only) background dimension returned by
the retrofit of the data from each network
backgs_av - arithmetic mean of the background signal over the
outputs of the networks in the current netset
backgs_lb - 95% confidence interval lower bound for the back-
ground signal obtained from netset statistics
backgs_ub - 95% confidence interval upper bound for the back-
ground signal obtained from netset statistics
retros_av - arithmetic mean of the trace retrofit(s) over the
outputs of the networks in the current netset
retros_lb - 95% confidence interval lower bound for the retrofit
signal obtained from netset statistics
retros_ub - 95% confidence interval upper bound for the retrofit
signal obtained from netset statistics
mdpths_av - arithmetic mean of the modulation depth(s) over the
outputs of the networks in the current netset
mdpths_st - standard deviation of modulation depth predictions
obtained from netset statistics
dist_ax - the distance axis matching the distances distribution
and satisfying the constraints imposed by the timing
of the input signal and the limits of DEERNet
dist_av - arithmetic mean of the distance distributions(s) over
the netset
dist_lb - 95% confidence interval lower bound for the distance
distribution(s) obtained from netset statistics
dist_ub - 95% confidence interval upper bound for the distance
distribution(s) obtained from netset statistics
Examples
First, we load experimental data:
% Load experimental data
[deer_trace,time_axis]=elexsys2deernet('data_deeran/CT_DEER_mix_28_36');
This results in the following console output:
========= DEERNet 2.8 data import from ELEXSYS ========= DTA file: data_deeran/CT_DEER_mix_28_36.DTA DSC file: data_deeran/CT_DEER_mix_28_36.DSC Complex data autophased, phi = 9.2977 degrees: |old_real| = 0.98534, |old_imag| = 0.17063 |new_real| = 0.99841, |new_imag| = 0.056365 Automatic data truncation: signal maximum found at point 40, prior points deleted, time axis shifted to start at zero. ========================================================
The data is then sent to DEERNet:
% Run deernet analysis
deernet(deer_trace,time_axis,expt='deer');
With no output arguments requested in the call to DEERNet, the following plot is produced.
And the following data is printed to the console:
===================== DEERNet 2.8 ====================== Background model: DEER (stretched exponential) DEER BG dimension range: [3,3.5] (default) Kernel type: dd (pure dipole-dipole) Number of traces in the batch: 1 Data sampling: uniform, npts=489, tmax=3.904 us Net layout, expt-(samp)-npts-nout: deer-(512)-512-512 Data resampled from 489 to 512 time points Visible distance range: [11.9167,74.0676] Angstrom Trace 1, modulation depth, average: 0.73493 Trace 1, modulation depth, st.dev.: 0.0061848 Trace 1, (init. ampl.)*MD, average: 5098401.559 Trace 1, (init. ampl.)*MD, st.dev.: 42906.0243 Trace 1, background decay rate (MHz), average: 1.403 Trace 1, background decay rate (MHz), st.dev.: 0.033539 Trace 1, background dimension, average: 3.4436 Trace 1, background dimension, st.dev.: 0.051029
Dozens of further examples are available in examples/deernet folder of Spinach distribution.
Notes
1. Do not supply excessively long baseline tails in the input data - unlike Tikhonov tools, DEERNet does not need those, it works better if you cut off baseline tails.
2. The input DEER trace must be cropped on the left to make the first point of the trace correspond to the maximum.
This is done automatically in elexsys2deernet.m, and this is the only preprocessing required by DEERNet - it can handle background and noise.
3. For non-uniform sampling, the default netset can handle the following combinations of time grids and sampling schedules:
512-point time grid, 128 points sampled
512-point time grid, 64 points sampled
See also
elexsys2deernet.m, deer_lib_gen.m, dist_range.m, process_using.m, train_one_net.m, Neural network module, Built-in_experiments
Version 2.8, authors: Ilya Kuprov, Steve Worswick, Gunnar Jeschke, Jake Keeley, Tajwar Choudhury
