fitmnr

Fit multinomial regression model

Since R2023a

Syntax

``MnrMdl = fitmnr(X,Y)``
``MnrMdl = fitmnr(Tbl,Y)``
``MnrMdl = fitmnr(Tbl,ResponseVarName)``
``MnrMdl = fitmnr(Tbl,Formula)``
``MnrMdl = fitmnr(___,Name=Value)``

Description

example

````MnrMdl = fitmnr(X,Y)` fits a multinomial regression model and returns a `MultinomialRegression` object `MnrMdl` for the predictor data in the matrix `X` and the response data in `Y`. The input `Y` can be a matrix of counts or a vector of response variable classes. ```
````MnrMdl = fitmnr(Tbl,Y)` uses the variables in `Tbl` as the predictor data. Each table variable corresponds to a different predictor variable.```
````MnrMdl = fitmnr(Tbl,ResponseVarName)` uses the variables in `Tbl` as the predictor and response data. The `ResponseVarName` argument specifies which variable contains the response data.```

example

````MnrMdl = fitmnr(Tbl,Formula)` specifies the multinomial regression model in Wilkinson Notation. The terms in `Formula` use only the variable names in `Tbl`.```

example

````MnrMdl = fitmnr(___,Name=Value)` specifies options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes. For example, you can specify the link function and the model type.```

Examples

collapse all

Load the `fisheriris` data set.

`load fisheriris`

The column vector `species` contains iris flowers of three different species: setosa, versicolor, virginica. The double matrix `meas` contains of four types of measurements for the flowers: the length and width of sepals and petals in centimeters. The data in `species` is nominal, meaning that no natural order exists among the iris species.

Use the `unique` function to display the iris species in order of their first appearance in the `species` vector.

`unique(species)`
```ans = 3x1 cell {'setosa' } {'versicolor'} {'virginica' } ```

The output shows that virginica is the last species in the `species` vector.

Fit a nominal multinomial regression model for the predictor data in `meas` and the response data in `species`. By default, the `fitmnr` function uses virginica as the reference category because it appears last in `species`.

`MnrModel = fitmnr(meas,species)`
```MnrModel = Multinomial regression with nominal responses Value SE tStat pValue _______ ______ _______ __________ (Intercept_setosa) 2018.4 12.404 162.72 0 x1_setosa 673.85 3.5783 188.32 0 x2_setosa -568.2 3.176 -178.9 0 x3_setosa -516.44 3.5403 -145.87 0 x4_setosa -2760.9 7.1203 -387.75 0 (Intercept_versicolor) 42.638 5.2719 8.0878 6.0776e-16 x1_versicolor 2.4652 1.1228 2.1956 0.028124 x2_versicolor 6.6809 1.4789 4.5176 6.2559e-06 x3_versicolor -9.4294 1.2934 -7.2906 3.086e-13 x4_versicolor -18.286 2.0967 -8.7214 2.7476e-18 150 observations, 290 error degrees of freedom Dispersion: 1 Chi^2-statistic vs. constant model: 317.6851, p-value = 7.0555e-64 ```

`MnrModel` is a multinomial regression model object that contains the results of fitting a nominal multinomial regression model to the data. The output shows coefficient statistics for each predictor in `meas`. The small p-values in the column `pValue` indicate that all coefficients are statistically significant at the 95% confidence level.

Investigate the general form of the model equations by using the `Formula` property of `MnrModel`.

`MnrModel.Formula`
```ans = logit(y) ~ 1 + x1 + x2 + x3 + x4 ```

The output shows that the link function for `MnrModel` is the default multinomial `logit` link function. You can use the fitted model coefficients and the general form of the model equations to write these fitted model equations:

`$\mathrm{ln}\left(\frac{{\pi }_{setosa}}{{\pi }_{virginica}}\right)=2018.4+673.9{x}_{1}-568.2{x}_{2}-516.4{x}_{3}-2760.9{x}_{4}$`

`$\mathrm{ln}\left(\frac{{\pi }_{versicolor}}{{\pi }_{virginica}}\right)=42.6+2.5{x}_{1}+6.7{x}_{2}-9.4{x}_{3}-18.3{x}_{4}$`

The equations describe the effects of the predictor variables on the quotient of the probability of a flower being in a category by the probability of a flower being in the reference category. For example, the estimated coefficient 2.5 in the second equation indicates that the probability of a flower being versicolor divided by the probability of a flower being virginica increases exp(2.5) times for each unit increase in ${x}_{1}$. For more information about nominal multinomial regression model equations, see Multinomial Models for Nominal Responses.

