Compute frequencies from (3 essential) probabilities.

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

Usage

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

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

Boolean value that determines whether frequency values 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.

sample

Boolean value that determines whether frequency values are sampled from N, given the probability values of prev, sens, and spec. Default: sample = FALSE.

Note: Sampling uses sample() and returns integer values.

Value

A list freq containing 11 key 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)
12. rate of hits, given accuracy p_acc_hi:
  
  p_acc_hi = hi/dec_cor = (1 - cr/dec_cor)
13. rate of false alarms, given inaccuracy p_err_fa:
  
  p_err_fa = fa/dec_err = (1 - mi/dec_err)
Beware of rounding and sampling issues! If frequencies are rounded (by round = TRUE in comp_freq) or sampled from probabilities (by sample = TRUE), then any probabilities computed from freq may differ from original and 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).

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 key frequencies
#> [1] 11

# Rounding:
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
#> 

# Sampling (from probabilistic description):
comp_freq_prob(prev = .5, sens = .5, spec = .5, N = 100, sample = TRUE)  # freq values vary
#> $N
#> [1] 100
#> 
#> $cond_true
#> [1] 54
#> 
#> $cond_false
#> [1] 46
#> 
#> $dec_pos
#> [1] 51
#> 
#> $dec_neg
#> [1] 49
#> 
#> $dec_cor
#> [1] 55
#> 
#> $dec_err
#> [1] 45
#> 
#> $hi
#> [1] 30
#> 
#> $mi
#> [1] 24
#> 
#> $fa
#> [1] 21
#> 
#> $cr
#> [1] 25
#> 

# 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
#>