Explore Local Model Types

Polynomials

At the local level, if you have one input factor, you can choose Polynomial directly from the list of local model classes. Here you can choose the order of polynomials used, and you can define a datum model for this kind of local model.

If there is more than one input factor, you can choose Linear Models from the Local Model Class list, then you can choose Polynomial or Hybrid Spline. This is a different polynomial model where you can change more settings such as Stepwise, the Term Editor (where you can remove any model terms) and you can choose different orders for different factors (as with the global level polynomial models). See Local Model Class: Linear Models.

Different response features are available for this polynomial model and the Linear Models: Polynomial choice. You can view these by clicking the Response Features tab on the Local Model Setup dialog box. Single input polynomials can have a datum model, and you can define response features relative to the datum. See Datum Models.

The following response features are permitted for the polynomial model class:

See the global model section Polynomials for a general description of polynomial models.

Polynomial Spline

A spline is a piecewise polynomial, where different sections of polynomial are fitted smoothly together. The location of each break is called a knot. Polynomial splines are essential for modeling torque/spark curves.

This model has only one knot. You can choose the orders of the polynomials above and below the knot. See also Hybrid Splines. These global models also use splines, but use the same order polynomial throughout.

Polynomial splines are only available for single input factors. The following example shows a typical torque/spark curve, which requires a spline to fit properly. The knot is shown as a red spot at the maximum, and the curvature above and below the knot is different. In this case, there is a cubic basis function below the knot and a quadratic above.

To model responses that are characterized in appearance by a single and well-defined stationary point with asymmetrical curvature either side of the local minimum or maximum, define the following spline class,

where k is the knot location, denotes a regression coefficient, , .

where c is the user-specified degree for the left polynomial, h is the user-specified degree for the right polynomial, and the subscripts Low and High denote to the left (below) and right of (above) the knot, respectively.

Excluding terms in and ensures that the first derivative at the knot position is continuous. In addition, by definition the constant must be equal to the value of the fit function at the knot, that is, the value at the stationary point.

For this model class, response features can be chosen as

Truncated Power Series Basis (TPSBS) Splines

A general class of spline functions with arbitrary (but strictly increasing) knot sequence:

:

This defines a spline of order m with knot sequence

For this model class, response features can be chosen as

You can remove any of the polynomial terms from the model.

Free Knot Splines

The basis is not the best suited for the purposes of estimation and evaluation, as the design matrix might be poorly conditioned. In addition, the number of arithmetic operations required to evaluate the spline function depends on the location of relative to the knots. These properties can lead to numeric inaccuracies, especially when the number of knots is large. You can reduce such problems by employing B-splines.

The most important aspect is that for moderate m the design matrix expressed in terms of B-splines is relatively well conditioned.

For this model class, response features can be chosen as

Value of the fit function at a user specified value

Three Parameter Logistic Model

The equation $$y_j=\frac{\alpha }{1+\exp [-\kappa (x_j-\gamma )]}$$ defines the three parameter logistic curve.

where is the final size achieved, $${\rm K}$$is a scale parameter, and is the x-ordinate of the point of inflection of the curve.

The curve has asymptotes y_j = 0 as x_j $$\to$$ -∞ and as x_j$$\to$$ ∞. Growth rate is at a maximum when y_j = α/2, which occurs when x_j = $$\gamma$$. Maximum growth rate corresponds to

The following constraints apply to the fit coefficients:

The response feature vector g for the three parameter logistic function is defined as

Morgan-Mercer-Flodin Model

This equation defines the Morgan-Mercer-Flodin (MMF) growth model.

where α is the value of the upper asymptote, β is the value of the lower asymptote, $${\rm K}$$ is a scaling parameter, and δ is a parameter that controls the location of the point of inflection for the curve. The point of inflection is located at

for

There is no point of inflection for δ < 1. All the MMF curves are sublogistic, in the sense that the point of inflection is always located below 50% growth (0.5α). The following constraints apply to the fit coefficient values:

This equation provides the response feature vector g.

Four-Parameter Logistic Curve

This equation defines the four-parameter logistic model.

with constraints , and . Again, is the value of the upper asymptote, is a scaling factor, and is a factor that locates the x-ordinate of the point of inflection at

The following constraints apply to the fit coefficient values:

This is the available response feature vector:

Richards Curves

This equation defines the Richards curves family of growth models.

δ ≠ 1

