Fit discriminant analysis classifier
returns a fitted discriminant analysis model based on the input variables (also
known as predictors, features, or attributes) contained in the table
Mdl
= fitcdiscr(Tbl
,ResponseVarName
)Tbl
and output (response or labels) contained in
ResponseVarName
.
fits a classifier with additional options specified by one or more namevalue
pair arguments, using any of the previous syntaxes. For example, you can
optimize hyperparameters to minimize the model’s crossvalidation loss, or
specify the cost of misclassification, the prior probabilities for each class,
or the observation weights.Mdl
= fitcdiscr(___,Name,Value
)
Load Fisher's iris data set.
load fisheriris
Train a discriminant analysis model using the entire data set.
Mdl = fitcdiscr(meas,species)
Mdl = ClassificationDiscriminant ResponseName: 'Y' CategoricalPredictors: [] ClassNames: {'setosa' 'versicolor' 'virginica'} ScoreTransform: 'none' NumObservations: 150 DiscrimType: 'linear' Mu: [3x4 double] Coeffs: [3x3 struct] Properties, Methods
Mdl
is a ClassificationDiscriminant
model. To access its properties, use dot notation. For example, display the group means for each predictor.
Mdl.Mu
ans = 3×4
5.0060 3.4280 1.4620 0.2460
5.9360 2.7700 4.2600 1.3260
6.5880 2.9740 5.5520 2.0260
To predict labels for new observations, pass Mdl
and predictor data to predict
.
This example shows how to optimize hyperparameters automatically using fitcdiscr
. The example uses Fisher's iris data.
Load the data.
load fisheriris
Find hyperparameters that minimize fivefold crossvalidation loss by using automatic hyperparameter optimization.
For reproducibility, set the random seed and use the 'expectedimprovementplus'
acquisition function.
rng(1) Mdl = fitcdiscr(meas,species,'OptimizeHyperparameters','auto',... 'HyperparameterOptimizationOptions',... struct('AcquisitionFunctionName','expectedimprovementplus'))
=====================================================================================================  Iter  Eval  Objective  Objective  BestSoFar  BestSoFar  Delta  Gamma    result   runtime  (observed)  (estim.)    =====================================================================================================  1  Best  0.66667  1.3141  0.66667  0.66667  13.261  0.25218   2  Best  0.02  0.51226  0.02  0.064227  2.7404e05  0.073264   3  Accept  0.04  0.31609  0.02  0.020084  3.2455e06  0.46974   4  Accept  0.66667  0.39453  0.02  0.020118  14.879  0.98622   5  Accept  0.046667  0.50662  0.02  0.019907  0.00031449  0.97362   6  Accept  0.04  0.58647  0.02  0.028438  4.5092e05  0.43616   7  Accept  0.046667  0.34729  0.02  0.031424  2.0973e05  0.9942   8  Accept  0.02  0.21367  0.02  0.022424  1.0554e06  0.0024286   9  Accept  0.02  0.21008  0.02  0.021105  1.1232e06  0.00014039   10  Accept  0.02  0.21403  0.02  0.020948  0.00011837  0.0032994   11  Accept  0.02  0.46597  0.02  0.020172  1.0292e06  0.027725   12  Accept  0.02  0.41797  0.02  0.020105  9.7792e05  0.0022817   13  Accept  0.02  0.37597  0.02  0.020038  0.00036014  0.0015136   14  Accept  0.02  0.40659  0.02  0.019597  0.00021059  0.0044789   15  Accept  0.02  0.21894  0.02  0.019461  1.1911e05  0.0010135   16  Accept  0.02  0.15173  0.02  0.01993  0.0017896  0.00071115   17  Accept  0.02  0.16054  0.02  0.019551  0.00073745  0.0066899   18  Accept  0.02  0.20745  0.02  0.019776  0.00079304  0.00011509   19  Accept  0.02  0.1341  0.02  0.019678  0.007292  0.0007911   20  Accept  0.046667  0.30405  0.02  0.019785  0.0074408  0.99945  =====================================================================================================  Iter  Eval  Objective  Objective  BestSoFar  BestSoFar  Delta  Gamma    result   runtime  (observed)  (estim.)    =====================================================================================================  21  Accept  0.02  0.17811  0.02  0.019043  0.0036004  0.0024547   22  Accept  0.02  0.19361  0.02  0.019755  2.5238e05  0.0015542   23  Accept  0.02  0.35374  0.02  0.0191  1.5478e05  0.0026899   24  Accept  0.02  0.29655  0.02  0.019081  0.0040557  0.00046815   25  Accept  0.02  0.24127  0.02  0.019333  2.959e05  0.0011358   26  Accept  0.02  0.3227  0.02  0.019369  2.3111e06  0.0029205   27  Accept  0.02  0.21419  0.02  0.019455  3.8898e05  0.0011665   28  Accept  0.02  0.13446  0.02  0.019449  0.0035925  0.0020278   29  Accept  0.66667  0.21061  0.02  0.019479  998.93  0.064276   30  Accept  0.02  0.36249  0.02  0.01947  8.1557e06  0.0008004  __________________________________________________________ Optimization completed. MaxObjectiveEvaluations of 30 reached. Total function evaluations: 30 Total elapsed time: 83.0276 seconds. Total objective function evaluation time: 9.9662 Best observed feasible point: Delta Gamma __________ ________ 2.7404e05 0.073264 Observed objective function value = 0.02 Estimated objective function value = 0.01947 Function evaluation time = 0.51226 Best estimated feasible point (according to models): Delta Gamma __________ _________ 2.5238e05 0.0015542 Estimated objective function value = 0.01947 Estimated function evaluation time = 0.25472
Mdl = ClassificationDiscriminant ResponseName: 'Y' CategoricalPredictors: [] ClassNames: {'setosa' 'versicolor' 'virginica'} ScoreTransform: 'none' NumObservations: 150 HyperparameterOptimizationResults: [1x1 BayesianOptimization] DiscrimType: 'linear' Mu: [3x4 double] Coeffs: [3x3 struct] Properties, Methods
The fit achieved about 2% loss for the default 5fold cross validation.
This example shows how to optimize hyperparameters of a discriminant analysis model automatically using a tall array. The sample data set airlinesmall.csv
is a large data set that contains a tabular file of airline flight data. This example creates a tall table containing the data and uses it to run the optimization procedure.
When you perform calculations on tall arrays, MATLAB® uses either a parallel pool (default if you have Parallel Computing Toolbox™) or the local MATLAB session. If you want to run the example using the local MATLAB session when you have Parallel Computing Toolbox, you can change the global execution environment by using the mapreducer
function.
Create a datastore that references the folder location with the data. Select a subset of the variables to work with, and treat 'NA'
values as missing data so that datastore
replaces them with NaN
values. Create a tall table that contains the data in the datastore.
ds = datastore('airlinesmall.csv'); ds.SelectedVariableNames = {'Month','DayofMonth','DayOfWeek',... 'DepTime','ArrDelay','Distance','DepDelay'}; ds.TreatAsMissing = 'NA'; tt = tall(ds) % Tall table
Starting parallel pool (parpool) using the 'local' profile ... Connected to the parallel pool (number of workers: 6). tt = M×7 tall table Month DayofMonth DayOfWeek DepTime ArrDelay Distance DepDelay _____ __________ _________ _______ ________ ________ ________ 10 21 3 642 8 308 12 10 26 1 1021 8 296 1 10 23 5 2055 21 480 20 10 23 5 1332 13 296 12 10 22 4 629 4 373 1 10 28 3 1446 59 308 63 10 8 4 928 3 447 2 10 10 6 859 11 954 1 : : : : : : : : : : : : : :
Determine the flights that are late by 10 minutes or more by defining a logical variable that is true for a late flight. This variable contains the class labels. A preview of this variable includes the first few rows.
Y = tt.DepDelay > 10 % Class labels
Y = M×1 tall logical array 1 0 1 1 0 1 0 0 : :
Create a tall array for the predictor data.
X = tt{:,1:end1} % Predictor data
X = M×6 tall double matrix Columns 1 through 4 10 21 3 642 10 26 1 1021 10 23 5 2055 10 23 5 1332 10 22 4 629 10 28 3 1446 10 8 4 928 10 10 6 859 : : : : : : : : Columns 5 through 6 8 308 8 296 21 480 13 296 4 373 59 308 3 447 11 954 : : : :
Remove rows in X
and Y
that contain missing data.
R = rmmissing([X Y]); % Data with missing entries removed
X = R(:,1:end1);
Y = R(:,end);
Standardize the predictor variables.
Z = zscore(X);
Optimize hyperparameters automatically using the 'OptimizeHyperparameters'
namevalue pair argument. Find the optimal 'DiscrimType'
value that minimizes holdout crossvalidation loss. (Specifying 'auto'
uses 'DiscrimType'
.) For reproducibility, use the 'expectedimprovementplus'
acquisition function and set the seeds of the random number generators using rng
and tallrng
. The results can vary depending on the number of workers and the execution environment for the tall arrays. For details, see Control Where Your Code Runs (MATLAB).
rng('default') tallrng('default') [Mdl,FitInfo,HyperparameterOptimizationResults] = fitcdiscr(Z,Y,... 'OptimizeHyperparameters','auto',... 'HyperparameterOptimizationOptions',struct('Holdout',0.3,... 'AcquisitionFunctionName','expectedimprovementplus'))
Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 2: Completed in 5.8 sec  Pass 2 of 2: Completed in 5.1 sec Evaluation completed in 17 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 2.7 sec Evaluation completed in 2.8 sec ======================================================================================  Iter  Eval  Objective  Objective  BestSoFar  BestSoFar  DiscrimType    result   runtime  (observed)  (estim.)   ======================================================================================  1  Best  0.11354  27.911  0.11354  0.11354  quadratic  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.4 sec Evaluation completed in 2.7 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.3 sec  2  Accept  0.11354  9.1078  0.11354  0.11354  pseudoQuadra  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 2.5 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.7 sec Evaluation completed in 1.7 sec  3  Accept  0.12869  9.0635  0.11354  0.11859  pseudoLinear  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.3 sec Evaluation completed in 2.1 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.2 sec  4  Accept  0.12745  8.1875  0.11354  0.1208  diagLinear  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 2.1 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.2 sec  5  Accept  0.12869  8.1795  0.11354  0.12238  linear  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.2 sec  6  Best  0.11301  7.3598  0.11301  0.12082  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 2.6 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.2 sec  7  Accept  0.11301  8.1574  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.6 sec Evaluation completed in 1.7 sec  8  Accept  0.11301  7.8032  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.8 sec Evaluation completed in 2.6 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.2 sec  9  Accept  0.11301  8.2363  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 2 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  10  Accept  0.11301  7.3819  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  11  Accept  0.11301  7.0881  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  12  Accept  0.11301  6.9635  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  13  Accept  0.11301  6.9543  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.7 sec Evaluation completed in 2.5 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.7 sec Evaluation completed in 1.7 sec  14  Accept  0.11301  8.415  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  15  Accept  0.11301  6.9447  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  16  Accept  0.11301  6.968  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 2 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  17  Accept  0.11301  7.2919  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  18  Accept  0.11301  7.0682  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.7 sec Evaluation completed in 2.5 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  19  Accept  0.11301  7.8015  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1 sec Evaluation completed in 1.1 sec  20  Accept  0.11301  6.9002  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec ======================================================================================  Iter  Eval  Objective  Objective  BestSoFar  BestSoFar  DiscrimType    result   runtime  (observed)  (estim.)   ======================================================================================  21  Accept  0.11301  6.9957  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  22  Accept  0.11301  6.9259  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  23  Accept  0.11354  7.0707  0.11301  0.11301  quadratic  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.8 sec Evaluation completed in 2.5 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1 sec Evaluation completed in 1.1 sec  24  Accept  0.11354  7.5755  0.11301  0.11301  pseudoQuadra  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.2 sec  25  Accept  0.11301  6.9713  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.6 sec Evaluation completed in 1.6 sec  26  Accept  0.11354  7.4111  0.11301  0.11301  quadratic  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  27  Accept  0.11301  6.9108  0.11301  0.11301  diagQuadrati  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.8 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1 sec Evaluation completed in 1.1 sec  28  Accept  0.11354  6.712  0.11301  0.11301  pseudoQuadra  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.7 sec Evaluation completed in 2.3 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  29  Accept  0.11354  7.3625  0.11301  0.11301  quadratic  Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.9 sec Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1.1 sec Evaluation completed in 1.1 sec  30  Accept  0.11354  6.9669  0.11301  0.11301  quadratic  __________________________________________________________ Optimization completed. MaxObjectiveEvaluations of 30 reached. Total function evaluations: 30 Total elapsed time: 286.0737 seconds. Total objective function evaluation time: 244.685 Best observed feasible point: DiscrimType _____________ diagQuadratic Observed objective function value = 0.11301 Estimated objective function value = 0.11301 Function evaluation time = 7.3598 Best estimated feasible point (according to models): DiscrimType _____________ diagQuadratic Estimated objective function value = 0.11301 Estimated function evaluation time = 7.6251 Evaluating tall expression using the Parallel Pool 'local':  Pass 1 of 1: Completed in 1 sec Evaluation completed in 1.7 sec
Mdl = classreg.learning.classif.CompactClassificationDiscriminant PredictorNames: {'x1' 'x2' 'x3' 'x4' 'x5' 'x6'} ResponseName: 'Y' CategoricalPredictors: [] ClassNames: [0 1] ScoreTransform: 'none' DiscrimType: 'diagQuadratic' Mu: [2×6 double] Coeffs: [2×2 struct] Properties, Methods
FitInfo = struct with no fields.
HyperparameterOptimizationResults = BayesianOptimization with properties: ObjectiveFcn: @createObjFcn/tallObjFcn VariableDescriptions: [1×1 optimizableVariable] Options: [1×1 struct] MinObjective: 0.1130 XAtMinObjective: [1×1 table] MinEstimatedObjective: 0.1130 XAtMinEstimatedObjective: [1×1 table] NumObjectiveEvaluations: 30 TotalElapsedTime: 286.0737 NextPoint: [1×1 table] XTrace: [30×1 table] ObjectiveTrace: [30×1 double] ConstraintsTrace: [] UserDataTrace: {30×1 cell} ObjectiveEvaluationTimeTrace: [30×1 double] IterationTimeTrace: [30×1 double] ErrorTrace: [30×1 double] FeasibilityTrace: [30×1 logical] FeasibilityProbabilityTrace: [30×1 double] IndexOfMinimumTrace: [30×1 double] ObjectiveMinimumTrace: [30×1 double] EstimatedObjectiveMinimumTrace: [30×1 double]
Tbl
— Sample dataSample data used to train the model, specified as a table. Each row of Tbl
corresponds to one observation, and each column corresponds to one predictor variable.
Optionally, Tbl
can contain one additional column for the response
variable. Multicolumn variables and cell arrays other than cell arrays of character
vectors are not allowed.
If Tbl
contains the response variable, and you want to use all remaining
variables in Tbl
as predictors, then specify the response variable by
using ResponseVarName
.
If Tbl
contains the response variable, and you want to use only a subset of
the remaining variables in Tbl
as predictors, then specify a formula
by using formula
.
If Tbl
does not contain the response variable, then specify a response
variable by using Y
. The length of the response variable and the
number of rows in Tbl
must be equal.
Data Types: table
ResponseVarName
— Response variable nameTbl
Response variable name, specified as the name of a variable in
Tbl
.
You must specify ResponseVarName
as a character vector or string scalar.
For example, if the response variable Y
is
stored as Tbl.Y
, then specify it as
'Y'
. Otherwise, the software
treats all columns of Tbl
, including
Y
, as predictors when training
the model.
The response variable must be a categorical, character, or string array, logical or numeric
vector, or cell array of character vectors. If
Y
is a character array, then each
element of the response variable must correspond to one row of
the array.
It is a good practice to specify the order of the classes by using the
ClassNames
namevalue pair argument.
Data Types: char
 string