Load the `fisheriris` data set.

`load fisheriris`

The column vector `species` contains iris flowers of three different species: setosa, versicolor, virginica. The double matrix `meas` contains of four types of measurements for the flowers: the length and width of sepals and petals in centimeters.

Create a table containing the flower measurements and the species data by using the `table` function.

```tbl = table(meas(:,1),meas(:,2),meas(:,3),meas(:,4),species,... VariableNames=["Sepal_Length","Petal_Length","Sepal_Width","Petal_Width","Species"])```
```tbl=150×5 table Sepal_Length Petal_Length Sepal_Width Petal_Width Species ____________ ____________ ___________ ___________ __________ 5.1 3.5 1.4 0.2 {'setosa'} 4.9 3 1.4 0.2 {'setosa'} 4.7 3.2 1.3 0.2 {'setosa'} 4.6 3.1 1.5 0.2 {'setosa'} 5 3.6 1.4 0.2 {'setosa'} 5.4 3.9 1.7 0.4 {'setosa'} 4.6 3.4 1.4 0.3 {'setosa'} 5 3.4 1.5 0.2 {'setosa'} 4.4 2.9 1.4 0.2 {'setosa'} 4.9 3.1 1.5 0.1 {'setosa'} 5.4 3.7 1.5 0.2 {'setosa'} 4.8 3.4 1.6 0.2 {'setosa'} 4.8 3 1.4 0.1 {'setosa'} 4.3 3 1.1 0.1 {'setosa'} 5.8 4 1.2 0.2 {'setosa'} 5.7 4.4 1.5 0.4 {'setosa'} ⋮ ```

Fit a multinomial regression model to the flower data using the measurements as the predictor data and the species as the response data. By default, `fitmnr` uses virginica as the reference category because it appears last the `Species` column of `tbl`. Specify the formula for the regression model to investigate whether the interaction between sepal width and sepal length is statistically significant.

`MnrModel = fitmnr(tbl,"Species ~ Sepal_Width*Sepal_Length + Petal_Width + Petal_Length")`
```MnrModel = Multinomial regression with nominal responses Value SE tStat pValue _______ ______ ________ ___________ (Intercept_setosa) 232.64 50.281 4.6268 3.7137e-06 Sepal_Length_setosa 11.918 10.31 1.156 0.24768 Petal_Length_setosa 27.965 4.5863 6.0975 1.0775e-09 Sepal_Width_setosa -5.2318 13.66 -0.38302 0.70171 Petal_Width_setosa -260.77 9.3403 -27.919 1.5677e-171 Sepal_Length:Sepal_Width_setosa -10.453 2.2141 -4.7211 2.3452e-06 (Intercept_versicolor) -231.52 43.626 -5.3068 1.1158e-07 Sepal_Length_versicolor 48.459 8.178 5.9255 3.1133e-09 Petal_Length_versicolor 7.5712 1.7854 4.2406 2.2288e-05 Sepal_Width_versicolor 47.602 9.5989 4.9591 7.0832e-07 Petal_Width_versicolor -20.603 2.7859 -7.3955 1.4089e-13 Sepal_Length:Sepal_Width_versicolor -9.5086 1.7102 -5.5598 2.7005e-08 150 observations, 288 error degrees of freedom Dispersion: 1 Chi^2-statistic vs. constant model: 318.3928, p-value = 1.9971e-62 ```

`MnrModel` is a multinomial regression model object that contains the results of fitting a (default) nominal multinomial regression model to the data. The output shows coefficient statistics for each predictor in `meas`. The small p-value for the interaction term in each log odds equation indicates that the interaction between sepal length and sepal width has a statistically significant effect on the log quotient of the probability of a flower being in a category by the probability of a flower being in the reference category. For more information about nominal multinomial regression model equations, see Multinomial Models for Nominal Responses.

Load the `carbig` data set.

`load carbig`

The variables `Acceleration`, `Displacement`, `Horsepower`, and `Weight` contain data for car acceleration, engine displacement, horsepower, and weight, respectively. The variable `MPG` contains car mileage data.

Sort the data in `MPG` into four categories using the `discretize` function. Create a table of predictor data using the `table` function.

