edge
Classification edge for classification ensemble model
Description
returns the classification edge
e
= edge(ens
,tbl
,ResponseVarName
)e
for the trained classification ensemble model
ens
using the predictor data in table
tbl
and the class labels in
tbl.ResponseVarName
.
The classification edge e
is a vector or scalar depending on
the setting of the Mode
name-value
argument.
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 indices of weak learners in the ensemble to use for calculating margins, specify
observation weights, and perform computations in parallel.e
= edge(___,Name=Value
)
Note
If the predictor data X
or the predictor variables in
tbl
contain any missing values, the
edge
function might return NaN. For more
details, see edge might return NaN for predictor data with missing values.
Examples
Find Classification Edge of Training Data
Find the classification edge for some of the data used to train a boosted ensemble classifier.
Load the ionosphere
data set.
load ionosphere
Train an ensemble of 100 boosted classification trees using AdaBoostM1.
t = templateTree(MaxNumSplits=1); % Weak learner template tree object ens = fitcensemble(X,Y,"Method","AdaBoostM1","Learners",t);
Find the classification edge for the last few rows.
E = edge(ens,X(end-10:end,:),Y(end-10:end))
E = 8.3310
Input Arguments
ens
— Classification ensemble model
ClassificationEnsemble
model object | ClassificationBaggedEnsemble
model object | CompactClassificationEnsemble
model object
Classification ensemble model, specified as a ClassificationEnsemble
or ClassificationBaggedEnsemble
model object trained with fitcensemble
, or a CompactClassificationEnsemble
model object created with compact
.
tbl
— Sample data
table
Sample data, specified as a table. Each row of tbl
corresponds to
one observation, and each column corresponds to one predictor variable.
tbl
must contain all of the predictors used to train the model.
Multicolumn variables and cell arrays other than cell arrays of character vectors are
not allowed.
If you trained ens
using sample data contained in a table, then
the input data for edge
must also be in a table.
Data Types: table
ResponseVarName
— Response variable name
name of variable in tbl
Response variable name, specified as the name of a variable in
tbl
. If tbl
contains the response variable
used to train ens
, then you do not need to specify
ResponseVarName
.
If you specify ResponseVarName
, you must specify it 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.
The response variable must be a categorical, character, or string array, a logical or numeric vector, or a cell array of character vectors. If the response variable is a character array, then each element must correspond to one row of the array.
Data Types: char
| string
Y
— Class labels
categorical array | character array | string array | logical vector | numeric vector | cell array of character vectors
Class labels, specified as a categorical, character, or string array, a logical or numeric
vector, or a cell array of character vectors. Y
must have the same
data type as tbl
or X
. (The software treats string arrays as cell arrays of character
vectors.)
Y
must be of the same type as the classification used to train
ens
, and its number of elements must equal the number of rows
of tbl
or X
.
Data Types: categorical
| char
| string
| logical
| single
| double
| cell
X
— Predictor data
numeric matrix
Predictor data, specified as a numeric matrix.
Each row of X
corresponds to one observation, and each column
corresponds to one variable. The variables in the columns of X
must
be the same as the variables used to train ens
.
The number of rows in X
must equal the number of rows in
Y
.
If you trained ens
using sample data contained in a matrix, then
the input data for edge
must also be in a matrix.
Data Types: double
| single
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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: edge(Mdl,X,Mode="individual",UseParallel=true)
specifies to output a vector with one element per trained learner, and to run in
parallel.
Learners
— Indices of weak learners
[1:ens.NumTrained]
(default) | vector of positive integers
Indices of the weak learners in the ensemble to use with
edge
, specified as a
vector of positive integers in the range
[1:ens.NumTrained
]. By default,
the function uses all learners.
Example: Learners=[1 2 4]
Data Types: single
| double
Mode
— Aggregation level for output
"ensemble"
(default) | "individual"
| "cumulative"
Aggregation level for the output, specified as "ensemble"
,
"individual"
, or "cumulative"
.
Value | Description |
---|---|
"ensemble" | The output is a scalar value, the loss for the entire ensemble. |
"individual" | The output is a vector with one element per trained learner. |
"cumulative" | The output is a vector in which element J is
obtained by using learners 1:J from the input
list of learners. |
Example: Mode="individual"
Data Types: char
| string
UseObsForLearner
— Option to use observations for learners
true(N,T)
(default) | logical matrix
Option to use observations for learners, specified as a logical matrix of size
N
-by-T
, where:
When UseObsForLearner(i,j)
is true
(default),
learner j
is used in predicting the class of row i
of X
.
Example: UseObsForLearner=logical([1 1; 0 1; 1 0])
Data Types: logical matrix
UseParallel
— Flag to run in parallel
false
or 0
(default) | true
or 1
Flag to run in parallel, specified as a numeric or logical
1
(true
) or 0
(false
). If you specify UseParallel=true
, the
edge
function executes for
-loop iterations by
using parfor
. The loop runs in parallel when you
have Parallel Computing Toolbox™.
Example: UseParallel=true
Data Types: logical
Weights
— Observation weights
ones(size(X,1),1)
(default) | numeric vector | name of variable in tbl
Observation weights, specified as a numeric vector or the name of a
variable in tbl
. If you supply weights,
edge
computes the weighted classification
edge.
If you specify Weights
as a numeric vector, then
the size of Weights
must be equal to the number of
observations in X
or tbl
. The
software normalizes Weights
to sum up to the value
of the prior probability in the respective class.
If you specify Weights
as the name of a variable
in tbl
, you must specify it as a character vector
or string scalar. For example, if the weights are stored as
tbl.w
, then specify Weights
as "w"
. Otherwise, the software treats all columns of
tbl
, including tbl.w
, as
predictors.
Data Types: single
| double
| char
| string
More About
Margin
The classification margin is the difference between the
classification score for the true class and maximal
classification score for the false classes. Margin is a column vector with the same
number of rows as in the matrix X
.
Score (ensemble)
For ensembles, a classification score represents the confidence of a classification into a class. The higher the score, the higher the confidence.
Different ensemble algorithms have different definitions for their scores. Furthermore, the range of scores depends on ensemble type. For example:
AdaBoostM1
scores range from –∞ to ∞.Bag
scores range from0
to1
.
Classification Edge
The edge is the weighted mean value of the classification
margin. The weights are the class probabilities in
ens
.Prior
. If you supply weights in the
Weights
name-value argument, those weights are used instead
of class probabilities.
Extended Capabilities
Tall Arrays
Calculate with arrays that have more rows than fit in memory.
Usage notes and limitations:
You cannot use the
UseParallel
name-value argument with tall arrays.
For more information, see Tall Arrays.
Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.
To run in parallel, set the UseParallel
name-value argument to
true
in the call to this function.
For more general information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).
You cannot use the UseParallel
name-value
argument with tall arrays, GPU arrays, or code generation.
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
Usage notes and limitations:
The
edge
function does not support ensembles trained using decision tree learners with surrogate splits.
For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).
Version History
Introduced in R2011aR2022a: edge
returns a different value for a model with a nondefault cost matrix
If you specify a nondefault cost matrix when you train the input model object, the edge
function returns a different value compared to previous releases.
The edge
function uses the prior
probabilities stored in the Prior
property to normalize the observation
weights of the input data. The way the function uses the Prior
property
value has not changed. However, the property value stored in the input model object has changed
for a model with a nondefault cost matrix, so the function can return a different value.
For details about the property value changes, see Cost property stores the user-specified cost matrix.
If you want the software to handle the cost matrix, prior
probabilities, and observation weights in the same way as in previous releases, adjust the prior
probabilities and observation weights for the nondefault cost matrix, as described in Adjust Prior Probabilities and Observation Weights for Misclassification Cost Matrix. Then, when you train a
classification model, specify the adjusted prior probabilities and observation weights by using
the Prior
and Weights
name-value arguments, respectively,
and use the default cost matrix.
R2022a: edge
might return NaN for predictor data with missing values
The edge
function no longer omits an observation
with a NaN score when computing the weighted mean of the classification margins.
Therefore, edge
might now return NaN when the
predictor data X
or the predictor variables in
tbl
contain any missing values. In most cases, if the
test set observations do not contain missing predictors, the
edge
function does not return NaN.
This change improves the automatic selection of a classification model when
you use fitcauto
. Before this change, the software might select a model
(expected to best classify new data) with few non-NaN predictors.
If edge
in your code returns NaN, you can update
your code to avoid this result. Remove or replace the missing values by using
rmmissing
or fillmissing
, respectively.
The following table shows the classification models for which the
edge
object function might return NaN. For more
details, see the Compatibility Considerations for each
edge
function.
Model Type | Full or Compact Model Object | edge Object Function |
---|---|---|
Discriminant analysis classification model | ClassificationDiscriminant , CompactClassificationDiscriminant | edge |
Ensemble of learners for classification | ClassificationEnsemble , CompactClassificationEnsemble | edge |
Gaussian kernel classification model | ClassificationKernel | edge |
k-nearest neighbor classification model | ClassificationKNN | edge |
Linear classification model | ClassificationLinear | edge |
Neural network classification model | ClassificationNeuralNetwork , CompactClassificationNeuralNetwork | edge |
Support vector machine (SVM) classification model | edge |
MATLAB Command
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.
Select a Web Site
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: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)