riskyr (version 0.1.0)

plot_fnet: Plot a network diagram of frequencies and probabilities.

Description

plot_fnet draws a network diagram of frequencies (as nodes) and probabilities (as edges) from a sufficient and valid set of 3 essential probabilities (prev, and sens or its complement mirt, and spec or its complement fart) or existing frequency information freq and a population size of N individuals.

Usage

plot_fnet(prev = num$prev, sens = num$sens, mirt = NA, spec = num$spec,
  fart = NA, N = freq$N, round = TRUE, by = "cddc", area = "sq",
  p.lbl = "num", show.accu = TRUE, w.acc = 0.5,
  title.lbl = txt$scen.lbl, popu.lbl = txt$popu.lbl,
  cond.true.lbl = txt$cond.true.lbl, cond.false.lbl = txt$cond.false.lbl,
  dec.pos.lbl = txt$dec.pos.lbl, dec.neg.lbl = txt$dec.neg.lbl,
  hi.lbl = txt$hi.lbl, mi.lbl = txt$mi.lbl, fa.lbl = txt$fa.lbl,
  cr.lbl = txt$cr.lbl, col.txt = grey(0.01, alpha = 0.99), box.cex = 0.85,
  col.boxes = pal, col.border = grey(0.33, alpha = 0.99), lwd = 1.5,
  box.lwd = 1.5, col.shadow = grey(0.11, alpha = 0.99), cex.shadow = 0)

Arguments

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.

mirt

The decision's miss rate 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.

N

The number of individuals in the population. A suitable value of N is computed, if not provided.

round

A Boolean option specifying whether computed frequencies are rounded to integers. Default: round = TRUE.

by

A character code specifying the perspective (or 1st category by which the population is split into subsets) with 4 options:

1. "cd" ... by condition;

2. "dc" ... by decision;

3. "cddc" ... 1st by condition, 2nd by decision;

4. "dccd" ... 1st by decision, 2nd by condition.

area

A character code specifying the area of the boxes (or their relative sizes) with 4 options:

1. "no" ... all boxes are shown with the same size;

2. "sq" ... boxes are squares with area sizes scaled proportional to frequencies (default);

3. "hr" ... boxes are horizontal rectangles with area sizes scaled proportional to frequencies;

4. "vr" ... boxes are vertical rectangles with area sizes scaled proportional to frequencies.

p.lbl

A character code specifying the type of probability information (on edges) with 4 options:

1. "nam" ... names of probabilities;

2. "num" ... numeric values of probabilities (rounded to 3 decimals) (default);

3. "mix" ... names of essential probabilities, values of complements;

4. "min" ... minimal labels: names of essential probabilities.

show.accu

Option for showing current accuracy metrics accu in the plot. Default: show.accu = TRUE.

w.acc

Weigthing parameter w used to compute weighted accuracy w.acc in comp_accu. Default: w.acc = .50.

Various other options allow the customization of text labels and colors:

title.lbl

Text label for current plot title. Default: title.lbl = txt$scen.lbl.

popu.lbl

Text label for current population popu.

cond.true.lbl

Text label for current cases of cond.true.

cond.false.lbl

Text label for current cases of cond.false.

dec.pos.lbl

Text label for current cases of dec.pos.

dec.neg.lbl

Text label for current cases of dec.neg.

hi.lbl

Text label for hits hi.

mi.lbl

Text label for misses mi.

fa.lbl

Text label for false alarms fa.

cr.lbl

Text label for correct rejections cr.

col.txt

Color for text labels (in boxes).

box.cex

Scaling factor for text (in boxes). Default: box.cex = .90.

col.boxes

Colors of boxes (a single color or a vector with named colors matching the number of current boxes). Default: Current color information contained in pal.

col.border

Color of borders. Default: col.border = grey(.33, alpha = .99).

lwd

Width of arrows.

box.lwd

Width of boxes.

col.shadow

Color of box shadows. Default: col.shadow = grey(.11, alpha = .99).

cex.shadow

Scaling factor of shadows (values > 0 showing shadows). Default: cex.shadow = 0.

Value

Nothing (NULL).

Details

plot_fnet is a generalization of plot_tree and offers the additional option of plotting the interplay between the 9 frequencies of freq and and the 10 probabilities of prob in a single network diagram.

The option by (as 2 or 4 characters) allows specifying 4 different ways of arranging frequencies:

1. "cd" plots a tree diagram in which the population is split by condition;

2. "dc" plots a tree diagram in which the population is split by decision;

3. "cddc" plots a network diagram in which the population is split 1st by condition, 2nd by decision (default);

