Difference between revisions of "Deer lib gen.m"

From Spinach Documentation Wiki
Jump to: navigation, search
(Update function See also links and function index membership)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:deer_lib_gen.m}} __NOTOC__
 
{{DISPLAYTITLE:deer_lib_gen.m}} __NOTOC__
−
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.
+
Generates a library of distance distributions and corresponding DEER or RIDME traces for use in neural network training. Full details are given in our papers on the subject:
 +
 
 +
                https://doi.org/10.1126/sciadv.aat5218
 +
                https://doi.org/10.1073/pnas.2016917118
 +
                https://doi.org/10.1016/j.jmr.2022.107186
  
 
==Syntax==
 
==Syntax==
  
−
     [time_grid,dist_grid,dist_distr_lib,...
+
     library=deer_lib_gen(file_name,parameters)
−
      deer_ffact_lib,background_lib,deer_trace_lib,...
 
−
      deer_clean_lib,exchange_lib,parameters]=deer_lib_gen(file_name,parameters)
 
  
−
==Arguments==
+
==Parameters==
 
Required fields of the parameters.* structure:
 
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_time          - DEER trace duration, seconds
 
   
 
   
−
     max_exch          - maximum exchange coupling, MHz
+
     max_exch          - maximum exchange coupling, fraction of
−
                         (NMR convention)
+
                         the maximum frequency representable on
 +
                        the current time discretisation grid
 
   
 
   
−
     min_exch         - minimum exchange coupling, MHz
+
     max_exch         - minimum exchange coupling, fraction of
−
                         (NMR convention)
+
                         the maximum frequency representable on
 +
                        the current time discretisation grid
 
   
 
   
 
     ntraces          - number of traces you wish to generate
 
     ntraces          - number of traces you wish to generate
Line 30: Line 28:
 
                         in the distance distribution
 
                         in the distance distribution
 
   
 
   
−
     npoints           - number of digitisation points in the
+
     np_time           - number of digitisation points in the
−
                         DEER trace and the distance distribu-
+
                         DEER trace
−
                         tion
+
 +
    np_dist          - number of digitisation points in the
 +
                         distance distribution
 
   
 
   
−
     noise_lvl        - RMS noise level as a fraction of the
+
    npt_acq          - number of digitization points actually
−
                        modulation depth
+
                        acquired in a sparsely sampled dataset;
 +
                        points are distributed randomly with
 +
                        uniform sampling probability
 +
 +
     noise_lvl        - maximum RMS noise level as a fraction
 +
                        of the modulation depth (min is zero)
 
   
 
   
 
     min_fwhm          - minimum FWHM for a gaussian in the dis-
 
     min_fwhm          - minimum FWHM for a gaussian in the dis-
Line 47: Line 52:
 
   
 
   
 
     min_mdep          - maximum DEER modulation depth
 
     min_mdep          - maximum DEER modulation depth
 +
 +
    expt              - background model, 'deer' or 'ridme'
 
   
 
   
 
     max_brate        - maximum background signal decay
 
     max_brate        - maximum background signal decay
−
                         rate, s^-1
+
                         rate, s^-1 (DEER backgrounds only)
 
   
 
   
 
     min_brate        - minimum background signal decay  
 
     min_brate        - minimum background signal decay  
−
                         rate, s^-1
+
                         rate, s^-1 (DEER backgrounds only)
 
   
 
   
 
     min_bdim          - minimum background dimensionality
 
     min_bdim          - minimum background dimensionality
 +
                        (DEER backgrounds only)
 
   
 
   
 
     max_bdim          - maximum background dimensionality
 
     max_bdim          - maximum background dimensionality
 +
                        (DEER backgrounds only)
 +
 +
    max_tshift        - maximum number of time discretisation
 +
                        points to shift the trace by, either
 +
                        forward or backward
  
 
==Outputs==
 
==Outputs==
 +
The function returns library.* structure with the following fields:
  
 
     time_grid        - time grid (seconds) as a row vector
 
     time_grid        - time grid (seconds) as a row vector
Line 64: Line 78:
 
     dist_grid        - distance grid (Angsrom) as a row vector
 
     dist_grid        - distance grid (Angsrom) as a row vector
 
   
 
   
−
     dist_distr_lib    - all distance distributions as a horizonal
+
     dist_distr_lib    - all distance distributions as a horizon-
−
                        stack of row vectors
+
                         tal stack of column vectors
−
 
−
    deer_ffact_lib    - all DEER form factors as a horizonal
 
−
                         stack of row vectors
 
 
   
 
   
 
     background_lib    - all background signals as a horizonal  
 
     background_lib    - all background signals as a horizonal  
−
                         stack of row vectors, shifted and scaled
+
                         stack of column vectors, shifted and  
−
                         to match DEER traces
+
                         scaled to match DEER/RIDME traces
 
   
 
   
−
     deer_trace_lib   - all complete DEER traces as a horizonal
+
     deer_noisy_lib   - all complete DEER/RIDME traces as a  
−
                         stack of row vectors
+
                         horizonal stack of column vectors
 
   
 
   
 
     deer_clean_lib    - DEER traces as they would come out, but
 
     deer_clean_lib    - DEER traces as they would come out, but
−
                         without the noise
+
                         without the noise; horizonal stack of
−
 
+
                        column vectors
 +
 
     exchange_lib      - exchange interaction (MHz), a row vector
 
     exchange_lib      - exchange interaction (MHz), a row vector
−
                         conataining the value for each example
