riskyr (version 0.1.0)

comp_freq: Compute frequencies from (3 essential) probabilities.

Description

comp_freq computes frequencies (typically as rounded integers) given 3 basic probabilities -- prev, sens, and spec -- -- for a population of N individuals. It returns a list of 9 frequencies freq as its output.

Usage

comp_freq(prev = num$prev, sens = num$sens, spec = num$spec, N = num$N,
  round = TRUE)

Arguments

prev

The condition's prevalence prev (i.e., the probability of condition being TRUE).

sens

The decision's sensitivity sens (i.e., the conditional probability of a positive decision provided that the condition is TRUE).

spec

The decision's specificity value spec (i.e., the conditional probability of a negative decision provided that the condition is FALSE).

N

The number of individuals in the population. If N is unknown (NA), a suitable minimum value is computed by comp_min_N.

round

A Boolean value that determines whether frequencies are rounded to the nearest integer. Default: round = TRUE.

Value

A list freq containing 9 frequency values.

Details

In addition to prev, both sens and spec are necessary arguments. If only their complements mirt or fart are known, use the wrapper function comp_freq_prob which also accepts mirt and fart as inputs (but requires that the entire set of provided probabilities is sufficient and consistent). Alternatively, use comp_complement, comp_comp_pair, or comp_complete_prob_set to obtain the 3 essential probabilities.

comp_freq is the frequency counterpart to the probability function comp_prob.

By default, comp_freq rounds frequencies to nearest integers to avoid decimal values in freq. Use round = FALSE to switch off rounding.

Key relationships:

1. to probabilities: A population of N individuals can be split into 2 subsets in 2 different ways:

   1. by condition: The frequency cond.true depends on the prevalence prev and the frequency cond.false depends on the prevalence's complement 1 - prev.

   2. by decision: The frequency dec.pos depends on the proportion of positive decisions ppod and the frequency dec.neg depends on the proportion of negative decisions 1 - ppod.

   The population size N is a free parameter (independent of the essential probabilities prev, sens, and spec).

   If N is unknown, a suitable minimum value can be computed by comp_min_N.

2. to other frequencies: In a population of size N the following relationships hold:

   • N = cond.true + cond.false (by condition)

   • N = dec.pos + dec.neg (by decision)

   • N = dec.cor + dec.err (by correspondence of decision to condition)

   • N = hi + mi + fa + cr (by condition x decision)

See Also

num contains basic numeric variables; init_num initializes basic numeric variables; freq contains current frequency information; prob contains current probability information; comp_prob computes current probability information; comp_complement computes a probability's complement; comp_comp_pair computes pairs of complements; comp_complete_prob_set completes valid sets of probabilities; comp_min_N computes a suitable population size N (if missing).

Other functions computing frequencies: comp_freq_freq, comp_freq_prob, comp_min_N, comp_popu, comp_prob_prob

Examples

# NOT RUN {
comp_freq()                  # => ok, using current defaults
length(comp_freq())          # => 11

# Ways to succeed:
comp_freq(prev = 1, sens = 1, spec = 1, 100)  # => ok, N hits (TP)
comp_freq(prev = 1, sens = 1, spec = 0, 100)  # => ok, N hits
comp_freq(prev = 1, sens = 0, spec = 1, 100)  # => ok, N misses (FN)
comp_freq(prev = 1, sens = 0, spec = 0, 100)  # => ok, N misses
comp_freq(prev = 0, sens = 1, spec = 1, 100)  # => ok, N correct rejections (TN)
comp_freq(prev = 0, sens = 1, spec = 0, 100)  # => ok, N false alarms (FP)

# Watch out for:
comp_freq(prev = 1, sens = 1, spec = 1, N = NA)  # => ok, but warning that N = 1 was computed
comp_freq(prev = 1, sens = 1, spec = 1, N =  0)  # => ok, but all 0 + warning (extreme case: N hits)
comp_freq(prev = .5, sens = .5, spec = .5, N = 10, round = TRUE)   # => ok, rounded (see mi and fa)
comp_freq(prev = .5, sens = .5, spec = .5, N = 10, round = FALSE)  # => ok, not rounded

# Ways to fail:
comp_freq(prev = NA,  sens = 1, spec = 1,  100)   # => NAs + warning (prev NA)
comp_freq(prev = 1,  sens = NA, spec = 1,  100)   # => NAs + warning (sens NA)
comp_freq(prev = 1,  sens = 1,  spec = NA, 100)   # => NAs + warning (spec NA)
comp_freq(prev = 8,  sens = 1,  spec = 1,  100)   # => NAs + warning (prev beyond range)
comp_freq(prev = 1,  sens = 8,  spec = 1,  100)   # => NAs + warning (sens beyond range)


# }