create_ad: Generate an artifact distribution object for use in...

In psychmeta: Psychometric Meta-Analysis Toolkit

Generate an artifact distribution object for use in artifact-distribution meta-analysis programs.

Description

This function generates artifact-distribution objects containing either interactive or Taylor series artifact distributions. Use this to create objects that can be supplied to the ma_r_ad and ma_r_ad functions to apply psychometric corrections to barebones meta-analysis objects via artifact distribution methods.

Allows consolidation of observed and estimated artifact information by cross-correcting artifact distributions and forming weighted artifact summaries.

For u ratios, error variances can be computed for independent samples (i.e., settings in which the unrestricted standard deviation comes from an external study) or dependent samples (i.e., settings in which the range-restricted standard deviation comes from a sample that represents a subset of the applicant sample that provided the unrestricted standard deviation). The former circumstance is presumed to be more common, so error variances are computed for independent samples by default.

Usage

create_ad(
  ad_type = c("tsa", "int"),
  rxxi = NULL,
  n_rxxi = NULL,
  wt_rxxi = n_rxxi,
  rxxi_type = rep("alpha", length(rxxi)),
  k_items_rxxi = rep(NA, length(rxxi)),
  rxxa = NULL,
  n_rxxa = NULL,
  wt_rxxa = n_rxxa,
  rxxa_type = rep("alpha", length(rxxa)),
  k_items_rxxa = rep(NA, length(rxxa)),
  ux = NULL,
  ni_ux = NULL,
  na_ux = NULL,
  wt_ux = ni_ux,
  dep_sds_ux_obs = rep(FALSE, length(ux)),
  ut = NULL,
  ni_ut = NULL,
  na_ut = NULL,
  wt_ut = ni_ut,
  dep_sds_ut_obs = rep(FALSE, length(ut)),
  mean_qxi = NULL,
  var_qxi = NULL,
  k_qxi = NULL,
  mean_n_qxi = NULL,
  qxi_dist_type = rep("alpha", length(mean_qxi)),
  mean_k_items_qxi = rep(NA, length(mean_qxi)),
  mean_rxxi = NULL,
  var_rxxi = NULL,
  k_rxxi = NULL,
  mean_n_rxxi = NULL,
  rxxi_dist_type = rep("alpha", length(mean_rxxi)),
  mean_k_items_rxxi = rep(NA, length(mean_rxxi)),
  mean_qxa = NULL,
  var_qxa = NULL,
  k_qxa = NULL,
  mean_n_qxa = NULL,
  qxa_dist_type = rep("alpha", length(mean_qxa)),
  mean_k_items_qxa = rep(NA, length(mean_qxa)),
  mean_rxxa = NULL,
  var_rxxa = NULL,
  k_rxxa = NULL,
  mean_n_rxxa = NULL,
  rxxa_dist_type = rep("alpha", length(mean_rxxa)),
  mean_k_items_rxxa = rep(NA, length(mean_rxxa)),
  mean_ux = NULL,
  var_ux = NULL,
  k_ux = NULL,
  mean_ni_ux = NULL,
  mean_na_ux = rep(NA, length(mean_ux)),
  dep_sds_ux_spec = rep(FALSE, length(mean_ux)),
  mean_ut = NULL,
  var_ut = NULL,
  k_ut = NULL,
  mean_ni_ut = NULL,
  mean_na_ut = rep(NA, length(mean_ut)),
  dep_sds_ut_spec = rep(FALSE, length(mean_ut)),
  estimate_rxxa = TRUE,
  estimate_rxxi = TRUE,
  estimate_ux = TRUE,
  estimate_ut = TRUE,
  var_unbiased = TRUE,
  ...
)

Arguments

