edge

Classification edge

expand all in page

Syntax

E = edge(ens,tbl,ResponseVarName) E = edge(ens,tbl,Y) E = edge(ens,X,Y) E = edge(___,Name,Value)

Description

E= edge(ens,tbl,ResponseVarName)returns the classification edge forenswith datatbland classificationtbl.ResponseVarName.

E= edge(ens,tbl,Y)returns the classification edge forenswith datatbland classificationY.

E= edge(ens,X,Y)returns the classification edge forenswith dataXand classificationY.

E= edge(___,Name,Value)computes the edge with additional options specified by one or moreName,Valuepair arguments, using any of the previous syntaxes.

Note

If the predictor dataXor the predictor variables intblcontain any missing values, theedgefunction can return NaN. For more details, seeedge can return NaN for predictor data with missing values.

Input Arguments

`ens`	A classification ensemble constructed with`fitcensemble`, or a compact classification ensemble constructed with`compact`.
`tbl`	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 this method must also be in a table.
`ResponseVarName`	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.
`X`	矩阵中每一行代表一个观察,and each column represents a predictor. The number of columns in`X`must equal the number of predictors in`ens`. If you trained`ens`using sample data contained in a matrix, then the input data for this method must also be in a matrix.
`Y`	Class labels of observations in`tbl`or`X`.`Y`should be of the same type as the classification used to train`ens`, and its number of elements should equal the number of rows of`tbl`or`X`.

Name-Value Arguments

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, whereNameis the argument name andValueis 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 encloseNamein quotes.

`learners`	Indices of weak learners in the ensemble ranging from`1`to`ens.NumTrained`.`edge`uses only these learners for calculating loss. Default:`1:NumTrained`
`mode`	Meaning of the output`E`: `'ensemble'`—`E`is a scalar value, the edge for the entire ensemble. `'individual'`—`E`is a vector with one element per trained learner. `'cumulative'`—`E`is a vector in which element`J`is obtained by using learners`1:J`from the input list of learners. Default:`'ensemble'`
`UseObsForLearner`	A logical matrix of size`N`-by-`T`, where: `N`is the number of rows of`X`. `T`is the number of weak learners in`ens`. When`UseObsForLearner(i,j)`is`true`, learner`j`is used in predicting the class of row`i`of`X`. Default:`true(N,T)`
`UseParallel`	Indication to perform inference in parallel, specified as`false`(compute serially) or`true`(并行计算)。并行计算要求es Parallel Computing Toolbox™. Parallel inference can be faster than serial inference, especially for large datasets. Parallel computation is supported only for tree learners. Default:`false`
`weights`	Observation weights, a numeric vector of length`size(X,1)`. If you supply weights,`edge`computes weighted classification edge. Default:`ones(size(X,1),1)`

Output Arguments

`E`	The classification edge, a vector or scalar depending on the setting of the`mode`name-value pair. Classification edge is weighted average classification margin.

Examples

expand all

Find Classification Edge of Training Data

Open Live Script

Find the classification edge for some of the data used to train a boosted ensemble classifier.

Load theionospheredata set.

loadionosphere

Train an ensemble of 100 boosted classification trees using AdaBoostM1.

t = templateTree('MaxNumSplits',1);% Weak learner template tree objectens = fitcensemble(X,Y,'Method','AdaBoostM1',“那时rs',t);

Find the classification edge for the last few rows.

E = edge(ens,X(end-10:end,:),Y(end-10:end))

E = 8.3310

More About

expand all

Margin

The classificationmarginis the difference between the classificationscorefor 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 matrixX.

Score (ensemble)

For ensembles, a classificationscorerepresents 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:

AdaBoostM1scores range from –∞ to ∞.
Bagscores range from0to1.

Edge

Theedgeis the weighted mean value of the classification margin. The weights are the class probabilities inens.Prior. If you supply weights in theweightsname-value pair, 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 useUseParallelwith tall arrays.

For more information, seeTall Arrays.

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, set theUseParallelname-value argument totruein the call to this function.

For more general information about parallel computing, seeRun MATLAB Functions with Automatic Parallel Support(Parallel Computing Toolbox).

You cannot useUseParallelwith tall or GPU arrays.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

Theedgefunction does not support ensembles trained using decision tree learners with surrogate splits.

For more information, seeRun MATLAB Functions on a GPU(Parallel Computing Toolbox).

Version History

expand all

R2022a:`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, theedgefunction returns a different value compared to previous releases.

Theedgefunction uses the prior probabilities stored in thePriorproperty to normalize the observation weights of the input data. The way the function uses thePriorproperty 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 change, seeCost property stores the user-specified cost matrix.

If you want the software to handle the cost matrix, prior probabilities, and observation weights as in previous releases, adjust the prior probabilities and observation weights for the nondefault cost matrix, as described inAdjust 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 thePriorandWeightsname-value arguments, respectively, and use the default cost matrix.

R2022a:`edge`can return NaN for predictor data with missing values

Theedgefunction no longer omits an observation with a NaN score when computing the weighted mean of the classification margins. Therefore,edgecan now return NaN when the predictor dataXor the predictor variables intblcontain any missing values. In most cases, if the test set observations do not contain missing predictors, theedgefunction does not return NaN.

This change improves the automatic selection of a classification model when you usefitcauto. Before this change, the software might select a model (expected to best classify new data) with few non-NaN predictors.

Ifedgein your code returns NaN, you can update your code to avoid this result. Remove or replace the missing values by usingrmmissingorfillmissing, respectively.

The following table shows the classification models for which theedgeobject function might return NaN. For more details, see the Compatibility Considerations for eachedgefunction.

Model Type	Full or Compact Model Object	`edge`Object Function
判别分析分类模型	`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	`ClassificationSVM`,`CompactClassificationSVM`	`edge`

edge

Syntax

Description

Input Arguments

Name-Value Arguments

Output Arguments

Examples

Find Classification Edge of Training Data

More About

Margin

Score (ensemble)

Edge

Extended Capabilities

Tall ArraysCalculate with arrays that have more rows than fit in memory.

Automatic Parallel SupportAccelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

GPU ArraysAccelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2022a:edgereturns a different value for a model with a nondefault cost matrix

R2022a:edgecan return NaN for predictor data with missing values

See Also

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

R2022a:`edge`returns a different value for a model with a nondefault cost matrix

R2022a:`edge`can return NaN for predictor data with missing values