formula
— Explanatory model of response variable and subset of predictor variablesExplanatory model of the response variable and a subset of the predictor variables,
specified as a character vector or string scalar in the form
'Y~X1+X2+X3'
. In this form, Y
represents the
response variable, and X1
, X2
, and
X3
represent the predictor variables.
To specify a subset of variables in Tbl
as predictors for
training the model, use a formula. If you specify a formula, then the software does not
use any variables in Tbl
that do not appear in
formula
.
The variable names in the formula must be both variable names in Tbl
(Tbl.Properties.VariableNames
) and valid MATLAB^{®} identifiers.
You can verify the variable names in Tbl
by using the isvarname
function. The following code returns logical 1
(true
) for each variable that has a valid variable name.
cellfun(@isvarname,Tbl.Properties.VariableNames)
Tbl
are not valid, then convert them by using the
matlab.lang.makeValidName
function.Tbl.Properties.VariableNames = matlab.lang.makeValidName(Tbl.Properties.VariableNames);
Data Types: char
 string
Y
— Class labelsClass labels, specified as a categorical, character, or string array, a logical or numeric
vector, or a cell array of character vectors. Each row of Y
represents the classification of the corresponding row of X
.
The software considers NaN
, ''
(empty character vector),
""
(empty string), <missing>
, and
<undefined>
values in Y
to be missing
values. Consequently, the software does not train using observations with a missing
response.
Data Types: categorical
 char
 string
 logical
 single
 double
 cell
