# Documentation

### This is machine translation

Translated by
Mouse over 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.

```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 = 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 R-Squared: 0.745, Adjusted R-Squared 0.743 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.

```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 = 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 R-Squared: 0.745, Adjusted R-Squared 0.743 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.

```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 = fitnlm(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 a nonlinear regression model for estimation using a function handle or model syntax.

```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 = 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 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 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 R-Squared: 0.999, Adjusted R-Squared 0.998 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 R-Squared: 0.807, Adjusted R-Squared 0.803 F-statistic vs. constant model: 203, p-value = 2.34e-35```

```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 = 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 R-Squared: 0.998, Adjusted R-Squared 0.998 F-statistic vs. zero model: 1.14e+03, p-value = 3.49e-11```

```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 = 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 R-Squared: 0.999, Adjusted R-Squared 0.998 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'`a`1`
`'proportional'`b`1`
`'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
`DerivStep`Relative 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)`
`Display`Amount 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'`
`FunValCheck`Character vector indicating to check for invalid values, such as `NaN` or `Inf`, from the model function.`'on'`
`MaxIter`Maximum number of iterations allowed. Positive integer.`200`
`RobustWgtFun`Weight 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`[]`
`Tune`Tuning 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`.
`TolFun`Termination tolerance for the objective function value. Positive scalar.`1e-8`
`TolX`Termination 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) ./ r`1.339
`'bisquare'` (default)`w = (abs(r)<1) .* (1 - r.^2).^2`4.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) ./ r`1.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.