comp_freq_prob computes frequency information
from a sufficient and valid set of 3 essential probabilities
(prev, and
sens or its complement mirt, and
spec or its complement fart).
It returns a list of 11 key frequencies (freq)
as its output.
comp_freq_prob(
prev = prob$prev,
sens = prob$sens,
mirt = NA,
spec = prob$spec,
fart = NA,
tol = 0.01,
N = freq$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).
sens is optional when its complement mirt is provided.
The decision's miss rate mirt
(i.e., the conditional probability of a negative decision
provided that the condition is TRUE).
mirt is optional when its complement sens is provided.
The decision's specificity value spec
(i.e., the conditional probability
of a negative decision provided that the condition is FALSE).
spec is optional when its complement fart is provided.
The decision's false alarm rate fart
(i.e., the conditional probability
of a positive decision provided that the condition is FALSE).
fart is optional when its complement spec is provided.
A numeric tolerance value for is_complement.
Default: tol = .01.
The number of individuals in the population.
If N is unknown (NA),
a suitable minimum value is computed by comp_min_N.
A Boolean value that determines whether frequencies are
rounded to the nearest integer.
Default: round = TRUE.
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.
comp_freq_prob is a wrapper function for the more basic
function comp_freq, which only accepts
3 essential probabilities (i.e., prev, sens,
and spec) as inputs.
Defaults and constraints:
Initial values:
By default, the values of prev, sens,
and spec are initialized to the probability information
currently contained in prob.
Similarly, the population size N uses the frequency
information currently contained in freq as its default.
If N is unknown (NA),
a suitable minimum value is computed by comp_min_N.
Constraints:
When using comp_freq_prob with the arguments
mirt and fart, their complements
sens and spec must either be
valid complements (as in is_complement) or
set to NA.
In addition to prev, both sens
and spec are necessary arguments.
If only their complements mirt or fart
are known, first use comp_complement,
comp_comp_pair, or comp_complete_prob_set
to compute the 3 essential probabilities.
Rounding:
By default, comp_freq_prob and its basic function
comp_freq 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 frequencies and probabilities
(see documentation of comp_freq or comp_prob for details):
Three perspectives on a population:
by condition / by decision / by accuracy.
Defining probabilities in terms of frequencies:
Probabilities can be computed as ratios between frequencies, but beware of rounding and sampling issues!
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_freq computes current frequency information from (4 essential) frequencies;
comp_prob_freq computes current probability information from (4 essential) frequencies;
comp_prob_prob computes current probability information from (3 essential) probabilities;
num contains basic numeric variables;
init_num initializes basic numeric variables;
freq contains current frequency information;
comp_freq computes 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(),
comp_min_N(),
comp_prob_prob()
Other format conversion functions:
comp_freq_freq(),
comp_prob_freq(),
comp_prob_prob()
# Basics:
comp_freq_prob(prev = .1, sens = .9, spec = .8, N = 100) # ok: hi = 9, ... cr = 72.
#> $N
#> [1] 100
#>
#> $cond_true
#> [1] 10
#>
#> $cond_false
#> [1] 90
#>
#> $dec_pos
#> [1] 27
#>
#> $dec_neg
#> [1] 73
#>
#> $dec_cor
#> [1] 81
#>
#> $dec_err
#> [1] 19
#>
#> $hi
#> [1] 9
#>
#> $mi
#> [1] 1
#>
#> $fa
#> [1] 18
#>
#> $cr
#> [1] 72
#>
# Same case with complements (using NAs to prevent defaults):
comp_freq_prob(prev = .1, sens = NA, mirt = .1, spec = NA, fart = .2, N = 100) # same result
#> $N
#> [1] 100
#>
#> $cond_true
#> [1] 10
#>
#> $cond_false
#> [1] 90
#>
#> $dec_pos
#> [1] 27
#>
#> $dec_neg
#> [1] 73
#>
#> $dec_cor
#> [1] 81
#>
#> $dec_err
#> [1] 19
#>
#> $hi
#> [1] 9
#>
#> $mi
#> [1] 1
#>
#> $fa
#> [1] 18
#>
#> $cr
#> [1] 72
#>
comp_freq_prob() # ok, using probability info currently contained in prob
#> $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_prob()) # list of 11 key frequencies
#> [1] 11
all.equal(freq, comp_freq_prob()) # TRUE, unless prob has been changed after computing freq
#> [1] TRUE
freq <- comp_freq_prob() # computes frequencies and stores them in freq
# Ways to work:
comp_freq_prob(prev = 1, sens = 1, spec = 1, N = 101) # ok + warning: 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] 101
#>
#> $cond_true
#> [1] 101
#>
#> $cond_false
#> [1] 0
#>
#> $dec_pos
#> [1] 101
#>
#> $dec_neg
#> [1] 0
#>
#> $dec_cor
#> [1] 101
#>
#> $dec_err
#> [1] 0
#>
#> $hi
#> [1] 101
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 0
#>
# Same case with complements (note NAs to prevent default arguments):
comp_freq_prob(prev = 1, sens = NA, mirt = 0, spec = NA, fart = 0, N = 101)
#> Warning: Extreme case (prev = 1 & sens = 1):
#> N hi (TP) cases; 0 cond_false or dec_false cases; NPV = NaN.
#> $N
#> [1] 101
#>
#> $cond_true
#> [1] 101
#>
#> $cond_false
#> [1] 0
#>
#> $dec_pos
#> [1] 101
#>
#> $dec_neg
#> [1] 0
#>
#> $dec_cor
#> [1] 101
#>
#> $dec_err
#> [1] 0
#>
#> $hi
#> [1] 101
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 0
#>
comp_freq_prob(prev = 1, sens = 1, spec = 0, N = 102) # ok + warning: 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] 102
#>
#> $cond_true
#> [1] 102
#>
#> $cond_false
#> [1] 0
#>
#> $dec_pos
#> [1] 102
#>
#> $dec_neg
#> [1] 0
#>
#> $dec_cor
#> [1] 102
#>
#> $dec_err
#> [1] 0
#>
#> $hi
#> [1] 102
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 0
#>
comp_freq_prob(prev = 1, sens = 0, spec = 1, N = 103) # ok + warning: 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] 103
#>
#> $cond_true
#> [1] 103
#>
#> $cond_false
#> [1] 0
#>
#> $dec_pos
#> [1] 0
#>
#> $dec_neg
#> [1] 103
#>
#> $dec_cor
#> [1] 0
#>
#> $dec_err
#> [1] 103
#>
#> $hi
#> [1] 0
#>
#> $mi
#> [1] 103
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 0
#>
comp_freq_prob(prev = 1, sens = 0, spec = 0, N = 104) # ok + warning: 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] 104
#>
#> $cond_true
#> [1] 104
#>
#> $cond_false
#> [1] 0
#>
#> $dec_pos
#> [1] 0
#>
#> $dec_neg
#> [1] 104
#>
#> $dec_cor
#> [1] 0
#>
#> $dec_err
#> [1] 104
#>
#> $hi
#> [1] 0
#>
#> $mi
#> [1] 104
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 0
#>
comp_freq_prob(prev = 0, sens = 1, spec = 1, N = 105) # ok + warning: 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] 105
#>
#> $cond_true
#> [1] 0
#>
#> $cond_false
#> [1] 105
#>
#> $dec_pos
#> [1] 0
#>
#> $dec_neg
#> [1] 105
#>
#> $dec_cor
#> [1] 105
#>
#> $dec_err
#> [1] 0
#>
#> $hi
#> [1] 0
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 0
#>
#> $cr
#> [1] 105
#>
comp_freq_prob(prev = 0, sens = 1, spec = 0, N = 106) # ok + warning: 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] 106
#>
#> $cond_true
#> [1] 0
#>
#> $cond_false
#> [1] 106
#>
#> $dec_pos
#> [1] 106
#>
#> $dec_neg
#> [1] 0
#>
#> $dec_cor
#> [1] 0
#>
#> $dec_err
#> [1] 106
#>
#> $hi
#> [1] 0
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 106
#>
#> $cr
#> [1] 0
#>
# Same case with complements (using NAs to prevent defaults):
comp_freq_prob(prev = 0, sens = NA, mirt = 0,
spec = NA, fart = 1, N = 106) # ok + warning: 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] 106
#>
#> $cond_true
#> [1] 0
#>
#> $cond_false
#> [1] 106
#>
#> $dec_pos
#> [1] 106
#>
#> $dec_neg
#> [1] 0
#>
#> $dec_cor
#> [1] 0
#>
#> $dec_err
#> [1] 106
#>
#> $hi
#> [1] 0
#>
#> $mi
#> [1] 0
#>
#> $fa
#> [1] 106
#>
#> $cr
#> [1] 0
#>
# Rounding:
comp_freq_prob(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_prob(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_prob(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
#>
# 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] 46
#>
#> $cond_false
#> [1] 54
#>
#> $dec_pos
#> [1] 50
#>
#> $dec_neg
#> [1] 50
#>
#> $dec_cor
#> [1] 50
#>
#> $dec_err
#> [1] 50
#>
#> $hi
#> [1] 23
#>
#> $mi
#> [1] 23
#>
#> $fa
#> [1] 27
#>
#> $cr
#> [1] 27
#>
# Watch out for:
comp_freq_prob(prev = 1, sens = 1, spec = 1, N = NA) # ok + warning: N = 1 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_prob(prev = 1, sens = 1, spec = 1, N = 0) # ok, but all 0 + warning (NPV = NaN)
#> 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_prob(prev = .5, sens = .5, spec = .5, N = 10, round = TRUE) # ok, but all rounded
#> $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_prob(prev = .5, sens = .5, spec = .5, N = 10, round = FALSE) # ok, but 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_prob(prev = NA, sens = 1, spec = 1, 100) # NAs + no warning (prev NA)
#> Warning: Please enter a valid set of essential probabilities.
comp_freq_prob(prev = 1, sens = NA, spec = 1, 100) # NAs + no warning (sens NA)
#> Warning: Please enter a valid set of essential probabilities.
comp_freq_prob(prev = 1, sens = 1, spec = NA, 100) # NAs + no warning (spec NA)
#> Warning: Please enter a valid set of essential probabilities.
comp_freq_prob(prev = 8, sens = 1, spec = 1, 100) # NAs + warning (prev beyond range)
#> Warning: Please enter a valid set of essential probabilities.
comp_freq_prob(prev = 1, sens = 8, spec = 1, 100) # NAs + warning (sens & spec beyond range)
#> Warning: Please enter a valid set of essential probabilities.