# 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 true 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.

## Input Arguments

`ens`

— Classification ensemble model

`ClassificationEnsemble`

model object | `CompactClassificationEnsemble`

model object

Full classification ensemble model, specified as a `ClassificationEnsemble`

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`

`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 weak learners in the ensemble to use in
`edge`

, specified as a vector of positive integers in the range
[1:`ens.NumTrained`

]. By default, all learners are used.

**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`

## 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

## 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 from`0`

to`1`

.

### 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 R2011a**

### 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, 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` |

## See Also

`margin`

| `loss`

| `predict`

| `ClassificationEnsemble`

| `CompactClassificationEnsemble`

| `fitcensemble`

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## 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)