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
)
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 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
.
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.
A list freq
containing 11 key frequency values.
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:
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
.
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
.
by accuracy (i.e., correspondence of decision to condition):
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:
prevalence prev
:
sensitivity sens
:
miss rate mirt
:
specificity spec
:
false alarm rate fart
:
proportion of positive decisions ppod
:
positive predictive value PPV
:
negative predictive value NPV
:
false detection rate FDR
:
false omission rate FOR
:
accuracy acc
:
rate of hits, given accuracy p_acc_hi
:
rate of false alarms, given inaccuracy p_err_fa
:
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).
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()
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
#>