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

Value

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

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

See Also

init_num and num for basic numeric parameters; init_txt and txt for current text settings; init_pal and pal for current color settings.

Other riskyr scenario functions: plot.riskyr(), summary.riskyr()

Other functions initializing scenario information: init_num(), init_pal(), init_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


[Package riskyr version 0.4.0 Index]