# weighted.precision.factor.md

|                           |                 |
| ------------------------- | --------------: |
| weighted.precision.factor | R Documentation |

### Precision

#### Description

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

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

```r
safe_precision <- function(x, y, ...) {
  stopifnot(
    !anyNA(x), !anyNA(y),
    length(x) == length(y)
  )
  precision(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 precision
## via S3 dispatching
precision(confusion_matrix)

## additional performance metrics
## below
```

{% endcode %}

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

#### Usage

```r
## S3 method for class 'factor'
weighted.precision(actual, predicted, w, estimator = 0L, na.rm = TRUE, ...)
```

#### Arguments

| `actual`, `predicted` | <p>A pair of \<integer> or \<factor> vectors of length<code>n</code>, and <code>k</code><br>levels.</p>                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `w`                   | A \<double> vector of sample weights.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `estimator`           | <p>An \<integer>-value of length <code>1</code><br>(default: <code>0</code>).</p><ul><li>0 - a named \<double>-vector of length k<br>(class-wise)</li><li>1 - a \<double> value (Micro averaged metric)</li><li>2 - a \<double> value (Macro averaged metric)</li></ul>                                                                                                                                                                                                      |
| `na.rm`               | <p>A \<logical> value of length <code>1</code><br>(default: TRUE). If TRUE, NA values are removed from the computation.<br>This argument is only relevant when <code>micro != NULL</code>. When<code>na.rm = TRUE</code>, the computation corresponds to<code>sum(c(1, 2, NA), na.rm = TRUE) / length(na.omit(c(1, 2, NA)))</code>.<br>When <code>na.rm = FALSE</code>, the computation corresponds to<code>sum(c(1, 2, NA), na.rm = TRUE) / length(c(1, 2, NA))</code>.</p> |
| `...`                 | Arguments passed into other methods.                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### Value

If `estimator` is given as

* 0 - a named \<double> vector of length k
* 1 - a \<double> value (Micro averaged metric)
* 2 - a \<double> value (Macro averaged metric)

#### Other names

The precision has other names depending on research field:

* Positive Predictive Value, `ppv()`

#### 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")
)



## Generate sample
## weights
sample_weights <- runif(
   n = length(actual_classes)
)

## Evaluate performance
SLmetrics::weighted.precision(
   actual    = actual_classes, 
   predicted = predicted_classes, 
   w         = sample_weights
)
```

```

</div>

```
