function model = fitmnr(X, y, varargin)
%FITMNR Fit a multinomial regression model
%   MODEL = FITMNR(X, Y) returns a fitted MultinomialRegression model MODEL
%   for double/single predictor data X and response Y. Y can be a character 
%   or string array, categorical, logical or numeric vector, or cell array 
%   of character vectors. Y can also be a double/single matrix of counts of
%   responses. If Y is an N x K matrix, for N observations and K classes,
%   Y(i,j) represents the number of times observation i gave class j as the
%   response.
%
%   MODEL = FITMNR(TBL, Y) returns a fitted MultinomialRegression model
%   MODEL using predictor data in a table TBL. Y is the response, and can
%   be the same as above.
%
%   MODEL = FITMNR(TBL, RESPONSEVARNAME) fits a MultinomialRegression model
%   to the data in TBL. RESPONSEVARNAME is a character vector or a string of
%   a variable in TBL. FITMNR uses the variable specified by RESPONSEVARNAME 
%   as the response values to construct the model.
%
%   MODEL = FITMNR(TBL, FORMULA) fits a MultinomialRegression model to the
%   data in TBL, using the FORMULA to define the model, the response
%   variable, and the predictors. FORMULA is a character vector or string
%   of a formula in Wilkinson notation that describes the model to fit. The
%   formula terms must use the names of variables in TBL.
%
%   MODEL = FITMNR(__, NAME1=VAL1, ...) specifies optional name-value
%   arguments:
%       CategoricalPredictors - Which predictors should be treated as 
%                                 categorical variables. Pass 'CategoricalPredictors' 
%                                 as one of:
%                                   - A numeric vector with indices between
%                                     1 and M, where M is the number of predictor 
%                                     variables.
%                                   - A logical vector of length M, where
%                                     a true entry means that the corresponding 
%                                     predictor is a categorical variable.
%                                   - A string array or cell array of 
%                                     character vectors, where each element 
%                                     in the array is the name of a predictor 
%                                     variable. The names must match names
%                                     in table TBL if given, or match entries 
%                                     in 'PredictorNames' otherwise.
%                                   - 'all', indicating that all predictors
%                                     should be treated as categorical.
%                                 By default, numeric predictors are
%                                 treated as continuous, and predictor
%                                 variables of other types are treated as
%                                 categorical.
%
%       EstimateDispersion - A logical scalar indicating if the model
%                              should estimate a dispersion parameter for 
%                              use in computing the standard error (true), 
%                              or if the model should use the theoretical 
%                              value of 1 (false). The default is false.
%
%       IncludeClassInteractions - A logical scalar indicating if the
%                                    model should be fit with interactions 
%                                    between the coefficients and the classes. 
%                                    If false, the model fits a common set 
%                                    of coefficients for the predictor variables 
%                                    across all multinomial categories.  
%                                    This is often described as "parallel 
%                                    regression". If true, the model has different 
%                                    coefficients across categories. In all 
%                                    cases, the model has different intercepts 
%                                    across categories. If 'ModelType' is
%                                    'ordinal', the default is false.
%                                    Otherwise, the default is true.
%
%       IterationLimit - A positive scalar integer. Multinomial
%                          regression is fitted via an iterative algorithm. 
%                          'IterationLimit' controls the maximum number of
%                          iterations that are done to fit the model. The
%                          default is 100.
%
%       Link - The link function to use for the models. The link function 
%                defines the relationship g(mu_ij) = x_i*b_j between the mean 
%                response for the i-th observation in the j-th category, mu_ij, 
%                and the linear combination of predictors x_i*b_j. Specify 
%                'Link' as one of 'logit' (default), 'probit', 'comploglog', 
%                or 'loglog'.  If 'ModelType' is 'nominal', only 'logit' is 
%                supported.
%
%       ModelType - The type of model to fit, one of 'nominal' (default),
%                     'ordinal', or 'hierarchical'.
%   
%       PredictorNames - A string array or cell array of character vectors 
%                          of names for the predictor variables. For a table 
%                          TBL, these names must be a subset of the variable 
%                          names in TBL, and only the selected variables are 
%                          used. This argument is ignored when FORMULA is given. 
%                          The default is all variables in TBL. For X, this
%                          argument sets the name for the predictors, in the 
%                          order they appear. The default is {'x1','x2', ...} 
%                          for X, and TBL.Properties.VariableNames, excluding 
%                          the response variable name if it lives within TBL.
%
%       ResponseName - A character vector or string scalar of the name of 
%                        the response. This argument is ignored if RESPONSEVARNAME
%                        or FORMULA are given.
%
%       Tolerance - A positive scalar which determines how close the parameter
%                     estimates must be between iterations to consider the 
%                     model fitting algorithm as having converged. The default 
%                     is 1e-6.
%
%       Weights - A double/single vector of non-negative observations
%                   weights. The vector must have the same number of rows as
%                   the number of observations. The default is a vector of
%                   1s.
%
%   Example: Fit a multinomial regression to the Fisher iris dataset
%   load fisheriris
%   model = fitmnr(meas, species)
%   See also MultinomialRegression, fitglm, fitclinear, fitcecoc

%   Copyright 2022 The MathWorks, Inc.

y = convertStringsToChars(y);
[varargin{:}] = convertStringsToChars(varargin{:});
model = MultinomialRegression.fit(X, y, varargin{:});
end