Neural network module

DEERNet is a collection of functions that make and use deep neural networks for processing DEER data. The approach is described in detail in https://dx.doi.org/10.1126/sciadv.aat5218

Using DEERNet

Simply feed your DEER data to deernet.m or (better) download DeerAnalysis2018, which is easy to use and has DEERNet integrated.

Training your own networks

1. Use deer_lib_gen.m to build the training database.
2. Use train_one_net.m repeatedly to create a netset.
3. Use netset_curate.m to eliminate low-performance networks.
4. Use the resulting netset with deernet.m or deernet_bckg.m

Functions

deer_lib_gen.m

Generates a library of simulated DEER data for use in neural network training and validation.

deer_resample.m

Resamples a suuplied DEER trace to fit the number of digitsation points expected by the neural network.

deernet.m

Uses a curated ensemble of neural networks to extract a distance distribution from primary DEER data.

elexsys2deernet.m

Prepares standard Bruker Elexsys datasets for input into the deernet.m function.

netset_curate.m

Evaluates an ensemble of neural networks and decides which ones are best.

process_using.m

Runs the DEER data processing using a specified neural network file.

train_one_net.m

Trains a single neural network using supplied parameters.

netset_params.m

Adds the training set and network design parameters for a netset to the MATLAB workspace.

Netset folder structure

A netset is a collection of (typically 100) pre-trained networks that is used to obtain a measure of certainty in DEERNet calculations. Netsets for distance distribution and background signal extraction are supplied with Spinach. Each netset directory must contain a number of *.mat files, numbered sequentially from 1:

	1.mat
	2.mat
	  .
	  . 
	n.mat

The directory must also contain the two supporting files:

	good_nets.mat   - 1 x m cell array (where m < n). The cells 
			  contain character arrays holding the names
			  of the networks selected by the curation
			  process (See: netset_curate.m).

	netset_params.m - function containing the netset training
			  parameters, described here.

Spinach includes four trained and curated ensembles of networks with the architecture shown above. For each ensemble, a set of 100 networks was trained and passed through the curation function to identify the networks with best performance.

• Purely dipolar systems:
  • net_set_any_peaks (26 networks) - trained on the full range of peak widths.
  • net_set_broad_peaks (28 networks) - optimised for broader distributions.
  • net_set_sharp_peaks (21 networks) - optimised for sharper distributions.

• Exchange coupled systems:
  • net_set_with_exch (26 networks) - trained to be resilient to an exchange interaction of ± 5 MHz.

See the netset_params.m function within the relevant directories for detailed ensemble parameters.

Training parameters structure

All fields required in the "parameters" structure used throughout the neural network module are listed below.

Training set parameters:

  parameters.ntraces     - number of traces you wish to generate

  parameters.min_dist    - lower limit of distance distributions, 
                           Angstrom

  parameters.max_dist    - upper limit of distance distributions, 
                           Angstrom

  parameters.max_time    - DEER trace duration, seconds

  parameters.max_exch    - maximum exchange coupling, MHz
                          (NMR convention)

  parameters.min_exch    - minimum exchange coupling, MHz
                          (NMR convention)

  parameters.ndistmax    - maximum number of skewed gaussians 
                           in the distance distribution

  parameters.npoints     - number of digitisation points in the
                           DEER trace and the distance distribu-
                           tion

  parameters.noise_lvl   - RMS noise level as a fraction of the
                           modulation depth

  parameters.min_fwhm    - minimum FWHM for a skewed gaussian in
                           the distance distribution, fraction of
                           distance
 
  parameters.max_fwhm    - maximum FWHM for a skewed gaussian in
                           the distance distribution, fraction of
                           distance
 
  parameters.min_skew    - minimum shape parameter for a skewed 
                           gaussian in the distance distribution

  parameters.max_skew    - maximum shape parameter for a skewed 
                           gaussian in the distance distribution
  
  parameters.max_mdep    - minimum DEER modulation depth

  parameters.min_mdep    - maximum DEER modulation depth

  parameters.max_brate   - maximum background signal decay
                           rate, s^-1
 
  parameters.min_brate   - minimum background signal decay 
                           rate, s^-1
 
  parameters.min_bdim    - minimum background dimensionality
 
  parameters.max_bdim    - maximum background dimensionality

Network design parameters:

  parameters.layer_sizes - number of neurons per layer, expected
			   as a horizontal vector where the number
			   of elements is the number of layers
			   desired.

  parameters.lastlayer   - activation function to use in the 
			   neural network output layer. 

  parameters.method      - neural network training algorithm 
			   selection.