comp_prob: Compute probabilities from (3 essential) probabilities.
In riskyr: Rendering Risk Literacy more Transparent

comp_prob

R Documentation

Compute probabilities from (3 essential) probabilities.

Description

comp_prob computes current probability information from 3 essential probabilities (prev, sens or mirt, spec or fart). It returns a list of 13 key probabilities prob as its output.

Usage

comp_prob(
  prev = num$prev,
  sens = num$sens,
  mirt = NA,
  spec = num$spec,
  fart = NA,
  tol = 0.01
)

Arguments

`prev`	The condition's prevalence value `prev` (i.e., the probability of the condition being `TRUE`).
`sens`	The decision's sensitivity value `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 value `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`.

Details

comp_prob assumes that a sufficient and consistent set of essential probabilities (i.e., prev and either sens or its complement mirt, and either spec or its complement fart) is provided.

comp_prob computes and returns a full set of basic and various derived probabilities (e.g., the probability of a positive decision ppod, the probability of a correct decision acc, the predictive values PPV and NPV, as well as their complements FDR and FOR) in its output of a list prob.

Extreme probabilities (sets containing two or more probabilities of 0 or 1) may yield unexpected values (e.g., predictive values PPV or NPV turning NaN when is_extreme_prob_set evaluates to TRUE).

comp_prob is the probability counterpart to the frequency function comp_freq.

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)
Note: When frequencies are rounded (by round = TRUE in comp_freq), probabilities computed from freq may differ from 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).

Value

A list prob containing 13 key probability values.

Examples

# Basics:
comp_prob(prev = .11, sens = .88, spec = .77)                        # => ok: PPV = 0.3210614
comp_prob(prev = .11, sens = NA, mirt = .12, spec = NA, fart = .23)  # => ok: PPV = 0.3210614
comp_prob()          # => ok, using current defaults
length(comp_prob())  # => 13 probabilities

# Ways to work:
comp_prob(.99, sens = .99, spec = .99)              # => ok: PPV = 0.999898
comp_prob(.99, sens = .90, spec = NA, fart = .10)   # => ok: PPV = 0.9988789

# Watch out for extreme cases:
comp_prob(1, sens = 0, spec = 1)      # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = 0)      # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = NA, fart = 0)  # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = NA, fart = 1)  # => ok, but with warnings (as PPV & FDR are NaN)

# Watch out for extreme cases:
comp_prob(1, sens = 0, spec = 1)      # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = 0)      # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = NA, fart = 0)  # => ok, but with warnings (as PPV & FDR are NaN)
comp_prob(1, sens = 0, spec = NA, fart = 1)  # => ok, but with warnings (as PPV & FDR are NaN)

comp_prob(1, sens = 1, spec = 0)      # => ok, but with warnings (as NPV & FOR are NaN)
comp_prob(1, sens = 1, spec = 1)      # => ok, but with warnings (as NPV & FOR are NaN)
comp_prob(1, sens = 1, spec = NA, fart = 0)  # => ok, but with warnings (as NPV & FOR are NaN)
comp_prob(1, sens = 1, spec = NA, fart = 1)  # => ok, but with warnings (as NPV & FOR are NaN)

# Ways to fail:
comp_prob(NA, 1, 1, NA)  # => only warning: invalid set (prev not numeric)
comp_prob(8,  1, 1, NA)  # => only warning: prev no probability
comp_prob(1,  8, 1, NA)  # => only warning: sens no probability
comp_prob(1,  1, 1,  1)  # => only warning: is_complement not in tolerated range

riskyr documentation built on Aug. 15, 2022, 9:09 a.m.