prompt.monte

34 """Class containing the functions for Monte Carlo and related simulations.""" 35

36 - def create_data(self, method='back_calc'):

37 """Function for creating simulation data. 38 39 Keyword Arguments 40 ~~~~~~~~~~~~~~~~~ 41 42 method: The simulation method. 43 44 45 Description 46 ~~~~~~~~~~~ 47 48 The method argument can either be set to 'back_calc' or 'direct', the choice of which 49 determines the simulation type. If the values or parameters are calculated rather than 50 minimised, this option will have no effect, hence, 'back_calc' and 'direct' are identical. 51 52 For error analysis, the method argument should be set to 'back_calc' which will result in 53 proper Monte Carlo simulations. The data used for each simulation is back calculated from 54 the minimised model parameters and is randomised using Gaussian noise where the standard 55 deviation is from the original error set. When the method is set to 'back_calc', this 56 function should only be called after the model is fully minimised. 57 58 The simulation type can be changed by setting the method argument to 'direct'. This will 59 result in simulations which cannot be used in error analysis and which are no longer Monte 60 Carlo simulations. However, these simulations are required for certain model selection 61 techniques (see the documentation for the model selection function for details), and can be 62 used for other purposes. Rather than the data being back calculated from the fitted model 63 parameters, the data is generated by taking the original data and randomising using Gaussian 64 noise with the standard deviations set to the original error set. 65 """ 66 67 # Function intro text. 68 if self._exec_info.intro: 69 text = self._exec_info.ps3 + "monte_carlo.create_data(" 70 text = text + "method=" + repr(method) + ")" 71 print(text) 72 73 # The argument checks. 74 arg_check.is_str(method, 'method') 75 76 # Execute the functional code. 77 monte_carlo.create_data(method=method)

78 79

80 - def error_analysis(self, prune=0.0):

81 """Function for calculating parameter errors from the Monte Carlo simulations. 82 83 Keyword Arguments 84 ~~~~~~~~~~~~~~~~~ 85 86 prune: Legacy argument corresponding to 'trim' in Art Palmer's Modelfree program. 87 88 89 Description 90 ~~~~~~~~~~~ 91 92 Parameter errors are calculated as the standard deviation of the distribution of parameter 93 values. This function should never be used if parameter values are obtained by minimisation 94 and the simulation data are generated using the method 'direct'. The reason is because only 95 true Monte Carlo simulations can give the true parameter errors. 96 97 The prune argument is legacy code which corresponds to the 'trim' option in Art Palmer's 98 Modelfree program. To remove failed simulations, the eliminate function should be used 99 prior to this function. Eliminating the simulations specifically identifies and removes the 100 failed simulations whereas the prune argument will only, in a few cases, positively identify 101 failed simulations but only if severe parameter limits have been imposed. Most failed 102 models will pass through the pruning process and hence cause a catastrophic increase in the 103 parameter errors. If the argument must be used, the following must be taken into account. 104 If the values or parameters are calculated rather than minimised, the prune argument must be 105 set to zero. The value of this argument is proportional to the number of simulations 106 removed prior to error calculation. If prune is set to 0.0, all simulations are used for 107 calculating errors, whereas a value of 1.0 excludes all data. In almost all cases prune 108 must be set to zero, any value greater than zero will result in an underestimation of the 109 error values. If a value is supplied, the lower and upper tails of the distribution of 110 chi-squared values will be excluded from the error calculation. 111 """ 112 113 # Function intro text. 114 if self._exec_info.intro: 115 text = self._exec_info.ps3 + "monte_carlo.error_analysis(" 116 text = text + "prune=" + repr(prune) + ")" 117 print(text) 118 119 # The argument checks. 120 arg_check.is_num(prune, 'prune') 121 122 # Execute the functional code. 123 monte_carlo.error_analysis(prune=prune)

124 125

126 - def initial_values(self):

127 """Function for setting the initial simulation parameter values. 128 129 Description 130 ~~~~~~~~~~~ 131 132 This function only effects where minimisation occurs and can therefore be skipped if the 133 values or parameters are calculated rather than minimised. However, if accidentally run in 134 this case, the results will be unaffected. It should only be called after the model or run 135 is fully minimised. Once called, the functions 'grid_search' and 'minimise' will only 136 effect the simulations and not the model parameters. 137 138 The initial values of the parameters for each simulation is set to the minimised parameters 139 of the model. A grid search can be undertaken for each simulation instead, although this 140 is computationally expensive and unnecessary. The minimisation function should be executed 141 for a second time after running this function. 142 """ 143 144 # Function intro text. 145 if self._exec_info.intro: 146 text = self._exec_info.ps3 + "monte_carlo.initial_values()" 147 print(text) 148 149 # Execute the functional code. 150 monte_carlo.initial_values()

151 152

153 - def off(self):