X
— Predictor dataPredictor values, specified as a numeric matrix. Each column of
X
represents one variable, and each row represents
one observation.
fitcdiscr
considers NaN
values in
X
as missing values. fitcdiscr
does not use observations with missing values for X
in
the fit.
Data Types: single
 double
Specify optional
commaseparated pairs of Name,Value
arguments. Name
is
the argument name and Value
is the corresponding value.
Name
must appear inside quotes. You can specify several name and value
pair arguments in any order as
Name1,Value1,...,NameN,ValueN
.
'DiscrimType','quadratic','SaveMemory','on'
specifies a
quadratic discriminant classifier and does not store the covariance matrix in the
output object.You cannot use any crossvalidation namevalue pair argument along with the
'OptimizeHyperparameters'
namevalue pair argument. You can modify
the crossvalidation for 'OptimizeHyperparameters'
only by using the
'HyperparameterOptimizationOptions'
namevalue pair
argument.
'ClassNames'
— Names of classes to use for trainingNames of classes to use for training, specified as the commaseparated pair consisting of
'ClassNames'
and a categorical, character, or string array, a
logical or numeric vector, or a cell array of character vectors.
ClassNames
must have the same data type as
Y
.
If ClassNames
is a character array, then each element must correspond to
one row of the array.
Use ClassNames
to:
Order the classes during training.
Specify the order of any input or output argument
dimension that corresponds to the class order. For example, use ClassNames
to
specify the order of the dimensions of Cost
or
the column order of classification scores returned by predict
.
Select a subset of classes for training. For example,
suppose that the set of all distinct class names in Y
is {'a','b','c'}
.
To train the model using observations from classes 'a'
and 'c'
only,
specify 'ClassNames',{'a','c'}
.
The default value for ClassNames
is the set of all distinct class names in
Y
.
Example: 'ClassNames',{'b','g'}
Data Types: categorical
 char
 string
 logical
 single
 double
 cell