```mileage = discretize(MPG,[9,19,29,39,48],"categorical"); X = table(Acceleration,Displacement,Horsepower,Weight,mileage,VariableNames=["Acceleration","Displacement","Horsepower","Weight","Mileage"])```
```X=406×5 table Acceleration Displacement Horsepower Weight Mileage ____________ ____________ __________ ______ ___________ 12 307 130 3504 [9, 19) 11.5 350 165 3693 [9, 19) 11 318 150 3436 [9, 19) 12 304 150 3433 [9, 19) 10.5 302 140 3449 [9, 19) 10 429 198 4341 [9, 19) 9 454 220 4354 [9, 19) 8.5 440 215 4312 [9, 19) 10 455 225 4425 [9, 19) 8.5 390 190 3850 [9, 19) 17.5 133 115 3090 <undefined> 11.5 350 165 4142 <undefined> 11 351 153 4034 <undefined> 10.5 383 175 4166 <undefined> 11 360 175 3850 <undefined> 10 383 170 3563 [9, 19) ⋮ ```

The `Mileage` column of the table `X` contains entries that are undefined.

Fit an ordinal multinomial regression model using `Acceleration`, `Displacement`, `Horsepower`, and `Weight` as predictor variables and `Mileage` as the response variable. `fitmnr` ignores the rows of `X` containing the undefined entries in the `Mileage` column.

`MnrModel = fitmnr(X,"Mileage",ModelType="ordinal")`
```MnrModel = Multinomial regression with ordinal responses Value SE tStat pValue _________ __________ _______ __________ (Intercept_[9, 19)) -16.69 1.9529 -8.5459 1.2757e-17 (Intercept_[19, 29)) -11.721 1.768 -6.6296 3.3667e-11 (Intercept_[29, 39)) -8.0606 1.7297 -4.6601 3.1603e-06 Acceleration 0.10476 0.079916 1.3109 0.18989 Displacement 0.010336 0.0049035 2.1078 0.035045 Horsepower 0.06452 0.01476 4.3712 1.2354e-05 Weight 0.0016638 0.00066089 2.5175 0.011821 392 observations, 1169 error degrees of freedom Dispersion: 1 Chi^2-statistic vs. constant model: 503.6344, p-value = 1.0964e-107 ```

`MnrModel` is a multinomial regression model object that contains the results of fitting an ordinal multinomial regression model to the data. The output shows coefficient statistics for each predictor in `X`. By default, `fitmnr` uses the `logit` link function and calculates common coefficients among the ordinal response categories. This type of model is sometimes called a proportional odds model. At the 95% confidence level, the $p$-values of 0.035045, 1.2354e-05, and 0.011821 indicate that each of the variables `Displacement`, `Horsepower`, and `Weight` has a statistically significant effect on a log quotient of probabilities. The numerator is the probability of a car's mileage being less than or equal to a certain value, and the denominator is the probability of a car's mileage being greater than that value.

You can use the fitted model coefficients and the general form of the model equations to write these fitted model equations:

`$\begin{array}{l}\mathrm{ln}\left(\frac{P\left({X}_{M}\le 19\right)}{P\left({X}_{M}>19\right)}\right)=-16.69+0.10476{X}_{A}+0.010336{X}_{D}+0.06452{X}_{H}+0.0016638{X}_{W}\end{array}$`

`$\begin{array}{l}\mathrm{ln}\left(\frac{P\left({X}_{M}\le 29\right)}{P\left({X}_{M}>29\right)}\right)=-11.721+0.10476{X}_{A}+0.010336{X}_{D}+0.06452{X}_{H}+0.0016638{X}_{W}\end{array}$`

`$\begin{array}{l}\mathrm{ln}\left(\frac{P\left({X}_{M}\le 39\right)}{P\left({X}_{M}>39\right)}\right)=-8.0606+0.10476{X}_{A}+0.010336{X}_{D}+0.06452{X}_{H}+0.0016638{X}_{W}\end{array}$`

${X}_{M}$, ${X}_{A}$, ${X}_{D}$, ${X}_{H}$, and ${X}_{W}$ represent the `Mileage`, `Acceleration`, `Displacement`, `Horsepower`, and `Weight` variables in `X`, respectively. For more information about the equations and the significance of terms in an ordinal multinomial regression model, see Multinomial Models for Ordinal Responses.

Input Arguments

collapse all

Predictor data, specified as an n-by-p numeric matrix, where n is the number of observations in the data set and p is the number of predictor variables. Each row of `X` corresponds to an observation, and each column corresponds to a predictor variable.

Note

`fitmnr` automatically includes a constant term (intercept) in all models. Do not include a column of 1s in `X`.

Data Types: `single` | `double`

Response category labels, specified as an n-by-k matrix, or an n-by-1 numeric vector, logical vector, string vector, categorical array, or cell array of character vectors.

• If `Y` is an n-by-k matrix, n is the number of observations in the data set, and k is the number of response categories. Y(i,j) is the number of outcomes of the multinomial category j for the predictor combinations given by X(i,:). In this case, the function determines the number of observations at each predictor combination.

