Documentation Center

  • Trials
  • Product Updates

NonLinearModel.fit

Class: NonLinearModel

Fit nonlinear regression model

NonLinearModel.fit will be removed in a future release. Use fitnlm instead.

Syntax

mdl = NonLinearModel.fit(tbl,modelfun,beta0)
mdl = NonLinearModel.fit(X,y,modelfun,beta0)
mdl = NonLinearModel.fit(...,modelfun,beta0,Name,Value)

Description

mdl = NonLinearModel.fit(tbl,modelfun,beta0) fits the model specified by modelfun to variables in the table or dataset array tbl, and returns the nonlinear model mdl. NonLinearModel.fit estimates model coefficients using an iterative procedure starting from the initial values in beta0.

mdl = NonLinearModel.fit(X,y,modelfun,beta0) fits a nonlinear regression model using the column vector y as a response variable and the columns of the matrix X as predictor variables.

mdl = NonLinearModel.fit(...,modelfun,beta0,Name,Value) fits a nonlinear regression model with additional options specified by one or more Name,Value pair arguments.

Input Arguments

expand all

tbl — Input datatable | dataset array

Input data, specified as a table or dataset array. If you do not specify the predictor and response variables, the last variable is the response variable and the others are the predictor variables by default.

Predictor variables and response variable must be numeric.

To set a different column as the response variable, use the ResponseVar name-value pair argument. To use a subset of the columns as predictors, use the PredictorVars name-value pair argument.

Data Types: single | double | logical

X — Predictor variablesmatrix

Predictor variables, specified as an n-by-p matrix, where n is the number of observations and p is the number of predictor variables. Each column of X represents one variable, and each row represents one observation.

By default, there is a constant term in the model, unless you explicitly remove it, so do not include a column of 1s in X.

Data Types: single | double | logical

y — Response variablevector

Response variable, specified as an n-by-1 vector, where n is the number of observations. Each entry in y is the response for the corresponding row of X.

Data Types: single | double

modelfun — Functional form of the modelfunction handle | string of the form 'y ~ f(b1,b2,...,bj,x1,x2,...,xk)'

Functional form of the model, specified as either of the following.

  • Function handle @modelfun or @(b,x)modelfun, where

    • b is a coefficient vector with the same number of elements as beta0.

    • x is a matrix with the same number of columns as X or the number of predictor variable columns of tbl.

    modelfun(b,x) returns a column vector that contains the same number of rows as x. Each row of the vector is the result of evaluating modelfun on the corresponding row of x. In other words, modelfun is a vectorized function, one that operates on all data rows and returns all evaluations in one function call. modelfun should return real numbers to obtain meaningful coefficients.

  • String of the form 'y ~ f(b1,b2,...,bj,x1,x2,...,xk)', where f represents a scalar function of the scalar coefficient variables b1,...,bj and the scalar data variables x1,...,xk.

beta0 — Coefficientsnumeric vector

Coefficients for the nonlinear model, specified as a numeric vector. NonLinearModel starts its search for optimal coefficients from beta0.

Data Types: single | double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'CoefficientNames' — Names of the model coefficients{'b1','b2',...,'bk'} (default) | cell array of strings

Names of the model coefficients, specified as a cell array of strings.

Data Types: char

'ErrorModel' — Form of the error variance model'constant' (default) | 'proportional' | 'combined'

Form of the error variance model, specified as one of the following. Each model defines the error using a standard mean-zero and unit-variance variable e in combination with independent components: the function value f, and one or two parameters a and b

'constant' (default)
'proportional'
'combined'

The only allowed error model when using Weights is 'constant'.

    Note:   options.RobustWgtFun must have value [] when using an error model other than 'constant'.

Example: 'ErrorModel','proportional'

'ErrorParameters' — Initial estimates of the error model parametersnumeric array

Initial estimates of the error model parameters for the chosen ErrorModel, specified as a numeric array.

Error ModelParametersDefault Values
'constant'a1
'proportional'b1
'combined'a, b[1,1]

