riskyr: Create a riskyr scenario.
In riskyr: Rendering Risk Literacy more Transparent

riskyr

R Documentation

Create a riskyr scenario.

Description

riskyr creates a scenario of class "riskyr", which can be visualized by the plot method plot.riskyr and summarized by the summary method summary.riskyr.

Usage

riskyr(
  scen_lbl = txt$scen_lbl,
  popu_lbl = txt$popu_lbl,
  N_lbl = txt$N_lbl,
  cond_lbl = txt$cond_lbl,
  cond_true_lbl = txt$cond_true_lbl,
  cond_false_lbl = txt$cond_false_lbl,
  dec_lbl = txt$dec_lbl,
  dec_pos_lbl = txt$dec_pos_lbl,
  dec_neg_lbl = txt$dec_neg_lbl,
  acc_lbl = txt$acc_lbl,
  dec_cor_lbl = txt$dec_cor_lbl,
  dec_err_lbl = txt$dec_err_lbl,
  sdt_lbl = txt$sdt_lbl,
  hi_lbl = txt$hi_lbl,
  mi_lbl = txt$mi_lbl,
  fa_lbl = txt$fa_lbl,
  cr_lbl = txt$cr_lbl,
  prev = NA,
  sens = NA,
  spec = NA,
  fart = NA,
  N = NA,
  hi = NA,
  mi = NA,
  fa = NA,
  cr = NA,
  scen_lng = txt$scen_lng,
  scen_txt = txt$scen_txt,
  scen_src = txt$scen_src,
  scen_apa = txt$scen_apa,
  round = TRUE,
  sample = FALSE
)

Arguments

`scen_lbl`	The current scenario title (sometimes in Title Caps).
`popu_lbl`	A brief description of the current population or sample.
`N_lbl`	A label for the current population `popu` or sample.
`cond_lbl`	A label for the condition or feature (e.g., some disease) currently considered.
`cond_true_lbl`	A label for the presence of the current condition or `cond_true` cases (the condition's true state of TRUE).
`cond_false_lbl`	A label for the absence of the current condition or `cond_false` cases (the condition's true state of FALSE).
`dec_lbl`	A label for the decision or judgment (e.g., some diagnostic test) currently made.
`dec_pos_lbl`	A label for positive decisions or `dec_pos` cases (e.g., predicting the presence of the condition).
`dec_neg_lbl`	A label for negative decisions or `dec_neg` cases (e.g., predicting the absence of the condition).
`acc_lbl`	A label for accuracy (i.e., correspondence between condition and decision or judgment).
`dec_cor_lbl`	A label for correct (or accurate) decisions or judgments.
`dec_err_lbl`	A label for incorrect (or erroneous) decisions or judgments.
`sdt_lbl`	A label for the combination of condition and decision currently made.
`hi_lbl`	A label for hits or true positives `hi` (i.e., correct decisions of the presence of the condition, when the condition is actually present).
`mi_lbl`	A label for misses or false negatives `mi` (i.e., incorrect decisions of the absence of the condition when the condition is actually present).
`fa_lbl`	A label for false alarms or false positives `fa` (i.e., incorrect decisions of the presence of the condition when the condition is actually absent).
`cr_lbl`	A label for correct rejections or true negatives `cr` (i.e., a correct decision of the absence of the condition, when the condition is actually absent). Essential probabilities:
`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.
`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. Essential frequencies:
`N`	The number of individuals in the scenario's population. A suitable value of `N` is computed, if not provided.
`hi`	The number of hits `hi` (or true positives).
`mi`	The number of misses `mi` (or false negatives).
`fa`	The number of false alarms `fa` (or false positives).
`cr`	The number of correct rejections `cr` (or true negatives). Details and source information:
`scen_lng`	Language of the current scenario (as character code). Options: `"en"` for English, `"de"` for German.
`scen_txt`	A longer text description of the current scenario (which may extend over several lines).
`scen_src`	Source information for the current scenario.
`scen_apa`	Source information for the current scenario according to the American Psychological Association (APA style).
`round`	Boolean value that determines whether frequency values are rounded to the nearest integer. Default: `round = TRUE`. Note: Only rounding when using `comp_freq_prob` (i.e., computing `freq` from `prob` description).
`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: Only sampling when using `comp_freq_prob` (i.e., computing `freq` from `prob` description).

Format

An object of class "riskyr" with textual and numeric information describing a risk-related scenario.

Details

Beyond basic scenario information (i.e., text elements describing a scenario) only the population size N and the essential probabilities prev, sens, spec, and fart are used and returned.

Note:

Basic text information and some numeric parameters (see num and init_num) are integral parts of a riskyr scenario.
By contrast, basic color information (see pal and init_pal) is not an integral part, but independently defined.
The names of probabilities (see prob) are currently not an integral part of txt and riskyr scenarios (but defined in prob_lbl_def and label_prob).

Value

An object of class "riskyr" describing a risk-related scenario.

Scenario-specific titles and text labels (see txt).

Examples

# Defining scenarios: -----
# (a) minimal information:
hustosis <- riskyr(scen_lbl = "Screening for hustosis",
                   N = 1000, prev = .04, sens = .80, spec = .95)

# (2) detailed information:
scen_reoffend <- riskyr(scen_lbl = "Identify reoffenders",
                        cond_lbl = "being a reoffender",
                        popu_lbl = "Prisoners",
                        cond_true_lbl = "has reoffended",
                        cond_false_lbl = "has not reoffended",
                        dec_lbl = "test result",
                        dec_pos_lbl = "will reoffend",
                        dec_neg_lbl = "will not reoffend",
                        sdt_lbl = "combination",
                        hi_lbl = "reoffender found", mi_lbl = "reoffender missed",
                        fa_lbl = "false accusation", cr_lbl = "correct release",
                        prev = .45,  # prevalence of being a reoffender.
                        sens = .98,
                        spec = .46, fart = NA,  # (provide 1 of 2)
                        N = 753,
                        scen_src = "Example scenario")

# Using scenarios: -----
summary(hustosis)
plot(hustosis)

summary(scen_reoffend)
plot(scen_reoffend)

# 2 ways of defining the same scenario:
s1 <- riskyr(prev = .5, sens = .5, spec = .5, N = 100)  # s1: define by 3 prob & N
s2 <- riskyr(hi = 25, mi = 25, fa = 25, cr = 25)        # s2: same scenario by 4 freq
all.equal(s1, s2)  # should be TRUE

# Rounding and sampling:
s3 <- riskyr(prev = 1/3, sens = 2/3, spec = 6/7, N = 100, round = FALSE)  # s3: w/o rounding
s4 <- riskyr(prev = 1/3, sens = 2/3, spec = 6/7, N = 100, sample = TRUE)  # s4: with sampling

# Note:
riskyr(prev = .5, sens = .5, spec = .5, hi = 25, mi = 25, fa = 25, cr = 25)  # works (consistent)
riskyr(prev = .5, sens = .5, spec = .5, hi = 25, mi = 25, fa = 25)           # works (ignores freq)

## Watch out for:
# riskyr(hi = 25, mi = 25, fa = 25, cr = 25, N = 101)  # warns, uses actual sum of freq
# riskyr(prev = .4, sens = .5, spec = .5, hi = 25, mi = 25, fa = 25, cr = 25)  # warns, uses freq

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