% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/q_functions.R
\name{q_power_mediation}
\alias{q_power_mediation}
\alias{print.q_power_mediation}
\alias{plot.q_power_mediation}
\alias{summary.q_power_mediation}
\alias{q_power_mediation_simple}
\alias{q_power_mediation_serial}
\alias{q_power_mediation_parallel}
\title{All-in-One Power Estimation For Mediation Models}
\usage{
q_power_mediation(
  model = NULL,
  pop_es = NULL,
  number_of_indicators = NULL,
  reliability = NULL,
  loading_difference = NULL,
  reference = NULL,
  test_fun = NULL,
  test_more_args = list(),
  target_power = 0.8,
  nrep = NULL,
  n = NULL,
  R = 1000,
  ci_type = c("mc", "boot"),
  seed = NULL,
  iseed = NULL,
  parallel = TRUE,
  progress = TRUE,
  simulation_progress = NULL,
  max_trials = NULL,
  algorithm = NULL,
  ...,
  mode = c("power", "region", "n")
)

\method{print}{q_power_mediation}(x, mode = c("all", "region", "n", "power"), ...)

\method{plot}{q_power_mediation}(x, ...)

\method{summary}{q_power_mediation}(object, ...)

q_power_mediation_simple(
  a = "m",
  b = "m",
  cp = "n",
  number_of_indicators = NULL,
  reliability = NULL,
  loading_difference = NULL,
  reference = NULL,
  test_more_args = list(),
  target_power = 0.8,
  nrep = NULL,
  n = NULL,
  R = 1000,
  ci_type = c("mc", "boot"),
  seed = NULL,
  iseed = NULL,
  parallel = TRUE,
  progress = TRUE,
  simulation_progress = NULL,
  max_trials = NULL,
  algorithm = NULL,
  ...,
  mode = c("power", "region", "n")
)

q_power_mediation_serial(
  ab = c("m", "m"),
  ab_other = "n",
  cp = "n",
  number_of_indicators = NULL,
  reliability = NULL,
  loading_difference = NULL,
  reference = NULL,
  test_more_args = list(),
  target_power = 0.8,
  nrep = NULL,
  n = NULL,
  R = 1000,
  ci_type = c("mc", "boot"),
  seed = NULL,
  iseed = NULL,
  parallel = TRUE,
  progress = TRUE,
  simulation_progress = NULL,
  max_trials = NULL,
  algorithm = NULL,
  ...,
  mode = c("power", "region", "n")
)

q_power_mediation_parallel(
  as = c("m", "m"),
  bs = c("m", "m"),
  cp = "n",
  number_of_indicators = NULL,
  reliability = NULL,
  loading_difference = NULL,
  reference = NULL,
  omnibus = c("all_sig", "at_least_one_sig", "at_least_k_sig"),
  at_least_k = 1,
  test_more_args = list(),
  target_power = 0.8,
  nrep = NULL,
  n = NULL,
  R = 1000,
  ci_type = c("mc", "boot"),
  seed = NULL,
  iseed = NULL,
  parallel = TRUE,
  progress = TRUE,
  simulation_progress = NULL,
  max_trials = NULL,
  algorithm = NULL,
  ...,
  mode = c("power", "region", "n")
)
}
\arguments{
\item{model}{The \code{lavaan} model
syntax of the population model,
to be used by \code{\link[=ptable_pop]{ptable_pop()}}.
See 'Details' of
on how to specify the model.
Ignored if \code{ptable} is
specified.}

\item{pop_es}{The character vector or
multiline string to
specify population effect sizes
(population values of parameters). See
the help page on how to specify this
argument.
Ignored if \code{ptable} is
specified.}

\item{number_of_indicators}{A named
vector to specify the number of
indicators for each factors. See
the help page on how to set this
argument. Default is \code{NULL} and all
variables in the model syntax are
observed variables.
See the help page on how
to use this argument.}

\item{reliability}{A named vector
(for a single-group model) or a
named list of named vectors
(for a multigroup model)
to set the reliability coefficient
of each set of indicators. Default
is \code{NULL}.
See the help page on how
to use this argument.}

\item{loading_difference}{A named vector
(for a single-group model) or a
named list of named vectors
(for a multigroup model)
to set the difference in factor
loadings between neighboring indicators
of each set of indicators. Default
is \code{NULL}, and all indicators of
a factor have
the same factor loadings. If specified,
must be specified for all factors
named in \code{reliability}, even for
those with all loadings equal.}

\item{reference}{A named vector
(for a single-group model) or a
named list of named vectors
(for a multigroup model)
to indicate which indicator will
be the first indicator (and so
is the reference indicator, by default).
Default
is \code{NULL}, and for all factors,
the indicator with
the medium loading in a factor is
the first indicator. Has no effect
if loading difference is zero (and
so all indicators have the same
loadings). If specified,
must be specified for all factors
named in \code{reliability}, even for
those with all loadings equal. Accepted
values are \code{"medium"}, \code{"weakest"},
and \code{"strongest"}.}

\item{test_fun}{A function to do the
test. See 'Details' of \code{\link[=power4test]{power4test()}}
for the requirement of this function.}

\item{test_more_args}{A named list of
additional arguments to be passed
to the test function
(\code{\link[=test_indirect_effect]{test_indirect_effect()}} for
simple and serial mediation models,
and \code{\link[=test_k_indirect_effects]{test_k_indirect_effects()}}
for parallel mediation models).
Similar to \code{test_args} in
\code{\link[=power4test]{power4test()}}.}

\item{target_power}{The target power,
a value greater than 0 and less than
one.}

\item{nrep}{The number of replications
to generate the simulated datasets.
Default is \code{NULL} and will be determined
internally.}

\item{n}{The sample size for the
first run of \code{\link[=power4test]{power4test()}}. Must be
set to a sample size if \code{mode} is
\code{"power"}. For the other modes,
if \code{NULL}, the default, it will be
determined internally.}

\item{R}{The number of replications
to generate the Monte Carlo or
bootstrapping estimates
for each fit output. No Monte Carlo
nor bootstrapping
estimates will be generated if \code{R}
is set to \code{NULL}.}

\item{ci_type}{The type of
simulation-based confidence
intervals to use. Can be either
\code{"mc"} for Monte Carlo method
(the default) or \code{"boot"} for
nonparametric bootstrapping method.
Relevant for test functions that
make use of estimates generate by
\code{\link[=gen_boot]{gen_boot()}} or \code{\link[=gen_mc]{gen_mc()}}, such as
\code{\link[=test_indirect_effect]{test_indirect_effect()}}.}

\item{seed}{The seed for the random
number generator. Used by
\code{\link[=n_region_from_power]{n_region_from_power()}}.}

\item{iseed}{The seed for the random
number generator. Used by
\code{\link[=power4test]{power4test()}}.}

\item{parallel}{If \code{TRUE}, parallel
processing will be used when calling
other functions, if appropriate.}

\item{progress}{If \code{TRUE}, the progress
of each step will be displayed.
Default is \code{TRUE}.}

\item{simulation_progress}{Logical.
Whether the progress in each call
to \code{\link[=power4test]{power4test()}}, \code{\link[=power4test_by_n]{power4test_by_n()}},
or \code{\link[=power4test_by_es]{power4test_by_es()}}
is shown. To be passed to
the \code{progress} argument of these
functions.
If \code{NULL}, set automatically based
on the algorithm used.}

\item{max_trials}{The maximum number
of trials in searching the value
with the target power. Rounded
up if not an integer.
If \code{NULL}, set automatically based
on the algorithm used.}

\item{algorithm}{The algorithm to be
used in mode \code{"region"} and \code{"n"}.
If \code{NULL}, then it will be determined
internally based on the \code{mode}. (The
default may be different from that
of \code{\link[=n_region_from_power]{n_region_from_power()}} and
\code{\link[=n_from_power]{n_from_power()}})}

\item{...}{For \verb{q_power_mediation_*},
these are optional arguments to
be passed to \code{\link[=power4test]{power4test()}} and
\code{\link[=n_region_from_power]{n_region_from_power()}}.
For the \code{print} method, these
are optional arguments to
be passed to \code{\link[=rejection_rates]{rejection_rates()}}
as well as other print methods
(see \code{\link[=print.power4test]{print.power4test()}} and
\code{\link[=print.n_region_from_power]{print.n_region_from_power()}}).
For the \code{plot} method, these
are optional arguments to
be passed to \code{\link[=plot.n_region_from_power]{plot.n_region_from_power()}}.
For the \code{summary} method, these
are optional arguments to
be passed to \code{\link[=summary.n_region_from_power]{summary.n_region_from_power()}}.}

\item{mode}{For \verb{q_power_mediation_*, this is the mode of what to do. If }"power"\verb{, then only [power4test()] will be called, and the level of power will be estimated. If }"region"\verb{, then the region of sample sizes with levels of power not significantly different from the target power will be searched by calling [n_region_from_power()]. For the }print\verb{method, this indicates what to print. If}"region"\verb{and the output of [n_region_from_power()] is available, it will print the results of [n_region_from_power()] if available. If}"n"\verb{, then the output of [n_from_power()] will be printed if available. If }"power"\verb{, then the output of [power4test()] will be printed. If }"all"`, then all available outputs
will be printed.}

\item{x}{The object
for the relevant methods.}

\item{object}{For the \code{summary}
method of \code{\link[=q_power_mediation]{q_power_mediation()}}
outputs.}

\item{a}{For a simple mediation
model, this is the population effect
size for the path from \code{x} to \code{m} .}

\item{b}{For a simple mediation
model, this is the population effect
size for the path from \code{m} to \code{y} .}

\item{cp}{For a simple mediation
model, this is the population effect
size for the direct path from
\code{c} to \code{y} .}

\item{ab}{For a serial mediation
model, this is a numeric vector
of the population effect
sizes along the path
\code{x->m1->m2->...->y}.}

\item{ab_other}{Should be one single
value. This is the population effect
sizes of all other paths not along
\code{x->m1->m2->...->y}, except for the
direct path from \code{x} to \code{y}.}

\item{as}{For a parallel mediation
model, this is a numeric vector
of the population effect
sizes for the paths from \code{x} to
the mediators: \code{x->m1}, \code{x->m2},
... \code{x->mp}, for a parallel mediation
model with \code{p} mediators.}

\item{bs}{For a parallel mediation
model, this is a numeric vector
of the population effect
sizes for the paths from the
mediators to \code{y}: \code{m1->y}, \code{m2->y},
... \code{mp->y}, for a parallel mediation
model with \code{p} mediators.}

\item{omnibus}{\code{"all_sig"}, the
default, then
the test is declared significant if
\emph{all} paths are significant. If
\code{"at_least_one_sig"}, then only
one row of test is stored, and the
test is declared significant if
at least one of the paths is
significant. If \code{"at_least_k_sig"},
then only one row of test is stored,
and the test is declared significant
if at least \code{k} of the paths is
significant, \code{k} determined by the
argument \code{at_least_k}.}

\item{at_least_k}{The minimum number
of paths required to be significant
for the omnibus test to be considered
significant. Used when
\code{omnibus} is \code{"at_least_k_sig"}.}
}
\value{
A named list of outputs.
If \code{mode} is \code{power}, then a
\code{power4test} object is set to the
element \code{power4test}.
If \code{mode} is \code{region}, then a
\code{n_region_from_power} object is
set of the element \code{n_region_from_power}.
If \code{mode} is \code{n_from_power}, then a
\code{n_from_power} object is
set to the \code{n_from_power} element.

The \code{print} method of \code{q_power_mediation}
returns \code{x} invisibly. Called for
its side effect.

The \code{plot}-method of \code{q_power_mediation}
returns \code{NULL}.
It will plot either the output of
\code{\link[=n_region_from_power]{n_region_from_power()}}
(mode \code{"region"}) or the output of
\code{\link[=n_from_power]{n_from_power()}} (mode \code{"n"}).
If no output from
either of these functions is available,
nothing wil be plotted.

The \code{summary} method for
\code{q_power_mediation} objects returns
the output of \code{\link[=summary]{summary()}} for
either the output of \code{\link[=n_region_from_power]{n_region_from_power()}}
(mode \code{"region"}) or the output of
\code{\link[=n_from_power]{n_from_power()}} (mode \code{"n"}).
Return \code{NULL} if no output from
either of these functions is available.
}
\description{
All-in-one functions for
estimating power or finding the
region with target power for common
mediation models.
}
\section{All-in-One Functions for Common Mediation Models}{
These functions are wrappers
that call \code{\link[=power4test]{power4test()}} and
\code{\link[=n_region_from_power]{n_region_from_power()}} to (a)
estimate the level of power for
a mediation model, given the population
effects and the sample size, and
(b) find the region of sample sizes
with the levels of power not
significantly different from the
target power.

They are convenient functions that
set the argument values automatically
for common mediation models before
calling \code{\link[=power4test]{power4test()}} and
\code{\link[=n_region_from_power]{n_region_from_power()}}. Please refer
to the help pages of these two
functions for the details on how
the estimation and the search are
conducted.

For some arguments not described in
details here, please refer to the
help pages of \code{\link[=power4test]{power4test()}}
and \code{\link[=n_region_from_power]{n_region_from_power()}},
}

\section{Simple Mediation Model}{
The function \code{\link[=q_power_mediation_simple]{q_power_mediation_simple()}}
can be used for the power analysis of
a simple mediation model with only
one mediator.

This function will fit
the following model:

\preformatted{"m ~ x
 y ~ m + x"}
}

\section{Serial Mediation Model}{
The function \code{\link[=q_power_mediation_serial]{q_power_mediation_serial()}}
can be used for the power analysis of
a serial mediation model with only
any number of mediators.

This is the model being fitted if
the model has two mediators:

\preformatted{"m1 ~ x
 m2 ~ m1 + x
 y ~ m2 + m1 + x"}
}

\section{Parallel Mediation Model}{
The function \code{\link[=q_power_mediation_parallel]{q_power_mediation_parallel()}}
can be used for the power analysis of
a parallel mediation model with only
any number of mediators.

This is the model being fitted if
the model has two mediators:

\preformatted{"m1 ~ x
 m2 ~ x
 y ~ m2 + m1 + x"}
}

\section{An Arbitrary Mediation Model}{
The function \code{\link[=q_power_mediation]{q_power_mediation()}},
an advanced function,
can be used for the power analysis of
an arbitrary mediation model.
The model and the population effect
sizes are specified as in \code{\link[=power4test]{power4test()}}.

This is an example of a model with
both parallel paths and serial paths:

\preformatted{model <-
 "
 m1 ~ x
 m21 ~ m1
 m22 ~ m1
 y ~ m21 + m22 + x
 "}

\preformatted{pop_es <-
"
m1 ~ x: m
m21 ~ m1: m
m22 ~ m1: m
y ~ m21: m
y ~ m22: m
"}

Knowledge of using \code{\link[=power4test]{power4test()}}
is required to use this advanced
function.

If this advanced function is used,
users need to specify \code{test_fun}
as when using \code{\link[=power4test]{power4test()}}, and
need to set \code{test_args} correctly
}

\examples{

\dontrun{

# An arbitrary mediation model

model <-
"
m1 ~ x
m21 ~ m1
m22 ~ m1
y ~ m21 + m22
"
pop_es <-
"
m1 ~ x: m
m21 ~ m1: m
m22 ~ m1: m
y ~ m21: m
y ~ m22: m
"

# NOTE: In real power analysis:
# - Set R to an appropriate value.
# - Remove nrep or set nrep to the desired value.
# - Remove parallel or set it to TRUE to enable parallel processing.
# - Remove progress or set it to TRUE to see the progress.

outa1 <- q_power_mediation(
    model = model,
    pop_es = pop_es,
    n = 100,
    R = 199,
    test_fun = test_k_indirect_effects,
    test_more_args = list(x = "x",
                          y = "y",
                          omnibus = "all"),
    seed = 1234,
    mode = "region",
    nrep = 20,
    parallel = FALSE,
    progress = FALSE
  )
outa1
summary(outa1)
plot(outa1)

}


# Simple mediation model

# NOTE: In real power analysis:
# - Set R to an appropriate value.
# - Remove nrep or set nrep to the desired value.
# - Remove parallel or set it to TRUE to enable parallel processing.
# - Remove progress or set it to TRUE to see the progress.

out <- q_power_mediation_simple(
    a = "m",
    b = "m",
    cp = "n",
    n = 50,
    R = 79,
    seed = 1234,
    nrep = 10,
    parallel = FALSE,
    progress = FALSE
  )
out

# If mode = "region" is added, can call the following
# summary(out)
# plot(out)


\dontrun{
# Serial mediation model

# NOTE: In real power analysis:
# - Set R to an appropriate value.
# - Remove nrep or set nrep to the desired value.
# - Remove parallel or set it to TRUE to enable parallel processing.
# - Remove progress or set it to TRUE to see the progress.

outs <- q_power_mediation_serial(
    ab = c("s", "m", "l"),
    ab_others = "n",
    cp = "s",
    n = 50,
    R = 199,
    seed = 1234,
    mode = "region",
    nrep = 20,
    parallel = FALSE,
    progress = FALSE
  )
outs
summary(outs)
plot(outs)
}


\dontrun{
# Parallel mediation model

# NOTE: In real power analysis:
# - Set R to an appropriate value.
# - Remove nrep or set nrep to the desired value.
# - Remove parallel or set it to TRUE to enable parallel processing.
# - Remove progress or set it to TRUE to see the progress.

outp <- q_power_mediation_parallel(
    as = c("s", "m"),
    bs = c("m", "s"),
    cp = "n",
    n = 100,
    R = 199,
    seed = 1234,
    mode = "region",
    nrep = 20,
    parallel = FALSE,
    progress = FALSE
  )
outp
summary(outp)
plot(outp)
}

}
\seealso{
See \code{\link[=power4test]{power4test()}} and
\code{\link[=n_region_from_power]{n_region_from_power()}} for full
details on how these functions
work.
}
