Difference between revisions of "Neural network module"

From Spinach Documentation Wiki
Jump to: navigation, search
(→‎Netset folder structure)
 
(57 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
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
+
__NOTOC__
 +
''DEERNet'' (a separate GitHub repository from Spinach) 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). The reasons why it works so well are analysed in (https://www.pnas.org/content/118/5/e2016917118). Practical guidance is given in (https://doi.org/10.1016/j.jmr.2022.107186).
  
−
==Functions==
+
==Using DEERNet==
 +
Import your data with [[elexsys2deernet.m]] and feed it into [[deernet.m]] - examples are provided in examples/deernet directory. You will get outputs that look like the following:
 +
 
 +
[[File:deernet2_example.png]]
 +
 
 +
==Functions - DEERNet==
 
;[[deer_lib_gen.m]]
 
;[[deer_lib_gen.m]]
 
:Generates a library of simulated DEER data for use in neural network training and validation.
 
: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]]
 
;[[deernet.m]]
−
:Uses a curated ensemble of neural networks to extract a distance distribution from primary DEER data.
+
:Uses an ensemble of neural networks to extract distance distributions from DEER data.
 +
;[[dist_range.m]]
 +
:Distance range estimation for a given time grid.
 
;[[elexsys2deernet.m]]
 
;[[elexsys2deernet.m]]
 
:Prepares standard Bruker Elexsys datasets for input into the [[deernet.m]] function.
 
: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]]
 
;[[process_using.m]]
−
:Runs the DEER data processing using a specified neural network file.
+
:Runs DEER data processing using a specified neural network file.
 
;[[train_one_net.m]]
 
;[[train_one_net.m]]
 
:Trains a single neural network using supplied parameters.
 
: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 [[netset_params.m|here]].
 
−
 
−
[[File:ann_diagram_deernet.PNG|750x97px|DEERNet neural network architecture]]
 
−
 
−
''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 [[netset_curate.m|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:'''
+
==Functions - descrambling==
 +
;[[descramble.m]]
 +
:Weight matrix descrambling using Tikhonov smoothness criterion.
 +
;[[left_diag.m]]
 +
:Weight matrix descrambling using maximum diagonality criterion.
  
−
  parameters.ntraces    - number of traces you wish to generate
+
==Custom layers and networks==
 +
;[[dist_net.m]]
 +
:Returns an untrained distance distribution DEERNet for processing fully sampled data.
 +
;[[dist_vet.m]]
 +
:Returns an untrained distance distribution DEERNet for processing sparsely sampled data.
 +
;[[logsLayer.m]]
 +
:Logsigmoidal activation function layer.
 +
;[[renormLayer.m]]
 +
:Renormalisation layer for probability distributions.
  
−
  parameters.min_dist    - lower limit of distance distributions,
+
==Service functions==
−
                            Angstrom
+
;[[DEERDatastore.m]]
−
+
:Infinite datastore of DEER data for spin-1/2 electrons.
−
  parameters.max_dist    - upper limit of distance distributions,
+
;[[deerplot.m]]
−
                            Angstrom
+
:Plotting subsystem of DEERNet.
−
+
;[[library_dd.m]]
−
  parameters.max_time    - DEER trace duration, seconds
+
:Training database parameters for the purely dipolar DEERNet.
−
 
−
  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:'''
+
;[[nonnans.m]]
 +
:Returns the non-NaN elements of a numerical array.
 +
;[[signal_model.m]]
 +
:DEER signal model used for DEERNet and DEERVet back-calculations.
  
−
  parameters.layer_sizes - number of neurons per layer, expected
+
''Version 2.6, authors: [[Ilya Kuprov]], [[Steve Worswick]], [[Jake Amey]], [[Jake Keeley]], [[Tajwar Choudhury]]''
−
  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.
 

Latest revision as of 13:16, 25 April 2026

DEERNet (a separate GitHub repository from Spinach) 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). The reasons why it works so well are analysed in (https://www.pnas.org/content/118/5/e2016917118). Practical guidance is given in (https://doi.org/10.1016/j.jmr.2022.107186).

Using DEERNet

Import your data with elexsys2deernet.m and feed it into deernet.m - examples are provided in examples/deernet directory. You will get outputs that look like the following:

Deernet2 example.png

Functions - DEERNet

deer_lib_gen.m
Generates a library of simulated DEER data for use in neural network training and validation.
deernet.m
Uses an ensemble of neural networks to extract distance distributions from DEER data.
dist_range.m
Distance range estimation for a given time grid.
elexsys2deernet.m
Prepares standard Bruker Elexsys datasets for input into the deernet.m function.
process_using.m
Runs DEER data processing using a specified neural network file.
train_one_net.m
Trains a single neural network using supplied parameters.

Functions - descrambling

descramble.m
Weight matrix descrambling using Tikhonov smoothness criterion.
left_diag.m
Weight matrix descrambling using maximum diagonality criterion.

Custom layers and networks

dist_net.m
Returns an untrained distance distribution DEERNet for processing fully sampled data.
dist_vet.m
Returns an untrained distance distribution DEERNet for processing sparsely sampled data.
logsLayer.m
Logsigmoidal activation function layer.
renormLayer.m
Renormalisation layer for probability distributions.

Service functions

DEERDatastore.m
Infinite datastore of DEER data for spin-1/2 electrons.
deerplot.m
Plotting subsystem of DEERNet.
library_dd.m
Training database parameters for the purely dipolar DEERNet.
nonnans.m
Returns the non-NaN elements of a numerical array.
signal_model.m
DEER signal model used for DEERNet and DEERVet back-calculations.

Version 2.6, authors: Ilya Kuprov, Steve Worswick, Jake Amey, Jake Keeley, Tajwar Choudhury

Retrieved from "https://spindynamics.org/wiki/index.php?title=Neural_network_module&oldid=7495"