Merge pull request #35 from rcalinjageman/development

meta_ function tests and documentation

NAMESPACE

@@ -44,7 +44,6 @@ export(meta_mean)
 export(meta_pdiff_two)
 export(meta_proportion)
 export(meta_r)
-export(meta_smd_two)
 export(overview)
 export(overview_nominal)
 export(plot_correlation)

R/meta_any.R

@@ -5,7 +5,11 @@
 #' predicted sampling variance for each study.
 #'
 #'
-#' @details The meta-analytic effect size, confidence interval and heterogeneity
+#' @details
+#' #' Once you generate an estimate with this function, you can visualize
+#' it with [esci::plot_meta()].
+#'
+#' The meta-analytic effect size, confidence interval and heterogeneity
 #' estimates all come from [metafor::rma()].
 #'
 #' The diamond ratio and its confidence interval come from
@@ -37,49 +41,50 @@
 #'
 #' @returns An esci-estimate object; a list of data frames and properties.
 #' Returned tables include:
-#' * es_meta - A data frame with one overall.  If a moderator was
+#' * **es_meta** - A data frame of meta-analytic effect sizes.  If a moderator was
 #' defined, there is an additional row for each level of the moderator.
-#'   * effect_label -  Study label
-#'   * effect_size - Effect size
-#'   * LL - Lower bound of conf_level% confidence interval
-#'   * UL - Upper bound of conf_level% confidence interval
-#'   * SE - Expected standard error
-#'   * k - Number of studies
-#'   * diamond_ratio - ratio of random to fixed effects meta-analtics effect sizes
-#'   * diamond_ratio_LL - lower bound of conf_level% confidence interval for diamond ratio
-#'   * diamond_ratio_UL - upper bound of conf_level% confidence interval for diamond ratio
-#'   * I2 -  I2 measure of heterogeneity
-#'   * I2_LL - Lower bound of conf_level% confidence interval for I2
-#'   * I2_UL - upper bound of conf_level% confidence interval for I2
-#'   * PI_LL - lower bound of conf_level% of prediction interval
-#'   * PI_UL - upper bound of conf_level% of prediction interval
-#'   * p - p value for the meta-analytic effect size, based on null of exactly 0
-#'   * width - width of the effect-size confidence interval
-#'   * FE_effect_size - effect size of the fixed-effects model (regardless of if fixed effects was selected
-#'   * RE_effect_size - effect size of the random-effects model (regardless of if random effects was selected
-#'   * FE_CI_width - width of the fixed-effects confidence interval, used to calculate diamond ratio
-#'   * RE_CI_width - width of the fixed-effects confidence interval, used to calculate diamond ratio
-#' * es_heterogeneity - A data frame of of heterogeneity values and
+#'   * *effect_label* -  Study label
+#'   * *effect_size* - Effect size
+#'   * *LL* - Lower bound of conf_level% confidence interval
+#'   * *UL* - Upper bound of conf_level% confidence interval
+#'   * *SE* - Expected standard error
+#'   * *k* - Number of studies
+#'   * *diamond_ratio* - ratio of random to fixed effects meta-analtics effect sizes
+#'   * *diamond_ratio_LL* - lower bound of conf_level% confidence interval for diamond ratio
+#'   * *diamond_ratio_UL* - upper bound of conf_level% confidence interval for diamond ratio
+#'   * *I2* -  I2 measure of heterogeneity
+#'   * *I2_LL* - Lower bound of conf_level% confidence interval for I2
+#'   * *I2_UL* - upper bound of conf_level% confidence interval for I2
+#'   * *PI_LL* - lower bound of conf_level% of prediction interval
+#'   * *PI_UL* - upper bound of conf_level% of prediction interval
+#'   * *p* - p value for the meta-analytic effect size, based on null of exactly 0
+#'   * *width - width of the effect-size confidence interval
+#'   * *FE_effect_size* - effect size of the fixed-effects model (regardless of if fixed effects was selected
+#'   * *RE_effect_size* - effect size of the random-effects model (regardless of if random effects was selected
+#'   * *FE_CI_width* - width of the fixed-effects confidence interval, used to calculate diamond ratio
+#'   * *RE_CI_width* - width of the fixed-effects confidence interval, used to calculate diamond ratio
+#' * **es_heterogeneity** - A data frame of of heterogeneity values and
 #' conf_level% CIs for the meta-analytic effect size.  If a moderator was defined
 #' also reports heterogeneity estimates for each level of the moderator.