154 """Function for turning simulations off.""" 155 156 # Function intro text. 157 if self._exec_info.intro: 158 text = self._exec_info.ps3 + "monte_carlo.off()" 159 print(text) 160 161 # Execute the functional code. 162 monte_carlo.off()

163 164

165 - def on(self):

166 """Function for turning simulations on.""" 167 168 # Function intro text. 169 if self._exec_info.intro: 170 text = self._exec_info.ps3 + "monte_carlo.on()" 171 print(text) 172 173 # Execute the functional code. 174 monte_carlo.on()

175 176

177 - def setup(self, number=500):

178 """Function for setting up Monte Carlo simulations. 179 180 Keyword Arguments 181 ~~~~~~~~~~~~~~~~~ 182 183 number: The number of Monte Carlo simulations. 184 185 186 Description 187 ~~~~~~~~~~~ 188 189 This function must be called prior to any of the other Monte Carlo functions. The effect is 190 that the number of simulations will be set and that simulations will be turned on. 191 """ 192 193 # Function intro text. 194 if self._exec_info.intro: 195 text = self._exec_info.ps3 + "monte_carlo.setup(" 196 text = text + "number=" + repr(number) + ")" 197 print(text) 198 199 # The argument checks. 200 arg_check.is_int(number, 'number of Monte Carlo simulations') 201 202 # Execute the functional code. 203 monte_carlo.setup(number=number)

204 205 206 207 # Modify all docstrings. 208 ######################## 209 210 __description__ = """ 211 Monte Carlo Simulation Overview 212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 213 214 For proper error analysis using Monte Carlo simulations, a sequence of function calls is 215 required for running the various simulation components. The steps necessary for 216 implementing Monte Carlo simulations are: 217 218 1. The measured data set together with the corresponding error set should be loaded into 219 relax. 220 221 2. Either minimisation is used to optimise the parameters of the chosen model, or a 222 calculation is run. 223 224 3. To initialise and turn on Monte Carlo simulations, the number of simulations, n, needs 225 to be set. 226 227 4. The simulation data needs to be created either by back calculation from the fully 228 minimised model parameters from step 2 or by direct calculation when values are calculated 229 rather than minimised. The error set is used to randomise each simulation data set by 230 assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo 231 simulation. 232 233 5. Prior to minimisation of the parameters of each simulation, initial parameter estimates 234 are required. These are taken as the optimised model parameters. An alternative is to use 235 a grid search for each simulation to generate initial estimates, however this is extremely 236 computationally expensive. For the case where values are calculated rather than minimised, 237 this step should be skipped (although the results will be unaffected if this is accidentally 238 run). 239 240 6. Each simulation requires minimisation or calculation. The same techniques as used in 241 step 2, excluding the grid search when minimising, should be used for the simulations. 242 243 7. Failed simulations are removed using the techniques of model elimination. 244 245 8. The model parameter errors are calculated from the distribution of simulation 246 parameters. 247 248 249 Monte Carlo simulations can be turned on or off using functions within this class. Once the 250 function for setting up simulations has been called, simulations will be turned on. The 251 effect of having simulations turned on is that the functions used for minimisation (grid 252 search, minimise, etc) or calculation will only affect the simulation parameters and not the 253 model parameters. By subsequently turning simulations off using the appropriate function, 254 the functions used in minimisation will affect the model parameters and not the simulation 255 parameters. 256 257 258 An example, for model-free analysis, which includes only the functions required for 259 implementing the above steps is: 260 261 relax> grid_search(inc=11) # Step 2. 262 relax> minimise('newton') # Step 2. 263 relax> monte_carlo.setup(number=500) # Step 3. 264 relax> monte_carlo.create_data(method='back_calc') # Step 4. 265 relax> monte_carlo.initial_values() # Step 5. 266 relax> minimise('newton') # Step 6. 267 relax> eliminate() # Step 7. 268 relax> monte_carlo.error_analysis() # Step 8. 269 270 An example for reduced spectral density mapping is: 271 272 relax> calc() # Step 2. 273 relax> monte_carlo.setup(number=500) # Step 3. 274 relax> monte_carlo.create_data(method='back_calc') # Step 4. 275 relax> calc() # Step 6. 276 relax> monte_carlo.error_analysis() # Step 8. 277 """ 278 279 create_data.__doc__ = create_data.__doc__ + "\n\n" + __description__ 280 error_analysis.__doc__ = error_analysis.__doc__ + "\n\n" + __description__ 281 initial_values.__doc__ = initial_values.__doc__ + "\n\n" + __description__ 282 off.__doc__ = off.__doc__ + "\n\n" + __description__ 283 on.__doc__ = on.__doc__ + "\n\n" + __description__ 284 setup.__doc__ = setup.__doc__ + "\n\n" + __description__

Source Code for Module prompt.monte_carlo