Difference between revisions of "Deer lib gen.m"

From Spinach Documentation Wiki
Jump to: navigation, search
Line 1: Line 1:
 
{{DISPLAYTITLE:deer_lib_gen.m}}
 
{{DISPLAYTITLE:deer_lib_gen.m}}
−
Generates a library of distance distributions and corresponding simulated DEER traces using the parameters supplied, in a 4 step process:
+
Generates a library of distance distributions and corresponding DEER traces for use in neural network training. Full details are given in our [https://dx.doi.org/10.1126/sciadv.aat5218 paper] on the subject.
−
 
 
−
#The batch of simulated spin label distributions are generated as a randomly selected number of skew normal distributions.
 
−
#:<math>p(r)=\frac{2}{\sigma \sqrt{2 \pi}}e^{- \frac{(r-r_0)^2}{2 \sigma ^2}} \int_{- \infty}^{ \alpha \left (\frac{(r-r_0)}{\sigma} \right )} e^{- \frac{t^2}{2}}dt  </math>
 
−
#The DEER form factor ''d''(''t'') is computed from the distributions using the kernel for DEER in the presence of exchange coupling (Equation 2 in our [https://dx.doi.org/10.1126/sciadv.aat5218 paper]).
 
−
#:<math>\gamma(r,t)=\sqrt{\frac{\pi}{6Dt}} \left [ cos [(D+J)t]FrC \left [ \sqrt{\frac{6Dt}{\pi}} \right ] + sin [(D+J)t]FrS \left [ \sqrt{\frac{6Dt}{\pi}} \right ] \right ] </math>
 
−
#Simulated background, ''b''(''t'') and additive noise tracks ''n''(''t'') are mixed with the DEER form factor;
 
−
#:<math>s(t)=[1-\lambda+\lambda d (t)]b(t)+n(t) </math>
 
−
#*the background signal is generated as a stretched exponential function,
 
−
#:<math>b(t)=exp \left [ -(kt)^{n/3} \right ]  </math>
 
−
#*the noise track is uncorrelated, representing the instrumental noise expected during the indirect acquisition in the DEER method.
 
−
#The distance distributions and DEER traces are then scaled to the neural network activation range:
 
−
#*distributions are uniformly scaled to 0.75,
 
−
#*DEER trace are scaled and shifted to make the first and last points equal to 1 and 0 respectively.
 
−
 
 
−
For each pair in the training set the variables controlling the shape of the distance distribution; the amount of exchange coupling to include; the form of the background contribution to the signal; and the level of noise are randomly selected from the ranges provided in the [[Neural network module#Training parameters structure|parameters]] structure.
 
  
 
==Syntax==
 
==Syntax==
  
−
     deer_lib_gen(file_name,parameters)
+
     [time_grid,dist_grid,dist_distr_lib,...
−
 
+
      deer_ffact_lib,background_lib,deer_trace_lib,...
−
    [output arguments]=deer_lib_gen(file_name,parameters)
+
      noise_line_lib,exchange_lib,parameters]=deer_lib_gen(file_name,parameters)
  
 
==Arguments==
 
==Arguments==
−
 
+
Required fields of the parameters.* structure:
−
    file_name      - name of output *.mat file, include
+
−
    a full path to specify the output
+
    min_dist          - lower limit of distance distributions,
−
      location.      
+
                        Angstrom
−
 
+
−
    parameters     - training set parameters, with fields
+
    max_dist          - upper limit of distance distributions,
−
    described [[Neural network module#Training parameters structure|here]].
+
                        Angstrom
 +
 +
    max_time          - DEER trace duration, seconds
 +
 +
    max_exch          - maximum exchange coupling, MHz
 +
                        (NMR convention)
 +
 +
    min_exch          - minimum exchange coupling, MHz
 +
                        (NMR convention)
 +
 +
    ntraces          - number of traces you wish to generate
 +
 +
    ndistmax          - maximum number of skewed gaussians
 +
                        in the distance distribution
 +
 +
    npoints          - number of digitisation points in the
 +
                        DEER trace and the distance distribu-
 +
                        tion
 +
 +
    noise_lvl        - RMS noise level as a fraction of the
 +
                        modulation depth
 +
 +
    min_fwhm          - minimum FWHM for a skewed gaussian in
 +
                        the distance distribution, fraction of
 +
                        distance
 +
 +
    max_fwhm          - maximum FWHM for a skewed gaussian in
 +
                        the distance distribution, fraction of
 +
                        distance
 +
 +
    min_skew          - minimum shape parameter for a skewed
 +
                        gaussian in the distance distribution
 +
 +
    max_skew          - maximum shape parameter for a skewed
 +
                        gaussian in the distance distribution
 +
 +
    max_mdep          - minimum DEER modulation depth
 +
 +
    min_mdep          - maximum DEER modulation depth
 +
 +
    max_brate        - maximum background signal decay
 +
                        rate, s^-1
 +
 +
     min_brate        - minimum background signal decay
 +
                        rate, s^-1
 +
 +
    min_bdim          - minimum background dimensionality
 +
 +
    max_bdim          - maximum background dimensionality
  
 
==Outputs==
 
==Outputs==
−
The function output arguments are listed below, in the order expected:
 
  
−
    time_grid     - the time axis for the DEER traces, in
+
    time_grid         - time grid (seconds) as a row vector
−
    seconds. A row vector.
 
 
   
 
   
−
    dist_grid     - distance grid for the distributions,
+
    dist_grid         - distance grid (Angsrom) as a row vector
−
    in Angstroms. A row vetor.
 
 
   
 
   
−
    dist_distr_lib - all distance distributions, a horizontal
+
    dist_distr_lib   - all distance distributions as a horizonal
−
    array of column vectors.
+
                        stack of row vectors
 
   
 
   
−
    deer_ffact_lib - all DEER form factors, a horizontal
+
    deer_ffact_lib   - all DEER form factors as a horizonal
−
    array of column vectors.
+
                        stack of row vectors
 
   
 
   
−
    background_lib - all background signals, a horizontal
+
    background_lib   - all background signals as a horizonal
−
    array of column vectors.
+
                        stack of row vectors, shifted and scaled
 +
                        to match DEER traces
 
   
 
   
−
    deer_trace_lib - all primary DEER traces, a horizontal
+
    deer_trace_lib   - all complete DEER traces as a horizonal
−
    array of column vectors.
+
                        stack of row vectors
−
         
 
−
    noise_line_lib - all noise tracks, a horizontal array
 
−
                      of column vectors.
 
 
   
 
   
−
     exchange_lib  - exchange coupling scalar used to in
+
    noise_line_lib    - all noise tracks as a horizonal
−
    generating each trace, a row vector.
+
                        stack of row vectors
 +
 
 +
    exchange_lib     - exchange interaction (MHz), a row vector
 +
                        conataining the value for each example
 
   
 
   
−
    parameters     - the parameters structure, unchanged.
+
    parameters       - parameters array as received
−
 
 
−
The function may be called with a specified file name (including a full path), in which case the output arguments are also saved in a .mat file at that location. If the file name input is left empty then the database is not saved.           
 
  
−
        file_name=[];
+
If a file name is provided, these variables are written into that file.
  
 
==Examples==
 
==Examples==

Revision as of 16:23, 22 August 2018

Generates a library of distance distributions and corresponding DEER traces for use in neural network training. Full details are given in our paper on the subject.

Syntax

    [time_grid,dist_grid,dist_distr_lib,...
     deer_ffact_lib,background_lib,deer_trace_lib,...
     noise_line_lib,exchange_lib,parameters]=deer_lib_gen(file_name,parameters)

Arguments

Required fields of the parameters.* structure: 

   min_dist          - lower limit of distance distributions, 
                       Angstrom

   max_dist          - upper limit of distance distributions, 
                       Angstrom

   max_time          - DEER trace duration, seconds

   max_exch          - maximum exchange coupling, MHz
                       (NMR convention)

   min_exch          - minimum exchange coupling, MHz
                       (NMR convention)

   ntraces           - number of traces you wish to generate

   ndistmax          - maximum number of skewed gaussians 
                       in the distance distribution

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

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

   min_fwhm          - minimum FWHM for a skewed gaussian in
                       the distance distribution, fraction of
                       distance

   max_fwhm          - maximum FWHM for a skewed gaussian in
                       the distance distribution, fraction of
                       distance

   min_skew          - minimum shape parameter for a skewed 
                       gaussian in the distance distribution

   max_skew          - maximum shape parameter for a skewed 
                       gaussian in the distance distribution

   max_mdep          - minimum DEER modulation depth

   min_mdep          - maximum DEER modulation depth

   max_brate         - maximum background signal decay
                       rate, s^-1

   min_brate         - minimum background signal decay 
                       rate, s^-1

   min_bdim          - minimum background dimensionality

   max_bdim          - maximum background dimensionality

Outputs

   time_grid         - time grid (seconds) as a row vector

   dist_grid         - distance grid (Angsrom) as a row vector

   dist_distr_lib    - all distance distributions as a horizonal 
                       stack of row vectors

   deer_ffact_lib    - all DEER form factors as a horizonal 
                       stack of row vectors

   background_lib    - all background signals as a horizonal 
                       stack of row vectors, shifted and scaled
                       to match DEER traces

   deer_trace_lib    - all complete DEER traces as a horizonal 
                       stack of row vectors

   noise_line_lib    - all noise tracks as a horizonal 
                       stack of row vectors
 
   exchange_lib      - exchange interaction (MHz), a row vector
                       conataining the value for each example

   parameters        - parameters array as received

If a file name is provided, these variables are written into that file.

Examples

The example below first loads the netset parameters from the ensemble optimised for all peak widths, and then generates a library of 1000 trace/distribution pairs. The example may be run from the examples/deernet/ directory. 

	% Load the training set parameters
	run('net_set_any_peaks/netset_params.m'); 

	% Specify number of traces to produce
	parameters.ntraces=1000;

	% Set the training database name
	file_name='dlg_example_set.mat';

	% Generate the training library
	[time_grid,dist_grid,dist_distr_lib,...
 	deer_ffact_lib,background_lib,deer_trace_lib,...
 	noise_line_lib,exchange_lib,parameters]=deer_lib_gen(file_name,parameters);

This example will add the output libraries to the MATLAB workspace, as well as saving them in the working directory as "dlg_example_set.mat"

  • Example distance distribution.

  • DEER trace and components for example distribution.

Notes

  • As the dipolar modulation frequency is a cubic function of the inter-spin distance, a scaling relationship exists betweent the distance range and the duration of the DEER signal.

\[\frac{t_A}{r_A^3}=\frac{t_B}{r_B^3} \]

  • An important factor when generating data for training is the dynamic range - the ratio between the longest and shortest distances represented in the training set.
  • The training set DEER traces should be sufficiently discretised (parameters.npoints) to reproduce all frequencies present.

See also

netset_curate.m, train_one_net.m


Version 2.2, authors: Ilya Kuprov, Steve Worswick, Gunnar Jeschke

Retrieved from "https://spindynamics.org/wiki/index.php?title=Deer_lib_gen.m&oldid=3323"