Walkthrough models

This wiki page provides an overview of how to modify model objects.

Change the parameter limits of an existing model

The most basic task when fitting is to change the limits of the model parameters. To begin, perform a fit with the normal full model

load demo.mat
a = bt.fit(bt.model.full,f,s_single)

Next, make a copy of +bt/+model/full.m and call the copy +bt/+model/full_gee_extended.m. This now defines a new class called full_gee_extended. Open the file, and change the class definition on line 1, the name of the constructor on line 28, and the string naming the model on line 29, to this new class. These lines originally read

1 	classdef full < bt.model.template
28	function self = full() % Constructor
29	self.name = 'model_full';

and you should change them to

1 	classdef full_gee_extended < bt.model.template
28	function self = full_gee_extended() % Constructor
29	self.name = 'model_full_gee_extended';

Having completed these steps, you have now created a new model called full_gee_extended. You can now run

b = bt.fit(bt.model.full_gee_extended,f,s_single)

Of course, the model is identical in substance to bt.model.full, so your results will not be any different. Now that we have created a new model object, we can now start to make the changes we want to test. For full_gee_extended, let's suppose we wanted to see what happens if Gee is allowed to take larger values. The default limits in full.m are:

self.limits = [  0  -40   0  -40   -5  10   100    0.075  0 ;...
	            20    0  40    0    0  100  800    0.14   1  ];

The rows correspond to the lower and upper bounds, and the columns correspond to the parameter, in the same order as in self.param_names. For full.m, we have

self.param_names = {'Gee','Gei','Gese','Gesre','Gsrs','Alpha','Beta','t0','EMGa'};

so the upper bound on Gee in self.limits in the first column, second row. We can double it as follows:

self.limits = [  0  -40   0  -40   -5  10   100    0.075  0 ;...
	            40    0  40    0    0  100  800    0.14   1  ];

and then run the fit

b = bt.fit(bt.model.full_gee_extended,f,s_single)

As shown below, the plot now reflects the new upper bound on Gee.

Note that if you run b.interactive_fit or any of the other plots, the updated limit will automatically be used.

General approach

1. Make a copy of one of the existing models
2. Update the list of parameters, units, limits
3. Step through each function implemented by the model, and update it to support the new parameters. Pay particular attention to
   • objective, because this is probably where your parameters have an effect
   • validate_params if a simple range is insufficient to rule out all invalid parameter values
   • initialize_fit - you will need to add your parameter to the vector of initial values returned by this function

If your model is based heavily on another existing one, you can inherit from that model instead of template. For example, reduced_emgf is almost identical to reduced except it has an extra EMG parameter. Since most of the auxiliary functions are unchanged, reduced_emgf inherits from reduced and only overloads the functions in which the EMG parameter is required. full_norm takes this a step further by even calling full.objective before performing its own special renormalization.

Lastly, one very important step is to tune the initial step size for the chain. This is best accomplished by setting debugmode = true in one of the wrappers, such that the trace plot for the chain is displayed. Generally, not enough steps are being accepted and the trace plot looks like a series of steps, you should decrease the initial step size. Whereas if the initial step size is too small, the trace plot will show that it takes a long time to reach the stationary distribution. In particular, the amplitude of the trace plot will likely increase with the number of steps, and the initial step size is probably too small if the amplitude is still increasing after the burn-in period.