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 11 frequencies freq as its output.

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). The decision's sensitivity sens (i.e., the conditional probability of a positive decision provided that the condition is TRUE). The decision's specificity value spec (i.e., the conditional probability of a negative decision provided that the condition is FALSE). The number of individuals in the population. If N is unknown (NA), a suitable minimum value is computed by comp_min_N. Boolean value that determines whether frequencies are rounded to the nearest integer. Default: round = TRUE. Note: Removed n_digits parameter: Number of digits to which frequency values are to be rounded when round = FALSE. Default: n_digits = 5.

## Value

A list freq containing 11 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 and its wrapper function comp_freq_prob round frequencies to nearest integers to avoid decimal values in freq (i.e., round = TRUE by default). When frequencies are rounded, probabilities computed from freq may differ from exact probabilities. Using the option round = FALSE turns off rounding.

Key relationships between probabilities and frequencies:

• Three perspectives on a population:

A population of N individuals can be split into 2 subsets of frequencies in 3 different ways:

1. by condition:

N = cond_true + cond_false

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:

N = dec_pos + dec_neg

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.

3. by accuracy (i.e., correspondence of decision to condition):

N = dec_cor + dec_err

Each perspective combines 2 pairs of the 4 essential probabilities (hi, mi, fa, cr).

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

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

• Defining probabilities in terms of frequencies:

Probabilities are -- determine, describe, or are defined as -- the relationships between frequencies. Thus, they can be computed as ratios between frequencies:

1. prevalence prev:

prev = cond_true/N = (hi + mi) / (hi + mi + fa + cr)

2. sensitivity sens:

sens = hi/cond_true = hi / (hi + mi) = (1 - mirt)

3. miss rate mirt:

mirt = mi/cond_true = mi / (hi + mi) = (1 - sens)

4. specificity spec:

spec = cr/cond_false = cr / (fa + cr) = (1 - fart)

5. false alarm rate fart:

fart = fa/cond_false = fa / (fa + cr) = (1 - spec)

6. proportion of positive decisions ppod:

ppod = dec_pos/N = (hi + fa) / (hi + mi + fa + cr)

7. positive predictive value PPV:

PPV = hi/dec_pos = hi / (hi + fa) = (1 - FDR)

8. negative predictive value NPV:

NPV = cr/dec_neg = cr / (mi + cr) = (1 - FOR)

9. false detection rate FDR:

FDR = fa/dec_pos = fa / (hi + fa) = (1 - PPV)

10. false omission rate FOR:

FOR = mi/dec_neg = mi / (mi + cr) = (1 - NPV)

11. accuracy acc:

acc = dec_cor/N = (hi + cr) / (hi + mi + fa + cr)

Note: When frequencies are rounded (by round = TRUE in comp_freq), probabilities computed from freq may differ from exact probabilities.

Functions translating between representational formats: comp_prob_prob, comp_prob_freq, comp_freq_prob, comp_freq_freq (see documentation of comp_prob_prob for details).

comp_freq_prob corresponding wrapper function; 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

