# 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 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`. The interpretation of `L` depends on the loss function (`LossFun`) and weighting scheme (`Weights`). In general, better classifiers yield smaller classification loss values. The default `LossFun` value is `"classiferror"` (misclassification rate in decimal).```

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

## Input Arguments

expand 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 when training the model.

Data Types: `char` | `string`

Responses, 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 with the same number of elements as `Y`. The formula for `loss` with `weights` is described in the section Weighted Mean Squared Error.

Data Types: `single` | `double`

## Examples

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