'Cost'
— Cost of misclassificationCost of misclassification of a point, specified as the commaseparated
pair consisting of 'Cost'
and one of the following:
Square matrix, where Cost(i,j)
is
the cost of classifying a point into class j
if
its true class is i
(i.e., the rows correspond
to the true class and the columns correspond to the predicted class).
To specify the class order for the corresponding rows and columns
of Cost
, additionally specify the ClassNames
namevalue
pair argument.
Structure S
having two fields: S.ClassNames
containing
the group names as a variable of the same type as Y
,
and S.ClassificationCosts
containing the cost matrix.
The default is Cost(i,j)=1
if i~=j
,
and Cost(i,j)=0
if i=j
.
Data Types: single
 double
 struct
'Delta'
— Linear coefficient threshold0
(default)  nonnegative scalar valueLinear coefficient threshold, specified as the commaseparated
pair consisting of 'Delta'
and a nonnegative scalar
value. If a coefficient of Mdl
has magnitude smaller
than Delta
, Mdl
sets this coefficient
to 0
, and you can eliminate the corresponding predictor
from the model. Set Delta
to a higher value to
eliminate more predictors.
Delta
must be 0
for quadratic
discriminant models.
Data Types: single
 double
'DiscrimType'
— Discriminant type'linear'
(default)  'quadratic'
 'diaglinear'
 'diagquadratic'
 'pseudolinear'
 'pseudoquadratic'