+
                         containing the value for each example
 
   
 
   
 
     parameters        - parameters array as received
 
     parameters        - parameters array as received
Line 88: Line 100:
  
 
==Examples==
 
==Examples==
−
The example below loads the parameters from one of the example files and generates a library of 1000 DEER traces.
+
The example below generates a library of 1000 DEER traces.
  
−
% Load the training set parameters
+
        % Load default parameters
−
netset_params;  
+
        parameters=library_dd;
 +
 +
        % Number of traces
 +
        parameters.ntraces=1000;
 
   
 
   
−
% Specify number of traces to produce
+
        % Time and distance point counts
−
parameters.ntraces=1000;
+
        parameters.np_time=512;
 +
        parameters.np_dist=512;
 
   
 
   
−
% Set the training database name
+
        % PDS experiment type
−
file_name='dlg_example_set.mat';
+
        parameters.expt='deer';
 
   
 
   
−
% Generate the training library
+
        % Generate the training library
−
[time_grid,dist_grid,dist_distr_lib,...
+
        library=deer_lib_gen([],parameters);
−
        deer_ffact_lib,background_lib,deer_trace_lib,...
 
−
        deer_clean_lib,exchange_lib,parameters]=deer_lib_gen(file_name,parameters)
 
  
 
One of the resulting DEER traces is shown below.
 
One of the resulting DEER traces is shown below.
Line 112: Line 126:
  
 
==Notes==
 
==Notes==
−
Multiple caveats exist in the training process. Please read our [https://dx.doi.org/10.1126/sciadv.aat5218 paper] carefully before training your own networks.
+
Multiple caveats exist in the training process. Please read our papers carefully before training your own networks.
  
 
==See also==
 
==See also==
−
[[Neural network module]]
+
[[deernet.m]], [[dist_range.m]], [[elexsys2deernet.m]], [[process_using.m]], [[train_one_net.m]], [[Neural network module]], [[Built-in_experiments]]
−
 
 
−
[[Built-in_experiments#DEER.2FPELDOR_experiments|DEER/PELDOR experiments]]
 
−
 
 
  
−
''Version 2.5, authors: [[Ilya Kuprov]], [[Steve Worswick]], [[Jake Keeley]], [[Gunnar Jeschke]]''
+
''Version 2.8, authors: [[Ilya Kuprov]], [[Steve Worswick]], [[Jake Keeley]], [[Gunnar Jeschke]]''

Latest revision as of 19:35, 6 June 2026

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

               https://doi.org/10.1126/sciadv.aat5218
               https://doi.org/10.1073/pnas.2016917118
               https://doi.org/10.1016/j.jmr.2022.107186

Syntax

    library=deer_lib_gen(file_name,parameters)

Parameters

Required fields of the parameters.* structure: 

   max_time          - DEER trace duration, seconds

   max_exch          - maximum exchange coupling, fraction of
                       the maximum frequency representable on
                       the current time discretisation grid

   max_exch          - minimum exchange coupling, fraction of
                       the maximum frequency representable on
                       the current time discretisation grid

   ntraces           - number of traces you wish to generate

   ndistmax          - maximum number of skewed gaussians 
                       in the distance distribution

   np_time           - number of digitisation points in the
                       DEER trace

   np_dist           - number of digitisation points in the
                       distance distribution

   npt_acq           - number of digitization points actually
                       acquired in a sparsely sampled dataset;
                       points are distributed randomly with
                       uniform sampling probability

   noise_lvl         - maximum RMS noise level as a fraction
                       of the modulation depth (min is zero)

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

   max_fwhm          - maximum FWHM for a gaussian in the dis-
                       tance distribution, fraction of distance
                       range

   max_mdep          - minimum DEER modulation depth

   min_mdep          - maximum DEER modulation depth

   expt              - background model, 'deer' or 'ridme'

   max_brate         - maximum background signal decay
                       rate, s^-1 (DEER backgrounds only)

   min_brate         - minimum background signal decay 
                       rate, s^-1 (DEER backgrounds only)

   min_bdim          - minimum background dimensionality
                       (DEER backgrounds only)

   max_bdim          - maximum background dimensionality
                       (DEER backgrounds only)

   max_tshift        - maximum number of time discretisation
                       points to shift the trace by, either
                       forward or backward

Outputs

The function returns library.* structure with the following fields: 

   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 horizon-
                       tal stack of column vectors

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

   deer_noisy_lib    - all complete DEER/RIDME traces as a 
                       horizonal stack of column vectors

   deer_clean_lib    - DEER traces as they would come out, but
                       without the noise; horizonal stack of 
                       column vectors

   exchange_lib      - exchange interaction (MHz), a row vector
                       containing 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 generates a library of 1000 DEER traces. 

       % Load default parameters
       parameters=library_dd; 

       % Number of traces
       parameters.ntraces=1000;

       % Time and distance point counts
       parameters.np_time=512;
       parameters.np_dist=512;

       % PDS experiment type
       parameters.expt='deer';

       % Generate the training library
       library=deer_lib_gen([],parameters);

One of the resulting DEER traces is shown below.

  • Distance distribution.

  • DEER trace and its components.

Notes

Multiple caveats exist in the training process. Please read our papers carefully before training your own networks.

See also

deernet.m, dist_range.m, elexsys2deernet.m, process_using.m, train_one_net.m, Neural network module, Built-in_experiments

Version 2.8, authors: Ilya Kuprov, Steve Worswick, Jake Keeley, Gunnar Jeschke

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