"S2f - generalised order parameter (faster motion)",
"S2s - generalised order parameter (slower motion)",
"tf - effective correlation time (faster motion)",
"ts - effective correlation time (slower motion)",
"Rex - chemical exchange relaxation", "r - average bond length <r>",
"CSA - chemical shift anisotropy"
],
wiz_combo_data=["s2", "te", "s2f", "s2s", "tf", "ts", "rex", "r", "csa"],
wiz_read_only=True)
uf.add_keyarg(name="spin_id",
basic_types=["str"],
desc_short="spin identification string",
desc="The spin identification string.",
can_be_none=True)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"This user function should almost never be used. It is provided for academic reasons for the study of old analyses and published results. If you are looking for a normal model-free model, use the model_free.select_model user function instead."
)
# Model-free equation.
uf.desc.append(Desc_container("Model-free equation"))
uf.desc[-1].add_paragraph(
"The model-free equation can be one of the following:")
uf.desc[-1].add_list_element(
"'mf_orig' selects the original model-free equations with parameters {S2, te}."
)
uf.desc[-1].add_list_element(
"'mf_ext' selects the extended model-free equations with parameters {S2f, tf, S2, ts}."
)
uf.desc[-1].add_list_element(
"'mf_ext2' selects the extended model-free equations with parameters {S2f, tf, S2s, ts}."
def _uf_param_table(self,
label=None,
caption=None,
scope='spin',
sets=['params', 'fixed'],
default=False,
units=False,
type=False):
""""Create the parameter documentation for the user function docstrings.
@keyword label: The label of the table. This is used to identify replicated tables, and is also used in the table referencing in the LaTeX compilation of the user manual. If this label is already used, the corresponding pre-constructed documentation object will be returned.
@type label: str
@keyword caption: The caption for the table.
@type caption: str
@keyword scope: The parameter scope to restrict the table to, defaulting to 'spin'.
@type scope: str or None
@keyword sets: The parameter sets to restrict the table to. If not given, then all parameters of the 'params' and 'fixed' sets will be added. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names.
@type sets: list of str
@keyword default: A flag which if True will cause the default parameter value to be included in the table.
@type default: bool
@keyword units: A flag which if True will cause the units to be included in the table.
@type units: bool
@keyword type: A flag which if True will cause the parameter type to be included in the table.
@type type: bool
@return: The parameter documentation.
@rtype: Desc_container instance
"""
# Sanity checks.
if label == None:
raise RelaxError("The table identifying label must be supplied.")
if label in self._uf_docs:
raise RelaxError(
"The table identifying label '%s' already exists." % label)
# Initialise the documentation object.
self._uf_docs[label] = Desc_container(self._uf_title)
# The parameter table.
table = uf_tables.add_table(label=label, caption=caption)
# Add the headings.
headings = ["Name", "Description"]
if default:
headings.append("Default")
if units:
headings.append("Units")
if type:
headings.append("Type")
table.add_headings(headings)
# Add each parameter, first of the parameter set, then the 'generic' set.
for set in sets:
for param in self.loop(set=set):
# Limit the scope.
if scope and self.scope(param) != scope:
continue
row = []
row.append(param)
row.append(self.description(param))
if default:
row.append("%s" % self.default_value(param))
if units:
row.append("%s" % self.units(param))
if type:
row.append("%s" % self.type_string(param))
table.add_row(row)
# Add the table to the documentation object.
self._uf_docs[label].add_table(table.label)
# Return the documentation object so that additional text can be added after the table.
return self._uf_docs[label]
# along with this program. If not, see <http://www.gnu.org/licenses/>. #
# #
###############################################################################
# Module docstring.
"""The monte_carlo user function definitions for Monte Carlo simulations."""
# relax module imports.
from graphics import WIZARD_IMAGE_PATH
from pipe_control import error_analysis
from user_functions.data import Uf_info
uf_info = Uf_info()
from user_functions.objects import Desc_container
# Generic description document, used in all user functions.
monte_carlo_desc = Desc_container("Monte Carlo Simulation Overview")
monte_carlo_desc.add_paragraph(
"For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:"
)
monte_carlo_desc.add_item_list_element(
"1",
"The measured data set together with the corresponding error set should be loaded into relax."
)
monte_carlo_desc.add_item_list_element(
"2",
"Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run."
)
monte_carlo_desc.add_item_list_element(
"3",
"To initialise and turn on Monte Carlo simulations, the number of simulations, n, needs to be set."
)
# Python module imports
from warnings import warn
# relax module imports.
from lib.errors import RelaxError, RelaxNoDomainError, RelaxNoSequenceError
from lib.io import read_spin_data
from lib.selection import Selection, spin_id_to_data_list
from lib.warnings import RelaxNoSpinWarning
from pipe_control import pipes
from pipe_control.interatomic import interatomic_loop
from pipe_control.mol_res_spin import exists_mol_res_spin_data, generate_spin_id_unique, return_spin, spin_loop
from user_functions.data import Uf_tables; uf_tables = Uf_tables()
from user_functions.objects import Desc_container
boolean_doc = Desc_container("Boolean operators")
boolean_doc.add_paragraph("The boolean operator can be used to change how spin systems or interatomic data containers are selected. The allowed values are: 'OR', 'NOR', 'AND', 'NAND', 'XOR', 'XNOR'. The following table details how the selections will occur for the different boolean operators.")
table = uf_tables.add_table(label="table: bool operators", caption="Boolean operators and their effects on selections")
table.add_headings(["Spin system or interatomic data container", "1", "2", "3", "4", "5", "6", "7", "8", "9"])
table.add_row(["Original selection", "0", "1", "1", "1", "1", "0", "1", "0", "1"])
table.add_row(["New selection", "0", "1", "1", "1", "1", "1", "0", "0", "0"])
table.add_row(["OR", "0", "1", "1", "1", "1", "1", "1", "0", "1"])
table.add_row(["NOR", "1", "0", "0", "0", "0", "0", "0", "1", "0"])
table.add_row(["AND", "0", "1", "1", "1", "1", "0", "0", "0", "0"])
table.add_row(["NAND", "1", "0", "0", "0", "0", "1", "1", "1", "1"])
table.add_row(["XOR", "0", "0", "0", "0", "0", "1", "1", "0", "1"])
table.add_row(["XNOR", "1", "1", "1", "1", "1", "0", "0", "1", "0"])
boolean_doc.add_table(table.label)
def boolean_deselect(current=None, boolean=None):
"Diffusion tensor parameters",
"All parameters from all spins",
"All parameters (diffusion and spin)"],
wiz_combo_data = [
"diff",
"all_spins",
"all"],
wiz_read_only = True,
)
uf.add_keyarg(
name = "fixed",
default = True,
py_type = "bool",
desc_short = "fixed",
desc = "A flag specifying if the parameters should be fixed or allowed to change."
)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph("The element can be any of the following:")
uf.desc[-1].add_item_list_element("'diff'", "The diffusion tensor parameters. This will allow all diffusion tensor parameters to be toggled.")
uf.desc[-1].add_item_list_element("'all_spins'", "Using this keyword, all parameters from all spins will be toggled.")
uf.desc[-1].add_item_list_element("'all'", "All parameters will be toggled. This is equivalent to combining both 'diff' and 'all_spins'.")
uf.desc[-1].add_paragraph("The flag 'fixed', if set to True, will fix parameters during optimisation whereas a value of False will allow parameters to vary.")
uf.backend = fix.fix
uf.menu_text = "&fix"
uf.gui_icon = "oxygen.status.object-locked"
uf.wizard_height_desc = 400
uf.wizard_size = (800, 600)
uf.wizard_apply_button = False
uf.wizard_image = WIZARD_IMAGE_PATH + 'object-locked-unlocked.png'
# #
# This program is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #
# GNU General Public License for more details. #
# #
# You should have received a copy of the GNU General Public License #
# along with this program. If not, see <http://www.gnu.org/licenses/>. #
# #
###############################################################################
# Module docstring.
"""Module containing various shared docstrings."""
# relax module imports.
from user_functions.objects import Desc_container
# Regular expression.
regexp_doc = Desc_container("Regular expression")
regexp_doc.add_paragraph("The python function 'match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.")
regexp_doc.add_paragraph("This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:")
regexp_doc.add_item_list_element("'[]'", "A sequence or set of characters to match to a single character. For example, '[sS]2' will match both 'S2' and 's2'.")
regexp_doc.add_item_list_element("'^'", "Match the start of the string.")
regexp_doc.add_item_list_element("'$'", "Match the end of the string. For example, '^[Ss]2$' will match 's2' but not 'S2f' or 's2s'.")
regexp_doc.add_item_list_element("'.'", "Match any character.")
regexp_doc.add_item_list_element("'x*'", "Match the character 'x' any number of times, for example 'x' will match, as will 'xxxxx'.")
regexp_doc.add_item_list_element("'.*'", "Match any sequence of characters of any length.")
regexp_doc.add_paragraph("Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.")
basic_types = ["str"],
desc_short = "parameter",
desc = "The parameter to copy. Only one parameter may be selected.",
wiz_element_type = 'combo',
wiz_combo_iter = value.get_parameters,
wiz_read_only = True
)
uf.add_keyarg(
name = "force",
default = False,
basic_types = ["bool"],
desc_short = "force flag",
desc = "A flag which, if set to True, will cause the destination parameter to be overwritten."
)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph("If this is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.")
# Prompt examples.
uf.desc.append(relax_fit_params.uf_doc(label="table: curve-fit parameter value setting"))
uf.desc.append(model_free_params.uf_doc(label="table: model-free parameter value setting"))
uf.desc.append(jw_mapping_params.uf_doc(label="table: J(w) parameter value setting"))
uf.desc.append(consistency_test_params.uf_doc(label="table: consistency testing parameter value setting"))
uf.desc.append(n_state_params.uf_doc(label="table: N-state parameter value setting"))
uf.desc.append(relax_disp_params.uf_doc(label="table: dispersion parameter value setting"))
uf.desc.append(frame_order_params.uf_doc(label="table: frame order parameters"))
uf.desc.append(Desc_container("Prompt examples"))
uf.desc[-1].add_paragraph("To copy the CSA values from the data pipe 'm1' to 'm2', type:")
uf.desc[-1].add_prompt("relax> value.copy('m1', 'm2', 'csa')")
uf.backend = value.copy
uf.menu_text = "©"
uf.gui_icon = "oxygen.actions.list-add"
desc="The name of the data pipe to copy the diffusion tensor data from.",
wiz_element_type='combo',
wiz_combo_iter=pipes.pipe_names,
wiz_read_only=True,
can_be_none=True)
uf.add_keyarg(
name="pipe_to",
py_type="str",
desc_short="destination data pipe",
desc="The name of the data pipe to copy the diffusion tensor data to.",
wiz_element_type='combo',
wiz_combo_iter=pipes.pipe_names,
wiz_read_only=True,
can_be_none=True)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"This will copy the diffusion tensor data between data pipes. The destination data pipe must not contain any diffusion tensor data. If the source or destination data pipes are not supplied, then both will default to the current data pipe (hence specifying at least one is essential)."
)
# Prompt examples.
uf.desc.append(Desc_container("Prompt examples"))
uf.desc[-1].add_paragraph(
"To copy the diffusion tensor from the data pipe 'm1' to the current data pipe, type:"
)
uf.desc[-1].add_prompt("relax> diffusion_tensor.copy('m1')")
uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_from='m1')")
uf.desc[-1].add_paragraph(
"To copy the diffusion tensor from the current data pipe to the data pipe 'm9', type:"
)
uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_to='m9')")
uf.desc[-1].add_paragraph(
from pipe_control.mol_res_spin import exists_mol_res_spin_data, spin_loop
from pipe_control.pipes import check_pipe
import specific_analyses
from specific_analyses.model_free.api import Model_free
from specific_analyses.model_free.model import model_map
from user_functions.data import Uf_tables
uf_tables = Uf_tables()
from user_functions.objects import Desc_container
# The API object.
api_model_free = Model_free()
# Classic style documentation.
classic_style_doc = Desc_container("Model-free classic style")
classic_style_doc.add_paragraph("Creator: Edward d'Auvergne")
classic_style_doc.add_paragraph('Argument string: "classic"')
classic_style_doc.add_paragraph(
"Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines."
)
classic_style_doc.add_paragraph("Supported data types:")
table = uf_tables.add_table(
label="table: model-free macro classic style",
caption="The model-free classic style for mapping model spin specific data onto 3D molecular structures using either PyMOL or Molmol.",
caption_short="The model-free classic style for PyMOL and Molmol data mapping.",
)
table.add_headings(["Data type", "String", "Description"])
table.add_row(
[
"S2.",
# The minimise.calculate user function.
uf = uf_info.add_uf('minimise.calculate')
uf.title = "Calculate the model parameters or the current target function value."
uf.title_short = "Model parameter or target function value calculation."
uf.display = True
uf.add_keyarg(
name="verbosity",
default=1,
basic_types=["int"],
desc_short="verbosity level",
desc=
"The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1."
)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"The operation of this user function is two-fold and depends on whether the solution for the models of the current analysis are found by direct calculation or by optimisation. The dual operations are:"
)
uf.desc[-1].add_item_list_element(
"Direct calculation models",
"For these models, the parameters will be directly calculated from the base data. This will be the exact solution and the user function will store the parameter values. The grid search and optimisation user functions are not implemented for this analysis type."
)
uf.desc[-1].add_item_list_element(
"Optimised models",
"This will call the target function normally used for optimisation for each model using the current parameter values. This can be used to manually find the chi-squared value for different parameter values. The parameter values will not be affected."
)
uf.backend = minimise.calc
uf.menu_text = "&calculate"
uf.gui_icon = "oxygen.categories.applications-education"
uf.wizard_size = (900, 500)
# #
# This program is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #
# GNU General Public License for more details. #
# #
# You should have received a copy of the GNU General Public License #
# along with this program. If not, see <http://www.gnu.org/licenses/>. #
# #
###############################################################################
# Module docstring.
"""Module containing various shared docstrings."""
# relax module imports.
from user_functions.objects import Desc_container
# Regular expression.
regexp_doc = Desc_container("Regular expression")
regexp_doc.add_paragraph("The python function 'match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.")
regexp_doc.add_paragraph("This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:")
regexp_doc.add_item_list_element("'[]'", "A sequence or set of characters to match to a single character. For example, '[sS]2' will match both 'S2' and 's2'.")
regexp_doc.add_item_list_element("'^'", "Match the start of the string.")
regexp_doc.add_item_list_element("'$'", "Match the end of the string. For example, '^[Ss]2$' will match 's2' but not 'S2f' or 's2s'.")
regexp_doc.add_item_list_element("'.'", "Match any character.")
regexp_doc.add_item_list_element("'x*'", "Match the character 'x' any number of times, for example 'x' will match, as will 'xxxxx'.")
regexp_doc.add_item_list_element("'.*'", "Match any sequence of characters of any length.")
regexp_doc.add_paragraph("Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.")
spin.warning = None
def return_conversion_factor(stat_type):
"""Dummy function for returning 1.0.
@param stat_type: The name of the statistic. This is unused!
@type stat_type: str
@return: A conversion factor of 1.0.
@rtype: float
"""
return 1.0
return_data_name_doc = Desc_container("Minimisation statistic data type string matching patterns")
table = uf_tables.add_table(label="table: min data type patterns", caption="Minimisation statistic data type string matching patterns.")
table.add_headings(["Data type", "Object name", "Patterns"])
table.add_row(["Chi-squared statistic", "'chi2'", "'^[Cc]hi2$' or '^[Cc]hi[-_ ][Ss]quare'"])
table.add_row(["Iteration count", "'iter'", "'^[Ii]ter'"])
table.add_row(["Function call count", "'f_count'", "'^[Ff].*[ -_][Cc]ount'"])
table.add_row(["Gradient call count", "'g_count'", "'^[Gg].*[ -_][Cc]ount'"])
table.add_row(["Hessian call count", "'h_count'", "'^[Hh].*[ -_][Cc]ount'"])
return_data_name_doc.add_table(table.label)
def return_data_name(name):
"""Return a unique identifying string for the minimisation parameter.
@param name: The minimisation parameter.
@type name: str
@return: The unique parameter identifying string.
import sys
from warnings import warn
# relax module imports.
from lib.errors import RelaxError, RelaxNoDomainError, RelaxNoSequenceError
from lib.selection import Selection, spin_id_to_data_list
from lib.sequence import read_spin_data, write_spin_data
from lib.warnings import RelaxNoSpinWarning
from pipe_control.interatomic import interatomic_loop
from pipe_control.mol_res_spin import check_mol_res_spin_data, exists_mol_res_spin_data, generate_spin_id_unique, return_spin, spin_loop
from pipe_control.pipes import check_pipe
from user_functions.data import Uf_tables; uf_tables = Uf_tables()
from user_functions.objects import Desc_container
boolean_doc = Desc_container("Boolean operators")
boolean_doc.add_paragraph("The boolean operator can be used to change how spin systems or interatomic data containers are selected. The allowed values are: 'OR', 'NOR', 'AND', 'NAND', 'XOR', 'XNOR'. The following table details how the selections will occur for the different boolean operators.")
table = uf_tables.add_table(label="table: bool operators", caption="Boolean operators and their effects on selections")
table.add_headings(["Spin system or interatomic data container", "1", "2", "3", "4", "5", "6", "7", "8", "9"])
table.add_row(["Original selection", "0", "1", "1", "1", "1", "0", "1", "0", "1"])
table.add_row(["New selection", "0", "1", "1", "1", "1", "1", "0", "0", "0"])
table.add_row(["OR", "0", "1", "1", "1", "1", "1", "1", "0", "1"])
table.add_row(["NOR", "1", "0", "0", "0", "0", "0", "0", "1", "0"])
table.add_row(["AND", "0", "1", "1", "1", "1", "0", "0", "0", "0"])
table.add_row(["NAND", "1", "0", "0", "0", "0", "1", "1", "1", "1"])
table.add_row(["XOR", "0", "0", "0", "0", "0", "1", "1", "0", "1"])
table.add_row(["XNOR", "1", "1", "1", "1", "1", "0", "0", "1", "0"])
boolean_doc.add_table(table.label)
def boolean_deselect(current=None, boolean=None):
uf.add_keyarg(name="dir",
py_type="str",
arg_type="dir sel",
desc_short="directory name",
desc="The directory to place the files.",
can_be_none=True)
uf.add_keyarg(
name="force",
default=False,
py_type="bool",
desc_short="force flag",
desc=
"A flag which if set to True will cause the results file to be overwritten if it already exists."
)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"The script file created is called 'dir/dasha_script'.")
# Optimisation algorithms.
uf.desc.append(Desc_container("Optimisation algorithms"))
uf.desc[-1].add_paragraph(
"The two minimisation algorithms within Dasha are accessible through the algorithm which can be set to:"
)
uf.desc[-1].add_item_list_element("'LM'", "The Levenberg-Marquardt algorithm,")
uf.desc[-1].add_item_list_element("'NR'", "Newton-Raphson algorithm.")
uf.desc[-1].add_paragraph(
"For Levenberg-Marquardt minimisation, the function 'lmin' will be called, while for Newton-Raphson, the function 'min' will be executed."
)
uf.backend = dasha.create
uf.menu_text = "&create"
uf.gui_icon = "oxygen.actions.list-add-relax-blue"
uf_info = Uf_info()
from user_functions.objects import Desc_container
from user_functions.wildcards import WILDCARD_PYMOL_MACRO, WILDCARD_STRUCT_PDB_ALL
# The user function class.
uf_class = uf_info.add_class('pymol')
uf_class.title = "Class for interfacing with PyMOL."
uf_class.menu_text = "&pymol"
uf_class.gui_icon = "relax.pymol_icon"
# The pymol.cartoon user function.
uf = uf_info.add_uf('pymol.cartoon')
uf.title = "Apply the PyMOL cartoon style and colour by secondary structure."
uf.title_short = "PyMOL cartoon style application."
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"This applies the PyMOL cartoon style which is equivalent to hiding everything and clicking on show cartoon. It also colours the cartoon with red helices, yellow strands, and green loops. The following commands are executed:"
)
uf.desc[-1].add_list_element("cmd.hide('everything', file)")
uf.desc[-1].add_list_element("cmd.show('cartoon', file)")
uf.desc[-1].add_list_element("util.cbss(file, 'red', 'yellow', 'green')")
uf.desc[-1].add_paragraph(
"where file is the file name without the '.pdb' extension.")
# Prompt examples.
uf.desc.append(Desc_container("Prompt examples"))
uf.desc[-1].add_paragraph("To apply this user function, type:")
uf.desc[-1].add_prompt("relax> pymol.cartoon()")
uf.backend = pymol_control.cartoon
uf.menu_text = "cart&oon"
uf.wizard_size = (700, 500)
from lib.errors import RelaxError, RelaxFuncSetupError, RelaxNoSequenceError, RelaxTensorError
from pipe_control import pipes
from pipe_control.mol_res_spin import exists_mol_res_spin_data, spin_loop
from pipe_control.pipes import check_pipe
import specific_analyses
from specific_analyses.model_free.api import Model_free
from specific_analyses.model_free.model import model_map
from user_functions.data import Uf_tables
uf_tables = Uf_tables()
from user_functions.objects import Desc_container
# The API object.
api_model_free = Model_free()
# Classic style documentation.
classic_style_doc = Desc_container("Model-free classic style")
classic_style_doc.add_paragraph("Creator: Edward d'Auvergne")
classic_style_doc.add_paragraph("Argument string: \"classic\"")
classic_style_doc.add_paragraph(
"Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines."
)
classic_style_doc.add_paragraph("Supported data types:")
table = uf_tables.add_table(
label="table: model-free macro classic style",
caption=
"The model-free classic style for mapping model spin specific data onto 3D molecular structures using either PyMOL or Molmol.",
caption_short=
"The model-free classic style for PyMOL and Molmol data mapping.")
table.add_headings(["Data type", "String", "Description"])
table.add_row([
"S2.", "'s2'",
# along with this program. If not, see <http://www.gnu.org/licenses/>. #
# #
###############################################################################
# Module docstring.
"""The monte_carlo user function definitions for Monte Carlo simulations."""
# relax module imports.
from graphics import WIZARD_IMAGE_PATH
from pipe_control import error_analysis
from user_functions.data import Uf_info; uf_info = Uf_info()
from user_functions.objects import Desc_container
# Generic description document, used in all user functions.
monte_carlo_desc = Desc_container("Monte Carlo Simulation Overview")
monte_carlo_desc.add_paragraph("For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:")
monte_carlo_desc.add_item_list_element("1", "The measured data set together with the corresponding error set should be loaded into relax.")
monte_carlo_desc.add_item_list_element("2", "Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.")
monte_carlo_desc.add_item_list_element("3", "To initialise and turn on Monte Carlo simulations, the number of simulations, n, needs to be set.")
monte_carlo_desc.add_item_list_element("4", "The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.")
monte_carlo_desc.add_item_list_element("5", "Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).")
monte_carlo_desc.add_item_list_element("6", "Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.")
monte_carlo_desc.add_item_list_element("7", "Failed simulations are removed using the techniques of model elimination.")
monte_carlo_desc.add_item_list_element("8", "The model parameter errors are calculated from the distribution of simulation parameters.")
monte_carlo_desc.add_paragraph("Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.")
monte_carlo_desc.add_paragraph("An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:")
monte_carlo_desc.add_prompt("relax> minimise.grid_search(inc=11) # Step 2.")
monte_carlo_desc.add_prompt("relax> minimise.execute('newton') # Step 2.")
monte_carlo_desc.add_prompt("relax> monte_carlo.setup(number=500) # Step 3.")
monte_carlo_desc.add_prompt("relax> monte_carlo.create_data(method='back_calc') # Step 4.")
desc_short="error",
desc="The baseplane RMSD error value.")
uf.add_keyarg(name="spectrum_id",
basic_types=["str"],
desc_short="spectrum ID string",
desc="The spectrum ID string.",
wiz_element_type='combo',
wiz_combo_iter=spectrum.get_ids,
wiz_read_only=True)
uf.add_keyarg(name="spin_id",
basic_types=["str"],
desc_short="spin ID string",
desc="The spin ID string.",
can_be_none=True)
# Description.
uf.desc.append(Desc_container())
uf.desc[-1].add_paragraph(
"The spectrum ID identifies the spectrum associated with the error and must correspond to a previously loaded set of intensities. If the spin ID is unset, then the error value for all spins will be set to the supplied value."
)
uf.backend = spectrum.baseplane_rmsd
uf.menu_text = "&baseplane_rmsd"
uf.gui_icon = "oxygen.actions.edit-rename"
uf.wizard_size = (800, 500)
uf.wizard_image = WIZARD_IMAGE_PATH + 'spectrum' + sep + 'spectrum_200.png'
# The spectrum.delete user function.
uf = uf_info.add_uf('spectrum.delete')
uf.title = "Delete the spectral data corresponding to the spectrum ID string."
uf.title_short = "Spectral data deletion."
uf.add_keyarg(name="spectrum_id",
basic_types=["str"],
