# sens

##### Sensitivity

These functions calculate the `sens()`

(sensitivity) of a measurement system
compared to a reference result (the "truth" or gold standard).
Highly related functions are `spec()`

, `ppv()`

, and `npv()`

.

##### Usage

`sens(data, ...)`# S3 method for data.frame
sens(data, truth, estimate, estimator = NULL, na_rm = TRUE, ...)

sens_vec(truth, estimate, estimator = NULL, na_rm = TRUE, ...)

##### Arguments

- data
Either a

`data.frame`

containing the`truth`

and`estimate`

columns, or a`table`

/`matrix`

where the true class results should be in the columns of the table.- ...
Not currently used.

- truth
The column identifier for the true class results (that is a

`factor`

). This should be an unquoted column name although this argument is passed by expression and supports quasiquotation (you can unquote column names). For`_vec()`

functions, a`factor`

vector.- estimate
The column identifier for the predicted class results (that is also

`factor`

). As with`truth`

this can be specified different ways but the primary method is to use an unquoted variable name. For`_vec()`

functions, a`factor`

vector.- estimator
One of:

`"binary"`

,`"macro"`

,`"macro_weighted"`

, or`"micro"`

to specify the type of averaging to be done.`"binary"`

is only relevant for the two class case. The other three are general methods for calculating multiclass metrics. The default will automatically choose`"binary"`

or`"macro"`

based on`estimate`

.- na_rm
A

`logical`

value indicating whether`NA`

values should be stripped before the computation proceeds.

##### Details

The sensitivity (`sens()`

) is defined as the proportion of positive
results out of the number of samples which were actually
positive.

When the denominator of the calculation is `0`

, sensitivity is undefined.
This happens when both `# true_positive = 0`

and `# false_negative = 0`

are true, which mean that there were no true events. When computing binary
sensitivity, a `NA`

value will be returned with a warning. When computing
multiclass sensitivity, the individual `NA`

values will be removed, and the
computation will procede, with a warning.

##### Value

A `tibble`

with columns `.metric`

, `.estimator`

,
and `.estimate`

and 1 row of values.

For grouped data frames, the number of rows returned will be the same as the number of groups.

For `sens_vec()`

, a single `numeric`

value (or `NA`

).

##### Relevant Level

There is no common convention on which factor level should
automatically be considered the "event" or "positive" result.
In `yardstick`

, the default is to use the *first* level. To
change this, a global option called `yardstick.event_first`

is
set to `TRUE`

when the package is loaded. This can be changed
to `FALSE`

if the *last* level of the factor is considered the
level of interest by running: `options(yardstick.event_first = FALSE)`

.
For multiclass extensions involving one-vs-all
comparisons (such as macro averaging), this option is ignored and
the "one" level is always the relevant result.

##### Multiclass

Macro, micro, and macro-weighted averaging is available for this metric.
The default is to select macro averaging if a `truth`

factor with more
than 2 levels is provided. Otherwise, a standard binary calculation is done.
See `vignette("multiclass", "yardstick")`

for more information.

##### Implementation

Suppose a 2x2 table with notation:

Reference | ||

Predicted | Positive | Negative |

Positive | A | B |

Negative | C | D |

The formulas used here are:

$$Sensitivity = A/(A+C)$$ $$Specificity = D/(B+D)$$ $$Prevalence = (A+C)/(A+B+C+D)$$ $$PPV = (Sensitivity * Prevalence) / ((Sensitivity * Prevalence) + ((1-Specificity) * (1-Prevalence)))$$ $$NPV = (Specificity * (1-Prevalence)) / (((1-Sensitivity) * Prevalence) + ((Specificity) * (1-Prevalence)))$$

See the references for discussions of the statistics.

##### References

Altman, D.G., Bland, J.M. (1994) ``Diagnostic tests 1:
sensitivity and specificity,'' *British Medical Journal*,
vol 308, 1552.

##### See Also

Other class metrics:
`accuracy()`

,
`bal_accuracy()`

,
`detection_prevalence()`

,
`f_meas()`

,
`j_index()`

,
`kap()`

,
`mcc()`

,
`npv()`

,
`ppv()`

,
`precision()`

,
`recall()`

,
`spec()`

##### Examples

```
# NOT RUN {
# Two class
data("two_class_example")
sens(two_class_example, truth, predicted)
# Multiclass
library(dplyr)
data(hpc_cv)
hpc_cv %>%
filter(Resample == "Fold01") %>%
sens(obs, pred)
# Groups are respected
hpc_cv %>%
group_by(Resample) %>%
sens(obs, pred)
# Weighted macro averaging
hpc_cv %>%
group_by(Resample) %>%
sens(obs, pred, estimator = "macro_weighted")
# Vector version
sens_vec(two_class_example$truth, two_class_example$predicted)
# Making Class2 the "relevant" level
options(yardstick.event_first = FALSE)
sens_vec(two_class_example$truth, two_class_example$predicted)
options(yardstick.event_first = TRUE)
# }
```

*Documentation reproduced from package yardstick, version 0.0.5, License: GPL-2*