You can only use the 'constant' error model when using Weights.

    Note:   options.RobustWgtFun must have value [] when using an error model other than 'constant'.

For example, if 'ErrorModel' has the value 'combined', you can specify the starting value 1 for a and the starting value 2 for b as follows.

Example: 'ErrorParameters',[1,2]

Data Types: char

'Exclude' — Observations to excludelogical or numeric index vector

Observations to exclude from the fit, specified as the comma-separated pair consisting of 'Exclude' and a logical or numeric index vector indicating which observations to exclude from the fit.

For example, you can exclude observations 2 and 3 out of 6 using either of the following examples.

Example: 'Exclude',[2,3]

Example: 'Exclude',logical([0 1 1 0 0 0])

Data Types: single | double | logical

'Options' — Options for controlling the iterative fitting procedure[ ] (default) | structure

Options for controlling the iterative fitting procedure, specified as a structure created by statset. The relevant fields are the nonempty fields in the structure returned by the call statset('nlinfit').

OptionMeaningDefault
DerivStepRelative difference used in finite difference derivative calculations. A positive scalar, or a vector of positive scalars the same size as the vector of parameters estimated by the Statistics Toolbox™ function using the options structure.eps^(1/3)
DisplayAmount of information displayed by the fitting algorithm.
  • 'off' — Displays no information.

  • 'final' — Displays the final output.

  • 'iter' — Displays iterative output to the Command Window.

'off'
FunValCheckString indicating to check for invalid values, such as NaN or Inf, from the model function.'on'
MaxIterMaximum number of iterations allowed. Positive integer.200
RobustWgtFunWeight function for robust fitting. Can also be a function handle that accepts a normalized residual as input and returns the robust weights as output. If you use a function handle, give a Tune constant. See Robust Options[]
TuneTuning constant used in robust fitting to normalize the residuals before applying the weight function. A positive scalar. Required if the weight function is specified as a function handle.See Robust Options for the default, which depends on RobustWgtFun.
TolFunTermination tolerance for the objective function value. Positive scalar.1e-8
TolXTermination tolerance for the parameters. Positive scalar.1e-8

Data Types: struct

'PredictorVars' — Predictor variablescell array of strings | logical or numeric index vector

Predictor variables to use in the fit, specified as the comma-separated pair consisting of 'PredictorVars' and either a cell array of strings of the variable names in the table or dataset array tbl, or a logical or numeric index vector indicating which columns are predictor variables.

The strings should be among the names in tbl, or the names you specify using the 'VarNames' name-value pair argument.

The default is all variables in X, or all variables in tbl except for ResponseVar.

For example, you can specify the second and third variables as the predictor variables using either of the following examples.

Example: 'PredictorVars',[2,3]

Example: 'PredictorVars',logical([0 1 1 0 0 0])

Data Types: single | double | logical | cell

'ResponseVar' — Response variablelast column in tbl (default) | string for variable name | logical or numeric index vector

Response variable to use in the fit, specified as the comma-separated pair consisting of 'ResponseVar' and either a string of the variable name in the table or dataset array tbl, or a logical or numeric index vector indicating which column is the response variable. You typically need to use 'ResponseVar' when fitting a table or dataset array tbl.

For example, you can specify the fourth variable, say yield, as the response out of six variables, in one of the following ways.

Example: 'ResponseVar','yield'

Example: 'ResponseVar',[4]

Example: 'ResponseVar',logical([0 0 0 1 0 0])

Data Types: single | double | logical | char

'VarNames' — Names of variables in fit{'x1','x2',...,'xn','y'} (default) | cell array of strings

Names of variables in fit, specified as the comma-separated pair consisting of 'VarNames' and a cell array of strings including the names for the columns of X first, and the name for the response variable y last.

'VarNames' is not applicable to variables in a table or dataset array, because those variables already have names.

