MultinomialRegression
statistics: MultinomialRegression
Multinomial regression model class.
A MultinomialRegression object holds a multinomial regression of a
categorical response on one or more predictors, fitted by mnrfit.
It is normally created with the fitmnr function. The response has
K categories, listed in ClassNames, and the model is one of
three kinds, named by ModelType: a nominal model contrasts each
category with the last, an ordinal model fits the cumulative probabilities
of ordered categories, and a hierarchical model fits each category against
the ones after it.
The most useful properties are Coefficients (a table of estimates,
standard errors, t-statistics and p-values), Deviance,
Fitted, Residuals, LogLikelihood,
ModelCriterion and Rsquared. ObservationInfo records
which rows were weighted or missing, and Variables holds the data
the model was built from. A fitted model supports predict,
feval and random, inference on its coefficients through
coefCI, coefTest and testDeviance, and partial
dependence through partialDependence and
plotPartialDependence.
Fitted, Residuals and ObservationInfo have one row per
input row. A row left out of the fit because a value it needs is
missing has NaN residuals and a missing label in Fitted, the
empty character vector, <undefined>, <missing> or
NaN as the type of ClassNames has it; MATLAB labels such a
row with the first class.
See also: fitmnr, mnrfit, mnrval, GeneralizedLinearModel
Source Code: MultinomialRegression
The MultinomialRegression class contains the following properties:
A table with one row per coefficient and four columns:
Value - estimated coefficient value
SE - standard error of the estimate
tStat - the estimate divided by its standard error
pValue - p-value of that statistic
The statistic is referred to the normal distribution, or to a
t-distribution on DFE degrees of freedom where the
dispersion is estimated. The row names are the coefficient names.
This property is read-only.
A square matrix with one row and column per coefficient, in the order of
CoefficientNames. It is scaled by Dispersion, so it is the
covariance under the estimated dispersion wherever one was estimated.
This property is read-only.
A string column, one name per coefficient. A coefficient of one category
joins the term to the category, (Intercept_class) and
term_class; a slope shared by every category is
named by its term alone. A categorical predictor contributes one term
per level bar the first, spelled name_level, and an
interaction joins its factors with a colon.
This property is read-only.
A positive integer.
This property is read-only.
A K-by-1 array in the type of the response: numeric, logical, a
cell array of character vectors, a string or a categorical array. A
character matrix response gives a cell array, and a matrix of counts the
numbers of its columns. The categories of a numeric, logical or text
response are sorted, and those of a categorical array are in the order of
its categories. A category without observations is no class. The last
class is the reference category of a nominal model. The model is fitted
in this order, so Fitted and predict name the class they
estimate; R2024a sorts the classes of text but fits them in the order the
data first shows them, so its labels name the wrong classes unless the
data show them sorted.
This property is read-only.
A logical scalar: true when each category has its own slopes,
false when every category shares them. The intercepts always
differ by category.
This property is read-only.
A character vector, 'logit', 'probit',
'comploglog' or 'loglog'. A nominal model always uses
the logit link.
This property is read-only.
A character vector, 'nominal', 'ordinal' or
'hierarchical'.
This property is read-only.
A nonnegative scalar, twice the difference between the log-likelihood of the saturated model and that of the fitted one. The difference between the deviances of two nested models follows a chi-square distribution.
This property is read-only.
The number of rows used in the fit times K-1, less the number of coefficients; for a hierarchical model each stage counts only the rows with observations that reach it.
This property is read-only.
A positive scalar, 1 unless EstimateDispersion is true. The
estimate is the square of the 'sfit' that mnrfit
returns, the Pearson statistic over the categories divided by
DFE, so it differs from MATLAB’s, as mnrfit documents.
The standard errors are scaled by its square root.
This property is read-only.
A logical scalar.
This property is read-only.
An N-by-1 array of the most probable class of each input row, in
the type of ClassNames; a row left out of the fit is a missing
label.
This property is read-only.
A scalar, -Deviance / 2: the log-likelihood measured from
that of the saturated model, as MATLAB reports it.
This property is read-only.
A structure with fields AIC, AICc, BIC and
CAIC, computed from LogLikelihood, the number of
coefficients m and the number of rows n used in the fit:
-2 * LogLikelihood + 2 * m, its small-sample correction
+ 2 * m * (m + 1) / (n - m - 1), -2 * LogLikelihood + m *
log (n) and -2 * LogLikelihood + m * (log (n) + 1).
This property is read-only.
A table with one row per input row and three variables, Raw,
Pearson and Deviance, the 'resid',
'residp' and 'residd' that mnrfit returns and
documents. Raw and Pearson have a column per category of a
nominal model, and one fewer for an ordinal or hierarchical model;
Deviance has one. A row left out of the fit is NaN.
This property is read-only.
A structure with fields Ordinary, 1 - L / L0, and
Adjusted, 1 - (L - m) / L0, where L is
LogLikelihood, L0 that of the model with intercepts alone
and m the number of coefficients.
This property is read-only.
A LinearFormula object over the variables of the model, with the
link on the response, such as logit(y) ~ 1 + x1 + x2.
This property is read-only.
The number of input rows used in the fit, those left out because a value was missing not counted. A row of a matrix of counts counts once, whatever number of observations it holds.
This property is read-only.
The number of predictors used in the fit.
This property is read-only.
The number of variables in the input data, the response and any variable the model does not use included.
This property is read-only.
A table with one row per input row and three variables: Weights,
the observation weight, Missing, true where a value the fit needs
is missing, and Subset, true where the row was used in the fit.
This property is read-only.
The row names of an input table, as a cell array of character vectors, or an empty cell array where there were none.
This property is read-only.
A cell array of character vectors, one per predictor used in the fit.
This property is read-only.
A character vector, 'y' by default.
This property is read-only.
A table with one row per variable and four variables: Class, the
class of the variable, Range, [min, max] of a continuous
variable or the levels of a categorical one, InModel, true for a
predictor used in the fit, and IsCategorical. The response is not
in the model and is categorical.
This property is read-only.
A cell array of character vectors naming every variable of the input data, the response included.
This property is read-only.
A table of the predictors and the response, with any other variable of an input table.
This property is read-only.
The MultinomialRegression class offers the following public methods:
MultinomialRegression: mdl = MultinomialRegression (X, Y)
MultinomialRegression: mdl = MultinomialRegression (Tbl, Y)
MultinomialRegression: mdl = MultinomialRegression (Tbl, ResponseVarName)
MultinomialRegression: mdl = MultinomialRegression (Tbl, Formula)
MultinomialRegression: mdl = MultinomialRegression (…, name, value)
This is the constructor that fitmnr calls, and it takes exactly
what fitmnr takes. See fitmnr for the arguments and the
name, value pairs.
See also: fitmnr
MultinomialRegression: label = predict (mdl, Xnew)
MultinomialRegression: [label, probs] = predict (mdl, Xnew)
MultinomialRegression: [label, probs, lower, upper] = predict (mdl, Xnew)
MultinomialRegression: […] = predict (…, name, value)
label = predict (mdl, Xnew) returns the most
probable class at each row of the new predictor data Xnew, in the
type of ClassNames. Xnew is a table holding every predictor
named in PredictorNames, or a numeric matrix with one column per
predictor where they are all numeric. A row holding a missing value is a
missing label.
probs holds the probabilities, one row per row of Xnew, and lower and upper their confidence bounds, from the delta method. The following name, value pairs are accepted:
| Name | Value |
|---|---|
'Alpha' | The significance level of the bounds, a scalar in (0, 1); the default 0.05 gives 95% bounds. |
'ProbabilityType' | 'category' (default), the
probability of each of the K categories; 'cumulative',
the probability of each of the first K-1 categories or any before
it; or 'conditional', the probability of each of the first
K-1 categories given that the response is not in an earlier one. |
The bounds are at the confidence level 1 - Alpha. R2024a takes Alpha as the confidence level itself, so its default bounds are at 5% and far too narrow.
See also: MultinomialRegression.feval, MultinomialRegression.random, mnrval
MultinomialRegression: label = feval (mdl, X1, …, Xp)
MultinomialRegression: label = feval (mdl, Xnew)
label = feval (mdl, X1, …, Xp)
takes one argument per predictor, each a column vector or a scalar, and a
scalar stands for every row. label = feval (mdl,
Xnew) takes a table or a matrix, as predict does. Either
returns what predict returns first, the most probable class.
See also: MultinomialRegression.predict
MultinomialRegression: ysim = random (mdl, Xnew)
MultinomialRegression: ysim = random (mdl, Xnew, NumTrials)
MultinomialRegression: ysim = random (…, type)
ysim = random (mdl, Xnew) draws one response at
each row of Xnew from the probabilities the model gives there.
Xnew is a table or a matrix, as predict takes it.
NumTrials, a positive integer, draws that many at each row.
type is 'samples' (default), for an
r-by-NumTrials array of class labels, in the type of
ClassNames, or 'counts', for an r-by-K
table counting how many draws fell in each class, one variable per
class.
See also: MultinomialRegression.predict
MultinomialRegression: ci = coefCI (mdl)
MultinomialRegression: ci = coefCI (mdl, alpha)
ci = coefCI (mdl) returns a p-by-2 matrix, one
row per coefficient in the order of CoefficientNames, of the lower
and upper limits of its 95% confidence interval,
Value +/- tinv (1 - alpha / 2, DFE) * SE. alpha, in
(0, 1), sets the level to 100 (1 - alpha)%.
See also: MultinomialRegression.coefTest
MultinomialRegression: p = coefTest (mdl)
MultinomialRegression: p = coefTest (mdl, H)
MultinomialRegression: p = coefTest (mdl, H, C)
MultinomialRegression: [p, F, r] = coefTest (…)
p = coefTest (mdl, H, C) tests the
hypothesis that H * b = C, where b is the
column of coefficients in the order of CoefficientNames. H
is a full-rank r-by-p matrix and C a vector of
r elements, zero by default; without H the hypothesis is
that every coefficient is zero. F is the Wald statistic divided by
r, and p its p-value from the F distribution on
r and DFE degrees of freedom.
See also: MultinomialRegression.coefCI, MultinomialRegression.testDeviance
MultinomialRegression: p = testDeviance (mdl)
MultinomialRegression: [p, stat] = testDeviance (mdl)
p = testDeviance (mdl) tests whether the model fits
better than one with an intercept for each category and no predictors,
comparing their deviances. Where the dispersion is fixed, stat is
the drop in deviance and p its chi-square p-value on as many
degrees of freedom as the model has coefficients beyond the intercepts;
where it is estimated, stat is that drop per degree of freedom
divided by Dispersion, and p its F p-value on those
and DFE degrees of freedom.
See also: MultinomialRegression.coefTest
MultinomialRegression: plotResiduals (mdl)
MultinomialRegression: plotResiduals (mdl, plotType)
MultinomialRegression: plotResiduals (ax, …)
MultinomialRegression: plotResiduals (…, name, value)
MultinomialRegression: h = plotResiduals (…)
plotResiduals (mdl) draws a histogram of the deviance
residuals, as a probability density. plotType chooses the plot:
| Type | Plot |
|---|---|
'histogram' | a histogram of the residuals (default) |
'caseorder' | the residuals against the row number |
'fitted' | the residuals against the fitted probability of the class |
'lagged' | each residual against the one before it |
'probability' | a normal probability plot |
'observed' | the observed share of each row in the class against its fitted probability, with the line y = x and a segment from it to each row |
'symmetry' | the residuals above their median against those below it |
The following name, value pairs are accepted:
| Name | Value |
|---|---|
'ResidualType' | 'deviance' (default),
'raw' or 'Pearson', a variable of Residuals. |
'ClassToPlot' | For raw and Pearson residuals, the
class whose column of residuals is plotted, and whose probability the
'fitted' and 'observed' plots show, a class named in
ClassNames; the first by default. The residuals of an ordinal or
hierarchical model have no column for the last class. With deviance
residuals it is ignored, with a warning, and the first class shown. |
'FaceColor', 'FaceAlpha', 'LineWidth' | The fill color, transparency and edge width of the bars of a histogram. |
'Color', 'LineStyle', 'Marker' | The color, line style and marker of the residuals in the other plots. |
ax is the axes to draw in, the current axes by default. h is the patch of a histogram, and for the other plots a column of the line of residuals and its reference lines.
See also: MultinomialRegression.Residuals
MultinomialRegression: plotSlice (mdl)
MultinomialRegression: plotSlice (mdl, Xnew)
MultinomialRegression: plotSlice (mdl, plotType)
MultinomialRegression: plotSlice (mdl, plotType, Xnew)
MultinomialRegression: plotSlice (ax, …)
MultinomialRegression: plotSlice (…, name, value)
MultinomialRegression: h = plotSlice (…)
A slice varies one continuous predictor over its range and holds every
other predictor fixed, a categorical one at its most common level. The
ranges and the fixed values are taken from the data the model was
fitted on, or from Xnew, a table or a matrix as predict
takes it; a single row of Xnew gives each predictor the range from
its value to 10% above it. plotType chooses the plot:
| Type | Plot |
|---|---|
'interactive' | (default) a figure with one plot per continuous predictor, each the probability of one class along that predictor, the others fixed at the middle of their ranges, with its 95% confidence band shaded and dashed and dotted lines through the middle. |
'histogram' | overlaid bars of the probability of each class at 40 values along one predictor, the others fixed at their means. |
'stackedhist' | the same probabilities as stacked bars. |
MATLAB’s interactive plot is an app whose menus and boxes change the class, the predictors and the fixed values; here the figure has no such controls, and the plot is drawn again to change them.
The following name, value pairs are accepted:
| Name | Value |
|---|---|
'ClassToPlot' | For the interactive plot, the class
whose probability is drawn, the first of ClassNames by default. |
'PredictorToVary' | For the histograms, the name of the continuous predictor to vary, the first by default. |
'FaceColor', 'FaceAlpha', 'LineWidth' | The fill color ('auto' by default, a color per class), the
transparency (0.6) and the edge width (0.5) of the bars of a histogram. |
'EdgeColor', 'LineStyle' | The edge color and line style of the stacked bars, black up to 150 bars and none beyond, and a solid line. |
ax is the axes to draw a histogram in, the current axes by default. h is the figure of the interactive plot, and for the histograms a column of one patch or bar object per class.
See also: MultinomialRegression.predict, plotPartialDependence