plot.x_from_power: Plot The Results of 'x_from_power'

Description

It plots the results of 'x_from_power', such as the estimated power against sample size.

Usage

# S3 method for x_from_power
plot(
  x,
  what = c("ci", "power_curve", "final_x", "final_power", "target_power", switch(x$x, n =
    "sig_area", es = NULL)),
  text_what = c("final_x", "final_power", switch(x$x, n = "sig_area", es = NULL)),
  digits = 3,
  main = paste0("Power Curve ", "(Target Power: ", formatC(x$target_power, digits =
    digits, format = "f"), ")"),
  xlab = NULL,
  ylab = "Estimated Power",
  ci_level = 0.95,
  pars_ci = list(),
  pars_power_curve = list(),
  pars_ci_final_x = list(lwd = 2, length = 0.2, col = "blue"),
  pars_target_power = list(lty = "dashed", lwd = 2, col = "black"),
  pars_final_x = list(lty = "dotted"),
  pars_final_power = list(lty = "dotted", col = "blue"),
  pars_text_final_x = list(y = 0, pos = 3, cex = 1),
  pars_text_final_power = list(pos = 3, cex = 1),
  pars_sig_area = list(col = adjustcolor("lightblue", alpha.f = 0.1)),
  pars_text_sig_area = list(cex = 1),
  ...
)
# S3 method for n_region_from_power
plot(
  x,
  what = c("ci", "power_curve", "final_x", "final_power", "target_power", "sig_area"),
  text_what = c("final_x", "final_power", "sig_area"),
  digits = 3,
  main = paste0("Power Curve ", "(Target Power: ", formatC(x$below$target_power, digits =
    digits, format = "f"), ")"),
  xlab = NULL,
  ylab = "Estimated Power",
  ci_level = 0.95,
  pars_ci = list(),
  pars_power_curve = list(),
  pars_ci_final_x = list(lwd = 2, length = 0.2, col = "blue"),
  pars_target_power = list(lty = "dashed", lwd = 2, col = "black"),
  pars_final_x = list(lty = "dotted"),
  pars_final_power = list(lty = "dotted", col = "blue"),
  pars_text_final_x = list(y = 0, pos = 3, cex = 1),
  pars_text_final_power = list(cex = 1),
  pars_sig_area = list(col = adjustcolor("lightblue", alpha.f = 0.1)),
  pars_text_sig_area = list(cex = 1),
  ...
)

Value

The plot-method of x_from_power

returns x invisibly. It is called for its side effect.

The plot-method of n_region_from_power

returns x invisibly. It is called for its side effect.

Arguments

x: An x_from_power object, the output of x_from_power().
what: A character vector of what to include in the plot. Possible values are "ci" (confidence intervals for the estimated value of the predictor), "power_curve" (the crude power curve, if available), "final_x" (a vertical line for the value of the predictor with estimated power close enough to the target power by confidence interval), "final_power" (a horizontal line for the estimated power of the final value of the predictor), "target_power" (a horizontal line for the target power), and "sig_area" (the area significantly higher or lower than the target power, if goal is "close_enough" and what is "lb" or "ub"). By default, all these elements will be plotted.
text_what: A character vector of what numbers to be added as labels. Possible values are "final_x" (the value of the predictor with estimated power close enough to the target power by confidence interval) "final_power" (the estimated power of the final value of the predictor), and "sig_area" (labeling the area significantly higher or lower than the target power, if goal is "close_enough" and what is "lb" or "ub"). By default, all these labels will be added.
digits: The number of digits after the decimal that will be used when adding numbers.
main: The title of the plot.
xlab, ylab: The labels for the horizontal and vertical axes, respectively.
ci_level: The level of confidence of the confidence intervals, if requested. Default is .95, denoting 95%.
pars_ci: A named list of arguments to be passed to arrows() to customize the drawing of the confidence intervals.
pars_power_curve: A named list of arguments to be passed to points() to customize the drawing of the power curve.
pars_ci_final_x: A named list of arguments to be passed to arrows() to customize the drawing of the confidence interval of the final value of the predictor.
pars_target_power: A named list of arguments to be passed to abline() when drawing the horizontal line for the target power.
pars_final_x: A named list of arguments to be passed to abline() when drawing the vertical line for the final value of the predictor.
pars_final_power: A named list of arguments to be passed to abline() when drawing the horizontal line for the estimated power at the final value of the predictor.
pars_text_final_x: A named list of arguments to be passed to text() when adding the label for the final value of the predictor.
pars_text_final_power: A named list of arguments to be passed to text() when adding the label for the estimated power of final value of the predictor.
pars_sig_area: A named list of arguments to be passed to rect() when shading the area significantly higher or lower than the target power.
pars_text_sig_area: A named list of arguments to be passed to text() when labelling the area significantly higher or lower than the target power.
...: Optional arguments. Passed to plot() when drawing the estimated power against the predictor.

Details

The plot method of x_from_power objects currently plots the relation between estimated power and the values examined by x_from_power(). Other elements can be requested (see the argument what), and they can be customized individually.

The plot-method for n_region_from_power objects is a modified version of the plot-method for x_from_power. It plots the results of two runs of n_from_power() in one plot. It is otherwise similar to the plot-method for x_from_power.

Examples

Run this code


# Specify the population model

mod <-
"
m ~ x
y ~ m + x
"

# Specify the population values

mod_es <-
"
m ~ x: m
y ~ m: l
y ~ x: n
"

# Generate the datasets

sim_only <- power4test(nrep = 10,
                       model = mod,
                       pop_es = mod_es,
                       n = 100,
                       do_the_test = FALSE,
                       iseed = 1234)

# Do a test

test_out <- power4test(object = sim_only,
                       test_fun = test_parameters,
                       test_args = list(pars = "m~x"))

# Determine the sample size with a power of .80 (default)

power_vs_n <- x_from_power(test_out,
                           x = "n",
                           progress = TRUE,
                           target_power = .80,
                           final_nrep = 10,
                           max_trials = 1,
                           seed = 2345)
plot(power_vs_n)