ad_type	Type of artifact distribution to be computed: Either "tsa" for Taylor series approximation or "int" for interactive.
rxxi	Vector of incumbent reliability estimates.
n_rxxi	Vector of sample sizes associated with the elements of rxxi.
wt_rxxi	Vector of weights associated with the elements of rxxi (by default, sample sizes will be used as weights).
rxxi_type, rxxa_type, qxi_dist_type, rxxi_dist_type, qxa_dist_type, rxxa_dist_type	String vector identifying the types of reliability estimates supplied (e.g., "alpha", "retest", "interrater_r", "splithalf"). See the documentation for ma_r for a full list of acceptable reliability types.
k_items_rxxi, mean_k_items_qxi, mean_k_items_rxxi, k_items_rxxa, mean_k_items_qxa, mean_k_items_rxxa	Numeric vector of the number of items in each scale (or mean number of items, for pre-specified distributions).
rxxa	Vector of applicant reliability estimates.
n_rxxa	Vector of sample sizes associated with the elements of rxxa.
wt_rxxa	Vector of weights associated with the elements of rxxa (by default, sample sizes will be used as weights).
ux	Vector of observed-score u ratios.
ni_ux	Vector of incumbent sample sizes associated with the elements of ux.
na_ux	Vector of applicant sample sizes that can be used in estimating the sampling error of supplied ux values. NULL by default. Only used when ni_ux is not NULL. If supplied, must be either a scalar or the same length as ni_ux.
wt_ux	Vector of weights associated with the elements of ux (by default, sample sizes will be used as weights).
dep_sds_ux_obs	Logical scalar or vector determining whether supplied ux values were computed using dependent samples (TRUE) or independent samples (FALSE).
ut	Vector of true-score u ratios.
ni_ut	Vector of incumbent sample sizes associated with the elements of ut.
na_ut	Vector of applicant sample sizes that can be used in estimating the sampling error of supplied ut values. NULL by default. Only used when ni_ut is not NULL. If supplied, must be either a scalar or the same length as ni_ut.
wt_ut	Vector of weights associated with the elements of ut (by default, sample sizes will be used as weights).
dep_sds_ut_obs	Logical scalar or vector determining whether supplied ut values were computed using dependent samples (TRUE) or independent samples (FALSE).
mean_qxi	Vector that can be used to supply the means of externally computed distributions of incumbent square-root reliabilities.
var_qxi	Vector that can be used to supply the variances of externally computed distributions of incumbent square-root reliabilities.
k_qxi	Vector that can be used to supply the number of studies included in externally computed distributions of incumbent square-root reliabilities.
mean_n_qxi	Vector that can be used to supply the mean sample sizes of externally computed distributions of incumbent square-root reliabilities.
mean_rxxi	Vector that can be used to supply the means of externally computed distributions of incumbent reliabilities.
var_rxxi	Vector that can be used to supply the variances of externally computed distributions of incumbent reliabilities.
k_rxxi	Vector that can be used to supply the number of studies included in externally computed distributions of incumbent reliabilities.
mean_n_rxxi	Vector that can be used to supply the mean sample sizes of externally computed distributions of incumbent reliabilities.
mean_qxa	Vector that can be used to supply the means of externally computed distributions of applicant square-root reliabilities.
var_qxa	Vector that can be used to supply the variances of externally computed distributions of applicant square-root reliabilities.
k_qxa	Vector that can be used to supply the number of studies included in externally computed distributions of applicant square-root reliabilities.
mean_n_qxa	Vector that can be used to supply the mean sample sizes of externally computed distributions of applicant square-root reliabilities.
mean_rxxa	Vector that can be used to supply the means of externally computed distributions of applicant reliabilities.
var_rxxa	Vector that can be used to supply the variances of externally computed distributions of applicant reliabilities.
k_rxxa	Vector that can be used to supply the number of studies included in externally computed distributions of applicant reliabilities.
mean_n_rxxa	Vector that can be used to supply the mean sample sizes of externally computed distributions of applicant reliabilities.
mean_ux	Vector that can be used to supply the means of externally computed distributions of observed-score u ratios.
var_ux	Vector that can be used to supply the variances of externally computed distributions of observed-score u ratios.
k_ux	Vector that can be used to supply the number of studies included in externally computed distributions of observed-score u ratios.
mean_ni_ux	Vector that can be used to supply the mean incumbent sample sizes of externally computed distributions of observed-score u ratios.
mean_na_ux	Vector or scalar that can be used to supply the mean applicant sample size(s) of externally computed distributions of observed-score u ratios.
dep_sds_ux_spec	Logical scalar or vector determining whether externally computed ux distributions were computed using dependent samples (TRUE) or independent samples (FALSE).
mean_ut	Vector that can be used to supply the means of externally computed distributions of true-score u ratios.
var_ut	Vector that can be used to supply the variances of externally computed distributions of true-score u ratios.
k_ut	Vector that can be used to supply the number of studies included in externally computed distributions of true-score u ratios.
mean_ni_ut	Vector that can be used to supply the mean sample sizes for of externally computed distributions of true-score u ratios.
mean_na_ut	Vector or scalar that can be used to supply the mean applicant sample size(s) of externally computed distributions of true-score u ratios.
dep_sds_ut_spec	Logical scalar or vector determining whether externally computed ut distributions were computed using dependent samples (TRUE) or independent samples (FALSE).
estimate_rxxa	Logical argument to estimate rxxa values from other artifacts (TRUE) or to only used supplied rxxa values (FALSE). TRUE by default.
estimate_rxxi	Logical argument to estimate rxxi values from other artifacts (TRUE) or to only used supplied rxxi values (FALSE). TRUE by default.
estimate_ux	Logical argument to estimate ux values from other artifacts (TRUE) or to only used supplied ux values (FALSE). TRUE by default.
estimate_ut	Logical argument to estimate ut values from other artifacts (TRUE) or to only used supplied ut values (FALSE). TRUE by default.
var_unbiased	Logical scalar determining whether variance should be unbiased (TRUE) or maximum-likelihood (FALSE).
...	Further arguments.