where α is the upper asymptote, $$\gamma$$ is the location of the point of inflection on the x axis, $${\rm K}$$ is a scaling factor, and δ is a parameter that indirectly locates the point of inflection.

The y-ordinate of the point of inflection is determined from

Richards also derived the average normalized growth rate for the curve as

The following constraints apply to the fit coefficient values:

Finally, the response feature vector g for Richards family of growth curves is defined as

Weibul Growth Curve

This equation defines the Weibul growth curve.

where is the value of the upper curve asymptote, is the value of the lower curve asymptote, is a scaling parameter, and is a parameter that controls the x-ordinate for the point of inflection for the curve at

The following constraints apply to the curve fit parameters:

The associated response feature vector is

Exponential Growth Curve

This equation defines the exponential growth model.

where α is the value of the upper asymptote, β is the initial size, and $${\rm K}$$ is a scale parameter (time constant controlling the growth rate). The following constraints apply to the fit coefficients:

The response feature vector g for the exponential growth model is defined as

Gompertz Growth Model

Another useful formulation that does not exhibit a symmetric point of inflection is the Gompertz growth model. The defining equation is

where α is the final size, $${\rm K}$$ is a scaling factor, and $$\gamma$$ is the x-ordinate of the point of inflection. The corresponding y-ordinate of the point of inflection occurs at

With maximum growth rate

The following constraints apply to the selection of parameter values for the Gompertz model:

α > 0, $${\rm K}$$ > 0, $$\gamma$$ > 0.

The response feature vector g for the Gompertz growth model is defined as

Examine the Example User-Defined Model

This example demonstrates how to create a user-defined model for the Weibul function:

y = alpha - (alpha - beta).*exp(-(kappa.*x).^delta)

Observe that the file is called by the toolbox using

varargout= weibul(m,x,varargin)

Where the variables are given by

m = the xregusermod object
x = input data as a column vector for fast eval

The first function in the template file is a vectorized evaluation of the function. First, the model parameters are extracted:

b= double(m);

Then, the evaluation occurs:

y = b(1) - (b(1)-b(2)).*exp(-(b(3).*x).^b(4));

Compulsory Local Functions.  Edit these local functions as follows:

Enter the number of input factors. For functions y = f(x) this is 1.

function n= i_nfactors(U,b)
n= 1;

Enter the number of fitted parameters. In this example, there are four parameters in the Weibul model.

function n= i_numparams(U,b)
n= 4;

The following local function returns a column vector of initial values (param) for the parameters to fit. The initial values can be defined to be data-dependent; hence there is a flag to signal if the data is not worth fitting (OK). In weibul.m there is a routine for calculating a data-dependent initial parameter estimate. If no data is supplied, the default parameter values are used.

function [param,OK]= i_initial(U,b,X,Y)
param= [2 1 2 5]';
OK=1;

Optional Local Functions.   You can use the following optional local functions to set additional parameters

function p= i_reconstruct(U,b,Yrf,dG,rfuser) 
%I_RECONSTRUCT nonlinear reconstruction
%
% p = i_reconstruct(m,b,Yrf,dG,rfuser)
%  Inputs
%     Yrf   response feature values
%     dG    default Jacobian of response features
%     rfuser index to the user-defined response features so you can find
%     out which response features are which. rfuser(i) = 0 if the
%     rf is a parameter.
%
% If all response features are linear in model parameters then you do not
% need to define 'i_reconstruct'. 

% reconstruct linear response features using this line
p= Yrf/dG';

% find which response feature is a nonlinear user-defined response feature
f= rfuser>size(p,2);
if ~any(rfuser==3)
   % need to use delta (must be > 1) for reconstruction to work
   p(:,4)= max(p(:,4),1+16*eps);
   
   p(:,3)= ((p(:,4)-1)./p(:,4)).^(1./p(:,4))./Yrf(:,f);
end

Check the Model into the Toolbox

After you create a user-defined model file, save it somewhere on the path.

Check in the model. The check in process ensures that the model you have defined provides an interface that allows the toolbox to evaluate and fit it. If the checkin procedure succeeds, the toolbox registers the model and makes it available for fitting when you use appropriate input data.

At the command-line, with the example file on the path, you need to create a model and some input data, then call checkin. For the user-defined Weibul function, call checkin with the example model, its name, and some appropriate data.