• If `Y` is an n-by-1 numeric vector, logical vector, string vector, categorical array, or cell array of character vectors, the value of the vector or array indicates the response for each observation. In this case, all sample sizes are 1.

Data Types: `single` | `double` | `logical` | `char` | `string` | `cell` | `categorical`

Predictor and response data, specified as a table. The variables of `Tbl` can contain numeric or categorical data. When you specify `Tbl`, you must also specify the response data using the input argument `Y`, `ResponseVarName`, or `Formula`.

• If you specify the response data in `Y`, the table variables represent only the predictor data for the multinomial regression. A row of predictor values in `Tbl` corresponds to the observation in `Y` at the same position. `Tbl` must have the same number of rows as the length of `Y`.

• If you do not specify `Y`, you must indicate which variable in `Tbl` contains the response data by using the `ResponseVarName` or `Formula` input argument. You can also choose a subset of factors in `Tbl` to use in the multinomial regression by setting the `PredictorNames` name-value argument. The `fitmnr` function associates the values of the predictor variables in `Tbl` with the response data in the same row.

Example: ```snake=table(weight,length,species); fitmnr(snake,"species")```

Data Types: `table`

Name of the variable to use as the response, specified as a string scalar or character vector. `ResponseVarName` indicates which variable in `Tbl` contains the response data. When you specify `ResponseVarName`, you must also specify the `Tbl` input argument.

Example: ```snake=table(weight,length,species); fitmnr(snake,"species")```

Data Types: `char` | `string`

Multinomial regression model to fit, specified as a string scalar or a character vector in Wilkinson notation.

Example: Specify the multinomial regression model as a sum of the variables `meas1`, `meas2`, and `meas3` and their three-way interaction by using the formula ```"species ~ meas1 + meas2 + meas3 + meas1:meas2:meas3"```.

Data Types: `char` | `string`

Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: `fitmnr(X,Y,Link="probit",ModelType="ordinal",CategoricalPredictors=[1,2])` specifies `"probit"` as the link function for an ordinal multinomial regression model, and specifies the first two columns in `X` as categorical variables.

Predictors to treat as categorical, specified as a numeric or string vector, a cell array of character vectors, or `"all"`.

Specify `CategoricalPredictors` as one of the following:

• Numeric vector of indices between 1 and p, where p is the number of predictor variables. The index of a predictor variable is the order in which it appears in the columns of the matrix `X` or table `Tbl`.

• Logical vector of length p, where a true entry indicates that the corresponding predictor is categorical.

• String array or cell array of character vectors, where each element in the array is the name of a predictor variable. The predictor names must match the names in `PredictorNames` or `Tbl`.

• `"all"`, indicating that all predictor variables are categorical.

By default, `fitmnr` treats numeric predictors as continuous, and predictor variables of other types as categorical. For more information about categorical data, see Natural Representation of Categorical Data.

Example: ```CategoricalPredictors=["Location" "Smoker"]```

Example: `CategoricalPredictors=[1 3 4]`

Data Types: `single` | `double` | `logical` | `string` | `cell`

Indicator for estimating a dispersion parameter, specified as a numeric or logical `0` (`false`) or `1` (`true`).

ValueDescription
`0` (`false`)Use the theoretical dispersion value of 1 (default).
`1` (`true`)Estimate a dispersion parameter for the multinomial distribution for use in computing standard errors.

Example: `EstimateDispersion=1`

Data Types: `single` | `double` | `logical`

Indicator for an interaction between response categories and coefficients, specified as a numeric or logical `1` (`true`) or `0` (`false`).

ValueDescription
`1` (`true`)Default for nominal and hierarchical models. Fit a model with different coefficients across classes.
`0` (`false`)Default for ordinal models. Fit a model with a common set of coefficients for the predictor variables, across all multinomial classes. This type of model is often called a parallel regression or proportional odds model. For nominal models, `fitmnr` returns an intercept-only model if you set `IncludeClassInteractions` to `false`.

In all cases, the model has different intercepts across classes. The `IncludeClassInteractions` value determines the dimensions of the output array `MultinomialRegression.Coefficients`.

Example: `IncludeClassInteractions=1`

Data Types: `single` | `double` | `logical`

Maximum number of iteratively reweighted least squares (IRLS) iterations used to fit the model, specified as a positive integer. The default value for `IterationLimit` is `100`.

Example: `IterationLimit=400`

Data Types: `single` | `double`

Link function to use for ordinal and hierarchical models, specified as one of the values in the following table.

