inspect_data_dichotomous: Validate dichotomous data
In inspector: Validation of Arguments and Objects in User-Defined Functions

Description Usage Arguments Details Value See Also Examples

inspect_data_dichotomous checks if an object contains data that is eligible to have been generated by a series of Bernoulli trials. This can be useful to validate inputs in user-defined functions.

1	inspect_data_dichotomous(data, success, allow_nas = TRUE, warning_nas = FALSE)

`data, success`	Arbitrary objects. `success` is meant to indicate the value of `data` that corresponds to a success.
`allow_nas`	Logical value. If `TRUE` then `NA` and `NaN` values in `data` are allowed. If `FALSE`, execution is stopped and an error message is thrown in case there are `NA` or `NaN` values in `data`.
`warning_nas`	Logical value. If `TRUE` then the presence of `NA` or `NaN` values in `data` generates a warning message. `NA` and `NaN` values pass silently otherwise (if `allow_nas` is set to`TRUE`).

inspect_data_dichotomous conducts a series of tests to check if data is eligible to have been generated by a series of Bernoulli trials. Namely, inspect_data_dichotomous checks if:

data and success are NULL or empty.
data and success are atomic and have an eligible data type (logical, integer, double, character).
data and success have NA or NaN values.
The number of unique values in data and success are adequate.
success has length 1.
success is observed in data.

inspect_data_dichotomous does not return any output. There are three possible outcomes:

The call is silent if:
- data is eligible to have been generated by a series of Bernoulli trials and there are no NA or NaN values in data.
- data is eligible to have been generated by a series of Bernoulli trials, there are some NA or NaN values in data, allow_nas is set to TRUE and warning_nas is set to FALSE.
An informative warning message is thrown if:
- data is eligible to have been generated by a series of Bernoulli trials and success is not observed in data.
- data is eligible to have been generated by a series of Bernoulli trials, there are NA or NaN values in data and both allow_nas and warning_nas are set to TRUE.
An informative error message is thrown and the execution is stopped if:
- data is not eligible to have been generated by a series of Bernoulli trials.
- data is eligible to have been generated by a series of Bernoulli trials, there are some NA or NaN values in data and allow_nas is set to FALSE.

inspect_par_bernoulli to validate Bernoulli/Binomial proportions.
inspect_data_categorical and inspect_data_cat_as_dichotom to validate categorical data.
inspect_par_multinomial to validate vectors of Multinomial proportions.

# Calls that pass silently:
x1 <- c(1, 0, 0, 1, 0)
x2 <- c(FALSE, FALSE, TRUE)
x3 <- c("yes", "no", "yes")
x4 <- factor(c("yes", "no", "yes"))
x5 <- c(1, 0, 0, 1, 0, NA)
inspect_data_dichotomous(x1, success = 1)
inspect_data_dichotomous(x2, success = TRUE)
inspect_data_dichotomous(x3, success = "yes")
inspect_data_dichotomous(x4, success = "yes")
inspect_data_dichotomous(x5, success = 1)

# Calls that throw an informative warning message:
y1 <- c(1, 1, NA, 0, 0)
y2 <- c(0, 0)
success <- 1
try(inspect_data_dichotomous(y1, success = 1, warning_nas = TRUE))
try(inspect_data_dichotomous(y2, success = success))

# Calls that throw an informative error message:
try(inspect_data_dichotomous(NULL, 1))
try(inspect_data_dichotomous(c(1, 0), NULL))
try(inspect_data_dichotomous(list(1, 0), 1))
try(inspect_data_dichotomous(c(1, 0), list(1)))
try(inspect_data_dichotomous(numeric(0), 0))
try(inspect_data_dichotomous(1, numeric(0)))
try(inspect_data_dichotomous(NaN, 1))
try(inspect_data_dichotomous(NA, 1))
try(inspect_data_dichotomous(c(1, 0), NA))
try(inspect_data_dichotomous(c(1, 0), NaN))
try(inspect_data_dichotomous(c(1, 0), 2))