# cmatrix.md

|         |                 |
| ------- | --------------: |
| cmatrix | R Documentation |

### Confusion Matrix

#### Description

A generic S3 function to compute the *confusion matrix* for a\
classification model. This function dispatches to S3 methods in`cmatrix()` and performs no input validation. If you supply NA values or\
vectors of unequal length (e.g. `length(x) != length(y)`), the\
underlying `C++` code may trigger undefined behavior and crash your `R`\
session.

**Defensive measures**

Because `cmatrix()` operates on raw pointers, pointer-level faults (e.g.\
from NA or mismatched length) occur before any `R`-level error handling.\
Wrapping calls in `try()` or `tryCatch()` will *not* prevent `R`-session\
crashes.

To guard against this, wrap `cmatrix()` in a "safe" validator that\
checks for NA values and matching length, for example:

{% code overflow="wrap" lineNumbers="true" %}

```r
safe_cmatrix <- function(x, y, ...) {
  stopifnot(
    !anyNA(x), !anyNA(y),
    length(x) == length(y)
  )
  cmatrix(x, y, ...)
}
```

{% endcode %}

Apply the same pattern to any custom metric functions to ensure input\
sanity before calling the underlying `C++` code.

**The workhorse**

`cmatrix()` is the main function for classification metrics with cmatrix\
S3 dispatch. These functions internally calls `cmatrix()`, so there is a\
signficant gain in computing the confusion matrix first, and then pass\
it onto the metrics. For example:

{% code overflow="wrap" lineNumbers="true" %}

```r
## Compute confusion matrix
confusion_matrix <- cmatrix(actual, predicted)

## Evaluate accuracy
## via S3 dispatching
accuracy(confusion_matrix)

## Evaluate recall
## via S3 dispatching
recall(confusion_matrix)
```

{% endcode %}

#### Usage

```r
## Generic S3 method
## for Confusion Matrix
cmatrix(...)

## Generic S3 method
## for weighted Confusion Matrix
weighted.cmatrix(...)
```

#### Arguments

| `...` | <p>Arguments passed on to <code>cmatrix.factor</code>,<code>weighted.cmatrix.factor</code></p><p><code>actual,predicted</code></p><p>A pair of \<integer> or \<factor> vectors of length <code>n</code>, and <code>k</code> levels.</p><p><code>w</code></p><p>A \<double> vector of sample weights.</p> |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Value

A named `k` x `k` \<matrix>

#### Dimensions

There is no robust defensive measure against misspecifying the confusion\
matrix. If the arguments are passed correctly, the resulting confusion\
matrix is on the form:

|            |               |               |
| ---------- | :-----------: | ------------: |
|            | A (Predicted) | B (Predicted) |
| A (Actual) |     Value     |         Value |
| B (Actual) |     Value     |         Value |
|            |               |               |

#### References

James, Gareth, et al. An introduction to statistical learning. Vol. 112.\
No. 1. New York: springer, 2013.

Hastie, Trevor. "The elements of statistical learning: data mining,\
inference, and prediction." (2009).

Pedregosa, Fabian, et al. "Scikit-learn: Machine learning in Python."\
the Journal of machine Learning research 12 (2011): 2825-2830.

#### Examples

```r
## Classes and
## seed
set.seed(1903)
classes <- c("Kebab", "Falafel")

## Generate actual
## and predicted classes
actual_classes <- factor(
x = sample(x = classes, size = 1e3, replace = TRUE),
levels = c("Kebab", "Falafel")
)

predicted_classes <- factor(
x = sample(x = classes, size = 1e3, replace = TRUE),
levels = c("Kebab", "Falafel")
)

## Compute the confusion
## matrix
SLmetrics::cmatrix(
 actual    = actual_classes, 
 predicted = predicted_classes
)
```

```

</div>

```