checkin(xregusermod, 'weibul', [0.1:0.01:0.2]');

This returns some command-line output, and a figure appears with the model name and variable names displayed over graphs of input and model evaluation output. The final command-line output:

Model successfully registered for 
Model-Based Calibration Toolbox software.

Verify That the Model Is Checked In

Recover from Editing Errors

If you modify the file that defines a checked-in model that you are currently using, the Model Browser tries to continue.

If the user-defined model has serious errors (e.g., you have altered the number of inputs or parameters, model evaluation, or the file cannot be found), the Model Browser changes the status of the current model to 'Not fitted'.

To recover from this state, first correct the problem in the file. Then (for Local Models) you can select Model > Fit Local to refit. You do not need to check the model in again, but if you have problems the error messages produced during a checkin might be useful in diagnosing faults.

If there is a minor fault with the file, then the Model Browser continues, using default values. Minor errors can include items such as label definitions, that is, faults in i_char, i_label, i_str_func, or i_foptions. A message appears in the command window providing details of these faults.

Create Folders

You can define a dynamic model using a Simulink model and a user-defined transient model file that describes parameters to fit in this model. Create folders for these files that are on the MATLAB path. Then, you must check the files into the Model-Based Calibration Toolbox™ product before you can use them for modeling.

Create Simulink Model

Create a Simulink model to represent your transient system.

Simulink inports represent the model inputs. Time is the first input to the model in Model-Based Calibration Toolbox software, but it is not an inport in the model. The model output is represented by a Simulink output. Only one scalar output is supported in the Model Browser.

Your Simulink model must have some free parameters that Model-Based Calibration Toolbox software will fit by nonlinear least squares. Use the same variable names in the model and the user-defined transient model file.

The Simulink model for the fuelPuddle example appears in the following figure. You will examine the example file (fuelPuddle.m) in a later section.

The block labels are not important. The model returns a single scalar output (here labeled “Mcyl”).

The toolbox defines the model parameters in the Model Workspace. You can see this in the Model Explorer. A vector of all parameters called p is also available.

Model Requirements.  For both continuous and discrete models, the following rules apply:

Create a User-Defined Transient Model File

Define a transient model file for your Simulink model, and this file must have the same name as your Simulink model.

Open the example file fuelPuddle.m (for the fuelPuddle model) to examine the code described in the following sections. Find the file here:

<MATLAB root>\toolbox\mbc\mbcmodels\@xregtransient\fuelPuddle.m

Compulsory Local Functions

Specify the following local functions:

Optional Local Functions

You do not need to edit the remaining local functions unless they are required. The comments in the code describe the role of each function. You use these functions most often when you are creating a user-defined model (see Local Model Class: User-Defined Models).

These labels are used on plots:

function c= i_labels(m,b)
b= {'\tau','x'};

You can use LaTeX notation, and it is correctly formatted. By default, the variable names defined in i_simvars are used to specify parameter names.

Check In to Toolbox

Having created a Simulink model and the corresponding function file, you must save each on the path, as described in Create Folders.

To ensure that the transient model you have defined provides an interface that allows the toolbox to evaluate and fit it, you check in the model. If this procedure succeeds, the toolbox registers the model and makes it available for fitting when you use appropriate input data.

At the command-line, with both template file and Simulink models on the path, create some input data, then call checkin. The procedure follows.

A successful checkin creates some command-line output, and a figure appears with the model name and variable names displayed over graphs of input and model evaluation output. The final command-line output (if checkin is called with a semicolon as in the previous example) is

Model successfully registered for
Model-Based Calibration Toolbox software

Using and Removing Transient Models

The fuelPuddle model is already checked in for you to use. Open the Model Browser and load data that has the necessary format to evaluate this transient model (two local inputs). Time input data must be increasing.

Create a Test Plan with two local input factors (the same number of input factors required by the fuelPuddle model). The Local Model Setup dialog box now offers the following options:

Select the fuelpuddle model, and click OK.

On building a response model with fuelPuddle as the local model, the toolbox fits the two parameters tau and x across all the tests.

Removing Checked-In Models.  To remove a checked-in model, close the Model Browser, and type the following command at the command-line:

remove(xregtransient, 'ModelName')

When you restart the toolbox, the command removes the checked-in transient model.

Power

These determine the weights using a function of the form . Fitting the covariance model involves estimating the parameter .

Exponential

These determine the weights using .

Mixed

These determine the weights using . There are two parameters to estimate, therefore using up another degree of freedom. This might be influential when you choose a covariance model if you are using a small data set.