Changes

{{tip|See the {{gna mailing list link|url== Tutorial ==[https://mail.gna.org/public/relax-devel/2013-06/msg00016.html See |text=mail archive]message}} for the original post.}}

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 analyticalanalytic, closed-form expressions as well as the models involving numerical numeric solutions of the Bloch-McConnell equations.

The tutorial will follow the example of the addition of the 'M61' model 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. This specific case is The models in the reference commits sections are in reverse chronological order and therefore the top links will be the Meiboom 1961 analytic model for 2-site fast exchange equation for R1rho-type experimentsmost recent and relevant.

=== Adding the model to the list =The test suite ==

Reference commit: This step is normally performed first. http://article.gmane.org/gmane.science.nmr.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 relaxproject.scm/17611

Firstly The idea is that real or synthetic data, for example as Sparky peak lists, is obtained or created for the model should be and added to the lists of the specific_analyses.relax_disp.variables moduletest suite directory <code>test_suite/shared_data/dispersion/</code>. The model name This is stored then used in a special variable which will be used throughout system test to check that the code in relaxcan consistently reproduce the results.

=== 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 relax_disponly 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.select_model user function front end ===

The next step An alternative 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 enduse real measured relaxation dispersion data. When the relaxation This data should be added as peak lists containing peak intensities to <code>test_suite/shared_data/dispersion chapter of the relax [[manual]] is created (this will be the docs/latex</relax_dispcode>.tex file) As the real solution cannot be known a priori, then the same description should results from relax must be added there as wellcompared to results obtained from another software program (possibly directly from a publication). The steps required for using such data are:

Reference commit: http://article* Add the original full peak lists to the directory.gmane.org/gmane.science.nmr.relax.scm/17615

Now the dispersion function needs to be added to the relax library * Make truncated versions of these files (ending in the lib<code>_trunc.relax_disp package*</code>)and add these as well. This should These will be designed as a simple Python function which takes used for the dispersion parameters and experimental variables, and calculates system test instead of the R2eff/R1rho values. The module can contain auxiliary functions for full data to allow the calculation. Some auxiliary functions, if not specific test to relaxation dispersion, may be better placed finish in other locations within the relax librarya reasonable amount of time.

The relaxation dispersion functions * Add a script which performs the full analysis in relax for the library currently take as an argument model. Also a data structure for script which performs the analysis using only the back-calculated [[R2eff]] model. See the <code>test_suite/R1rho values shared_data/dispersion/Hansen/*.py</code> scripts for reference - these scripts should be copied to your data directory and populate this structuremodified (using the <code>svn cp</code> command). This design is not essential if Once the target functionscripts are functional, described in they can be copied and modified for the next point, handles truncated data (again using the library function appropriately. Just look at the files in lib<code>svn cp</dispersion to get an idea of the design usedcode> command).

The dispersion * Copy the full analysis script to <code>test_suite/system_tests/scripts/relax_disp/</code in > with an appropriate name (always using the relax library must be robust<code>svn cp</code> command). This involves identifying parameter values or combinations which would cause failures can then be used in a new system test. Better still, the final save file from the mathematical operations (numerical issues not present in <code>r2eff_calc.py</code> script for the mathematics must truncated data can be considered)used to start the script. Note that parameter values This is again to save a lot of 0 are common within a grid searchcomputation time in the test. It should be decided if See the <code>test_tp02_data_to_ns_r1rho_2site()</code> system test in the R2eff<code>test_suite/R1rho value should be set to zero, to another value, or to something large (esystem_tests/relax_disp.gpy</code> file for a template. 1e100). For example:

Divisions If you are not a relax developer, a [https://sourceforge.net/p/nmr- always catch zeros in the denominator with if statements, even if you believe that this will never relax/tickets-support/ support request] can be encountered[https://sourceforge. Square roots net/p/nmr-relax/tickets- make sure that the value inside is always > 0support/new/ submitted]. Trigonometric functions - these should be tested You can attach files and add comments to that request for where they are not defined or where a relax developer to make the software implementation can no longer handle certain values. For example try cosh(1000) in Pythonchanges for you.

=== The target function =Creating a new experiment type ==

* The target function is used in optimisation and is a class methodwhich takes as a single argument the parameter vector[[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. This list ischanged by the minimisation algorithm during optimisationscience. The targetfunction should then return a single floating point number - thechi-squared valuenmr.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 support for Firstly the parameters ===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 commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17573commits ===

This is needed to enable the * 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 [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18239 r20483]* The [[DPL94]] modelat [http://article.gmane.org/gmane.science. This example is for the CR72nmr.relax.scm/17753 r19997]* The [[M61 skew]] model implementation as the parameters required for the at [http://article.gmane.org/gmane.science.nmr.relax.scm/17724 r19968]* The [[M61 ]] modelat [http://article.gmane.org/gmane.science.nmr.relax.scm/17611 r19855]match those of the preexisting LM63 * The [[No Rex]] modelat [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]

=== 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 back }} user function front end ===.

=== The test suite =relax_disp.select_model user function back end ==

This step is normally performed as step number 1* The [[MQ CR72]] model at [http://article. This is the mostgmane.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]important part that makes sure that the code not only works now, but* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17758 r20002]will continue working for the entire lifetime of the * 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 project.scm/17592 r19836]

The idea is that synthetic data (here == Adding support for example as Sparky peaklists) is created for the model and added to the test suite directorytest_suite/shared_data/dispersion/. This is then used in a systemtest to check that the code in relax can reproduce the data. It isvery important that the code added to the relax library is not used tocreate the synthetic data!parameters ==

=== Comparing to other software Reference commits ===

It can happen that a bug present in the lib* The [[MQ NS CPMG 2-site]] model at [http://article.dispersion package code isalso replicated in the synthetic datagmane.org/gmane.science. This is not uncommonnmr.Therefore it is very useful to use other software with the test datafrom step 7 to see if the original parameters can be foundrelax. A goodscm/18812 r21056]example can be seen in the test_suite* The [[CR72]] model at [http:/shared_data/dispersionarticle.gmane.org/Hansenwhich contains Drgmane.science.nmr. 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'.scm/17573 r19817]

Once the relax code is able to find identical or better results thanthe dispersion softwares, then the values found in the test suiteoptimisation can be locked in. == The assertEqual() andassertAlmostEqual() methods can be used to only allow the test to passwhen the correct values are found.target function ==

=== The auto-analysis =relax library ==

The model variable in specific_analyses.relax_disp.variables Now the dispersion function needs to be imported into added to the relax library (in the auto_analyses<code>lib.relax_disp module</code> package). This is then used in should be designed as a simple Python function which takes the write_results() method to output text files dispersion parameters and experimental variables, and Grace plots of calculates the parameters{{:R2eff}}/{{:R1rho}} values. Be sure that The module can contain auxiliary functions for the model variable is added calculation. Some auxiliary functions, if not specific to relaxation dispersion, may be better placed in other locations within the relax library. Remember to each part of this method corresponding add all new modules to the parameters of the model<code>lib.relax_disp.__init__</code> package <code>__all__</code> list.

=== The GUI ===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 model needs to also Divisions - always catch zeros in the denominator with if statements, even if you believe that this will never be added to the graphical user interface (GUI)encountered. This Square roots - make sure that the value inside is in the gui.analyses.auto_relax_disp modulealways > 0. The model variable Trigonometric functions - these should first be importedtested for where they are not defined or where the software implementation can no longer handle certain values. In the __init__For example try <code>cosh(1000) 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</code> in Python.

=== Reference commits === * The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18883 r21127]* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18824 r21068]* The [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18479 r20723]* 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 [[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] == Comparing to other software == 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 <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 == 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 <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 === * 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 [[NS R1rho 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18526 r20770]* The [[LM63 3-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18183 r20427] [http://article.gmane.org/gmane.science.nmr.relax.scm/18189 r20433] == The GUI == 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 <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 === * 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 [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18511 r20755]* The [[LM63 3-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18212 r20456]* The [[IT99]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17762 r20006]* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17762 r20006]* The [[M61B]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17762 r20006]* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17617 r19861]* The [[R2eff]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17617 r19861]* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836] [http://article.gmane.org/gmane.science.nmr.relax.scm/17617 r19861] == 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 <code>docs/latex/dispersion.tex</code> file). The model could also be included in the script section of the chapter. === 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 [[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 [[NS CPMG 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18122 r20366]* 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 [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18077 r20321] == 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 <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 === * The [[NS CPMG 2-site expanded]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18243 r20488]

[[Category:Relaxation_dispersionRelaxation dispersion analysis]]