4. "dccd" is yet to be implemented.

The option area (as 2 characters) allows specifying 4 different box shapes and sizes:

1. "no" shows all boxes in the same size (default);

2. "sq" shows boxes as squares with area sizes proportional to frequencies;

3. "hr" shows boxes as horizontal rectangles of area sizes proportional to frequencies;

4. "vr" shows boxes as vertical rectangles of area sizes proportional to frequencies. The resulting shapes and their relative proportions correspond to the areas in plot_mosaic.

If a prevalence value prev is provided, a new list of natural frequencies freq is computed by comp_freq. By contrast, if no prevalence value prev is provided, the values currently contained in freq are used. By default, comp_freq rounds frequencies to nearest integers to avoid decimal values in freq.

plot_fnet requires and uses the R package "diagram" (library("diagram")).

See Also

num contains basic numeric parameters; init_num initializes basic numeric parameters; freq contains current frequency information; comp_freq computes current frequency information; prob contains current probability information; comp_prob computes current probability information; pal contains current color settings; txt contains current text settings; comp_min_N computes a suitable minimum population size N.

Other visualization functions: plot.riskyr, plot_curve, plot_icons, plot_mosaic, plot_plane, plot_tree

Examples

# NOT RUN {
# Plotting existing freq:
plot_fnet()  # => plot current freq with default options
plot_fnet(by = "dccd")
plot_fnet(area = "no")
plot_fnet(p.lbl = "num")
plot_fnet(title.lbl = "")
plot_fnet(N = 33)
plot_fnet(N = NA)

# Computing and plotting new frequencies from probabilities:
plot_fnet(prev = 1/3)  # => changes prev, but uses current defaults of sens and spec
plot_fnet(prev = 1/3, N = 55)
plot_fnet(prev = 1/3, N = NA)
plot_fnet(prev = 1/3, round = FALSE)
plot_fnet(prev = .10, sens = .90, spec = 1/3, N = 100)
plot_fnet(prev = .10, sens = .90, spec = NA, fart = 1/3, N = 33)
plot_fnet(prev = .10, sens = .90, spec = 1/3, fart = NA, N = NA)
plot_fnet(prev = .10, sens = .90, spec = NA, fart = 1/3, N = NA)

# Perspective options:
plot_fnet(by = "cd")    # => 1. Tree diagram (by condition)
plot_fnet(by = "dc")    # => 2. Tree diagram (by decision)
plot_fnet(by = "cddc")  # => 3. Network diagram (1st by cond, 2nd by dec) (default)
plot_fnet(by = "dccd")  # => 4. Network diagram (1st by dec, 2nd by cond)

# Area options:
plot_fnet(area = "sq")  # => (default)
plot_fnet(area = "no")
plot_fnet(area = "sq", round = FALSE)
plot_fnet(area = "hr")
plot_fnet(area = "vr", round = FALSE)

# Accuracy:
plot_fnet(show.accu = TRUE)               # => default w = .5 (balanced accuracy "bacc")
plot_fnet(show.accu = TRUE, w.acc = 1/3)  # => (weighted accuracy "wacc")
plot_fnet(show.accu = FALSE)              # => no accuracy info.

# Rounding:
plot_fnet(prev = .1, sens = .7, spec = .9, N = 10, by = "cddc", area = "sq",
          p.lbl = "num", round = TRUE)    # => mi = 0
plot_fnet(prev = .1, sens = .7, spec = .9, N = 10, by = "cddc", area = "sq",
          p.lbl = "num", round = FALSE)   # => mi = 0.3

# Combining perspectives, areas, and label options:
plot_fnet(by = "cd", area = "sq", p.lbl = "nam")  # => by cond + sq + prob names
plot_fnet(by = "cd", area = "hr", p.lbl = "num")  # => by cond + hr + prob numbers
plot_fnet(by = "dc", area = "sq", p.lbl = "num")  # => by dec  + sq + mix names and numbers
plot_fnet(by = "dc", area = "vr", p.lbl = "mix")  # => by dec  + vr + min. labels

# Custom colors and shadows:
plot_fnet(prev = .08, sens = .92, spec = .95, N = 10000, area = "hr")
plot_fnet(area = "sq", col.boxes = "gold", col.border = "steelblue4",
          col.shadow = "steelblue4", cex.shadow = .008)
plot_fnet(N = NA, area = "vr", col.txt = "steelblue4", col.boxes = "lightyellow",
          col.border = grey(.3, .7), cex.shadow = .008, col.shadow = grey(.1, .9))


# }