plot.x_from_power: Plot The Results of 'x_from_power'

In power4mome: Power Analysis for Moderation and Mediation

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 class '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 class '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),
  ...
)

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.

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.

See Also

x_from_power()

Examples

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

power4mome documentation built on Sept. 9, 2025, 5:35 p.m.