Discriminant type, specified as the commaseparated pair consisting of
'DiscrimType'
and a character vector or string scalar in this
table.
Value  Description  Predictor Covariance Treatment 

'linear'  Regularized linear discriminant analysis (LDA) 

'diaglinear'  LDA  All classes have the same, diagonal covariance matrix. 
'pseudolinear'  LDA  All classes have the same covariance matrix. The software inverts the covariance matrix using the pseudo inverse. 
'quadratic'  Quadratic discriminant analysis (QDA)  The covariance matrices can vary among classes. 
'diagquadratic'  QDA  The covariance matrices are diagonal and can vary among classes. 
'pseudoquadratic'  QDA  The covariance matrices can vary among classes. The software inverts the covariance matrix using the pseudo inverse. 
To use regularization, you must specify 'linear'
.
To specify the amount of regularization, use the Gamma
namevalue
pair argument.
Example: 'DiscrimType','quadratic'
'FillCoeffs'
— Coeffs
property flag'on'
 'off'
Coeffs
property flag, specified as the commaseparated pair consisting of
'FillCoeffs'
and 'on'
or
'off'
. Setting the flag to 'on'
populates the
Coeffs
property in the classifier object. This can be
computationally intensive, especially when crossvalidating. The default is
'on'
, unless you specify a crossvalidation namevalue pair, in
which case the flag is set to 'off'
by default.
Example: 'FillCoeffs','off'
'Gamma'
— Amount of regularizationAmount of regularization to apply when estimating the covariance
matrix of the predictors, specified as the commaseparated pair consisting
of 'Gamma'
and a scalar value in the interval [0,1]. Gamma
provides
finer control over the covariance matrix structure than DiscrimType
.
If you specify 0
, then the software
does not use regularization to adjust the covariance matrix. That
is, the software estimates and uses the unrestricted, empirical covariance
matrix.
For linear discriminant analysis, if the empirical
covariance matrix is singular, then the software automatically applies
the minimal regularization required to invert the covariance matrix.
You can display the chosen regularization amount by entering Mdl.Gamma
at
the command line.
For quadratic discriminant analysis, if at least one class has an empirical covariance matrix that is singular, then the software throws an error.
If you specify a value in the interval (0,1), then
you must implement linear discriminant analysis, otherwise the software
throws an error. Consequently, the software sets DiscrimType
to 'linear'
.
If you specify 1
, then the software
uses maximum regularization for covariance matrix estimation. That
is, the software restricts the covariance matrix to be diagonal. Alternatively,
you can set DiscrimType
to 'diagLinear'
or 'diagQuadratic'
for
diagonal covariance matrices.
Example: 'Gamma',1
Data Types: single
 double
'PredictorNames'
— Predictor variable namesPredictor variable names, specified as the commaseparated pair consisting of
'PredictorNames'
and a string array of unique names or cell array
of unique character vectors. The functionality of 'PredictorNames'
depends on the way you supply the training data.
If you supply X
and Y
, then you
can use 'PredictorNames'
to give the predictor variables
in X
names.
The order of the names in PredictorNames
must correspond to the column order of X
.
That is, PredictorNames{1}
is the name of
X(:,1)
,
PredictorNames{2}
is the name of
X(:,2)
, and so on. Also,
size(X,2)
and
numel(PredictorNames)
must be
equal.
By default, PredictorNames
is
{'x1','x2',...}
.
If you supply Tbl
, then you can use
'PredictorNames'
to choose which predictor variables
to use in training. That is, fitcdiscr
uses only the
predictor variables in PredictorNames
and the response
variable in training.
PredictorNames
must be a subset of
Tbl.Properties.VariableNames
and cannot
include the name of the response variable.
By default, PredictorNames
contains the
names of all predictor variables.
It is a good practice to specify the predictors for training
using either 'PredictorNames'
or
formula
only.
Example: 'PredictorNames',{'SepalLength','SepalWidth','PetalLength','PetalWidth'}
Data Types: string
 cell
'Prior'
— Prior probabilities'empirical'
(default)  'uniform'
 vector of scalar values  structurePrior probabilities for each class, specified as the commaseparated
pair consisting of 'Prior'
and a value in this
table.
Value  Description 

'empirical'  The class prior probabilities are the class relative frequencies
in Y . 
'uniform'  All class prior probabilities are equal to 1/K, where K is the number of classes. 
numeric vector  Each element is a class prior probability. Order the elements
according to Mdl .ClassNames or
specify the order using the ClassNames namevalue
pair argument. The software normalizes the elements such that they
sum to 1 . 
structure  A structure

If you set values for both Weights
and Prior
,
the weights are renormalized to add up to the value of the prior probability
in the respective class.
Example: 'Prior','uniform'
Data Types: char
 string
 single
 double
 struct
