Difference between revisions of "Tutorial for adding relaxation dispersion models to relax"

From relax wiki
Jump to navigation Jump to search
(→‎Reference commits: Added the 'MQ NQ CPMG 2-site' model to the 'Adding the model to the list' section.)
m (Fix for the mail archive link.)
(43 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Introduction =
+
{{tip|See the [http://www.nmr-relax.com/mail.gna.org/public/relax-devel/2013-06/msg00016.html mail archive] for the original post.}}
See the [https://mail.gna.org/public/relax-devel/2013-06/msg00016.html mail archive] for the original post.
 
  
The following is a tutorial for adding new relaxation dispersion models for either CPMG-type or R1rho-type experiments to relax.  This includes both the models based on the analytic, closed-form expressions as well as the models involving numeric solutions of the Bloch-McConnell equations.
+
The following is a tutorial for adding new relaxation dispersion models for either CPMG-type or {{:R1rho}}-type experiments to the software relax.  This includes both the models based on the analytic, closed-form expressions as well as the models involving numeric solutions of the Bloch-McConnell equations.
  
 
The tutorial will follow the example of the addition of the models already present within relax, pointing to the relevant commits for reference.  To see the commit message and the code changes in colour, click on the links found within these commit messages.  The models in the reference commits sections are in reverse chronological order and therefore the top links will be the most recent and relevant.
 
The tutorial will follow the example of the addition of the models already present within relax, pointing to the relevant commits for reference.  To see the commit message and the code changes in colour, click on the links found within these commit messages.  The models in the reference commits sections are in reverse chronological order and therefore the top links will be the most recent and relevant.
 +
  
 
== The test suite ==
 
== The test suite ==
Line 10: Line 10:
 
This step is normally performed first.  This is the most important part that makes sure that the code not only works now, but will continue working for the entire lifetime of the relax project.
 
This step is normally performed first.  This is the most important part that makes sure that the code not only works now, but will continue working for the entire lifetime of the relax project.
  
The idea is that real or synthetic data, for example as Sparky peak lists, is obtained or created for the model and added to the test suite directory test_suite/shared_data/dispersion/.  This is then used in a system test to check that the code in relax can consistently reproduce the results.
+
The idea is that real or synthetic data, for example as Sparky peak lists, is obtained or created for the model and added to the test suite directory <code>test_suite/shared_data/dispersion/</code>.  This is then used in a system test to check that the code in relax can consistently reproduce the results.
  
 
=== Synthetic data ===
 
=== Synthetic data ===
Line 18: Line 18:
 
=== Measured data ===
 
=== Measured data ===
  
An alternative is to use real measured relaxation dispersion data.  This data should be added as peak lists containing peak intensities to test_suite/shared_data/dispersion/.  As the real solution cannot be known a priori, the results from relax must be compared to results obtained from another software program (possibly directly from a publication).  The steps required for using such data are:
+
An alternative is to use real measured relaxation dispersion data.  This data should be added as peak lists containing peak intensities to <code>test_suite/shared_data/dispersion/</code>.  As the real solution cannot be known a priori, the results from relax must be compared to results obtained from another software program (possibly directly from a publication).  The steps required for using such data are:
  
 
* Create a new directory name for the test data.
 
* Create a new directory name for the test data.
Line 24: Line 24:
 
* Add the original full peak lists to the directory.
 
* Add the original full peak lists to the directory.
  
* Make truncated versions of these files (ending in _trunc.*) and add these as well.  These will be used for the system test instead of the full data to allow the test to finish in a reasonable amount of time.
+
* Make truncated versions of these files (ending in <code>_trunc.*</code>) and add these as well.  These will be used for the system test instead of the full data to allow the test to finish in a reasonable amount of time.
  
* Add a script which performs the full analysis in relax for the model.  Also a script which performs the analysis using only the R2eff model.  See the '''test_suite/shared_data/dispersion/Hansen/*.py''' scripts for reference - these scripts should be copied to your data directory and modified (using the '''svn cp''' command).  Once the scripts are functional, they can be copied and modified for the truncated data (again using the '''svn cp''' command).
+
* Add a script which performs the full analysis in relax for the model.  Also a script which performs the analysis using only the [[R2eff]] model.  See the <code>test_suite/shared_data/dispersion/Hansen/*.py</code> scripts for reference - these scripts should be copied to your data directory and modified (using the <code>svn cp</code> command).  Once the scripts are functional, they can be copied and modified for the truncated data (again using the <code>svn cp</code> command).
  
* Copy the full analysis script to '''test_suite/system_tests/scripts/relax_disp/''' with an appropriate name (always using the '''svn cp''' command).  This can then be used in a new system test.  Better still, the final save file from the '''r2eff_calc.py''' script for the truncated data can be used to start the script.  This is again to save a lot of computation time in the test.  See the '''test_tp02_data_to_ns_r1rho_2site()''' system test in the '''test_suite/system_tests/relax_disp.py''' file for a template.
+
* Copy the full analysis script to <code>test_suite/system_tests/scripts/relax_disp/</code> with an appropriate name (always using the <code>svn cp</code> command).  This can then be used in a new system test.  Better still, the final save file from the <code>r2eff_calc.py</code> script for the truncated data can be used to start the script.  This is again to save a lot of computation time in the test.  See the <code>test_tp02_data_to_ns_r1rho_2site()</code> system test in the <code>test_suite/system_tests/relax_disp.py</code> file for a template.
  
 
If you are not a relax developer, a [https://gna.org/projects/relax support request] can be [https://gna.org/support/?func=additem&group=relax submitted].  You can attach files and add comments to that request for a relax developer to make the changes for you.
 
If you are not a relax developer, a [https://gna.org/projects/relax support request] can be [https://gna.org/support/?func=additem&group=relax submitted].  You can attach files and add comments to that request for a relax developer to make the changes for you.
Line 34: Line 34:
 
=== Reference commits ===
 
=== Reference commits ===
  
* The [[MQ NQ CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18774 r21018] [http://article.gmane.org/gmane.science.nmr.relax.scm/18775 r21019] [http://article.gmane.org/gmane.science.nmr.relax.scm/18776 r21020] [http://article.gmane.org/gmane.science.nmr.relax.scm/18780 r21024] [http://article.gmane.org/gmane.science.nmr.relax.scm/18784 r21028] [http://article.gmane.org/gmane.science.nmr.relax.scm/18785 r21029] [http://article.gmane.org/gmane.science.nmr.relax.scm/18786 r21030] [http://article.gmane.org/gmane.science.nmr.relax.scm/18787 r21031]
+
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18878 r21122]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18774 r21018] [http://article.gmane.org/gmane.science.nmr.relax.scm/18775 r21019] [http://article.gmane.org/gmane.science.nmr.relax.scm/18776 r21020] [http://article.gmane.org/gmane.science.nmr.relax.scm/18780 r21024] [http://article.gmane.org/gmane.science.nmr.relax.scm/18784 r21028] [http://article.gmane.org/gmane.science.nmr.relax.scm/18785 r21029] [http://article.gmane.org/gmane.science.nmr.relax.scm/18786 r21030] [http://article.gmane.org/gmane.science.nmr.relax.scm/18787 r21031]
 
* The [[TSMFK01]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18538 r20782]
 
* The [[TSMFK01]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18538 r20782]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18485 r20729] [http://article.gmane.org/gmane.science.nmr.relax.scm/18486 r20739] [http://article.gmane.org/gmane.science.nmr.relax.scm/18488 r20732]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18485 r20729] [http://article.gmane.org/gmane.science.nmr.relax.scm/18486 r20739] [http://article.gmane.org/gmane.science.nmr.relax.scm/18488 r20732]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18256 r20500] [http://article.gmane.org/gmane.science.nmr.relax.scm/18293 r20538] [http://article.gmane.org/gmane.science.nmr.relax.scm/18295 r20541] [http://article.gmane.org/gmane.science.nmr.relax.scm/18297 r20537]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18256 r20500] [http://article.gmane.org/gmane.science.nmr.relax.scm/18293 r20538] [http://article.gmane.org/gmane.science.nmr.relax.scm/18295 r20541] [http://article.gmane.org/gmane.science.nmr.relax.scm/18297 r20537]
 
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17647 r19891] [http://article.gmane.org/gmane.science.nmr.relax.scm/17648 r19892] [http://article.gmane.org/gmane.science.nmr.relax.scm/17649 r19893] [http://article.gmane.org/gmane.science.nmr.relax.scm/17662 r19906] [http://article.gmane.org/gmane.science.nmr.relax.scm/17663 r19907]
 
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17647 r19891] [http://article.gmane.org/gmane.science.nmr.relax.scm/17648 r19892] [http://article.gmane.org/gmane.science.nmr.relax.scm/17649 r19893] [http://article.gmane.org/gmane.science.nmr.relax.scm/17662 r19906] [http://article.gmane.org/gmane.science.nmr.relax.scm/17663 r19907]
 +
 +
== Creating a new experiment type ==
 +
 +
If the model being added is for a completely new data type, then support for this must be added.  In almost all cases, the experiment type will already be supported.
 +
 +
=== Reference commits ===
 +
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18814 r21058] [http://article.gmane.org/gmane.science.nmr.relax.scm/18816 r21060] [http://article.gmane.org/gmane.science.nmr.relax.scm/18817 r21061] [http://article.gmane.org/gmane.science.nmr.relax.scm/18819 r21063] [http://article.gmane.org/gmane.science.nmr.relax.scm/18820 r21064]
 +
  
 
== Adding the model to the list ==
 
== Adding the model to the list ==
  
Firstly the model should be added to the lists of the specific_analyses.relax_disp.variables module.  The model name is stored in a special variable which will be used throughout relax.
+
Firstly the model should be added to the lists of the <code>specific_analyses.relax_disp.variables</code> module.  The model name is stored in a special variable which will be used throughout relax.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
* The [[MQ NQ CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18788 r21032]
+
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18879 r21123]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18788 r21032]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18477 r20721]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18477 r20721]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18239 r20483]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18239 r20483]
Line 56: Line 67:
 
== The relax_disp.select_model user function front end ==
 
== The relax_disp.select_model user function front end ==
  
The next step is to add the model, its description, the equations for the analytic models, and all references to the relax_disp.select_model user function front end. When the relaxation dispersion chapter of the relax [[manual]] is created (this will be the docs/latex/relax_disp.tex file), then the same description should be added there as well.
+
The next step is to add the model, its description, the equations for the analytic models, and all references to the {{uf|relax_disp.select_model}} user function front end.
 +
 
  
 
=== Reference commits ===
 
=== Reference commits ===
  
 +
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18880 r21124]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18791 r21035]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18478 r20722]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18478 r20722]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18240 r20484]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18240 r20484]
Line 68: Line 82:
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17568 r19812]
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17568 r19812]
  
== The relax library ==
+
== The relax_disp.select_model user function back end ==
  
Now the dispersion function needs to be added to the relax library (in the lib.relax_disp package).  This should be designed as a simple Python function which takes the dispersion parameters and experimental variables, and calculates the R2eff/R1rho values.  The module can contain auxiliary functions for the calculation.  Some auxiliary functions, if not specific to relaxation dispersion, may be better placed in other locations within the relax library.
+
Now the back end of the {{uf|relax_disp.select_model}} user function for the model can be added.  This involved identifying the model and constructing the parameter list.
  
The relaxation dispersion functions in the library currently take as an argument a data structure for the back-calculated R2eff/R1rho values and populate this structure.  This design is not essential if the target function, described in the next point, handles the library function appropriately.  Just look at the files in lib/dispersion to get an idea of the design used.
+
=== Reference commits ===
  
The dispersion code in the relax library must be robust. This involves identifying parameter values or combinations which would cause failures in the mathematical operations (numerical issues not present in the mathematics must be considered). Note that parameter values of 0 are common within a grid search. It should be decided if the R2eff/R1rho value should be set to zero, to another value, or to something large (e.g. 1e100). For example:
+
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18881 r21125]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18811 r21055]
 +
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18482 r20726]
 +
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18249 r20493]
 +
* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17758 r20002]
 +
* The [[M61 skew]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17732 r19976]
 +
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17622 r19866]
 +
* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]
  
Divisions - always catch zeros in the denominator with if statements, even if you believe that this will never be encountered.  Square roots - make sure that the value inside is always > 0.  Trigonometric functions - these should be tested for where they are not defined or where the software implementation can no longer handle certain values.  For example try cosh(1000) in Python.
+
== Adding support for the parameters ==
  
In the reference example, the M61 model code was copied from the LM63 module and modified appropriately.
+
This is needed to enable the model.  It involves modifying many of the modules in the <code>specific_analyses.relax_disp</code> package.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18479 r20723]
+
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18812 r21056]
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18241 r20486] [http://article.gmane.org/gmane.science.nmr.relax.scm/18246 r20490] [http://article.gmane.org/gmane.science.nmr.relax.scm/18280 r20524]
+
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17573 r19817]
* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17756 r20000]
 
* The [[M61 skew]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17729 r19973]
 
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17615 r19859]
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17570 r19814] [http://article.gmane.org/gmane.science.nmr.relax.scm/17572 r19816] [http://article.gmane.org/gmane.science.nmr.relax.scm/17575 r19819] [http://article.gmane.org/gmane.science.nmr.relax.scm/17589 r19833]
 
  
 
== The target function ==
 
== The target function ==
Line 93: Line 110:
 
The target function is used in optimisation and is a class method which takes as a single argument the parameter vector.  This list is changed by the minimisation algorithm during optimisation.  The target function should then return a single floating point number - the chi-squared value.
 
The target function is used in optimisation and is a class method which takes as a single argument the parameter vector.  This list is changed by the minimisation algorithm during optimisation.  The target function should then return a single floating point number - the chi-squared value.
  
Again in this example, the code for the M61 is copied from the LM63 model and then modified.
+
Again in this example, the code for the [[M61]] is copied from the [[LM63]] model and then modified.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
 +
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18882 r21126]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18823 r21067]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18481 r20725]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18481 r20725]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18248 r20492]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18248 r20492]
Line 105: Line 124:
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17571 r19815]
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17571 r19815]
  
== Adding support for the parameters ==
+
== The relax library ==
  
This is needed to enable the model.  This example is for the CR72 model implementation as the parameters required for the M61 model match those of the preexisting LM63 model.
+
Now the dispersion function needs to be added to the relax library (in the <code>lib.relax_disp</code> package).  This should be designed as a simple Python function which takes the dispersion parameters and experimental variables, and calculates the {{:R2eff}}/{{:R1rho}} values.  The module can contain auxiliary functions for the calculation.  Some auxiliary functions, if not specific to relaxation dispersion, may be better placed in other locations within the relax library.  Remember to add all new modules to the <code>lib.relax_disp.__init__</code> package <code>__all__</code> list.
  
=== Reference commits ===
+
The relaxation dispersion functions in the library currently take as an argument a data structure for the back-calculated {{:R2eff}}/{{:R1rho}} values and populate this structure.  This design is not essential if the target function, described in the next point, handles the library function appropriately.  Just look at the files in <code>lib/dispersion</code> to get an idea of the design used.
  
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17573 r19817]
+
The dispersion code in the relax library must be robust.  This involves identifying parameter values or combinations which would cause failures in the mathematical operations (numerical issues not present in the mathematics must be considered). Note that parameter values of 0 are common within a grid search. It should be decided if the {{:R2eff}}/{{:R1rho}} value should be set to zero, to another value, or to something large (e.g. 1e100). For example:
  
== The relax_disp.select_model back end ==
+
Divisions - always catch zeros in the denominator with if statements, even if you believe that this will never be encountered. Square roots - make sure that the value inside is always > 0. Trigonometric functions - these should be tested for where they are not defined or where the software implementation can no longer handle certain valuesFor example try <code>cosh(1000)</code> in Python.
 
 
Now the back end of the relax_disp.select_model user function for the model can be addedThis involved identifying the model and constructing the parameter list.
 
  
 
=== Reference commits ===
 
=== Reference commits ===
  
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18482 r20726]
+
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18883 r21127]
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18249 r20493]
+
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18824 r21068]
* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17758 r20002]
+
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18479 r20723]
* The [[M61 skew]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17732 r19976]
+
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18241 r20486] [http://article.gmane.org/gmane.science.nmr.relax.scm/18246 r20490] [http://article.gmane.org/gmane.science.nmr.relax.scm/18280 r20524]
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17622 r19866]
+
* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17756 r20000]
* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]
+
* The [[M61 skew]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17729 r19973]
 +
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17615 r19859]
 +
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17570 r19814] [http://article.gmane.org/gmane.science.nmr.relax.scm/17572 r19816] [http://article.gmane.org/gmane.science.nmr.relax.scm/17575 r19819] [http://article.gmane.org/gmane.science.nmr.relax.scm/17589 r19833]
  
 
== Comparing to other software ==
 
== Comparing to other software ==
  
It can happen that a bug present in the lib.dispersion package code is also replicated in the synthetic data.  This is not uncommon.  Therefore it is very useful to use other software with the test data from the test-suite step to see if the original parameters can be found.  A good example can be seen in the test_suite/shared_data/dispersion/Hansen which contains Dr. Flemming Hansen's CPMG data (see the README file) and the results from different programs including NESSY, relax, CPMGFit, and ShereKhan.  The comparison is in the file 'software_comparison'.
+
It can happen that a bug present in the <code>lib.dispersion</code> package code is also replicated in the synthetic data.  This is not uncommon.  Therefore it is very useful to use other software with the test data from the test-suite step to see if the original parameters can be found.  A good example can be seen in the <code>test_suite/shared_data/dispersion/Hansen</code> which contains Dr. Flemming Hansen's CPMG data (see the README file) and the results from different programs including NESSY, relax, CPMGFit, and ShereKhan.  The comparison is in the file <code>software_comparison</code>.
  
Once the relax code is able to find identical or better results than the dispersion softwares, then the values found in the test suite optimisation can be locked in.  The assertEqual() and assertAlmostEqual() methods can be used to only allow the test to pass when the correct values are found.
+
Once the relax code is able to find identical or better results than the dispersion softwares, then the values found in the test suite optimisation can be locked in.  The <code>assertEqual()</code> and <code>assertAlmostEqual()</code> methods can be used to only allow the test to pass when the correct values are found.
  
 
== Debugging ==
 
== Debugging ==
  
 
This step should not require an explanation.  It goes hand-in-hand with the test suite and the comparison to other software.
 
This step should not require an explanation.  It goes hand-in-hand with the test suite and the comparison to other software.
 +
  
 
== The auto-analysis ==
 
== The auto-analysis ==
  
The model variable in specific_analyses.relax_disp.variables needs to be imported into the auto_analyses.relax_disp module.  This is then used in the write_results() method to output text files and Grace plots of the parameters.  Be sure that the model variable is added to each part of this method corresponding to the parameters of the model.
+
The model variable in <code>specific_analyses.relax_disp.variables</code> needs to be imported into the <code>auto_analyses.relax_disp</code> module.  This is then used in the <code>write_results()</code> method to output text files and Grace plots of the parameters.  Be sure that the model variable is added to each part of this method corresponding to the parameters of the model.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
 +
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18884 r21128]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18828 r21072]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18527 r20771]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18527 r20771]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18526 r20770]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18526 r20770]
Line 148: Line 170:
 
== The GUI ==
 
== The GUI ==
  
The model needs to also be added to the graphical user interface (GUI).  This is in the gui.analyses.auto_relax_disp module.  The model variable should first be imported.  In the __init__() method, it should be decided if the model should be selected by default or if the user should manually select the model during the analysis.  If the former, then it should be added to the ds.relax_gui.analyses[data_index].disp_models list.
+
The model needs to also be added to the graphical user interface (GUI).  This is in the <code>gui.analyses.auto_relax_disp</code> module.  The model variable should first be imported.  In the <code>__init__()</code> method, it should be decided if the model should be selected by default or if the user should manually select the model during the analysis.  If the former, then it should be added to the <code>ds.relax_gui.analyses[data_index].disp_models</code> list.
  
For the model to be accessible via the GUI, it must be added to the Disp_model_list_cpmg or Disp_model_list_r1rho model list classes (at the bottom of the module).  The model variable should be added to the models list, and the list of parameters added to the params list.
+
For the model to be accessible via the GUI, it must be added to the <code>Disp_model_list_cpmg</code> or <code>Disp_model_list_r1rho</code> model list classes (at the bottom of the module).  The model variable should be added to the models list, and the list of parameters added to the params list.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
 +
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18885 r21129]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18829 r21073]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18511 r20755]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18511 r20755]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18511 r20755]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18511 r20755]
Line 166: Line 190:
 
== The relax manual ==
 
== The relax manual ==
  
The next step is to add the model, its description, the equations for the analytic models, and all references to the relaxation dispersion chapter of the relax [[manual]] (the source is the docs/latex/dispersion.tex file).  The model could also be included in the script section of the chapter.
+
The next step is to add the model, its description, the equations for the analytic models, and all references to the relaxation dispersion chapter of the relax [[manual]] (the source is the <code>docs/latex/dispersion.tex</code> file).  The model could also be included in the script section of the chapter.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
 +
* The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18900 r21144]
 +
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18833 r21077]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18483 r20727]
 
* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18483 r20727]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18242 r20485] [http://article.gmane.org/gmane.science.nmr.relax.scm/18247 r20491] [http://article.gmane.org/gmane.science.nmr.relax.scm/18296 r20540]
 
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18242 r20485] [http://article.gmane.org/gmane.science.nmr.relax.scm/18247 r20491] [http://article.gmane.org/gmane.science.nmr.relax.scm/18296 r20540]
 
* The [[LM63 3-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18165 r20409]
 
* The [[LM63 3-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18165 r20409]
* The [[NS 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18122 r20366]
+
* The [[NS CPMG 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18122 r20366]
* The [[NS 2-site star]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18071 r20315]
+
* The [[NS CPMG 2-site star]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18071 r20315]
 
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18294 r20539]
 
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18294 r20539]
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18077 r20321]
 
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18077 r20321]
Line 180: Line 206:
 
== The sample scripts ==
 
== The sample scripts ==
  
If the added model is to be presented to the user, it should also be added to the sample scripts.  This includes all scripts in the sample_scripts/relax_disp/ directory.  For example it can be included in the MODELS list in the cpmg_analysis.py script.
+
If the added model is to be presented to the user, it should also be added to the sample scripts.  This includes all scripts in the <code>sample_scripts/relax_disp/</code> directory.  For example it can be included in the <code>MODELS</code> list in the <code>cpmg_analysis.py</code> script.
  
 
=== Reference commits ===
 
=== Reference commits ===
  
* The [[NS 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18243 r20488]
+
* The [[NS CPMG 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18243 r20488]
  
 
== See also ==
 
== See also ==
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]
[[Category:Relaxation_dispersion]]
+
[[Category:Relaxation dispersion analysis]]

Revision as of 11:23, 27 October 2017

Tip  See the mail archive for the original post.

The following is a tutorial for adding new relaxation dispersion models for either CPMG-type or R-type experiments to the software relax. This includes both the models based on the analytic, closed-form expressions as well as the models involving numeric solutions of the Bloch-McConnell equations.

The tutorial will follow the example of the addition of the models already present within relax, pointing to the relevant commits for reference. To see the commit message and the code changes in colour, click on the links found within these commit messages. The models in the reference commits sections are in reverse chronological order and therefore the top links will be the most recent and relevant.


The test suite

This step is normally performed first. This is the most important part that makes sure that the code not only works now, but will continue working for the entire lifetime of the relax project.

The idea is that real or synthetic data, for example as Sparky peak lists, is obtained or created for the model and added to the test suite directory test_suite/shared_data/dispersion/. This is then used in a system test to check that the code in relax can consistently reproduce the results.

Synthetic data

It is very important that the code added to the relax library is not used to create the synthetic data! This type of data is useful for checking that the known solution can be found by relax. The only issue is that the same mistake can be made in both relax and the script used to generated the synthetic data, in which case the buggy relax code will never be detected. To mitigate against this, testing against other software is recommended.

Measured data

An alternative is to use real measured relaxation dispersion data. This data should be added as peak lists containing peak intensities to test_suite/shared_data/dispersion/. As the real solution cannot be known a priori, the results from relax must be compared to results obtained from another software program (possibly directly from a publication). The steps required for using such data are:

  • Create a new directory name for the test data.
  • Add the original full peak lists to the directory.
  • Make truncated versions of these files (ending in _trunc.*) and add these as well. These will be used for the system test instead of the full data to allow the test to finish in a reasonable amount of time.
  • Add a script which performs the full analysis in relax for the model. Also a script which performs the analysis using only the R2eff model. See the test_suite/shared_data/dispersion/Hansen/*.py scripts for reference - these scripts should be copied to your data directory and modified (using the svn cp command). Once the scripts are functional, they can be copied and modified for the truncated data (again using the svn cp command).
  • Copy the full analysis script to test_suite/system_tests/scripts/relax_disp/ with an appropriate name (always using the svn cp command). This can then be used in a new system test. Better still, the final save file from the r2eff_calc.py script for the truncated data can be used to start the script. This is again to save a lot of computation time in the test. See the test_tp02_data_to_ns_r1rho_2site() system test in the test_suite/system_tests/relax_disp.py file for a template.

If you are not a relax developer, a support request can be submitted. You can attach files and add comments to that request for a relax developer to make the changes for you.

Reference commits

Creating a new experiment type

If the model being added is for a completely new data type, then support for this must be added. In almost all cases, the experiment type will already be supported.

Reference commits


Adding the model to the list

Firstly the model should be added to the lists of the specific_analyses.relax_disp.variables module. The model name is stored in a special variable which will be used throughout relax.

Reference commits

The relax_disp.select_model user function front end

The next step is to add the model, its description, the equations for the analytic models, and all references to the relax_disp.select_model user function front end.


Reference commits

The relax_disp.select_model user function back end

Now the back end of the relax_disp.select_model user function for the model can be added. This involved identifying the model and constructing the parameter list.

Reference commits

Adding support for the parameters

This is needed to enable the model. It involves modifying many of the modules in the specific_analyses.relax_disp package.

Reference commits

The target function

The target function is used in optimisation and is a class method which takes as a single argument the parameter vector. This list is changed by the minimisation algorithm during optimisation. The target function should then return a single floating point number - the chi-squared value.

Again in this example, the code for the M61 is copied from the LM63 model and then modified.

Reference commits

The relax library

Now the dispersion function needs to be added to the relax library (in the lib.relax_disp package). This should be designed as a simple Python function which takes the dispersion parameters and experimental variables, and calculates the R2,eff/R values. The module can contain auxiliary functions for the calculation. Some auxiliary functions, if not specific to relaxation dispersion, may be better placed in other locations within the relax library. Remember to add all new modules to the lib.relax_disp.__init__ package __all__ list.

The relaxation dispersion functions in the library currently take as an argument a data structure for the back-calculated R2,eff/R values and populate this structure. This design is not essential if the target function, described in the next point, handles the library function appropriately. Just look at the files in lib/dispersion to get an idea of the design used.

The dispersion code in the relax library must be robust. This involves identifying parameter values or combinations which would cause failures in the mathematical operations (numerical issues not present in the mathematics must be considered). Note that parameter values of 0 are common within a grid search. It should be decided if the R2,eff/R value should be set to zero, to another value, or to something large (e.g. 1e100). For example:

Divisions - always catch zeros in the denominator with if statements, even if you believe that this will never be encountered. Square roots - make sure that the value inside is always > 0. Trigonometric functions - these should be tested for where they are not defined or where the software implementation can no longer handle certain values. For example try cosh(1000) in Python.

Reference commits

Comparing to other software

It can happen that a bug present in the lib.dispersion package code is also replicated in the synthetic data. This is not uncommon. Therefore it is very useful to use other software with the test data from the test-suite step to see if the original parameters can be found. A good example can be seen in the test_suite/shared_data/dispersion/Hansen which contains Dr. Flemming Hansen's CPMG data (see the README file) and the results from different programs including NESSY, relax, CPMGFit, and ShereKhan. The comparison is in the file software_comparison.

Once the relax code is able to find identical or better results than the dispersion softwares, then the values found in the test suite optimisation can be locked in. The assertEqual() and assertAlmostEqual() methods can be used to only allow the test to pass when the correct values are found.

Debugging

This step should not require an explanation. It goes hand-in-hand with the test suite and the comparison to other software.


The auto-analysis

The model variable in specific_analyses.relax_disp.variables needs to be imported into the auto_analyses.relax_disp module. This is then used in the write_results() method to output text files and Grace plots of the parameters. Be sure that the model variable is added to each part of this method corresponding to the parameters of the model.

Reference commits

The GUI

The model needs to also be added to the graphical user interface (GUI). This is in the gui.analyses.auto_relax_disp module. The model variable should first be imported. In the __init__() method, it should be decided if the model should be selected by default or if the user should manually select the model during the analysis. If the former, then it should be added to the ds.relax_gui.analyses[data_index].disp_models list.

For the model to be accessible via the GUI, it must be added to the Disp_model_list_cpmg or Disp_model_list_r1rho model list classes (at the bottom of the module). The model variable should be added to the models list, and the list of parameters added to the params list.

Reference commits

The relax manual

The next step is to add the model, its description, the equations for the analytic models, and all references to the relaxation dispersion chapter of the relax manual (the source is the docs/latex/dispersion.tex file). The model could also be included in the script section of the chapter.

Reference commits

The sample scripts

If the added model is to be presented to the user, it should also be added to the sample scripts. This includes all scripts in the sample_scripts/relax_disp/ directory. For example it can be included in the MODELS list in the cpmg_analysis.py script.

Reference commits

See also