ValueFunction
`"logit"` (default)f(γ) = ln(γ/(1 –γ))
`"probit"`f(γ) = Φ-1(γ) — error term is normally distributed with variance 1
`"comploglog"`

f(γ) = ln(–ln(1 – γ))

`"loglog"`

f(γ) = ln(–ln(γ))

The link function defines the relationship between response probabilities and the linear combination of predictors. γ is a cumulative probability when the model has an ordinal response, and a conditional probability when the model is has a hierarchical response.

For an ordinal model, πj is the probability of an observation being in category j, and γ represents the cumulative probability of an observation being in categories 1 to j. The model with a logit link function has the form

`$\mathrm{ln}\left(\frac{\gamma }{1-\gamma }\right)=\mathrm{ln}\left(\frac{{\pi }_{1}+{\pi }_{2}+\cdots +{\pi }_{j}}{{\pi }_{j+1}+\cdots +{\pi }_{k}}\right)={\beta }_{0j}+{\beta }_{1}{X}_{1}+{\beta }_{2}{X}_{2}+\cdots +{\beta }_{p}{X}_{p},$`

where k represents the last category.

For a hierarchical model, πj and γ represent the probability that an observation is in category j given that it is not in the previous categories. The model with a logit link function has the form

`$\mathrm{ln}\left(\frac{\gamma }{1-\gamma }\right)=\mathrm{ln}\left(\frac{{\pi }_{j}}{{\pi }_{j+1}+\cdots +{\pi }_{k}}\right)={\beta }_{0j}+{\beta }_{1}{X}_{1}+{\beta }_{2}{X}_{2}+\cdots +{\beta }_{p}{X}_{p},$`

where k represents the last category.

You cannot specify `Link` for nominal models because they always use a multinomial logit link

`$\mathrm{ln}\left(\frac{{\pi }_{j}}{{\pi }_{r}}\right)={\beta }_{j0}+{\beta }_{j1}{X}_{j1}+{\beta }_{j2}{X}_{j2}+\cdots +{\beta }_{jp}{X}_{jp},\text{ }j=1,\text{\hspace{0.17em}}\dots ,k-1,$`

where πj is the probability of an observation being in category j, and r corresponds to the reference category. `fitmnr` uses the last category as the reference category for nominal models.

Example: `Link="loglog"`

Data Types: `char` | `string`

Type of model to fit, specified as one of the values in the following table.

ValueDescription
`"nominal"`(default)The response classes are not ordered. Multinomial regression is sometimes called softmax regression when `ModelType` is `"nominal"`.
`"ordinal"`The response classes have a natural order.
`"hierarchical"`The response classes are nested.

Example: `ModelType="hierarchical"`

Data Types: `char` | `string`

Predictor names, specified as a string vector or a cell array of character vectors.

• If you specify `Tbl` in the call to `fitmnr`, then `PredictorNames` must be a subset of the table variables in `Tbl`. `fitmnr` uses only the predictors specified in `PredictorNames`. In this case, the default value of `PredictorNames` is the collection of names of the predictor variables in `Tbl`.

• If you specify the matrix `X` in the call to `fitmnr`, you can specify any names for `PredictorNames`. In this case, the default value of `PredictorNames` is the 1-by-p cell array `['x1','x2',…,'xp']`, where p is the number of predictor variables.

When you specify `Formula`, `fitmnr` ignores `PredictorNames`.

Example: `PredictorNames=["time","latitude"]`

Data Types: `string` | `cell`

Name to assign to the response variable, specified as a string scalar or character vector. If you specify `ResponseVarName` or `Formula`, `fitmnr` ignores `ResponseName`.

Example: `ResponseName="City"`

Data Types: `char` | `string`

Termination tolerance for the Iteratively Reweighted Least Squares (IRLS) fitting algorithm, specified as a numeric scalar. If the relative difference of each coefficient is less than `Tolerance` across two iterations of the IRLS algorithm, then `fitmnr` considers the model to be converged. The default value for `Tolerance` is `1e-6`.

Example: `Tolerance=1e-4`

Data Types: `single` | `double`

Observation weights, specified as an n-by-1 numeric vector, where n is the number of observations. The default value for `Weights` is an n-by-1 vector of ones.

Example: `Weights`

Data Types: `single` | `double`

Output Arguments

collapse all

Multinomial regression model, returned as a `MultinomialRegression` model object.

Algorithms

If `X` or `Tbl` contains `NaN` values, `<undefined>` values, empty characters, or empty strings, the `fitmnr` function ignores the corresponding observations in `Y`.

Version History

Introduced in R2023a