'ResponseName'
— Response variable name'Y'
(default)  character vector  string scalarResponse variable name, specified as the commaseparated pair consisting of
'ResponseName'
and a character vector or string scalar.
If you supply Y
, then you can
use 'ResponseName'
to specify a name for the response
variable.
If you supply ResponseVarName
or formula
,
then you cannot use 'ResponseName'
.
Example: 'ResponseName','response'
Data Types: char
 string
'SaveMemory'
— Flag to save covariance matrix'off'
(default)  'on'
Flag to save covariance matrix, specified as the commaseparated
pair consisting of 'SaveMemory'
and either 'on'
or 'off'
.
If you specify 'on'
, then fitcdiscr
does
not store the full covariance matrix, but instead stores enough information
to compute the matrix. The predict
method computes the full covariance
matrix for prediction, and does not store the matrix. If you specify 'off'
,
then fitcdiscr
computes and stores the full covariance
matrix in Mdl
.
Specify SaveMemory
as 'on'
when
the input matrix contains thousands of predictors.
Example: 'SaveMemory','on'
'ScoreTransform'
— Score transformation'none'
(default)  'doublelogit'
 'invlogit'
 'ismax'
 'logit'
 function handle  ...Score transformation, specified as the commaseparated pair consisting of
'ScoreTransform'
and a character vector, string scalar, or
function handle.
This table summarizes the available character vectors and string scalars.
Value  Description 

'doublelogit'  1/(1 + e^{–2x}) 
'invlogit'  log(x / (1 – x)) 
'ismax'  Sets the score for the class with the largest score to 1 , and sets the
scores for all other classes to 0 
'logit'  1/(1 + e^{–x}) 
'none' or 'identity'  x (no transformation) 
'sign'  –1 for x < 0 0 for x = 0 1 for x > 0 
'symmetric'  2x – 1 
'symmetricismax'  Sets the score for the class with the largest score to 1 ,
and sets the scores for all other classes to –1 
'symmetriclogit'  2/(1 + e^{–x}) – 1 
For a MATLAB function or a function you define, use its function handle for score transform. The function handle must accept a matrix (the original scores) and return a matrix of the same size (the transformed scores).
Example: 'ScoreTransform','logit'
Data Types: char
 string
 function_handle
'Weights'
— Observation weightsTbl
Observation weights, specified as the commaseparated pair consisting
of 'Weights'
and a numeric vector of positive values
or name of a variable in Tbl
. The software weighs
the observations in each row of X
or Tbl
with
the corresponding value in Weights
. The size of Weights
must
equal the number of rows of X
or Tbl
.
If you specify the input data as a table Tbl
, then
Weights
can be the name of a variable in Tbl
that contains a numeric vector. In this case, you must specify
Weights
as a character vector or string scalar. For example, if
the weights vector W
is stored as Tbl.W
, then
specify it as 'W'
. Otherwise, the software treats all columns of
Tbl
, including W
, as predictors or the
response when training the model.
The software normalizes Weights
to sum up
to the value of the prior probability in the respective class.
By default, Weights
is ones(
,
where n
,1)n
is the number of observations in X
or Tbl
.
Data Types: double
 single
 char
 string
'CrossVal'
— Crossvalidation flag'off'
(default)  'on'
Crossvalidation flag, specified as the commaseparated pair
consisting of 'Crossval'
and 'on'
or 'off'
.
If you specify 'on'
, then the software implements
10fold crossvalidation.
To override this crossvalidation setting, use one of these
namevalue pair arguments: CVPartition
, Holdout
, KFold
,
or Leaveout
. To create a crossvalidated model,
you can use one crossvalidation namevalue pair argument at a time
only.
Alternatively, crossvalidate later by passing Mdl
to crossval
.
Example: 'CrossVal','on'
'CVPartition'
— Crossvalidation partition[]
(default)  cvpartition
partition objectCrossvalidation partition, specified as the commaseparated pair consisting of
'CVPartition'
and a cvpartition
partition
object created by cvpartition
. The partition object
specifies the type of crossvalidation and the indexing for the training and validation
sets.
To create a crossvalidated model, you can use one of these four namevalue pair arguments
only: CVPartition
, Holdout
,
KFold
, or Leaveout
.
Example: Suppose you create a random partition for 5fold crossvalidation on 500
observations by using cvp = cvpartition(500,'KFold',5)
. Then, you can
specify the crossvalidated model by using
'CVPartition',cvp
.
'Holdout'
— Fraction of data for holdout validationFraction of the data used for holdout validation, specified as the commaseparated pair
consisting of 'Holdout'
and a scalar value in the range (0,1). If you
specify 'Holdout',p
, then the software completes these steps:
Randomly select and reserve p*100
% of the data as
validation data, and train the model using the rest of the data.
Store the compact, trained model in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'Holdout',0.1
Data Types: double
 single
'KFold'
— Number of folds10
(default)  positive integer value greater than 1Number of folds to use in a crossvalidated model, specified as the commaseparated pair
consisting of 'KFold'
and a positive integer value greater than 1. If
you specify 'KFold',k
, then the software completes these steps:
Randomly partition the data into k
sets.
For each set, reserve the set as validation data, and train the model
using the other k
– 1 sets.
Store the k
compact, trained models in the cells of a
k
by1 cell vector in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'KFold',5
Data Types: single
 double
