riskyr (version 0.4.0)

comp_prob: 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
)

Value

A list prob containing 13 key probability values.

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

See Also

prob contains current probability information; accu contains current accuracy information; num contains basic numeric parameters; init_num initializes basic numeric parameters; pal contains current color information; txt contains current text information; freq contains current frequency information; comp_freq computes frequencies from probabilities; is_valid_prob_set verifies sets of probability inputs; is_extreme_prob_set verifies sets of extreme probabilities; comp_min_N computes a suitable minimum population size N; comp_freq_freq computes current frequency information from (4 essential) frequencies; comp_freq_prob computes current frequency information from (3 essential) probabilities; comp_prob_freq computes current probability information from (4 essential) frequencies; comp_prob_prob computes current probability information from (3 essential) probabilities.

Other functions computing probabilities: comp_FDR(), comp_FOR(), comp_NPV(), comp_PPV(), comp_accu_freq(), comp_accu_prob(), comp_acc(), comp_comp_pair(), comp_complement(), comp_complete_prob_set(), comp_err(), comp_fart(), comp_mirt(), comp_ppod(), comp_prob_freq(), comp_sens(), comp_spec()

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