riskyr (version 0.1.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 10 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.

Value

A list prob containing 10 probability values.

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

• Other functions translating between representational formats:

  1. comp_prob_prob (defined here) is a wrapper function for comp_prob and an analog to 3 other format conversion functions:

  2. comp_prob_freq computes current probability information contained in prob from 4 essential frequencies (hi, mi, fa, cr).

  3. comp_freq_prob computes current frequency information contained in freq from 3 essential probabilities (prev, sens, spec).

  4. comp_freq_freq computes current frequency information contained in freq from 4 essential frequencies (hi, mi, fa, cr).

• Two perspectives:

  A population of N individuals can be split into 2 subsets in 2 different ways:

  1. by condition:

     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:

     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.

  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.

• Combinations of frequencies:

  In a population of size N the following relationships hold:

  1. N = cond.true + cond.false = (hi + mi) + (fa + cr) (by condition)

  2. N = dec.pos + dec.neg = (hi + fa) + (mi + cr) (by decision)

  3. N = hi + mi + fa + cr (by condition x decision)

  The two perspectives (by condition vs. by decision) combine the 4 essential frequencies (i.e., hi, mi, fa, cr) in 2 different ways.

• Defining probabilities in terms of frequencies:

  Probabilities are numbers from 0 to 1 and determine, describe, or are defined as relationships between frequencies. The following probabilities 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. false detection rate FDR:

     FDR = fa/dec.pos = fa / (hi + fa) = (1 - PPV)

  9. negative predictive value NPV:

     NPV = cr/dec.neg = cr / (mi + cr) = (1 - FOR)

  10. false omission rate FOR:

      FOR = mi/dec.neg = mi / (mi + cr) = (1 - NPV)

See Also

prob contains current probability 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, comp_acc, comp_comp_pair, comp_complement, comp_complete_prob_set, comp_fart, comp_mirt, comp_ppod, comp_prob_freq, comp_sens, comp_spec

Examples

# NOT RUN {
# 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())  # => 10 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


# }