'Leaveout'
— Leaveoneout crossvalidation flag'off'
(default)  'on'
Leaveoneout crossvalidation flag, specified as the commaseparated pair consisting of
'Leaveout'
and 'on'
or
'off'
. If you specify 'Leaveout','on'
, then,
for each of the n observations (where n is the
number of observations excluding missing observations, specified in the
NumObservations
property of the model), the software completes
these steps:
Reserve the observation as validation data, and train the model using the other n – 1 observations.
Store the n compact, trained models in the cells of an
nby1 cell vector in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'Leaveout','on'
'OptimizeHyperparameters'
— Parameters to optimize'none'
(default)  'auto'
 'all'
 string array or cell array of eligible parameter names  vector of optimizableVariable
objectsParameters to optimize, specified as the commaseparated pair
consisting of 'OptimizeHyperparameters'
and one of
the following:
'none'
— Do not optimize.
'auto'
— Use
{'Delta','Gamma'}
.
'all'
— Optimize all eligible
parameters.
String array or cell array of eligible parameter names.
Vector of optimizableVariable
objects,
typically the output of hyperparameters
.
The optimization attempts to minimize the crossvalidation loss
(error) for fitcdiscr
by varying the parameters.
For information about crossvalidation loss (albeit in a different
context), see Classification Loss. To control the
crossvalidation type and other aspects of the optimization, use the
HyperparameterOptimizationOptions
namevalue
pair.
'OptimizeHyperparameters'
values override any values you set using
other namevalue pair arguments. For example, setting
'OptimizeHyperparameters'
to 'auto'
causes the
'auto'
values to apply.
The eligible parameters for fitcdiscr
are:
Delta
—
fitcdiscr
searches among positive
values, by default logscaled in the range
[1e6,1e3]
.
DiscrimType
—
fitcdiscr
searches among
'linear'
, 'quadratic'
,
'diagLinear'
,
'diagQuadratic'
,
'pseudoLinear'
, and
'pseudoQuadratic'
.
Gamma
—
fitcdiscr
searches among real values in
the range [0,1]
.
Set nondefault parameters by passing a vector of
optimizableVariable
objects that have nondefault
values. For example,
load fisheriris params = hyperparameters('fitcdiscr',meas,species); params(1).Range = [1e4,1e6];
Pass params
as the value of
OptimizeHyperparameters
.
By default, iterative display appears at the command line, and
plots appear according to the number of hyperparameters in the optimization. For the
optimization and plots, the objective function is log(1 + crossvalidation loss) for regression and the misclassification rate for classification. To control
the iterative display, set the Verbose
field of the
'HyperparameterOptimizationOptions'
namevalue pair argument. To
control the plots, set the ShowPlots
field of the
'HyperparameterOptimizationOptions'
namevalue pair argument.
For an example, see Optimize Discriminant Analysis Model.
Example: 'auto'
'HyperparameterOptimizationOptions'
— Options for optimizationOptions for optimization, specified as the commaseparated pair consisting of
'HyperparameterOptimizationOptions'
and a structure. This
argument modifies the effect of the OptimizeHyperparameters
namevalue pair argument. All fields in the structure are optional.
Field Name  Values  Default 

Optimizer 
 'bayesopt' 
AcquisitionFunctionName 
Acquisition functions whose names include
 'expectedimprovementpersecondplus' 
MaxObjectiveEvaluations  Maximum number of objective function evaluations.  30 for 'bayesopt' or 'randomsearch' , and the entire grid for 'gridsearch' 
MaxTime  Time limit, specified as a positive real. The time limit is in seconds, as measured by  Inf 
NumGridDivisions  For 'gridsearch' , the number of values in each dimension. The value can be
a vector of positive integers giving the number of
values for each dimension, or a scalar that
applies to all dimensions. This field is ignored
for categorical variables.  10 
ShowPlots  Logical value indicating whether to show plots. If true , this field plots
the best objective function value against the
iteration number. If there are one or two
optimization parameters, and if
Optimizer is
'bayesopt' , then
ShowPlots also plots a model of
the objective function against the
parameters.  true 
SaveIntermediateResults  Logical value indicating whether to save results when Optimizer is
'bayesopt' . If
true , this field overwrites a
workspace variable named
'BayesoptResults' at each
iteration. The variable is a BayesianOptimization object.  false 
Verbose  Display to the command line.
For details, see the
 1 
UseParallel  Logical value indicating whether to run Bayesian optimization in parallel, which requires Parallel Computing Toolbox™. Due to the nonreproducibility of parallel timing, parallel Bayesian optimization does not necessarily yield reproducible results. For details, see Parallel Bayesian Optimization.  false 
Repartition  Logical value indicating whether to repartition the crossvalidation at every iteration. If
 false 
