1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 """The monte_carlo user function definitions for Monte Carlo simulations."""
26
27
28 from graphics import WIZARD_IMAGE_PATH
29 from pipe_control import error_analysis
30 from user_functions.data import Uf_info; uf_info = Uf_info()
31 from user_functions.objects import Desc_container
32
33
34
35 monte_carlo_desc = Desc_container("Monte Carlo Simulation Overview")
36 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:")
37 monte_carlo_desc.add_item_list_element("1", "The measured data set together with the corresponding error set should be loaded into relax.")
38 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.")
39 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.")
40 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.")
41 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).")
42 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.")
43 monte_carlo_desc.add_item_list_element("7", "Failed simulations are removed using the techniques of model elimination.")
44 monte_carlo_desc.add_item_list_element("8", "The model parameter errors are calculated from the distribution of simulation parameters.")
45 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.")
46 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:")
47 monte_carlo_desc.add_prompt("relax> minimise.grid_search(inc=11) # Step 2.")
48 monte_carlo_desc.add_prompt("relax> minimise.execute('newton') # Step 2.")
49 monte_carlo_desc.add_prompt("relax> monte_carlo.setup(number=500) # Step 3.")
50 monte_carlo_desc.add_prompt("relax> monte_carlo.create_data(method='back_calc') # Step 4.")
51 monte_carlo_desc.add_prompt("relax> monte_carlo.initial_values() # Step 5.")
52 monte_carlo_desc.add_prompt("relax> minimise.execute('newton') # Step 6.")
53 monte_carlo_desc.add_prompt("relax> eliminate() # Step 7.")
54 monte_carlo_desc.add_prompt("relax> monte_carlo.error_analysis() # Step 8.")
55 monte_carlo_desc.add_paragraph("An example for reduced spectral density mapping is:")
56 monte_carlo_desc.add_prompt("relax> minimise.calculate() # Step 2.")
57 monte_carlo_desc.add_prompt("relax> monte_carlo.setup(number=500) # Step 3.")
58 monte_carlo_desc.add_prompt("relax> monte_carlo.create_data(method='back_calc') # Step 4.")
59 monte_carlo_desc.add_prompt("relax> minimise.calculate() # Step 6.")
60 monte_carlo_desc.add_prompt("relax> monte_carlo.error_analysis() # Step 8.")
61
62
63
64 uf_class = uf_info.add_class('monte_carlo')
65 uf_class.title = "Class containing the functions for Monte Carlo and related simulations."
66 uf_class.menu_text = "&monte_carlo"
67 uf_class.gui_icon = "oxygen.actions.roll-relax-blue"
68
69
70
71 uf = uf_info.add_uf('monte_carlo.create_data')
72 uf.title = "Create the Monte Carlo simulation data."
73 uf.title_short = "Data creation."
74 uf.add_keyarg(
75 name = "method",
76 default = "back_calc",
77 basic_types = ["str"],
78 desc_short = "method",
79 desc = "The simulation method.",
80 wiz_element_type = "combo",
81 wiz_combo_choices = ["Monte Carlo", "Bootstrapping"],
82 wiz_combo_data = ["back_calc", "direct"],
83 wiz_read_only = True
84 )
85 uf.add_keyarg(
86 name = "distribution",
87 default = "measured",
88 basic_types = ["str"],
89 desc_short = "distribution",
90 desc = "The error distribution method.",
91 wiz_element_type = "combo",
92 wiz_combo_choices = ["Measured error", "Reduced chi2", "Fixed error"],
93 wiz_combo_data = ["measured", "red_chi2", "fixed"],
94 wiz_read_only = True
95 )
96 uf.add_keyarg(
97 name = "fixed_error",
98 basic_types = ["float"],
99 default = None,
100 desc_short = "fixed error value for fixed error distribution.",
101 desc = "The fixed value to use when distribution is set to 'fixed'.",
102 can_be_none = True
103 )
104
105 uf.desc.append(Desc_container())
106 uf.desc[-1].add_paragraph("The method can either be set to back calculation (Monte Carlo) or direct (bootstrapping), the choice of which determines the simulation type. If the values or parameters are calculated rather than minimised, this option will have no effect. Errors should only be propagated via Monte Carlo simulations if errors have been measured. ")
107 uf.desc[-1].add_paragraph("For error analysis, the method should be set to back calculation which will result in proper Monte Carlo simulations. The data used for each simulation is back calculated from the minimised model parameters and is randomised using Gaussian noise where the standard deviation is from the original error set. When the method is set to back calculation, this function should only be called after the model is fully minimised.")
108 uf.desc[-1].add_paragraph("The simulation type can be changed by setting the method to direct. This will result in bootstrapping simulations which cannot be used in error analysis (and which are no longer Monte Carlo simulations). However, these simulations are required for certain model selection techniques (see the documentation for the model selection user function for details), and can be used for other purposes. Rather than the data being back calculated from the fitted model parameters, the data is generated by taking the original data and randomising using Gaussian noise with the standard deviations set to the original error set.")
109 uf.desc[-1].add_paragraph("The errors generated per simulation can either be generated indidual per datapoint and drawn from a gauss distrubtion described by the standard deviation of the indidual point, or it can be generated from a overall gauss distribution described by the standard deviation of the goodness of fit, where SD_fit = sqrt(chi2/(N-p)). The last possibility is to supply a fixed value of the standard deviation, from which gauss distribution to draw errors from.")
110 uf.desc.append(monte_carlo_desc)
111 uf.backend = error_analysis.monte_carlo_create_data
112 uf.menu_text = "&create_data"
113 uf.gui_icon = "oxygen.actions.list-add-relax-blue"
114 uf.wizard_height_desc = 500
115 uf.wizard_size = (1000, 750)
116 uf.wizard_apply_button = False
117 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
118
119
120
121 uf = uf_info.add_uf('monte_carlo.error_analysis')
122 uf.title = "Calculate parameter errors from the Monte Carlo simulations."
123 uf.title_short = "Error calculation."
124
125 uf.desc.append(Desc_container())
126 uf.desc[-1].add_paragraph("Parameter errors are calculated as the standard deviation of the distribution of parameter values. This function should never be used if parameter values are obtained by minimisation and the simulation data are generated using the method 'direct'. The reason is because only true Monte Carlo simulations can give the true parameter errors.")
127 uf.desc.append(monte_carlo_desc)
128 uf.backend = error_analysis.monte_carlo_error_analysis
129 uf.menu_text = "&error_analysis"
130 uf.gui_icon = "oxygen.actions.roll-relax-blue"
131 uf.wizard_height_desc = 620
132 uf.wizard_size = (1000, 750)
133 uf.wizard_apply_button = False
134 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
135
136
137
138 uf = uf_info.add_uf('monte_carlo.initial_values')
139 uf.title = "Set the initial simulation parameter values."
140 uf.title_short = "Initial value setting."
141
142 uf.desc.append(Desc_container())
143 uf.desc[-1].add_paragraph("This only effects where minimisation occurs and can therefore be skipped if the values or parameters are calculated rather than minimised. However, if accidentally run in this case, the results will be unaffected. It should only be called after the model or run is fully minimised. Once called, the user functions minimise.grid_search and minimise.execute will only effect the simulations and not the model parameters.")
144 uf.desc[-1].add_paragraph("The initial values of the parameters for each simulation is set to the minimised parameters of the model. A grid search can be undertaken for each simulation instead, although this is computationally expensive and unnecessary. The minimisation function should be executed for a second time after running this function.")
145 uf.desc.append(monte_carlo_desc)
146 uf.backend = error_analysis.monte_carlo_initial_values
147 uf.menu_text = "&initial_values"
148 uf.gui_icon = "oxygen.actions.list-add-relax-blue"
149 uf.wizard_height_desc = 620
150 uf.wizard_size = (1000, 750)
151 uf.wizard_apply_button = False
152 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
153
154
155
156 uf = uf_info.add_uf('monte_carlo.off')
157 uf.title = "Turn the Monte Carlo simulations off."""
158 uf.title_short = "Simulations off."""
159
160 uf.desc.append(Desc_container())
161 uf.desc[-1].add_paragraph("This will turn off the Monte Carlo simulations so that subsequent optimisation will operate directly on the model parameters and not on the simulations.")
162 uf.desc.append(monte_carlo_desc)
163 uf.backend = error_analysis.monte_carlo_off
164 uf.menu_text = "o&ff"
165 uf.gui_icon = "oxygen.actions.dialog-cancel"
166 uf.wizard_height_desc = 620
167 uf.wizard_size = (1000, 750)
168 uf.wizard_apply_button = False
169 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
170
171
172
173 uf = uf_info.add_uf('monte_carlo.on')
174 uf.title = "Turn the Monte Carlo simulations on."""
175 uf.title_short = "Simulations on."""
176
177 uf.desc.append(Desc_container())
178 uf.desc[-1].add_paragraph("This will turn on the Monte Carlo simulations so that subsequent optimisation will operate on the simulations rather than on the real model parameters.")
179 uf.desc.append(monte_carlo_desc)
180 uf.backend = error_analysis.monte_carlo_on
181 uf.menu_text = "o&n"
182 uf.gui_icon = "oxygen.actions.dialog-ok"
183 uf.wizard_height_desc = 620
184 uf.wizard_size = (1000, 750)
185 uf.wizard_apply_button = False
186 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
187
188
189
190 uf = uf_info.add_uf('monte_carlo.setup')
191 uf.title = "Set up the Monte Carlo simulations."
192 uf.title_short = "Simulation setup."
193 uf.add_keyarg(
194 name = "number",
195 default = 500,
196 basic_types = ["int"],
197 min = 3,
198 max = 100000,
199 desc_short = "number of Monte Carlo simulations",
200 desc = "The number of Monte Carlo simulations."
201 )
202
203 uf.desc.append(Desc_container())
204 uf.desc[-1].add_paragraph("This must be called prior to any of the other Monte Carlo functions. The effect is that the number of simulations will be set and that simulations will be turned on.")
205 uf.desc.append(monte_carlo_desc)
206 uf.backend = error_analysis.monte_carlo_setup
207 uf.menu_text = "&setup"
208 uf.gui_icon = "oxygen.actions.document-edit"
209 uf.wizard_height_desc = 570
210 uf.wizard_size = (1000, 750)
211 uf.wizard_apply_button = False
212 uf.wizard_image = WIZARD_IMAGE_PATH + 'monte_carlo.png'
213