# loss

Regression error for regression ensemble model

## Syntax

``L = loss(ens,tbl,ResponseVarName)``
``L = loss(ens,tbl,ResponseVarName)``
``L = loss(ens,tbl,Y)``
``L = loss(ens,X,Y)``
``L = loss(___,Name=Value)``

## Description

````L = loss(ens,tbl,ResponseVarName)` returns the mean squared error `L`between the predictions of `ens` to the data in `tbl`, compared to the true responses `tbl.ResponseVarName`. The interpretation of `L` depends on the loss function (`LossFun`) and weighting scheme (`Weights`). In general, better classifiers yield smaller classification loss values. The formula for `loss` is described in the section Weighted Mean Squared Error.```
````L = loss(ens,tbl,ResponseVarName)` returns the Classification Loss `L` for the trained classification ensemble model `ens` using the predictor data in table `tbl` and the true class labels in `tbl.ResponseVarName`.```

example

````L = loss(ens,tbl,Y)` returns the mean squared error between the predictions of `ens` to the data in `tbl`, compared to the true responses `Y`.```
````L = loss(ens,X,Y)` returns the mean squared error between the predictions of `ens` to the data in `X`, compared to the true responses `Y`.```
````L = loss(___,Name=Value)` 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 loss function, the aggregation level for output, and whether to perform calculations in parallel.```

## Examples

collapse all

Find the loss of an ensemble predictor using the `carsmall` data set.

Load the `carsmall` data set and select engine displacement, horsepower, and vehicle weight as predictors.

```load carsmall X = [Displacement Horsepower Weight];```

Train an ensemble of regression trees and find the regression error for predicting `MPG`.

```ens = fitrensemble(X,MPG); L = loss(ens,X,MPG)```
```L = 0.3463 ```

## Input Arguments

collapse all

Full regression ensemble model, specified as a `RegressionEnsemble` model object trained with `fitrensemble`, or a `CompactRegressionEnsemble` model object created with `compact`.

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 `loss` must also be in a table.

Data Types: `table`

Response variable name, specified as the name of a variable in `tbl`. The response variable must be a numeric vector.

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.

Data Types: `char` | `string`

Response data, specified as a numeric column vector with the same number of rows as `tbl` or `X`. Each entry in `Y` is the true response to the data in the corresponding row of `tbl` or `X`.

The software treats `NaN` values in `Y` as missing values. Observations with missing values for `Y` are not used in the loss calculation.

Data Types: `double` | `single`

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 `loss` 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: `loss(Mdl,X,Learners=[1 2 4],UseParallel=true)` specifies to use the first, second, and fourth weak learners in the ensemble, and to perform computations in parallel.

Indices of weak learners in the ensemble to use in `loss`, 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`

Loss function, specified as `"mse"` (mean squared error) or as a function handle. If you pass a function handle `fun`, `loss` calls it as

`fun(Y,Yfit,W)`

where `Y`, `Yfit`, and `W` are numeric vectors of the same length.

• `Y` is the observed response.

• `Yfit` is the predicted response.

• `W` is the observation weights.

The returned value of `fun(Y,Yfit,W)` must be a scalar.

Example: `LossFun="mse"`

Example: `LossFun=@Lossfun`

Data Types: `char` | `string` | `function_handle`

Aggregation level for the output, specified as `"ensemble"`, `"individual"`, or `"cumulative"`.

ValueDescription
`"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`

Logical matrix of size `N`-by-`NumTrained`, where `N` is the number of observations in `ens``.X`, and `NumTrained` is the number of weak learners. When `UseObsForLearner(i,j)` is `true` (default), learner `j` is used in predicting the response of row `i` of `X`.

Data Types: `logical matrix`

Flag to run in parallel, specified as a numeric or logical `1` (`true`) or `0` (`false`). If you specify `UseParallel=true`, the `loss` 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`

Observation weights, specified as a numeric vector or the name of a variable in `tbl`. The software weighs the observations in each row of `X` or `tbl` with the corresponding weight in `Weights`. The formula for `loss` with `Weights` is described in the section Weighted Mean Squared Error.

If you specify `Weights` as a numeric vector, then the size of `Weights` must be equal to the number of rows in `X` or `tbl`.

If you specify `Weights` as the name of a variable in `tbl`, you must do so 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.

If you do not specify your own loss function, then the software normalizes `Weights` to sum up to the value of the prior probability in the respective class.

Example: `Weights="W"`

Data Types: `single` | `double` | `char` | `string`

collapse all

### Weighted Mean Squared Error

Let n be the number of rows of data, xj be the jth row of data, yj be the true response to xj, and let f(xj) be the response prediction of `ens` to xj. Let w be the vector of weights (all one by default).

First the weights are divided by their sum so they add to one: www. The mean squared error L is

`$L=\sum _{j=1}^{n}{w}_{j}{\left(f\left({x}_{j}\right)-{y}_{j}\right)}^{2}.$`

## Version History

Introduced in R2011a