For example, if in your data, horsepower, acceleration, and model year of the cars are the predictor variables, and miles per gallon (MPG) is the response variable, then you can name the variables as follows.

Example: 'VarNames',{'Horsepower','Acceleration','Model_Year','MPG'}

Data Types: cell

'Weights' — Observation weightsones(n,1) (default) | vector of nonnegative scalar values | function handle

Observation weights, specified as a vector of nonnegative scalar values or function handle.

  • If you specify a vector, then it must have n elements, where n is the number of rows in tbl or y.

  • If you specify a function handle, then the function must accept a vector of predicted response values as input, and return a vector of real positive weights as output.

Given weights, W, NonLinearModel estimates the error variance at observation i by MSE*(1/W(i)), where MSE is the mean squared error.

Data Types: single | double | function_handle

Output Arguments

expand all

mdl — Nonlinear modelNonLinearModel object

Nonlinear model representing a least-squares fit of the response to the data, returned as a NonLinearModel object.

If the Options structure contains a nonempty RobustWgtFun field, the model is not a least-squares fit, but uses the RobustWgtFun robust fitting function.

For properties and methods of the nonlinear model object, mdl, see the NonLinearModel class page.

Definitions

Robust Options

Weight FunctionEquationDefault Tuning Constant
'andrews'w = (abs(r)<pi) .* sin(r) ./ r1.339
'bisquare' (default)w = (abs(r)<1) .* (1 - r.^2).^24.685
'cauchy'w = 1 ./ (1 + r.^2)2.385
'fair'w = 1 ./ (1 + abs(r))1.400
'huber'w = 1 ./ max(1, abs(r))1.345
'logistic'w = tanh(r) ./ r1.205
'talwar'w = 1 * (abs(r)<1)2.795
'welsch'w = exp(-(r.^2))2.985
[]No robust fitting

Examples

expand all

Nonlinear Model from a Table

Create a nonlinear model for auto mileage based on the carbig data.

Load the data and create a nonlinear model.

load carbig
tbl = table(Horsepower,Weight,MPG);
modelfun = @(b,x)b(1) + b(2)*x(:,1).^b(3) + ...
    b(4)*x(:,2).^b(5);
beta0 = [-50 500 -1 500 -1];
mdl = NonLinearModel.fit(tbl,modelfun,beta0)
mdl = 


Nonlinear regression model:
    MPG ~ b1 + b2*Horsepower^b3 + b4*Weight^b5

Estimated Coefficients:
          Estimate      SE        tStat       pValue 
          ________    _______    ________    ________

    b1     -49.383     119.97    -0.41164     0.68083
    b2      376.43     567.05     0.66384     0.50719
    b3    -0.78193    0.47168     -1.6578    0.098177
    b4      422.37     776.02     0.54428     0.58656
    b5    -0.24127    0.48325    -0.49926     0.61788


Number of observations: 392, Error degrees of freedom: 387
Root Mean Squared Error: 3.96
R-Squared: 0.745,  Adjusted R-Squared 0.743
F-statistic vs. constant model: 283, p-value = 1.79e-113

Nonlinear Model from Matrix Data

Create a nonlinear model for auto mileage based on the carbig data.

Load the data and create a nonlinear model.

load carbig
X = [Horsepower,Weight];
y = MPG;
modelfun = @(b,x)b(1) + b(2)*x(:,1).^b(3) + ...
    b(4)*x(:,2).^b(5);
beta0 = [-50 500 -1 500 -1];
mdl = NonLinearModel.fit(X,y,modelfun,beta0)
mdl = 


Nonlinear regression model:
    y ~ b1 + b2*x1^b3 + b4*x2^b5

Estimated Coefficients:
          Estimate    SE         tStat       pValue  
    b1     -49.383     119.97    -0.41164     0.68083
    b2      376.43     567.05     0.66384     0.50719
    b3    -0.78193    0.47168     -1.6578    0.098177
    b4      422.37     776.02     0.54428     0.58656
    b5    -0.24127    0.48325    -0.49926     0.61788


