comp_freq_prob: Compute frequencies from (3 essential) probabilities.
In hneth/riskyr: Rendering Risk Literacy more Transparent

comp_freq_prob

R Documentation

Compute frequencies from (3 essential) probabilities.

Description

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.

Usage

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
)

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`). `sens` is optional when its complement `mirt` is provided.
`mirt`	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.
`spec`	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.
`fart`	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.
`tol`	A numeric tolerance value for `is_complement`. Default: `tol = .01`.
`N`	The number of individuals in the population. If `N` is unknown (`NA`), a suitable minimum value is computed by `comp_min_N`.
`round`	A Boolean value that determines whether frequencies are rounded to the nearest integer. Default: `round = TRUE`.
`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.

Details

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

Value

A list freq containing 11 key frequency values.

Examples

# Basics:
comp_freq_prob(prev = .1, sens = .9, spec = .8, N = 100)  # ok: hi = 9, ... cr = 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

comp_freq_prob()                   # ok, using probability info currently contained in prob
length(comp_freq_prob())           # list of 11 key frequencies
all.equal(freq, comp_freq_prob())  # TRUE, unless prob has been changed after computing freq
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)

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

comp_freq_prob(prev = 1, sens = 1, spec = 0, N = 102)  # ok + warning: N hits (TP)
comp_freq_prob(prev = 1, sens = 0, spec = 1, N = 103)  # ok + warning: N misses (FN)
comp_freq_prob(prev = 1, sens = 0, spec = 0, N = 104)  # ok + warning: N misses (FN)
comp_freq_prob(prev = 0, sens = 1, spec = 1, N = 105)  # ok + warning: N correct rejections (TN)

comp_freq_prob(prev = 0, sens = 1, spec = 0, N = 106)  # ok + warning: N false alarms (FP)
# 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)

# Rounding:
comp_freq_prob(prev = .5, sens = .5, spec = .5, N = 1)   # yields fa = 1 (see ?round for reason)
comp_freq_prob(prev = .1, sens = .9, spec = .8, N = 10)  # 1 hit (TP, rounded)
comp_freq_prob(prev = .1, sens = .9, spec = .8, N = 10, round = FALSE)  # hi = .9

# Sampling (from probabilistic description):
comp_freq_prob(prev = .5, sens = .5, spec = .5, N = 100, sample = TRUE)  # freq values vary

# Watch out for:
comp_freq_prob(prev = 1, sens = 1, spec = 1, N = NA)  # ok + warning: N = 1 computed
comp_freq_prob(prev = 1, sens = 1, spec = 1, N =  0)  # ok, but all 0 + warning (NPV = NaN)
comp_freq_prob(prev = .5, sens = .5, spec = .5, N = 10, round = TRUE)  # ok, but all rounded
comp_freq_prob(prev = .5, sens = .5, spec = .5, N = 10, round = FALSE) # ok, but not rounded

# Ways to fail:
comp_freq_prob(prev = NA, sens = 1, spec = 1, 100)  # NAs + no warning (prev NA)
comp_freq_prob(prev = 1, sens = NA, spec = 1, 100)  # NAs + no warning (sens NA)
comp_freq_prob(prev = 1, sens = 1, spec = NA, 100)  # NAs + no warning (spec NA)
comp_freq_prob(prev = 8, sens = 1, spec = 1,  100)  # NAs + warning (prev beyond range)
comp_freq_prob(prev = 1, sens = 8, spec = 1,  100)  # NAs + warning (sens & spec beyond range)

hneth/riskyr documentation built on Feb. 18, 2024, 6:01 p.m.