# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# loss

Class: ClassificationKNN

Loss of k-nearest neighbor classifier

## Syntax

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

## Description

````L = loss(mdl,tbl,ResponseVarName)` returns a scalar representing how well `mdl` classifies the data in `tbl`, when `tbl.ResponseVarName` contains the true classifications.When computing the loss, `loss` normalizes the class probabilities in `tbl.ResponseVarNames` to the class probabilities used for training, stored in the `Prior` property of `mdl`.```
````L = loss(mdl,tbl,Y)` returns a scalar representing how well `mdl` classifies the data in `tbl`, when `Y` contains the true classifications.When computing the loss, `loss` normalizes the class probabilities in `Y` to the class probabilities used for training, stored in the `Prior` property of `mdl`.```
````L = loss(mdl,X,Y)` returns a scalar representing how well `mdl` classifies the data in `X`, when `Y` contains the true classifications.When computing the loss, `loss` normalizes the class probabilities in `Y` to the class probabilities used for training, stored in the `Prior` property of `mdl`.```
````L = loss(___,Name,Value)` returns the loss with additional options specified by one or more `Name,Value` pair arguments, using any of the previous syntaxes.```

## Input Arguments

expand all

k-nearest neighbor classifier model, returned as a classifier model object.

Note that using the `'CrossVal'`, `'KFold'`, `'Holdout'`, `'Leaveout'`, or `'CVPartition'` options results in a model of class `ClassificationPartitionedModel`. You cannot use a partitioned tree for prediction, so this kind of tree does not have a `predict` method.

Otherwise, `mdl` is of class `ClassificationKNN`, and you can use the `predict` method to make predictions.

Sample data used to train the model, specified as a table. Each row of `tbl` corresponds to one observation, and each column corresponds to one predictor variable. Optionally, `tbl` can contain one additional column for the response variable. Multi-column variables and cell arrays other than cell arrays of character vectors are not allowed.

If `tbl` contains the response variable used to train `mdl`, then you do not need to specify `ResponseVarName` or `Y`.

If you trained `mdl` using sample data contained in a `table`, then the input data for this method must also be in a table.

Data Types: `table`

Response variable name, specified as the name of a variable in `tbl`. If `tbl` contains the response variable used to train `mdl`, then you do not need to specify `ResponseVarName`.

If you specify `ResponseVarName`, then you must do so as a character vector. For example, if the response variable is stored as `tbl.response`, then specify it as `'response'`. Otherwise, the software treats all columns of `tbl`, including `tbl.response`, as predictors.

The response variable must be a categorical or character array, logical or numeric vector, or cell array of character vectors. If the response variable is a character array, then each element must correspond to one row of the array.

Matrix of predictor values. Each column of `X` represents one variable, and each row represents one observation.

A categorical array, cell array of character vectors, character array, logical vector, or a numeric vector with the same number of rows as `X`. Each row of `Y` represents the classification of the corresponding row of `X`.

### Name-Value Pair 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 single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

expand all

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

• The following lists available loss functions. Specify one using its corresponding character vector.

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

`'mincost'` is appropriate for classification scores that are posterior probabilities k-nearest neighbor models return posterior probabilities as classification scores by default (see `predict`).

• 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(mdl.ClassNames)`). 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 `mdl.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 `mdl.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.

Data Types: `char` | `function_handle`

Observation weights, specified as the comma-separated pair consisting of `'Weights'` and a numeric vector or the name of a variable in `tbl`.

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

If you specify `Weights` as the name of a variable in `tbl`, you must do so as a character vector, such as `'W'`. For example, if the weights are stored as `tbl.w`, then specify it as `'w'`. Otherwise, the software treats all columns of `tbl`, including `tbl.w`, as predictors.

`loss` normalizes the weights so that observation weights in each class sum to the prior probability of that class. When you supply `Weights`, `loss` computes weighted classification loss.

Data Types: `single` | `double`

## Output Arguments

expand all

Classification loss, returned as a scalar value. The meaning of the error depends on the values in `weights` and `lossfun`.

## Examples

expand all

Construct a k-nearest neighbor classifier for the Fisher iris data, where k = 5.

```load fisheriris ```

Construct a classifier for 5-nearest neighbors.

```mdl = fitcknn(meas,species,'NumNeighbors',5); ```

Examine the loss of the classifier for a mean observation classified `'versicolor'`.

```X = mean(meas); Y = {'versicolor'}; L = loss(mdl,X,Y) ```
```L = 0 ```

The classifier has no doubt that `'versicolor'` is the correct classification (all five nearest neighbors classify as `'versicolor'`).

expand all