riskyr: Create a riskyr scenario.

Description Usage Arguments Format Details Value See Also Examples

View source: R/riskyr_class.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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)

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

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, read_popu, summary.riskyr

Other functions initializing scenario information: init_num, init_pal, init_txt

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# 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

# Ways to work: -----
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 Jan. 3, 2019, 1:06 a.m.