Documentation

# edge

Classification edge for naive Bayes classifiers

## Syntax

``e = edge(Mdl,tbl,ResponseVarName)``
``e = edge(Mdl,tbl,Y)``
``e = edge(Mdl,X,Y)``
``e = edge(___,Name,Value)``

## Description

example

````e = edge(Mdl,tbl,ResponseVarName)` returns the classification edge (`e`) for the naive Bayes classifier `Mdl` using the predictor data in table `tbl` and the class labels in `tbl.ResponseVarName`.```

example

````e = edge(Mdl,tbl,Y)` returns the classification edge (`e`) for the naive Bayes classifier `Mdl` using predictor data in table `tbl` and the class labels in vector `Y`.```

example

````e = edge(Mdl,X,Y)` returns the classification edge (`e`) for the naive Bayes classifier `Mdl` using predictor data `X` and class labels `Y`.```

example

````e = edge(___,Name,Value)` computes the classification edge with additional options specified by one or more `Name,Value` pair arguments, using any of the previous syntaxes.```

## Input Arguments

expand all

Naive Bayes classifier, specified as a `ClassificationNaiveBayes` model or `CompactClassificationNaiveBayes` model returned by `fitcnb` or `compact`, respectively.

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

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

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.

The response variable must be a categorical, character, or string 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.

Data Types: `char` | `string`

Predictor data, specified as a numeric matrix.

Each row of `X` corresponds to one observation (also known as an instance or example), and each column corresponds to one variable (also known as a feature). The variables making up the columns of `X` should be the same as the variables that trained `Mdl`.

The length of `Y` and the number of rows of `X` must be equal.

Data Types: `double` | `single`

Class labels, specified as a categorical, character, or string array, logical or numeric vector, or cell array of character vectors. `Y` must be the same as the data type of `Mdl.ClassNames`. (The software treats string arrays as cell arrays of character vectors.)

The length of `Y` and the number of rows of `tbl` or `X` must be equal.

Data Types: `categorical` | `char` | `string` | `logical` | `single` | `double` | `cell`

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

Observation weights, specified as the comma-separated pair consisting of `'Weights'` and 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`.

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 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 add up to `1`.

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

## Output Arguments

expand all

Classification edge, returned as a scalar. If you supply `Weights`, then `e` is the weighted classification edge.

## Examples

expand all

```load fisheriris X = meas; % Predictors Y = species; % Response rng(1); % For reproducibility```

Train a naive Bayes classifier. Specify a 30% holdout sample for testing. It is good practice to specify the class order. Assume that each predictor is conditionally, normally distributed given its label.

```CVMdl = fitcnb(X,Y,'Holdout',0.30,... 'ClassNames',{'setosa','versicolor','virginica'}); CMdl = CVMdl.Trained{1}; % Extract trained, compact classifier testInds = test(CVMdl.Partition); % Extract the test indices XTest = X(testInds,:); YTest = Y(testInds);```

`CVMdl` is a `ClassificationPartitionedModel` classifier. It contains the property `Trained`, which is a 1-by-1 cell array holding a `CompactClassificationNaiveBayes` classifier that the software trained using the training set.

Estimate the test sample edge.

`e = edge(CMdl,XTest,YTest)`
```e = 0.8244 ```

The estimated test sample margin average is approximately `0.82`. This indicates that, on average, the test sample difference between the estimated posterior probability for the predicted class and the posterior probability for the class with the next lowest posterior probability is approximately 0.82. This indicates that the classifier labels with high confidence.

```load fisheriris X = meas; % Predictors Y = species; % Response rng(1);```

Suppose that the setosa iris measurements are lower quality because they were measured with an older technology. One way to incorporate this is to weigh the setosa iris measurements less than the other observations.

Define a weight vector that weighs the better quality observations twice the other observations.

```n = size(X,1); idx = strcmp(Y,'setosa'); weights = ones(size(X,1),1); weights(idx) = 0.5;```

Train a naive Bayes classifier. Specify the weighting scheme and a 30% holdout sample for testing. It is good practice to specify the class order. Assume that each predictor is conditionally, normally distributed given its label.

```CVMdl = fitcnb(X,Y,'Weights',weights,'Holdout',0.30,... 'ClassNames',{'setosa','versicolor','virginica'}); CMdl = CVMdl.Trained{1}; % Extract trained, compact classifier testInds = test(CVMdl.Partition); % Extract the test indices XTest = X(testInds,:); YTest = Y(testInds); wTest = weights(testInds);```

`CVMdl` is a `ClassificationPartitionedModel` classifier. It contains the property `Trained`, which is a 1-by-1 cell array holding a `CompactClassificationNaiveBayes` classifier that the software trained using the training set.

Estimate the test sample weighted edge using the weighting scheme.

`e = edge(CMdl,XTest,YTest,'Weights',wTest)`
```e = 0.7893 ```

The test sample weighted average margin is approximately 0.79. This indicates that, on average, the test sample difference between the estimated posterior probability for the predicted class and the posterior probability for the class with the next lowest posterior probability is approximately 0.79. This indicates that the classifier labels with high confidence.

The classifier edge measures the average of the classifier margins. One way to perform feature selection is to compare test sample edges from multiple models. Based solely on this criterion, the classifier with the highest edge is the best classifier.

```load fisheriris X = meas; % Predictors Y = species; % Response rng(1);```

Partition the data set into training and test sets. Specify a 30% holdout sample for testing.

```Partition = cvpartition(Y,'Holdout',0.30); testInds = test(Partition); % Indices for the test set XTest = X(testInds,:); YTest = Y(testInds,:);```

`Partition` defines the data set partition.

Define these two data sets:

• `fullX` contains all predictors.

• `partX` contains the last two predictors.

```fullX = X; partX = X(:,3:4);```

Train naive Bayes classifiers for each predictor set. Specify the partition definition.

```FCVMdl = fitcnb(fullX,Y,'CVPartition',Partition); PCVMdl = fitcnb(partX,Y,'CVPartition',Partition); FCMdl = FCVMdl.Trained{1}; PCMdl = PCVMdl.Trained{1};```

`FCVMdl` and `PCVMdl` are `ClassificationPartitionedModel` classifiers. They contain the property `Trained`, which is a 1-by-1 cell array holding a `CompactClassificationNaiveBayes` classifier that the software trained using the training set.

Estimate the test sample edge for each classifier.

`fullEdge = edge(FCMdl,XTest,YTest)`
```fullEdge = 0.8244 ```
`partEdge = edge(PCMdl,XTest(:,3:4),YTest)`
```partEdge = 0.8420 ```

The test-sample edges of the classifiers are nearly the same. However, the model trained using two predictors (`PCMdl`) is less complex.

expand all