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)
Arguments
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
Version 2.8, authors: Ilya Kuprov, Steve Worswick, Gunnar Jeschke, Jake Keeley, Tajwar Choudhury