# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# fitnlm

Fit nonlinear regression model

## Syntax

• mdl = fitnlm(tbl,modelfun,beta0)
example
• mdl = fitnlm(X,y,modelfun,beta0)
example
• mdl = fitnlm(___,modelfun,beta0,Name,Value)
example

## Description

example

mdl = fitnlm(tbl,modelfun,beta0) fits the model specified by modelfun to variables in the table or dataset array tbl, and returns the nonlinear model mdl.

fitnlm estimates model coefficients using an iterative procedure starting from the initial values in beta0.

example

mdl = fitnlm(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.

example

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

## Examples

collapse all

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

Load the data and create a nonlinear model.

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 = fitnlm(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
F-statistic vs. constant model: 283, p-value = 1.79e-113

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

Load the data and create a nonlinear model.

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 = fitnlm(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
F-statistic vs. constant model: 283, p-value = 1.79e-113

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.

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 = fitnlm(X,y,modelfun,beta0,'Options',opts);
Norm of         Norm of
-----------------------------------------------------------
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 a nonlinear regression model for estimation using a function handle or model syntax.

X = S.reactants;
y = S.rate;
beta0 = S.beta;

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

mdl = fitnlm(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
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

Alternatively, you can use an 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 = fitnlm(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
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

Generate sample data from the nonlinear regression model

$y={b}_{1}+{b}_{2}\mathrm{exp}\left\{-{b}_{3}x\right\}+\epsilon ,$

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 an expression to specify the model.

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

mdl = fitnlm(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
F-statistic vs. constant model: 203, p-value = 2.34e-35

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 = fitnlm(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
F-statistic vs. zero model: 1.14e+03, p-value = 3.49e-11

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 = fitnlm(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
F-statistic vs. zero model: 3.91e+03, p-value = 2.54e-13

## Input Arguments

collapse all

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.

You specify the response and predictor names in your model specification. If you do not specify a model, you can set a different column as the response variable by using the ResponseVar name-value pair argument. You can select a subset of the columns as predictors by using the PredictorVars name-value pair argument.

Data Types: single | double | logical

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.

Data Types: single | double | logical

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

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.

• Character vector 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.

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.

Example: 'ErrorModel','combined','Exclude',2,'Options',opt specifies the error model as the combined model, excludes the second observation from the fit, and uses the options defined in the structure opt to control the iterative fitting procedure.

collapse all

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

Data Types: char

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) $y=f+ae$ 'proportional' $y=f+bfe$ 'combined' $y=f+\left(a+b|f|\right)e$

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'

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: single | double

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 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('fitnlm').

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 and Machine Learning 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'
FunValCheckCharacter vector 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

Predictor variables to use in the fit, specified as the comma-separated pair consisting of 'PredictorVars' and either a cell array of character vectors 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 character vectors 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

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

If you specify a model, it specifies the response variable. Otherwise, when fitting a table or dataset array, 'ResponseVar' indicates which variable fitnlm should use as the response.

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

Names of variables in fit, specified as the comma-separated pair consisting of 'VarNames' and a cell array of character vectors 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

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

collapse all

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.

collapse all

### 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

### Algorithms

fitnlm uses the same fitting algorithm as nlinfit.

## 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.