Use no more than one of the following three field names.  
CVPartition  A cvpartition object, as created by cvpartition .  'Kfold',5 if you do not specify any crossvalidation
field 
Holdout  A scalar in the range (0,1) representing the holdout fraction.  
Kfold  An integer greater than 1. 
Example: 'HyperparameterOptimizationOptions',struct('MaxObjectiveEvaluations',60)
Data Types: struct
Mdl
— Trained discriminant analysis classification modelClassificationDiscriminant
model object  ClassificationPartitionedModel
crossvalidated model
objectTrained discriminant analysis classification model, returned as a ClassificationDiscriminant
model
object or a ClassificationPartitionedModel
crossvalidated model object.
If you set any of the namevalue pair arguments
KFold
, Holdout
,
CrossVal
, or CVPartition
, then
Mdl
is a
ClassificationPartitionedModel
crossvalidated model
object. Otherwise, Mdl
is a
ClassificationDiscriminant
model object.
To reference properties of Mdl
, use dot notation. For
example, to display the estimated component means at the Command Window,
enter Mdl.Mu
.
The model for discriminant analysis is:
Each class (Y
) generates data (X
) using a
multivariate normal distribution. That is, the model assumes X
has a Gaussian mixture distribution (gmdistribution
).
For linear discriminant analysis, the model has the same covariance matrix for each class, only the means vary.
For quadratic discriminant analysis, both means and covariances of each class vary.
predict
classifies so as to minimize the expected
classification cost:
$$\widehat{y}=\underset{y=1,\mathrm{...},K}{\mathrm{arg}\mathrm{min}}{\displaystyle \sum _{k=1}^{K}\widehat{P}\left(kx\right)C\left(yk\right)},$$
where
$$\widehat{y}$$ is the predicted classification.
K is the number of classes.
$$\widehat{P}\left(kx\right)$$ is the posterior probability of class k for observation x.
$$C\left(yk\right)$$ is the cost of classifying an observation as y when its true class is k.
For details, see Prediction Using Discriminant Analysis Models.
After training a model, you can generate C/C++ code that predicts labels for new data. Generating C/C++ code requires MATLAB Coder™. For details, see Introduction to Code Generation.
The classify
function also performs
discriminant analysis. classify
is usually more awkward to
use.
classify
requires you to fit the classifier every
time you make a new prediction.
classify
does not perform crossvalidation or
hyperparameter optimization.
classify
requires you to fit the classifier when
changing prior probabilities.
Usage notes and limitations:
Supported syntaxes are:
Mdl = fitcdiscr(Tbl,Y)
Mdl = fitcdiscr(X,Y)
Mdl = fitcdiscr(___,Name,Value)
[Mdl,FitInfo,HyperparameterOptimizationResults] =
fitcdiscr(___,Name,Value)
— fitcdiscr
returns the additional output arguments FitInfo
and
HyperparameterOptimizationResults
when you specify the
'OptimizeHyperparameters'
namevalue pair
argument.
The FitInfo
output argument is an empty structure array currently
reserved for possible future use.
The HyperparameterOptimizationResults
output argument is a BayesianOptimization
object or a
table of hyperparameters with associated values that describe the crossvalidation
optimization of hyperparameters.
'HyperparameterOptimizationResults'
is nonempty when the
'OptimizeHyperparameters'
namevalue pair argument is
nonempty at the time you create the model. The values in
'HyperparameterOptimizationResults'
depend on the value
you specify for the 'HyperparameterOptimizationOptions'
namevalue pair argument when you create the model.
If you specify 'bayesopt'
(default), then
HyperparameterOptimizationResults
is an object of class BayesianOptimization
.
If you specify 'gridsearch'
or
'randomsearch'
, then
HyperparameterOptimizationResults
is a table of the hyperparameters used, observed objective
function values (crossvalidation loss), and rank of
observations from lowest (best) to highest (worst).
Supported namevalue pair arguments, and any differences, are:
'ClassNames'
'Cost'
'DiscrimType'
'HyperparameterOptimizationOptions'
— For
crossvalidation, tall optimization supports only
'Holdout'
validation. For example, you can specify
fitcdiscr(X,Y,'OptimizeHyperparameters','auto','HyperparameterOptimizationOptions',struct('Holdout',0.2))
.
'OptimizeHyperparameters'
— The only eligible
parameter to optimize is 'DiscrimType'
. Specifying
'auto'
uses 'DiscrimType'
.
'PredictorNames'
'Prior'
'ResponseName'
'ScoreTransform'
'Weights'
For tall arrays and tall tables, fitcdiscr
returns
a CompactClassificationDiscriminant
object, which
contains most of the same properties as a ClassificationDiscriminant
object.
The main difference is that the compact object is sensitive to memory
requirements. The compact object does not include properties that
include the data, or that include an array of the same size as the
data. The compact object does not contain these ClassificationDiscriminant
properties:
ModelParameters
NumObservations
HyperparameterOptimizationResults
RowsUsed
XCentered
W
X
Y
Additionally, the compact object does not support these ClassificationDiscriminant
methods:
compact
crossval
cvshrink
resubEdge
resubLoss
resubMargin
resubPredict
For more information, see Tall Arrays (MATLAB).
To run in parallel, set the 'UseParallel'
option to true
.
To perform parallel hyperparameter optimization, use the 'HyperparameterOptions', struct('UseParallel',true)
namevalue pair argument in the call to this function.
For more information on parallel hyperparameter optimization, see Parallel Bayesian Optimization.
For more general information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).
ClassificationDiscriminant
 ClassificationPartitionedModel
 classify
 crossval
 predict
A modified version of this example exists on your system. Do you want to open this version instead?
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.