Value

Artifact distribution object (matrix of artifact-distribution means and variances) for use artifact-distribution meta-analyses.

Examples

## Example computed using observed values only:
create_ad(ad_type = "tsa", rxxa = c(.9, .8), n_rxxa = c(50, 150),
              rxxi = c(.8, .7), n_rxxi = c(50, 150),
              ux = c(.9, .8), ni_ux = c(50, 150))

create_ad(ad_type = "int", rxxa = c(.9, .8), n_rxxa = c(50, 150),
              rxxi = c(.8, .7), n_rxxi = c(50, 150),
              ux = c(.9, .8), ni_ux = c(50, 150))

## Example computed using all possible input arguments (arbitrary values):
rxxa <- rxxi <- ux <- ut <- c(.7, .8)
n_rxxa <- n_rxxi <- ni_ux <- ni_ut <- c(50, 100)
na_ux <- na_ut <- c(200, 200)
mean_qxa <- mean_qxi <- mean_ux <- mean_ut <- mean_rxxi <- mean_rxxa <- c(.7, .8)
var_qxa <- var_qxi <- var_ux <- var_ut <- var_rxxi <- var_rxxa <- c(.1, .05)
k_qxa <- k_qxi <- k_ux <- k_ut <- k_rxxa <- k_rxxi <- 2
mean_n_qxa <- mean_n_qxi <- mean_ni_ux <- mean_ni_ut <- mean_n_rxxa <- mean_n_rxxi <- c(100, 100)
dep_sds_ux_obs <- dep_sds_ux_spec <- dep_sds_ut_obs <- dep_sds_ut_spec <- FALSE
mean_na_ux <- mean_na_ut <- c(200, 200)

wt_rxxa <- n_rxxa
wt_rxxi <- n_rxxi
wt_ux <- ni_ux
wt_ut <- ni_ut

estimate_rxxa <- TRUE
estimate_rxxi <- TRUE
estimate_ux <- TRUE
estimate_ut <- TRUE
var_unbiased <- TRUE

create_ad(rxxa = rxxa, n_rxxa = n_rxxa, wt_rxxa = wt_rxxa,
              mean_qxa = mean_qxa, var_qxa = var_qxa,
              k_qxa = k_qxa, mean_n_qxa = mean_n_qxa,
              mean_rxxa = mean_rxxa, var_rxxa = var_rxxa,
              k_rxxa = k_rxxa, mean_n_rxxa = mean_n_rxxa,

              rxxi = rxxi, n_rxxi = n_rxxi, wt_rxxi = wt_rxxi,
              mean_qxi = mean_qxi, var_qxi = var_qxi,
              k_qxi = k_qxi, mean_n_qxi = mean_n_qxi,
              mean_rxxi = mean_rxxi, var_rxxi = var_rxxi,
              k_rxxi = k_rxxi, mean_n_rxxi = mean_n_rxxi,

              ux = ux, ni_ux = ni_ux, na_ux = na_ux, wt_ux = wt_ux,
              dep_sds_ux_obs = dep_sds_ux_obs,
              mean_ux = mean_ux, var_ux = var_ux, k_ux =
               k_ux, mean_ni_ux = mean_ni_ux,
              mean_na_ux = mean_na_ux, dep_sds_ux_spec = dep_sds_ux_spec,

              ut = ut, ni_ut = ni_ut, na_ut = na_ut, wt_ut = wt_ut,
              dep_sds_ut_obs = dep_sds_ut_obs,
              mean_ut = mean_ut, var_ut = var_ut,
              k_ut = k_ut, mean_ni_ut = mean_ni_ut,
              mean_na_ut = mean_na_ut, dep_sds_ut_spec = dep_sds_ut_spec,

              estimate_rxxa = estimate_rxxa, estimate_rxxi = estimate_rxxi,
              estimate_ux = estimate_ux, estimate_ut = estimate_ut, var_unbiased = var_unbiased)

psychmeta documentation built on June 22, 2024, 6:52 p.m.