confMeta: Creating _confMeta_ objects

In felix-hof/hMean: Confidence Curves and P-Value Functions for Meta-Analysis

Creating confMeta objects

Description

Function to create objects of class confMeta. This is the main class within the package. For an overview of available methods run methods(confMeta).

Usage

confMeta(
  estimates,
  SEs,
  study_names = NULL,
  conf_level = 0.95,
  fun,
  fun_name = NULL,
  ...
)

Arguments

estimates	A vector containing the normalized individual effect estimates. Must be of the same length as SEs and coercible to type 'double'.
SEs	The standard errors of the normalized individual effect estimates. Must be of the same length as estimates and coercible to type 'double'.
study_names	Either NULL (the default) or a vector that can be coerced to type 'character'. Must be of the same length as arguments estimates and SEs. The vector is used to differentiate the individual studies. For more information, check out the Details section.
conf_level	The confidence level. Must be a numeric vector of length one with it's value being in (0, 1).
fun	A function that combines individual effect estimates and the corresponding standard errors into a combined p-value. The function must have arguments named 'estimates', 'SEs', and 'mu'. Additional arguments are also allowed, but these must either have a default value or be passed via the ... argument. For more information, see the Details section.
fun_name	A character vector of length 1. The vector serves as an identifier for the function fun and is only used as a label in plots. The default is just the literal that the function fun is bound to.
...	Additional arguments passed to fun. See the Details section.

Details

# Function arguments

The argument `study_names` is used to differentiate between the
different individual estimates. If the argument is set to `NULL`,
the element 'study_names' in the return object will just be the a
character vector with elements "Study n" where n is a number from 1
to `length(elements)`. These names are only used in some of the
`autoplot` methods.

The argument `fun` must have arguments 'estimates', 'SEs',
and 'mu' but it can also have further arguments.
However, these must either have a default value or
need to be passed via the `...` argument. If there
are additional arguments passed via `...`,
`confMeta` will internally create a new
function that calls `fun` with the additional arguments fixed.
Thus, any any argument passed via `...` overwrites existing
defaults.
Since this is the p-value function that is used to calculate the
combined confidence interval(s), it should return a vector of class
'numeric' with value(s) in the interval [0, 1].

# Confidence intervals

The confidence intervals returned by `confMeta` are calculated as
follows:

The `individual_cis` are calculated as
\deqn{x_{i} \pm \Phi^{-1}{\text{conf_level}} \cdot \sigma_{i}}
where \eqn{x_{i}} corresponds to the elements of vector
`estimates}, \eqn{\Phi^{-1}} is the quantile function of
the standard normal distribution, conf_level is the confidence
level passed as argument `conf_level`, and
\eqn{\sigma_{i}}, are the standard errors passed in argument
`SEs`.

The boundaries of the confidence intervals returned in element
`joint_cis` are found by searching where the function returned
in element 'p_fun' is equal to 1-`conf_level`.

Value

An S3 object of class confMeta. The object contains the following elements:

estimates

The normalized individual effect estimates.

SEs

The standard errors of the normalized individual effect estimates.

study_names

The names of the individual studies.

conf_level

The confidence level.

individual_cis

The confidence intervals for the individual effects. The exact calculation of these intervals can be found in the Details section.

p_fun

A function with arguments named 'estimates', 'SEs', 'conf_level', and 'mu'. This is the p-value function that is used to find the combined confidence intervals.

fun_name

The name of the function. It is only used in plots as a legend entry.

joint_cis

The combined confidence interval(s). These are calculated by finding the mean values where the $p$-value function is larger than the confidence level in element conf_level.

gamma

The local minima within the range of the individual effect estimates. Column 'x' refers to the mean mu and column 'y' contains the corresponding $p$-value.

p_max

The local maxima of the $p$-value function. The column 'x' refers to the mean mu and the column 'y' contains the corresponding $p$-value.

p_0

The value of the $p$-value at mu = 0

comparison_cis

Combined confindence intervals calculated with other methods. These can be used to for comparison purposes. Currently, these other methods are random effects (REML), Hartung & Knapp, and Henmi & Copas.

comparison_p_0

The same as in element 'p_0' but for the comparison methods (Random effects, Hartung & Knapp, Henmi & Copas).

Examples

    # Simulate effect estimates and standard errors
    set.seed(42)
    n <- 5
    estimates <- rnorm(n)
    SEs <- rgamma(n, 5, 5)
    conf_level <- 0.95

    # Construct a simple confMeta object using p_edgington as
    # the p-value function
    cm <- confMeta(
        estimates = estimates,
        SEs = SEs,
        conf_level = conf_level,
        fun = p_edgington,
        fun_name = "Edgington  (one-sided input)",
        input_p = "one.sided"
    )
    cm2 <- confMeta(
        estimates = estimates,
        SEs = SEs,
        conf_level = conf_level,
        fun = p_edgington,
        fun_name = "Edgington (two-sided input)",
        input_p = "two.sided"
    )

    # Plot the object
    autoplot(cm, cm2, type = "p")                   # p-value function plot
    autoplot(cm, cm2, type = "forest")              # forest plot
    autoplot(cm, cm2, type = c("p", "forest"))      # both

felix-hof/hMean documentation built on Jan. 26, 2025, 4:59 p.m.