comp_freq()                  # => ok, using current defaults#> $N #> [1] 1000 #> #>$cond_true
#> [1] 250
#>
#> $cond_false #> [1] 750 #> #>$dec_pos
#> [1] 400
#>
#> $dec_neg #> [1] 600 #> #>$dec_cor
#> [1] 774
#>
#> $dec_err #> [1] 226 #> #>$hi
#> [1] 212
#>
#> $mi #> [1] 38 #> #>$fa
#> [1] 188
#>
#> $cr #> [1] 562 #> length(comp_freq()) # => 11#> [1] 11 # Rounding effects: comp_freq(prev = .5, sens = .5, spec = .5, N = 1) # => yields fa = 1 (see ?round for reason)#>$N
#> [1] 1
#>
#> $cond_true #> [1] 0 #> #>$cond_false
#> [1] 1
#>
#> $dec_pos #> [1] 1 #> #>$dec_neg
#> [1] 0
#>
#> $dec_cor #> [1] 0 #> #>$dec_err
#> [1] 1
#>
#> $hi #> [1] 0 #> #>$mi
#> [1] 0
#>
#> $fa #> [1] 1 #> #>$cr
#> [1] 0
#> comp_freq(prev = .1, sens = .9, spec = .8, N = 10)  # => 1 hit (TP, rounded)#> $N #> [1] 10 #> #>$cond_true
#> [1] 1
#>
#> $cond_false #> [1] 9 #> #>$dec_pos
#> [1] 3
#>
#> $dec_neg #> [1] 7 #> #>$dec_cor
#> [1] 8
#>
#> $dec_err #> [1] 2 #> #>$hi
#> [1] 1
#>
#> $mi #> [1] 0 #> #>$fa
#> [1] 2
#>
#> $cr #> [1] 7 #> comp_freq(prev = .1, sens = .9, spec = .8, N = 10, round = FALSE) # => hi = .9#>$N
#> [1] 10
#>
#> $cond_true #> [1] 1 #> #>$cond_false
#> [1] 9
#>
#> $dec_pos #> [1] 2.7 #> #>$dec_neg
#> [1] 7.3
#>
#> $dec_cor #> [1] 8.1 #> #>$dec_err
#> [1] 1.9
#>
#> $hi #> [1] 0.9 #> #>$mi
#> [1] 0.1
#>
#> $fa #> [1] 1.8 #> #>$cr
#> [1] 7.2
#> comp_freq(prev = 1/3, sens = 6/7, spec = 2/3, N = 1, round = FALSE)  # => hi = 0.2857143#> $N #> [1] 1 #> #>$cond_true
#> [1] 0.3333333
#>
#> $cond_false #> [1] 0.6666667 #> #>$dec_pos
#> [1] 0.5079365
#>
#> $dec_neg #> [1] 0.4920635 #> #>$dec_cor
#> [1] 0.7301587
#>
#> $dec_err #> [1] 0.2698413 #> #>$hi
#> [1] 0.2857143
#>
#> $mi #> [1] 0.04761905 #> #>$fa
#> [1] 0.2222222
#>
#> $cr #> [1] 0.4444444 #> # Extreme cases: comp_freq(prev = 1, sens = 1, spec = 1, 100) # => ok, N hits (TP)#> Warning: Extreme case (prev = 1 & sens = 1): #> N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.#>$N
#> [1] 100
#>
#> $cond_true #> [1] 100 #> #>$cond_false
#> [1] 0
#>
#> $dec_pos #> [1] 100 #> #>$dec_neg
#> [1] 0
#>
#> $dec_cor #> [1] 100 #> #>$dec_err
#> [1] 0
#>
#> $hi #> [1] 100 #> #>$mi
#> [1] 0
#>
#> $fa #> [1] 0 #> #>$cr
#> [1] 0
#> comp_freq(prev = 1, sens = 1, spec = 0, 100)  # => ok, N hits#> Warning: Extreme case (prev = 1 & sens = 1):
#>   N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.#> $N #> [1] 100 #> #>$cond_true
#> [1] 100
#>
#> $cond_false #> [1] 0 #> #>$dec_pos
#> [1] 100
#>
#> $dec_neg #> [1] 0 #> #>$dec_cor
#> [1] 100
#>
#> $dec_err #> [1] 0 #> #>$hi
#> [1] 100
#>
#> $mi #> [1] 0 #> #>$fa
#> [1] 0
#>
#> $cr #> [1] 0 #> comp_freq(prev = 1, sens = 0, spec = 1, 100) # => ok, N misses (FN)#> Warning: Extreme case (prev = 1 & sens = 0): #> N mi (FN) cases; 0 cond_false or dec_true cases; PPV = NaN.#>$N
#> [1] 100
#>
#> $cond_true #> [1] 100 #> #>$cond_false
#> [1] 0
#>
#> $dec_pos #> [1] 0 #> #>$dec_neg
#> [1] 100
#>
#> $dec_cor #> [1] 0 #> #>$dec_err
#> [1] 100
#>
#> $hi #> [1] 0 #> #>$mi
#> [1] 100
#>
#> $fa #> [1] 0 #> #>$cr
#> [1] 0
#> comp_freq(prev = 1, sens = 0, spec = 0, 100)  # => ok, N misses#> Warning: Extreme case (prev = 1 & sens = 0):
#>   N mi (FN) cases; 0 cond_false or dec_true cases; PPV = NaN.#> $N #> [1] 100 #> #>$cond_true
#> [1] 100
#>
#> $cond_false #> [1] 0 #> #>$dec_pos
#> [1] 0
#>
#> $dec_neg #> [1] 100 #> #>$dec_cor
#> [1] 0
#>
#> $dec_err #> [1] 100 #> #>$hi
#> [1] 0
#>
#> $mi #> [1] 100 #> #>$fa
#> [1] 0
#>
#> $cr #> [1] 0 #> comp_freq(prev = 0, sens = 1, spec = 1, 100) # => ok, N correct rejections (TN)#> Warning: Extreme case (prev = 0 & spec = 1): #> N cr (TN) cases; 0 cond_true or dec_false cases; NPV = NaN.#>$N
#> [1] 100
#>
#> $cond_true #> [1] 0 #> #>$cond_false
#> [1] 100
#>
#> $dec_pos #> [1] 0 #> #>$dec_neg
#> [1] 100
#>
#> $dec_cor #> [1] 100 #> #>$dec_err
#> [1] 0
#>
#> $hi #> [1] 0 #> #>$mi
#> [1] 0
#>
#> $fa #> [1] 0 #> #>$cr
#> [1] 100
#> comp_freq(prev = 0, sens = 1, spec = 0, 100)  # => ok, N false alarms (FP)#> Warning: Extreme case (prev = 0 & spec = 0):
#>   N fa (FP) cases; 0 cond_true or dec_true cases; PPV = NaN.#> $N #> [1] 100 #> #>$cond_true
#> [1] 0
#>
#> $cond_false #> [1] 100 #> #>$dec_pos
#> [1] 100
#>
#> $dec_neg #> [1] 0 #> #>$dec_cor
#> [1] 0
#>
#> $dec_err #> [1] 100 #> #>$hi
#> [1] 0
#>
#> $mi #> [1] 0 #> #>$fa
#> [1] 100
#>
#> $cr #> [1] 0 #> # Watch out for: comp_freq(prev = 1, sens = 1, spec = 1, N = NA) # => ok, but warning that N = 1 was computed#> Warning: Extreme case (prev = 1 & sens = 1): #> N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.#> Warning: Extreme case (prev = 1 & sens = 1): #> N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.#> Warning: Unknown population size N. A suitable minimum value of N = 1 was computed.#>$N
#> [1] 1
#>
#> $cond_true #> [1] 1 #> #>$cond_false
#> [1] 0
#>
#> $dec_pos #> [1] 1 #> #>$dec_neg
#> [1] 0
#>
#> $dec_cor #> [1] 1 #> #>$dec_err
#> [1] 0
#>
#> $hi #> [1] 1 #> #>$mi
#> [1] 0
#>
#> $fa #> [1] 0 #> #>$cr
#> [1] 0
#> comp_freq(prev = 1, sens = 1, spec = 1, N =  0)  # => ok, but all 0 + warning (extreme case: N hits)#> Warning: Extreme case (prev = 1 & sens = 1):
#>   N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.#> $N #> [1] 0 #> #>$cond_true
#> [1] 0
#>
#> $cond_false #> [1] 0 #> #>$dec_pos
#> [1] 0
#>
#> $dec_neg #> [1] 0 #> #>$dec_cor
#> [1] 0
#>
#> $dec_err #> [1] 0 #> #>$hi
#> [1] 0
#>
#> $mi #> [1] 0 #> #>$fa
#> [1] 0
#>
#> $cr #> [1] 0 #> comp_freq(prev = .5, sens = .5, spec = .5, N = 10, round = TRUE) # => ok, rounded (see mi and fa)#>$N
#> [1] 10
#>
#> $cond_true #> [1] 5 #> #>$cond_false
#> [1] 5
#>
#> $dec_pos #> [1] 5 #> #>$dec_neg
#> [1] 5
#>
#> $dec_cor #> [1] 4 #> #>$dec_err
#> [1] 6
#>
#> $hi #> [1] 2 #> #>$mi
#> [1] 3
#>
#> $fa #> [1] 3 #> #>$cr
#> [1] 2
#> comp_freq(prev = .5, sens = .5, spec = .5, N = 10, round = FALSE)  # => ok, not rounded#> $N #> [1] 10 #> #>$cond_true
#> [1] 5
#>
#> $cond_false #> [1] 5 #> #>$dec_pos
#> [1] 5
#>
#> $dec_neg #> [1] 5 #> #>$dec_cor
#> [1] 5
#>
#> $dec_err #> [1] 5 #> #>$hi
#> [1] 2.5
#>
#> $mi #> [1] 2.5 #> #>$fa
#> [1] 2.5
#>
#> $cr #> [1] 2.5 #> # Ways to fail: comp_freq(prev = NA, sens = 1, spec = 1, 100) # => NAs + warning (prev NA)#>$N
#> [1] NA
#>
#> $cond_true #> [1] NA #> #>$cond_false
#> [1] NA
#>
#> $dec_pos #> [1] NA #> #>$dec_neg
#> [1] NA
#>
#> $dec_cor #> [1] NA #> #>$dec_err
#> [1] NA
#>
#> $hi #> [1] NA #> #>$mi
#> [1] NA
#>
#> $fa #> [1] NA #> #>$cr
#> [1] NA
#> comp_freq(prev = 1,  sens = NA, spec = 1,  100)   # => NAs + warning (sens NA)#> $N #> [1] NA #> #>$cond_true
#> [1] NA
#>
#> $cond_false #> [1] NA #> #>$dec_pos
#> [1] NA
#>
#> $dec_neg #> [1] NA #> #>$dec_cor
#> [1] NA
#>
#> $dec_err #> [1] NA #> #>$hi
#> [1] NA
#>
#> $mi #> [1] NA #> #>$fa
#> [1] NA
#>
#> $cr #> [1] NA #> comp_freq(prev = 1, sens = 1, spec = NA, 100) # => NAs + warning (spec NA)#>$N
#> [1] NA
#>
#> $cond_true #> [1] NA #> #>$cond_false
#> [1] NA
#>
#> $dec_pos #> [1] NA #> #>$dec_neg
#> [1] NA
#>
#> $dec_cor #> [1] NA #> #>$dec_err
#> [1] NA
#>
#> $hi #> [1] NA #> #>$mi
#> [1] NA
#>
#> $fa #> [1] NA #> #>$cr
#> [1] NA
#> comp_freq(prev = 8,  sens = 1,  spec = 1,  100)   # => NAs + warning (prev beyond range)#> $N #> [1] NA #> #>$cond_true
#> [1] NA
#>
#> $cond_false #> [1] NA #> #>$dec_pos
#> [1] NA
#>
#> $dec_neg #> [1] NA #> #>$dec_cor
#> [1] NA
#>
#> $dec_err #> [1] NA #> #>$hi
#> [1] NA
#>
#> $mi #> [1] NA #> #>$fa
#> [1] NA
#>
#> $cr #> [1] NA #> comp_freq(prev = 1, sens = 8, spec = 1, 100) # => NAs + warning (sens beyond range)#>$N
#> [1] NA
#>
#> $cond_true #> [1] NA #> #>$cond_false
#> [1] NA
#>
#> $dec_pos #> [1] NA #> #>$dec_neg
#> [1] NA
#>
#> $dec_cor #> [1] NA #> #>$dec_err
#> [1] NA
#>
#> $hi #> [1] NA #> #>$mi
#> [1] NA
#>
#> $fa #> [1] NA #> #>$cr
#> [1] NA
#>