Nothing
R/control_psychmeta.R
In psychmeta: Psychometric Meta-Analysis Toolkit
Defines functions
control_psychmeta
Documented in
control_psychmeta
#' Control for \pkg{psychmeta} meta-analyses
#'
#' @param error_type Method to be used to estimate error variances: "mean" uses the mean effect size to estimate error variances and "sample" uses the sample-specific effect sizes.
#' @param conf_level Confidence level to define the width of the confidence interval (default = .95).
#' @param cred_level Credibility level to define the width of the credibility interval (default = .80).
#' @param conf_method Distribution to be used to compute the width of confidence intervals. Available options are "t" for \emph{t} distribution or "norm" for normal distribution.
#' @param cred_method Distribution to be used to compute the width of credibility intervals. Available options are "t" for \emph{t} distribution or "norm" for normal distribution.
#' @param var_unbiased Logical scalar determining whether variances should be unbiased (\code{TRUE}) or maximum-likelihood (\code{FALSE}).
#' @param pairwise_ads Logical value that determines whether to compute artifact distributions in a construct-pair-wise fashion (\code{TRUE}) or separately by construct (\code{FALSE}, default).
#' @param moderated_ads Logical value that determines whether to compute artifact distributions separately for each moderator combination (\code{TRUE}) or for overall analyses only (\code{FALSE}, default).
#' @param residual_ads Logical argument that determines whether to use residualized variances (\code{TRUE}) or observed variances (\code{FALSE}) of artifact distributions to estimate \code{sd_rho}.
#' @param check_dependence Logical scalar that determines whether database should be checked for violations of independence (\code{TRUE}) or not (\code{FALSE}).
#' @param collapse_method Character argument that determines how to collapse dependent studies. Options are "composite" (default), "average," and "stop."
#' @param intercor The intercorrelation(s) among variables to be combined into a composite. Can be a scalar, a named vector with element named according to the names of constructs, or output from the \code{control_intercor} function. Default scalar value is .5.
#' @param clean_artifacts If \code{TRUE}, multiple instances of the same construct (or construct-measure pair, if measure is provided) in the database are compared and reconciled with each other
#' in the case that any of the matching entries within a study have different artifact values. When impute_method is anything other than "stop", this method is always implemented to prevent discrepancies among imputed values.
#' @param impute_artifacts If \code{TRUE}, artifact imputation will be performed (see \code{impute_method} for imputation procedures). Default is \code{FALSE} for artifact-distribution meta-analyses and \code{TRUE} otherwise.
#' When imputation is performed, \code{clean_artifacts} is treated as \code{TRUE} so as to resolve all discrepancies among artifact entries before and after imputation.
#' @param impute_method Method to use for imputing artifacts. Choices are:
#' \itemize{
#' \item{bootstrap_mod}{\cr Select random values from the most specific moderator categories available (default).}
#' \item{bootstrap_full}{\cr Select random values from the full vector of artifacts.}
#' \item{simulate_mod}{\cr Generate random values from the distribution with the mean and variance of observed artifacts from the most specific moderator categories available.
#' (uses \code{rnorm} for u ratios and \code{rbeta} for reliability values).}
#' \item{simulate_full}{\cr Generate random values from the distribution with the mean and variance of all observed artifacts (uses \code{rnorm} for u ratios and \code{rbeta} for reliability values).}
#' \item{wt_mean_mod}{\cr Replace missing values with the sample-size weighted mean of the distribution of artifacts from the most specific moderator categories available (not recommended).}
#' \item{wt_mean_full}{\cr Replace missing values with the sample-size weighted mean of the full distribution of artifacts (not recommended).}
#' \item{unwt_mean_mod}{\cr Replace missing values with the unweighted mean of the distribution of artifacts from the most specific moderator categories available (not recommended).}
#' \item{unwt_mean_full}{\cr Replace missing values with the unweighted mean of the full distribution of artifacts (not recommended).}
#' \item{replace_unity}{\cr Replace missing values with 1 (not recommended).}
#' \item{stop}{\cr Stop evaluations when missing artifacts are encountered.}
#' }
#' If an imputation method ending in "mod" is selected but no moderators are provided, the "mod" suffix will internally be replaced with "full".
#' @param seed Seed value to use for imputing artifacts in a reproducible way. Default value is 42.
#' @param use_all_arts Logical scalar that determines whether artifact values from studies without valid effect sizes should be used in artifact distributions (\code{TRUE}; default) or not (\code{FALSE}).
#' @param estimate_pa Logical scalar that determines whether the unrestricted subgroup proportions associated with univariate-range-restricted effect sizes should be estimated by rescaling the range-restricted subgroup proportions as a function of the range-restriction correction (\code{TRUE}) or not (\code{FALSE}; default).
#' @param decimals Number of decimal places to which interactive artifact distributions should be rounded (default is 2 decimal places).
#' @param hs_override When \code{TRUE}, this will override settings for \code{wt_type} (will set to "sample_size"),
#' \code{error_type} (will set to "mean"),
#' \code{correct_bias} (will set to \code{TRUE}),
#' \code{conf_method} (will set to "norm"),
#' \code{cred_method} (will set to "norm"),
#' \code{var_unbiased} (will set to \code{FALSE}),
#' \code{residual_ads} (will be set to \code{FALSE}),
#' and \code{use_all_arts} (will set to \code{FALSE}).
#' @param zero_substitute Value to be used as a functionally equivalent substitute for exactly zero effect sizes in individual-correction meta-analyses to facilitate the estimation of corrected error variances. By default, this is set to \code{.Machine$double.eps}.
#' @param ... Further arguments to be passed to functions called within the meta-analysis.
#'
#' @return A list of control arguments in the package environment.
#' @export
#'
#' @examples
#' control_psychmeta()
control_psychmeta <- function(error_type = c("mean", "sample"),
conf_level = .95,
cred_level = .8,
conf_method = c("t", "norm"),
cred_method = c("t", "norm"),
var_unbiased = TRUE,
pairwise_ads = FALSE,
moderated_ads = FALSE,
residual_ads = TRUE,
check_dependence = TRUE,
collapse_method = c("composite", "average", "stop"),
intercor = control_intercor(),
clean_artifacts = TRUE,
impute_artifacts = TRUE,
impute_method = c("bootstrap_mod", "bootstrap_full",
"simulate_mod", "simulate_full",
"wt_mean_mod", "wt_mean_full",
"unwt_mean_mod", "unwt_mean_full",
"replace_unity", "stop"),
seed = 42,
use_all_arts = TRUE,
estimate_pa = FALSE,
decimals = 2,
hs_override = FALSE,
zero_substitute = .Machine$double.eps,
...){
control <- list(error_type = error_type,
conf_level = conf_level,
cred_level = cred_level,
conf_method = conf_method,
cred_method = cred_method,
var_unbiased = var_unbiased,
pairwise_ads = pairwise_ads,
moderated_ads = moderated_ads,
residual_ads = residual_ads,
check_dependence = check_dependence,
collapse_method = collapse_method,
intercor = intercor,
clean_artifacts = clean_artifacts,
impute_artifacts = impute_artifacts,
impute_method = impute_method,
seed = seed,
use_all_arts = use_all_arts,
estimate_pa = estimate_pa,
decimals = decimals,
hs_override = hs_override,
zero_substitute = zero_substitute)
additional_args <- list(...)
.psychmeta_ellipse_args <- additional_args$.psychmeta_ellipse_args
.control_psychmeta_arg <- additional_args$.control_psychmeta_arg
rm(additional_args)
if(length(.control_psychmeta_arg) > 0)
.control_psychmeta_arg <- .control_psychmeta_arg[names(.control_psychmeta_arg) != ""]
if(length(.control_psychmeta_arg) > 0)
.control_psychmeta_arg <- .control_psychmeta_arg[names(.control_psychmeta_arg) %in% names(control)]
if(length(.control_psychmeta_arg) > 0)
for(i in names(.control_psychmeta_arg)) control[[i]] <- .control_psychmeta_arg[[i]]
if(length(.psychmeta_ellipse_args) > 0)
.psychmeta_ellipse_args <- .psychmeta_ellipse_args[names(.psychmeta_ellipse_args) != ""]
if(length(.psychmeta_ellipse_args) > 0)
.psychmeta_ellipse_args <- .psychmeta_ellipse_args[names(.psychmeta_ellipse_args) %in% names(control)]
if(length(.psychmeta_ellipse_args) > 0)
for(i in names(.psychmeta_ellipse_args)) control[[i]] <- .psychmeta_ellipse_args[[i]]
control$error_type <- match.arg(control$error_type, c("mean", "sample"))
control$conf_level <- interval_warning(interval = control$conf_level, interval_name = "conf_level", default = .95)
if(!is.numeric(control$conf_level)) stop("'conf_level' must be numeric", call. = FALSE)
control$cred_level <- interval_warning(interval = control$cred_level, interval_name = "cred_level", default = .8)
if(!is.numeric(control$cred_level)) stop("'cred_level' must be numeric", call. = FALSE)
control$conf_method <- match.arg(control$conf_method, choices = c("t", "norm"))
control$cred_method <- match.arg(control$cred_method, choices = c("t", "norm"))
control$var_unbiased <- scalar_arg_warning(arg = control$var_unbiased, arg_name = "var_unbiased")
if(!is.logical(control$var_unbiased)) stop("'var_unbiased' must be logical", call. = FALSE)
control$pairwise_ads <- scalar_arg_warning(arg = control$pairwise_ads, arg_name = "pairwise_ads")
if(!is.logical(control$pairwise_ads)) stop("'pairwise_ads' must be logical", call. = FALSE)
control$moderated_ads <- scalar_arg_warning(arg = control$moderated_ads, arg_name = "moderated_ads")
if(!is.logical(control$moderated_ads)) stop("'moderated_ads' must be logical", call. = FALSE)
control$residual_ads <- scalar_arg_warning(arg = control$residual_ads, arg_name = "residual_ads")
if(!is.logical(control$residual_ads)) stop("'residual_ads' must be logical", call. = FALSE)
control$check_dependence <- scalar_arg_warning(control$check_dependence, arg_name = "check_dependence")
control$collapse_method <- match.arg(control$collapse_method, c("composite", "average", "stop"))
control$clean_artifacts <- scalar_arg_warning(arg = control$clean_artifacts, arg_name = "clean_artifacts")
if(!is.logical(control$clean_artifacts)) stop("'clean_artifacts' must be logical", call. = FALSE)
control$impute_artifacts <- scalar_arg_warning(arg = control$impute_artifacts, arg_name = "impute_artifacts")
if(!is.logical(control$impute_artifacts)) stop("'impute_artifacts' must be logical", call. = FALSE)
control$impute_method <- match.arg(control$impute_method, c("bootstrap_mod", "bootstrap_full",
"simulate_mod", "simulate_full",
"wt_mean_mod", "wt_mean_full",
"unwt_mean_mod", "unwt_mean_full",
"replace_unity", "stop"))
if(!is.numeric(control$seed)) stop("'seed' must be numeric", call. = FALSE)
if(any(is.na(seed))) seed <- NULL
if(length(seed) == 0) seed <- NULL
control$decimals <- scalar_arg_warning(arg = control$decimals, arg_name = "decimals")
if(!is.numeric(control$decimals)) stop("'decimals' must be numeric", call. = FALSE)
control$hs_override <- scalar_arg_warning(arg = control$hs_override, arg_name = "hs_override")
if(!is.logical(control$hs_override)) stop("'hs_override' must be logical", call. = FALSE)
control$use_all_arts <- scalar_arg_warning(arg = control$use_all_arts, arg_name = "use_all_arts")
if(!is.logical(control$use_all_arts)) stop("'use_all_arts' must be logical", call. = FALSE)
control$estimate_pa <- scalar_arg_warning(arg = control$estimate_pa, arg_name = "estimate_pa")
if(!is.logical(control$estimate_pa)) stop("'estimate_pa' must be logical", call. = FALSE)
control$zero_substitute <- scalar_arg_warning(arg = control$zero_substitute, arg_name = "zero_substitute")
if(!is.numeric(control$zero_substitute)) stop("'zero_substitute' must be numeric", call. = FALSE)
control
}
Try the psychmeta package in your browser
Any scripts or data that you put into this service are public.
psychmeta documentation built on Aug. 26, 2022, 5:14 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Defines functions control_psychmeta
Documented in control_psychmeta
#' Control for \pkg{psychmeta} meta-analyses
#'
#' @param error_type Method to be used to estimate error variances: "mean" uses the mean effect size to estimate error variances and "sample" uses the sample-specific effect sizes.
#' @param conf_level Confidence level to define the width of the confidence interval (default = .95).
#' @param cred_level Credibility level to define the width of the credibility interval (default = .80).
#' @param conf_method Distribution to be used to compute the width of confidence intervals. Available options are "t" for \emph{t} distribution or "norm" for normal distribution.
#' @param cred_method Distribution to be used to compute the width of credibility intervals. Available options are "t" for \emph{t} distribution or "norm" for normal distribution.
#' @param var_unbiased Logical scalar determining whether variances should be unbiased (\code{TRUE}) or maximum-likelihood (\code{FALSE}).
#' @param pairwise_ads Logical value that determines whether to compute artifact distributions in a construct-pair-wise fashion (\code{TRUE}) or separately by construct (\code{FALSE}, default).
#' @param moderated_ads Logical value that determines whether to compute artifact distributions separately for each moderator combination (\code{TRUE}) or for overall analyses only (\code{FALSE}, default).
#' @param residual_ads Logical argument that determines whether to use residualized variances (\code{TRUE}) or observed variances (\code{FALSE}) of artifact distributions to estimate \code{sd_rho}.
#' @param check_dependence Logical scalar that determines whether database should be checked for violations of independence (\code{TRUE}) or not (\code{FALSE}).
#' @param collapse_method Character argument that determines how to collapse dependent studies. Options are "composite" (default), "average," and "stop."
#' @param intercor The intercorrelation(s) among variables to be combined into a composite. Can be a scalar, a named vector with element named according to the names of constructs, or output from the \code{control_intercor} function. Default scalar value is .5.
#' @param clean_artifacts If \code{TRUE}, multiple instances of the same construct (or construct-measure pair, if measure is provided) in the database are compared and reconciled with each other
#' in the case that any of the matching entries within a study have different artifact values. When impute_method is anything other than "stop", this method is always implemented to prevent discrepancies among imputed values.
#' @param impute_artifacts If \code{TRUE}, artifact imputation will be performed (see \code{impute_method} for imputation procedures). Default is \code{FALSE} for artifact-distribution meta-analyses and \code{TRUE} otherwise.
#' When imputation is performed, \code{clean_artifacts} is treated as \code{TRUE} so as to resolve all discrepancies among artifact entries before and after imputation.
#' @param impute_method Method to use for imputing artifacts. Choices are:
#' \itemize{
#' \item{bootstrap_mod}{\cr Select random values from the most specific moderator categories available (default).}
#' \item{bootstrap_full}{\cr Select random values from the full vector of artifacts.}
#' \item{simulate_mod}{\cr Generate random values from the distribution with the mean and variance of observed artifacts from the most specific moderator categories available.
#' (uses \code{rnorm} for u ratios and \code{rbeta} for reliability values).}
#' \item{simulate_full}{\cr Generate random values from the distribution with the mean and variance of all observed artifacts (uses \code{rnorm} for u ratios and \code{rbeta} for reliability values).}
#' \item{wt_mean_mod}{\cr Replace missing values with the sample-size weighted mean of the distribution of artifacts from the most specific moderator categories available (not recommended).}
#' \item{wt_mean_full}{\cr Replace missing values with the sample-size weighted mean of the full distribution of artifacts (not recommended).}
#' \item{unwt_mean_mod}{\cr Replace missing values with the unweighted mean of the distribution of artifacts from the most specific moderator categories available (not recommended).}
#' \item{unwt_mean_full}{\cr Replace missing values with the unweighted mean of the full distribution of artifacts (not recommended).}
#' \item{replace_unity}{\cr Replace missing values with 1 (not recommended).}
#' \item{stop}{\cr Stop evaluations when missing artifacts are encountered.}
#' }
#' If an imputation method ending in "mod" is selected but no moderators are provided, the "mod" suffix will internally be replaced with "full".
#' @param seed Seed value to use for imputing artifacts in a reproducible way. Default value is 42.
#' @param use_all_arts Logical scalar that determines whether artifact values from studies without valid effect sizes should be used in artifact distributions (\code{TRUE}; default) or not (\code{FALSE}).
#' @param estimate_pa Logical scalar that determines whether the unrestricted subgroup proportions associated with univariate-range-restricted effect sizes should be estimated by rescaling the range-restricted subgroup proportions as a function of the range-restriction correction (\code{TRUE}) or not (\code{FALSE}; default).
#' @param decimals Number of decimal places to which interactive artifact distributions should be rounded (default is 2 decimal places).
#' @param hs_override When \code{TRUE}, this will override settings for \code{wt_type} (will set to "sample_size"),
#' \code{error_type} (will set to "mean"),
#' \code{correct_bias} (will set to \code{TRUE}),
#' \code{conf_method} (will set to "norm"),
#' \code{cred_method} (will set to "norm"),
#' \code{var_unbiased} (will set to \code{FALSE}),
#' \code{residual_ads} (will be set to \code{FALSE}),
#' and \code{use_all_arts} (will set to \code{FALSE}).
#' @param zero_substitute Value to be used as a functionally equivalent substitute for exactly zero effect sizes in individual-correction meta-analyses to facilitate the estimation of corrected error variances. By default, this is set to \code{.Machine$double.eps}.
#' @param ... Further arguments to be passed to functions called within the meta-analysis.
#'
#' @return A list of control arguments in the package environment.
#' @export
#'
#' @examples
#' control_psychmeta()
control_psychmeta <- function(error_type = c("mean", "sample"),
conf_level = .95,
cred_level = .8,
conf_method = c("t", "norm"),
cred_method = c("t", "norm"),
var_unbiased = TRUE,
pairwise_ads = FALSE,
moderated_ads = FALSE,
residual_ads = TRUE,
check_dependence = TRUE,
collapse_method = c("composite", "average", "stop"),
intercor = control_intercor(),
clean_artifacts = TRUE,
impute_artifacts = TRUE,
impute_method = c("bootstrap_mod", "bootstrap_full",
"simulate_mod", "simulate_full",
"wt_mean_mod", "wt_mean_full",
"unwt_mean_mod", "unwt_mean_full",
"replace_unity", "stop"),
seed = 42,
use_all_arts = TRUE,
estimate_pa = FALSE,
decimals = 2,
hs_override = FALSE,
zero_substitute = .Machine$double.eps,
...){
control <- list(error_type = error_type,
conf_level = conf_level,
cred_level = cred_level,
conf_method = conf_method,
cred_method = cred_method,
var_unbiased = var_unbiased,
pairwise_ads = pairwise_ads,
moderated_ads = moderated_ads,
residual_ads = residual_ads,
check_dependence = check_dependence,
collapse_method = collapse_method,
intercor = intercor,
clean_artifacts = clean_artifacts,
impute_artifacts = impute_artifacts,
impute_method = impute_method,
seed = seed,
use_all_arts = use_all_arts,
estimate_pa = estimate_pa,
decimals = decimals,
hs_override = hs_override,
zero_substitute = zero_substitute)
additional_args <- list(...)
.psychmeta_ellipse_args <- additional_args$.psychmeta_ellipse_args
.control_psychmeta_arg <- additional_args$.control_psychmeta_arg
rm(additional_args)
if(length(.control_psychmeta_arg) > 0)
.control_psychmeta_arg <- .control_psychmeta_arg[names(.control_psychmeta_arg) != ""]
if(length(.control_psychmeta_arg) > 0)
.control_psychmeta_arg <- .control_psychmeta_arg[names(.control_psychmeta_arg) %in% names(control)]
if(length(.control_psychmeta_arg) > 0)
for(i in names(.control_psychmeta_arg)) control[[i]] <- .control_psychmeta_arg[[i]]
if(length(.psychmeta_ellipse_args) > 0)
.psychmeta_ellipse_args <- .psychmeta_ellipse_args[names(.psychmeta_ellipse_args) != ""]
if(length(.psychmeta_ellipse_args) > 0)
.psychmeta_ellipse_args <- .psychmeta_ellipse_args[names(.psychmeta_ellipse_args) %in% names(control)]
if(length(.psychmeta_ellipse_args) > 0)
for(i in names(.psychmeta_ellipse_args)) control[[i]] <- .psychmeta_ellipse_args[[i]]
control$error_type <- match.arg(control$error_type, c("mean", "sample"))
control$conf_level <- interval_warning(interval = control$conf_level, interval_name = "conf_level", default = .95)
if(!is.numeric(control$conf_level)) stop("'conf_level' must be numeric", call. = FALSE)
control$cred_level <- interval_warning(interval = control$cred_level, interval_name = "cred_level", default = .8)
if(!is.numeric(control$cred_level)) stop("'cred_level' must be numeric", call. = FALSE)
control$conf_method <- match.arg(control$conf_method, choices = c("t", "norm"))
control$cred_method <- match.arg(control$cred_method, choices = c("t", "norm"))
control$var_unbiased <- scalar_arg_warning(arg = control$var_unbiased, arg_name = "var_unbiased")
if(!is.logical(control$var_unbiased)) stop("'var_unbiased' must be logical", call. = FALSE)
control$pairwise_ads <- scalar_arg_warning(arg = control$pairwise_ads, arg_name = "pairwise_ads")
if(!is.logical(control$pairwise_ads)) stop("'pairwise_ads' must be logical", call. = FALSE)
control$moderated_ads <- scalar_arg_warning(arg = control$moderated_ads, arg_name = "moderated_ads")
if(!is.logical(control$moderated_ads)) stop("'moderated_ads' must be logical", call. = FALSE)
control$residual_ads <- scalar_arg_warning(arg = control$residual_ads, arg_name = "residual_ads")
if(!is.logical(control$residual_ads)) stop("'residual_ads' must be logical", call. = FALSE)
control$check_dependence <- scalar_arg_warning(control$check_dependence, arg_name = "check_dependence")
control$collapse_method <- match.arg(control$collapse_method, c("composite", "average", "stop"))
control$clean_artifacts <- scalar_arg_warning(arg = control$clean_artifacts, arg_name = "clean_artifacts")
if(!is.logical(control$clean_artifacts)) stop("'clean_artifacts' must be logical", call. = FALSE)
control$impute_artifacts <- scalar_arg_warning(arg = control$impute_artifacts, arg_name = "impute_artifacts")
if(!is.logical(control$impute_artifacts)) stop("'impute_artifacts' must be logical", call. = FALSE)
control$impute_method <- match.arg(control$impute_method, c("bootstrap_mod", "bootstrap_full",
"simulate_mod", "simulate_full",
"wt_mean_mod", "wt_mean_full",
"unwt_mean_mod", "unwt_mean_full",
"replace_unity", "stop"))
if(!is.numeric(control$seed)) stop("'seed' must be numeric", call. = FALSE)
if(any(is.na(seed))) seed <- NULL
if(length(seed) == 0) seed <- NULL
control$decimals <- scalar_arg_warning(arg = control$decimals, arg_name = "decimals")
if(!is.numeric(control$decimals)) stop("'decimals' must be numeric", call. = FALSE)
control$hs_override <- scalar_arg_warning(arg = control$hs_override, arg_name = "hs_override")
if(!is.logical(control$hs_override)) stop("'hs_override' must be logical", call. = FALSE)
control$use_all_arts <- scalar_arg_warning(arg = control$use_all_arts, arg_name = "use_all_arts")
if(!is.logical(control$use_all_arts)) stop("'use_all_arts' must be logical", call. = FALSE)
control$estimate_pa <- scalar_arg_warning(arg = control$estimate_pa, arg_name = "estimate_pa")
if(!is.logical(control$estimate_pa)) stop("'estimate_pa' must be logical", call. = FALSE)
control$zero_substitute <- scalar_arg_warning(arg = control$zero_substitute, arg_name = "zero_substitute")
if(!is.numeric(control$zero_substitute)) stop("'zero_substitute' must be numeric", call. = FALSE)
control
}
Try the psychmeta package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.