# Generate an artifact distribution object for use in artifact-distribution meta-analysis programs. 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. ```r 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. ## Returns Artifact distribution object (matrix of artifact-distribution means and variances) for use artifact-distribution meta-analyses. ## Examples ```r ## 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) ```

create_ad function