-#'   * effect_label - study label
-#'   * moderator_variable_name - if moderator passed, gives name of the moderator
-#'   * moderator_variable_name - 'Overall' and each level of moderator, if passed
-#'   * measure - Name of the measure of heterogeneity
-#'   * LL - lower bound of conf_level% confidence interval
-#'   * UL - upper bound of conf_level% confidence interval
-#' * raw_data - A data from with one row for each study that was passed
-#'   * label - study label
-#'   * effect_size - effect size
-#'   * weight - study weight in the meta analysis
-#'   * sample_variance - expected level of sampling variation
-#'   * SE - expected standard error
-#'   * LL - lower bound of conf_level% confidence interval
-#'   * UL - upper bound of conf_level% confidence interval
-#'   * mean - used to calculate study p value; this is the d value entered for the study
-#'   * n - study sample size
-#'   * sd - use to calculate study p value; set to 1 for each study
-#'   * p - p value for the study, based on null of exactly 0
+#'   * *effect_label* - study label
+#'   * *moderator_variable_name* - if moderator passed, gives name of the moderator
+#'   * *moderator_level* - 'Overall' and each level of moderator, if passed
+#'   * *measure* - Name of the measure of heterogeneity
+#'   * *estimate* - Value of the heterogeneity estimate
+#'   * *LL* - lower bound of conf_level% confidence interval
+#'   * *UL* - upper bound of conf_level% confidence interval
+#' * **raw_data** - A data from with one row for each study that was passed
+#'   * *label* - study label
+#'   * *effect_size* - effect size
+#'   * *weight* - study weight in the meta analysis
+#'   * *sample_variance* - expected level of sampling variation
+#'   * *SE* - expected standard error
+#'   * *LL* - lower bound of conf_level% confidence interval
+#'   * *UL* - upper bound of conf_level% confidence interval
+#'   * *mean* - used to calculate study p value; this is the d value entered for the study
+#'   * *sd* - use to calculate study p value; set to 1 for each study
+#'   * *n* - study sample size
+#'   * *p* - p value for the study, based on null of exactly 0
 #'
 #' @export
 meta_any <- function(

R/meta_d1.R

@@ -5,6 +5,9 @@
 #' outcome is not measured on the same scale in all studies
 #'
 #' @details
+#' Once you generate an estimate with this function, you can visualize
+#' it with [esci::plot_meta()].
+#'
 #' Each study's effect size should be expressed as Cohen's
 #' d1: (mean - reference) / sd.
 #'
@@ -38,6 +41,91 @@
 #'
 #' @inherit meta_any return
 #'
+#' @examples
+#' # example code
+#'   original_7 <- data.frame(
+#' study_name = c(
+#'   "Aden (1993)"	,
+#'   "Buggs (1995)"	,
+#'   "Crazed (1999)"	,
+#'   "Dudley (2003)"	,
+#'   "Evers (2005)"	,
+#'   "Fox (2009)",
+#'   "Mine (2011)"
+#' ),
+#' rt_mean = c(
+#'   454	,
+#'   317	,
+#'   430	,
+#'   525	,
+#'   479	,
+#'   387,
+#'   531
+#' ),
+#' rt_sd = c(
+#'   142	,
+#'   158	,
+#'   137	,
+#'   260	,
+#'   144	,
+#'   165,
+#'   233
+#' ),
+#' rt_n = c(
+#'   24	,
+#'   7	,
+#'   20	,
+#'   8	,
+#'  14	,
+#'  13,
+#'   18
+#' ),
+#' subset = as.factor(
+#'   c(
+#'     "90s",
+#'    "90s",
+#'     "90s",
+#'     "00s",
+#'     "00s",
+#'     "00s",
+#'     "00s"
+#'   )
+#' ),
+#' d1_unbiased = c(
+#'   3.091587,
+#'   1.742751,
+#'   3.012857,
+#'   1.793487,
+#'   3.130074,
+#'   2.195209,
+#'   2.17667
+#' )
+#' )
+#'
+#'
+#' # Fixed effect, 95% CI
+#' estimate <- esci::meta_d1(
+#'   original_7,
+#'   d1_unbiased,
+#'   rt_n,
+#'   study_name,
+#'   random_effects = FALSE
+#' )
+#'
+#' estimate <- esci::meta_d1(
+#'   data = original_7,
+#'   ds = d1_unbiased,
+#'   ns = rt_n,
+#'   moderator = subset,
+#'   labels = study_name,
+#'   random_effects = FALSE
+#' )
+#'
+#' \dontrun{
+#' # Forest plot
+#' esci::plot_meta(estimate)
+#' }
+#'
 #'
 #' @export
 meta_d1 <- function(

R/meta_d2.R

@@ -1,25 +1,107 @@
-#' Estimate meta-analytic difference in magnitude between two ind. groups
+#' Estimate meta-analytic standardized mean difference across multiple
+#' two group studies (all paired, all independent, or a mix).
 #'
 #' @description
-#' `meta_d2` returns
+#' `meta_d2` is suitable for synthesizing across multiple two-group studies
+#' (paired or independent) with a continuous outcome measure but where not
+#' all studies are measured on the same scale, and instead the magnitude of
+#' difference for each study is expressed as d_s or d_avg.
+#'
+#'
+#' @details
+#' @details
+#' Once you generate an estimate with this function, you can visualize
+#' it with [esci::plot_meta()].
+#'
+#'
+#' Each study's effect size should be expressed as:
+#'   Cohen's d_s: (comparison_mean - reference_mean) / sd_pooled
+#' or
+#'   Cohen_'s d_avg: (comparison_mean - reference_mean) / sd_avg
+#'
+#' To enter d_s, set assume_equal_variance to TRUE
+#' To enter d_avg, set assume_equal_variance to FALSE
+#'
+#' And the d values should all be corrected for bias.
+#' The function [esci::CI_smd_ind_contrast()] can assist with converting
+#' raw data from each study to d_s or d_avg with bias correction.  It als
+#' has more details on calculation of these forms of d and their CIs.
+#'
+#'
+#' The meta-analytic effect size, confidence interval and heterogeneity
+#' estimates all come from [metafor::rma()].
+#'
+#' The diamond ratio and its confidence interval come from
+#' [esci::CI_diamond_ratio()].
 #'
 #'
 #' @param data A data frame or tibble
-#' @param ds comparison
-#' @param comparison_ns comparison
-#' @param reference_ns reference
+#' @param ds Set of bias-adjusted cohen's d_s or d_avg values, 1 for each study
+#' @param comparison_ns Set of comparison_group sample sizes, positive integers,
+#'   1 for each study
+#' @param reference_ns Set of reference_groups sample sizes, positive integers,
+#'   1 for each study
 #' @param r optional correlation between measures for w-s studies, NA otherwise
-#' @param labels labels
-#' @param moderator mod
-#' @param contrast contrast
-#' @param effect_label el
-#' @param random_effects re
-#' @param assume_equal_variance aev
+#' @param labels Optional set of labels, 1 for each study
+#' @param moderator Optional factor as a categorical moderator; should have k >
+#'   2 per group
+#' @param contrast Optional vector specifying a contrast between moderator
+#'   levels
+#' @param effect_label Optional character providing a human-friendly label for
+#'   the effect
+#' @param random_effects Boolean; TRUE for a random effects model; otherwise
+#'   fixed effects
+#' @param assume_equal_variance Defaults to FALSE
 #' @param conf_level The confidence level for the confidence interval.  Given in
 #'   decimal form.  Defaults to 0.95.
 #'
-#' @return Returnsobject of class esci_estimate
 #'
+#' @inherit meta_any return
+#'
+#'
+#' @examples
+#' # Data set -- see Introduction to the New Statistics, 1st edition
+#' lucky_golf <- data.frame(
+#'   study = c(paste("Damisch", seq(1:6)), "Calin 1", "Calin 2"),
+#'   my_smd = c(0.83, 0.986, 0.66, 0.78, 0.979, 0.86, 0.05, 0.047),
+#'   smd_corrected = c(0.806, 0.963, 0.647, 0.758, 0.950, 0.835, 0.050, 0.047),
+#'   n1 = c(14, 17, 20, 15, 14, 14, 58, 54),
+#'   n2 = c(14, 17, 21, 14, 14, 14, 66, 57),
+#'   subset = as.factor(c(rep("Germany", times = 6), rep("USA", times = 2)))
+#' )
+#'
+#' # Meta-analysis, random effects, assuming equal variance, no moderator
+#' estimate <- esci::meta_d2(
+#'   data = lucky_golf,
+#'   ds = smd_corrected,
+#'   comparison_ns = n1,
+#'   reference_ns = n2,
+#'   labels = study,
+#'   assume_equal_variance = TRUE,
+#'   random_effects = TRUE
+#' )
+#'
+#' \dontrun{
+#' # Forest plot
+#' esci::plot_meta(estimate)
+#' }
+#'
+#' # Meta-analysis, random effects, assuming equal variance
+#' estimate <- esci::meta_d2(
+#'   data = lucky_golf,
+#'   ds = smd_corrected,
+#'   comparison_ns = n1,
+#'   reference_ns = n2,
+#'   moderator = subset,
+#'   labels = study,
+#'   assume_equal_variance = TRUE,
+#'   random_effects = TRUE
+#' )
+#'
+#' \dontrun{
+#' # Forest plot
+#' esci::plot_meta(estimate)
+#' }
 #'
 #' @export
 meta_d2 <- function(
@@ -32,7 +114,7 @@ meta_d2 <- function(
   moderator = NULL,
   contrast = NULL,
   effect_label = "My effect",
-  assume_equal_variance = TRUE,
+  assume_equal_variance = FALSE,
   random_effects = TRUE,
   conf_level = .95
 )  {