Number of observations: 392, Error degrees of freedom: 387
Root Mean Squared Error: 3.96
R-Squared: 0.745,  Adjusted R-Squared 0.743
F-statistic vs. constant model: 283, p-value = 1.79e-113

Adjust Fitting Options in the Nonlinear Model

Create a nonlinear model for auto mileage based on the carbig data. Strive for more accuracy by lowering the TolFun option, and observe the iterations by setting the Display option.

Load the data and create a nonlinear model.

load carbig
X = [Horsepower,Weight];
y = MPG;
modelfun = @(b,x)b(1) + b(2)*x(:,1).^b(3) + ...
    b(4)*x(:,2).^b(5);
beta0 = [-50 500 -1 500 -1];

Create options to lower TolFun and to report iterative display, and create a model using the options.

opts = statset('Display','iter','TolFun',1e-10);
mdl = NonLinearModel.fit(X,y,modelfun,beta0,'Options',opts);
                                     Norm of         Norm of
   Iteration             SSE        Gradient           Step 
  -----------------------------------------------------------
           0     1.82248e+06
           1          678600          788810         1691.07
           2          616716     6.12739e+06         45.4738

%%%     Many iterations deleted   %%%

         122         6068.48         1.56393        0.629325
         123         6068.48         1.13809        0.432543
         124         6068.48        0.295962        0.297511
Iterations terminated: relative change in SSE less than OPTIONS.TolFun

Specify Nonlinear Regression Using Model String Syntax

Specify a nonlinear regression model for estimation using a function handle or model string syntax.

Load sample data.

S = load('reaction');
X = S.reactants;
y = S.rate;
beta0 = S.beta;

Use a function handle to specify the Hougen-Watson model for the rate data.

mdl = NonLinearModel.fit(X,y,@hougen,beta0)
mdl = 


Nonlinear regression model:
    y ~ hougen(b,X)

Estimated Coefficients:
          Estimate    SE          tStat     pValue 
    b1      1.2526     0.86701    1.4447    0.18654
    b2    0.062776    0.043561    1.4411    0.18753
    b3    0.040048    0.030885    1.2967    0.23089
    b4     0.11242    0.075157    1.4957    0.17309
    b5      1.1914     0.83671    1.4239     0.1923


Number of observations: 13, Error degrees of freedom: 8
Root Mean Squared Error: 0.193
R-Squared: 0.999,  Adjusted R-Squared 0.998
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

Alternatively, you can use a string expression to specify the Hougen-Watson model for the rate data.

myfun = 'y~(b1*x2-x3/b5)/(1+b2*x1+b3*x2+b4*x3)';
mdl2 = NonLinearModel.fit(X,y,myfun,beta0)
mdl2 = 


Nonlinear regression model:
    y ~ (b1*x2 - x3/b5)/(1 + b2*x1 + b3*x2 + b4*x3)

Estimated Coefficients:
          Estimate    SE          tStat     pValue 
    b1      1.2526     0.86701    1.4447    0.18654
    b2    0.062776    0.043561    1.4411    0.18753
    b3    0.040048    0.030885    1.2967    0.23089
    b4     0.11242    0.075157    1.4957    0.17309
    b5      1.1914     0.83671    1.4239     0.1923


Number of observations: 13, Error degrees of freedom: 8
Root Mean Squared Error: 0.193
R-Squared: 0.999,  Adjusted R-Squared 0.998
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

Estimate Nonlinear Regression Using Robust Fitting Options

Generate sample data from the nonlinear regression model

where b1, b2, and b3 are coefficients, and the error term is normally distributed with mean 0 and standard deviation 0.5.

modelfun = @(b,x)(b(1)+b(2)*exp(-b(3)*x));

rng('default') % for reproducibility
b = [1;3;2];
x = exprnd(2,100,1);
y = modelfun(b,x) + normrnd(0,0.5,100,1);

Set robust fitting options.

