`recall`

estimates the recall (a.k.a. sensitivity, true
positive rate -TPR-, or hit rate) for a nominal/categorical predicted-observed dataset.

`TPR`

alternative to `recall()`

.

`sensitivity`

alternative to `recall()`

.

`hitrate`

alternative to `recall()`

.

`FNR`

estimates false negative rate (or false alarm, or fall-out)
for a nominal/categorical predicted-observed dataset.

## Usage

```
recall(
data = NULL,
obs,
pred,
atom = FALSE,
pos_level = 2,
tidy = FALSE,
na.rm = TRUE
)
TPR(
data = NULL,
obs,
pred,
atom = FALSE,
pos_level = 2,
tidy = FALSE,
na.rm = TRUE
)
sensitivity(
data = NULL,
obs,
pred,
atom = FALSE,
pos_level = 2,
tidy = FALSE,
na.rm = TRUE
)
hitrate(
data = NULL,
obs,
pred,
atom = FALSE,
pos_level = 2,
tidy = FALSE,
na.rm = TRUE
)
FNR(
data = NULL,
obs,
pred,
atom = FALSE,
pos_level = 2,
tidy = FALSE,
na.rm = TRUE
)
```

## Arguments

- data
(Optional) argument to call an existing data frame containing the data.

- obs
Vector with observed values (character | factor).

- pred
Vector with predicted values (character | factor).

- atom
Logical operator (TRUE/FALSE) to decide if the estimate is made for each class (atom = TRUE) or at a global level (atom = FALSE); Default : FALSE. When dataset is "binomial" atom does not apply.

- pos_level
Integer, for binary cases, indicating the order (1|2) of the level corresponding to the positive. Generally, the positive level is the second (2) since following an alpha-numeric order, the most common pairs are

`(Negative | Positive)`

,`(0 | 1)`

,`(FALSE | TRUE)`

. Default : 2.- tidy
Logical operator (TRUE/FALSE) to decide the type of return. TRUE returns a data.frame, FALSE returns a list; Default : FALSE.

- na.rm
Logic argument to remove rows with missing values (NA). Default is na.rm = TRUE.

## Value

an object of class `numeric`

within a `list`

(if tidy = FALSE) or within a
`data frame`

(if tidy = TRUE).

## Details

The `recall`

(a.k.a. sensitivity or true positive rate -TPR-) is a
non-normalized coefficient that represents the ratio between the correctly
predicted cases (true positives -TP-) to the total number of actual observations
that belong to a given class (actual positives -P-).

For binomial cases, \(recall = \frac{TP}{P} = \frac{TP}{TP + FN} \)

The `recall`

metric is bounded between 0 and 1. The closer to 1 the better.
Values towards zero indicate low performance. It can be either estimated for
each particular class or at a global level.

Metrica offers 4 identical alternative functions that do the same job: i) `recall`

,
ii) `sensitivity`

, iii) `TPR`

, and iv) `hitrate`

. However, consider
when using `metrics_summary`

, only the `recall`

alternative is used.

The false negative rate (or false alarm, or fall-out) is the complement of the
recall, representing the ratio between the number of false negatives (FN)
to the actual number of positives (P). The `FNR`

formula is:

\(FNR = 1 - recall = 1 - TPR = \frac{FN}{P}\)

The `fpr`

is bounded between 0 and 1. The closer to 0 the better. Low performance
is indicated with fpr > 0.5.

For the formula and more details, see online-documentation

## References

Ting K.M. (2017)
Precision and Recall.
*In: Sammut C., Webb G.I. (eds) Encyclopedia of Machine Learning and Data Mining.*
*Springer, Boston, MA.* doi:10.1007/978-1-4899-7687-1_659

Ting K.M. (2017).
Sensitivity.
*In: Sammut C., Webb G.I. (eds) Encyclopedia of Machine Learning and Data Mining.*
*Springer, Boston, MA.* doi:10.1007/978-1-4899-7687-1_751

Trevethan, R. (2017).
*Sensitivity, Specificity, and Predictive Values: Foundations, Pliabilities, and Pitfalls*
_ in Research and Practice. Front. Public Health 5:307_ doi:10.3389/fpubh.2017.00307

## Examples

```
# \donttest{
set.seed(123)
# Two-class
binomial_case <- data.frame(labels = sample(c("True","False"), 100,
replace = TRUE), predictions = sample(c("True","False"), 100, replace = TRUE))
# Multi-class
multinomial_case <- data.frame(labels = sample(c("Red","Blue", "Green"), 100,
replace = TRUE), predictions = sample(c("Red","Blue", "Green"), 100, replace = TRUE))
# Get recall estimate for two-class case at global level
recall(data = binomial_case, obs = labels, pred = predictions, tidy = TRUE)
#> recall
#> 1 0.4561404
# Get FNR estimate for two-class case at global level
FNR(data = binomial_case, obs = labels, pred = predictions, tidy = TRUE)
#> FNR
#> 1 0.5438596
# Get recall estimate for each class for the multi-class case at global level
recall(data = multinomial_case, obs = labels, pred = predictions, tidy = TRUE,
atom = FALSE)
#> recall
#> 1 0.2770092
# Get recall estimate for the multi-class case at a class-level
recall(data = multinomial_case, obs = labels, pred = predictions, tidy = TRUE,
atom = TRUE)
#> recall
#> Blue 0.2727273
#> Green 0.2173913
#> Red 0.3409091
# }
```