# plr.cmatrix.md

|             |                 |
| ----------- | --------------: |
| plr.cmatrix | R Documentation |

### Positive Likelihood Ratio

#### Description

A generic S3 function to compute the *positive likelihood ratio* score\
for a classification model. This function dispatches to S3 methods in`plr()` 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 `plr()` 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 `plr()` in a "safe" validator that checks\
for NA values and matching length, for example:

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

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

{% endcode %}

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

**Efficient multi-metric evaluation**

For multiple performance evaluations of a classification model, first\
compute the confusion matrix once via `cmatrix()`. All other performance\
metrics can then be derived from this one object via S3 dispatching:

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

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

## evaluate positive likelihood ratio
## via S3 dispatching
plr(confusion_matrix)

## additional performance metrics
## below
```

{% endcode %}

The `plr.factor()` method calls `cmatrix()` internally, so explicitly\
invoking `plr.cmatrix()` yourself avoids duplicate computation, yielding\
significant speed and memory effciency gains when you need multiple\
evaluation metrics.

#### Usage

```r
## S3 method for class 'cmatrix'
plr(x, ...)
```

#### Arguments

|       |                                         |
| ----- | --------------------------------------- |
| `x`   | A confusion matrix created `cmatrix()`. |
| `...` | Arguments passed into other methods.    |

#### Value

A \<double>-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")
)


## Construct confusion
## matrix
confusion_matrix <- SLmetrics::cmatrix(
actual    = actual_classes,
predicted = predicted_classes
)

## Evaluate performance
SLmetrics::plr(confusion_matrix)

```

```

</div>

```