# resubLoss

Classification error by resubstitution

## Syntax

```L = resubLoss(ens) L = resubLoss(ens,Name,Value) ```

## Description

`L = resubLoss(ens)` returns the resubstitution loss, meaning the loss computed for the data that `fitcensemble` used to create `ens`.

`L = resubLoss(ens,Name,Value)` calculates loss with additional options specified by one or more `Name,Value` pair arguments. You can specify several name-value pair arguments in any order as `Name1,Value1,…,NameN,ValueN`.

## Input Arguments

 `ens` A classification ensemble created with `fitcensemble`.

### Name-Value Arguments

Specify optional comma-separated 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`.

`learners`

Indices of weak learners in the ensemble ranging from `1` to `NumTrained`. `resubLoss` uses only these learners for calculating loss.

Default: `1:NumTrained`

`lossfun`

Loss function, specified as the comma-separated pair consisting of `'LossFun'` and a built-in, loss-function name or function handle.

• The following table lists the available loss functions. Specify one using its corresponding character vector or string scalar.

ValueDescription
`'binodeviance'`Binomial deviance
`'classiferror'`Misclassified rate in decimal
`'exponential'`Exponential loss
`'hinge'`Hinge loss
`'logit'`Logistic loss
`'mincost'`Minimal expected misclassification cost (for classification scores that are posterior probabilities)
`'quadratic'`Quadratic loss

`'mincost'` is appropriate for classification scores that are posterior probabilities.

• Bagged and subspace ensembles return posterior probabilities by default (`ens.Method` is `'Bag'` or `'Subspace'`).

• If the ensemble method is `'AdaBoostM1'`, `'AdaBoostM2'`, `GentleBoost`, or `'LogitBoost'`, then, to use posterior probabilities as classification scores, you must specify the double-logit score transform by entering

`ens.ScoreTransform = 'doublelogit';`

• For all other ensemble methods, the software does not support posterior probabilities as classification scores.

• Specify your own function using function handle notation.

Suppose that `n` be the number of observations in `X` and `K` be the number of distinct classes (`numel(ens.ClassNames)`, `ens` is the input model). Your function must have this signature

``lossvalue = lossfun(C,S,W,Cost)``
where:

• The output argument `lossvalue` is a scalar.

• You choose the function name (`lossfun`).

• `C` is an `n`-by-`K` logical matrix with rows indicating which class the corresponding observation belongs. The column order corresponds to the class order in `ens.ClassNames`.

Construct `C` by setting `C(p,q) = 1` if observation `p` is in class `q`, for each row. Set all other elements of row `p` to `0`.

• `S` is an `n`-by-`K` numeric matrix of classification scores. The column order corresponds to the class order in `ens.ClassNames`. `S` is a matrix of classification scores, similar to the output of `predict`.

• `W` is an `n`-by-1 numeric vector of observation weights. If you pass `W`, the software normalizes them to sum to `1`.

• `Cost` is a K-by-`K` numeric matrix of misclassification costs. For example, ```Cost = ones(K) - eye(K)``` specifies a cost of `0` for correct classification, and `1` for misclassification.

Specify your function using `'LossFun',@lossfun`.

For more details on loss functions, see Classification Loss.

Default: `'classiferror'`

`mode`

Character vector or string scalar representing the meaning of the output `L`:

• `'ensemble'``L` is a scalar value, the loss for the entire ensemble.

• `'individual'``L` is a vector with one element per trained learner.

• `'cumulative'``L` is a vector in which element `J` is obtained by using learners `1:J` from the input list of learners.

Default: `'ensemble'`

## Output Arguments

 `L` Classification loss, by default the fraction of misclassified data. `L` can be a vector, and can mean different things, depending on the name-value pair settings.

## Examples

expand all

`load fisheriris`

Train a classification ensemble of 100 decision trees using AdaBoostM2. Specify tree stumps as the weak learners.

```t = templateTree('MaxNumSplits',1); ens = fitcensemble(meas,species,'Method','AdaBoostM2','Learners',t);```

Estimate the resubstitution classification error.

`loss = resubLoss(ens)`
```loss = 0.0333 ```

expand all