opts = statset('nlinfit');
opts.RobustWgtFun = 'bisquare';

Fit the nonlinear model using the robust fitting options. Here, use a string expression to specify the model.

b0 = [2;2;2];
modelstr = 'y ~ b1 + b2*exp(-b3*x)';

mdl = NonLinearModel.fit(x,y,modelstr,b0,'Options',opts)
mdl = 


Nonlinear regression model (robust fit):
    y ~ b1 + b2*exp( - b3*x)

Estimated Coefficients:
          Estimate    SE         tStat     pValue    
    b1    1.0218      0.07202    14.188    2.1344e-25
    b2    3.6619      0.25429    14.401     7.974e-26
    b3    2.9732      0.38496    7.7232    1.0346e-11


Number of observations: 100, Error degrees of freedom: 97
Root Mean Squared Error: 0.501
R-Squared: 0.807,  Adjusted R-Squared 0.803
F-statistic vs. constant model: 203, p-value = 2.34e-35

Fit Nonlinear Regression Model Using Weights Function Handle

Load sample data.

S = load('reaction');
X = S.reactants;
y = S.rate;
beta0 = S.beta;

Specify a function handle for observation weights. The function accepts the model fitted values as input, and returns a vector of weights.

 a = 1; b = 1;
 weights = @(yhat) 1./((a + b*abs(yhat)).^2);

Fit the Hougen-Watson model to the rate data using the specified observation weights function.

mdl = NonLinearModel.fit(X,y,@hougen,beta0,'Weights',weights)
mdl = 


Nonlinear regression model:
    y ~ hougen(b,X)

Estimated Coefficients:
          Estimate    SE          tStat     pValue 
    b1     0.83085     0.58224     1.427    0.19142
    b2     0.04095    0.029663    1.3805    0.20477
    b3    0.025063    0.019673     1.274    0.23842
    b4    0.080053    0.057812    1.3847    0.20353
    b5      1.8261       1.281    1.4256    0.19183


Number of observations: 13, Error degrees of freedom: 8
Root Mean Squared Error: 0.037
R-Squared: 0.998,  Adjusted R-Squared 0.998
F-statistic vs. zero model: 1.14e+03, p-value = 3.49e-11

Nonlinear Regression Model Using Nonconstant Error Model

Load sample data.

S = load('reaction');
X = S.reactants;
y = S.rate;
beta0 = S.beta;

Fit the Hougen-Watson model to the rate data using the combined error variance model.

mdl = NonLinearModel.fit(X,y,@hougen,beta0,'ErrorModel','combined')
mdl = 


Nonlinear regression model:
    y ~ hougen(b,X)

Estimated Coefficients:
          Estimate    SE          tStat     pValue 
    b1      1.2526     0.86702    1.4447    0.18654
    b2    0.062776    0.043561    1.4411    0.18753
    b3    0.040048    0.030885    1.2967    0.23089
    b4     0.11242    0.075158    1.4957    0.17309
    b5      1.1914     0.83671    1.4239     0.1923


Number of observations: 13, Error degrees of freedom: 8
Root Mean Squared Error: 1.27
R-Squared: 0.999,  Adjusted R-Squared 0.998
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

Algorithms

NonLinearModel.fit uses the same fitting algorithm as nlinfit.

Alternatives

You can also construct a nonlinear model using fitnlm.

References

[1] Seber, G. A. F., and C. J. Wild. Nonlinear Regression. Hoboken, NJ: Wiley-Interscience, 2003.

[2] DuMouchel, W. H., and F. L. O'Brien. "Integrating a Robust Option into a Multiple Regression Computing Environment." Computer Science and Statistics: Proceedings of the 21st Symposium on the Interface. Alexandria, VA: American Statistical Association, 1989.

[3] Holland, P. W., and R. E. Welsch. "Robust Regression Using Iteratively Reweighted Least-Squares." Communications in Statistics: Theory and Methods, A6, 1977, pp. 813–827.

See Also

|

More About

Was this topic helpful?