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.

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:

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).

See also

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_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 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] 52
#> 
#> $cond_false
#> [1] 48
#> 
#> $dec_pos
#> [1] 49
#> 
#> $dec_neg
#> [1] 51
#> 
#> $dec_cor
#> [1] 61
#> 
#> $dec_err
#> [1] 39
#> 
#> $hi
#> [1] 31
#> 
#> $mi
#> [1] 21
#> 
#> $fa
#> [1] 18
#> 
#> $cr
#> [1] 30
#> 

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