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 ==

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.

=== 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 relax_disp.select_model user function front end ===steps required for using such data are:

Reference commit: http://article* Create a new directory name for the test data.gmane.org/gmane.science.nmr.relax.scm/17612

The next step is to add the model, its description, the equations for * Add the analytic models, and all references original full peak lists 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 welldirectory.

Reference commit: * 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. http:See the <code>test_suite/shared_data/articledispersion/Hansen/*.gmanepy</code> scripts for reference - these scripts should be copied to your data directory and modified (using the <code>svn cp</code> command).org Once the scripts are functional, they can be copied and modified for the truncated data (again using the <code>svn cp</gmane.sciencecode> command).nmr.relax.scm/17615

Now * Copy the dispersion function needs full analysis script to be added to the relax library <code>test_suite/system_tests/scripts/relax_disp/</code> with an appropriate name (in always using the lib.relax_disp package<code>svn cp</code> command). This should can then be designed as used in a simple Python function which takes new system test. Better still, the dispersion parameters and experimental variables, and calculates final save file from the R2eff<code>r2eff_calc.py</R1rho valuescode> script for the truncated data can be used to start the script. The module can contain auxiliary functions for This is again to save a lot of computation time in the calculationtest. Some auxiliary functions, if not specific to relaxation dispersion, may be better placed See the <code>test_tp02_data_to_ns_r1rho_2site()</code> system test in other locations within the relax library<code>test_suite/system_tests/relax_disp.py</code> file for a template.

The relaxation dispersion functions in the library currently take as an argument If you are not a relax developer, a data structure for the back[https://sourceforge.net/p/nmr-relax/tickets-calculated R2effsupport/R1rho values and populate this structuresupport request] can be [https://sourceforge. This design is not essential if the target function, described in the next point, handles the library function appropriatelynet/p/nmr-relax/tickets-support/new/ submitted]. Just look at the You can attach files in lib/dispersion and add comments to that request for a relax developer to get an idea of make the design usedchanges for you.

Divisions * The [[MQ CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18878 r21122]* The [[MQ NS CPMG 2- always catch zeros in the denominator with if statements, even if you believe that this will never be encounteredsite]] model at [http://article.gmane.org/gmane. Square roots 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 [[NS R1rho 2- make sure that the value inside is always > 0site]] model at [http://article.gmane.org/gmane.science.nmr.relax. Trigonometric functions - these should be tested for where they are not defined or where the software implementation can no longer handle certain valuesscm/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 [[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. For example try cosh(1000) in Pythonrelax.scm/17663 r19907]

=== The target function Reference commits ===

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]

The target function is used in optimisation and is a class methodwhich takes as a single argument == Adding the model to the parameter vector. This list ischanged by the minimisation algorithm during optimisation. The targetfunction should then return a single floating point number - thechi-squared value.==

Again in this example, Firstly the code for model should be added to the M61 is copied from lists of the LM63<code>specific_analyses.relax_disp.variables</code> module. The model and then modifiedname is stored in a special variable which will be used throughout relax.

Reference commit: http://article== The relax_disp.gmane.org/gmane.science.nmr.relax.scm/17573select_model user function front end ==

This The next step is needed to enable add the model. This example is for , its description, the CR72model implementation as the parameters required equations for the M61 modelmatch those of analytic models, and all references to the preexisting LM63 model{{uf|relax_disp.select_model}} user function front end.

=== The relax_disp.select_model back end Reference commits ===

Reference commit* 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 [[TP02]] model at [http: //article.gmane.org/gmane.science.nmr.relax.scm/18240 r20484]* The [[DPL94]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17754 r19998]* The [[M61 skew]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17725 r19969]* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17612 r19856]* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/1762217568 r19812]

Now the back end of the == The relax_disp.select_model user function for themodel can be added. This involved identifying the model andconstructing the parameter list.back end ==

=== The test suite Reference commits ===

Reference commits* 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]

This step is normally performed as step number 1needed to enable the model. This is It involves modifying many of the mostimportant part that makes sure that modules in the <code>specific_analyses.relax_disp</code not only works now, butwill continue working for the entire lifetime of the relax project> package.

=== Comparing to other software =The target function ==

It can happen that a bug present The target function is used in the lib.dispersion package code optimisation and isalso replicated in a class method which takes as a single argument the synthetic dataparameter vector. This list is not uncommon.Therefore it is very useful to use other software with the test datafrom step 7 to see if changed by the original parameters can be found. A goodexample can be seen in the test_suite/shared_data/dispersion/Hansenwhich contains Dr. Flemming Hansen's CPMG data (see the README file)and the results from different programs including NESSY, relax,CPMGFit, and ShereKhanminimisation algorithm during optimisation. The comparison is in target function should then return a single floating point number - the file'software_comparison'chi-squared value.

Once Again in this example, the relax code for the [[M61]] is able to find identical or better results thancopied from the dispersion softwares, [[LM63]] model and 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 foundmodified.

=== The autorelaxation dispersion functions in the library currently take as an argument a data structure for the back-analysis ===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 model variable dispersion code in specific_analyses.relax_disp.variables needs to the relax library must be imported into the auto_analyses.relax_disp modulerobust. This is then used involves identifying parameter values or combinations which would cause failures in the write_resultsmathematical operations (numerical issues not present in the mathematics must be considered) method to output text files and Grace plots . Note that parameter values of the parameters0 are common within a grid search. Be sure that It should be decided if the model variable is added {{:R2eff}}/{{:R1rho}} value should be set to each part of this method corresponding zero, to another value, or to the parameters of the modelsomething large (e.g. 1e100). For example:

=== The GUI 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 needs to also be added to the graphical user interface (GUI)at [http://article.gmane.org/gmane. This is in the guiscience.analysesnmr.auto_relax_disp modulerelax. scm/17756 r20000]* The [[M61 skew]] model variable should first be importedat [http://article. In the __init__() method, it should be decided if the gmane.org/gmane.science.nmr.relax.scm/17729 r19973]* The [[M61]] model should be selected by default or if the user should manually select the at [http://article.gmane.org/gmane.science.nmr.relax.scm/17615 r19859]* The [[CR72]] model during the analysisat [http://article. If the former, then it should be added to the dsgmane.relax_guiorg/gmane.analysesscience.nmr.relax.scm/17570 r19814] [data_indexhttp://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.disp_models listrelax.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]]