Skip to contents

Information fraction within each trial and pooled across trials

Source: R/constructions.R, R/ifrac.R
ifrac.Rd

Design (default): computes information fractions within each trial from subgroup variances.

Usage

# S3 method for class 'interactmeta_da'
ifrac(x, ...)

# S3 method for class 'interactmeta_ad'
ifrac(x, ...)

# S3 method for class 'interactmeta_conventional'
ifrac(x, ...)

# S3 method for class 'interactmeta_swada'
ifrac(x, ...)

ifrac(x, ...)

# Default S3 method
ifrac(
  x,
  vi = NULL,
  trial = NULL,
  modifier = NULL,
  subgroup = NULL,
  big_var = 100^2,
  contrast = "all",
  contrast_sep = "-",
  reference = NULL,
  include_combined = FALSE,
  include_interaction = FALSE,
  yi = NULL,
  ...
)

# S3 method for class 'data.frame'
ifrac(
  x,
  ifrac = NULL,
  fit = NULL,
  tau = NULL,
  tau_gamma = NULL,
  reference = NULL,
  trial = "study",
  modifier = NULL,
  subgroup = "level",
  ifrac_var = NULL,
  contrast_sep = "-",
  summary = FALSE,
  prob = 0.95,
  big_var = 100^2,
  contrast = "all",
  include_combined = FALSE,
  include_interaction = FALSE,
  yi = NULL,
  ...
)

# S3 method for class 'interactmeta'
ifrac(
  x,
  ifrac = c("interaction", "overall"),
  ifrac_var = NULL,
  summary = FALSE,
  prob = 0.95,
  ...
)

# S3 method for class 'interactmeta_overall_ifrac'
ifrac(x, ...)

Arguments

x

Effect estimates. A numeric vector, or a data frame or escalc object with columns yi and vi. If omitted, yi is used.

...

Further arguments passed to methods.

vi

Numeric vector. Variance of the subgroup estimate. Not used when the estimates are a data frame or escalc object.

trial

Trial identifier. A vector (same length as the estimates), or when the estimates are a data frame the name of the trial column (default "trial").

modifier

Column name for the subgroup levels when the estimates are a data frame. A single string, supplied by name. Overrides subgroup. This is not the vector of subgroup labels; pass that vector in subgroup.

subgroup

Subgroup identifier. A vector (same length as the estimates), or when the estimates are a data frame the name of the subgroup column (default "subgroup").

big_var

Positive number. Variance used to impute a missing trial-by-subgroup cell (yi = 0, vi = big_var). For an escalc object, a row that already has the placeholder yi = 0 and vi = 8 keeps that estimate, and vi is replaced by big_var. Defaults to 100^2.

contrast

Either NULL (subgroup rows only, wide ifrac_<subgroup> columns), a character vector of length 2 giving the two subgroup labels to contrast within each trial (computed as label1 - label2, where label2 is the reference), or "all" (default) to add each non-reference subgroup vs the reference.

contrast_sep

String used between subgroup labels in the contrast row label. Defaults to "-".

reference

Optional. Used when contrast = "all". Comparisons are generated only between each non-reference subgroup and the reference subgroup (e.g. g2-g1, g3-g1, ...). If reference is NULL, the reference defaults to the first level of a factor subgroup, otherwise the first label in sorted unique order. Can be either an integer index or a subgroup label string.

When supplied, extra rows per trial are added with subgroup labels paste0(label1, contrast_sep, label2), and yi/vi computed as yi1 - yi2 and vi1 + vi2. Missing trial-by-subgroup combinations use the imputed yi=0 and vi=big_var.

include_combined

Logical. If FALSE (default), return subgroup rows only. If TRUE, append one precision-weighted combined row per trial with subgroup = "Combined".

include_interaction

Logical. If FALSE (default), return subgroup rows only while still using contrast to define the reference-centered ifrac_* design columns. If TRUE and contrast is not NULL, append interaction/contrast rows below subgroup rows.

Pooling ( interactmeta, or ifrac() data with ifrac_* columns): pass ifrac to pool trial-level fractions across studies. $$\bar{\omega} = \sum_i \pi_i w_i / \sum_i w_i.$$ With ifrac = "interaction" (default), \(w_i = 1/(\tau_\gamma^2 + \sigma_{Ai}^2 + \sigma_{Bi}^2)\) using the interaction-block SD \(\tau_\gamma\). With ifrac = "overall", \(w_i = 1/(\tau^2 + v_i)\) using the overall-block intercept SD \(\tau\) and \(v_i=\mathrm{Var}(m_i)=(1-\pi_i)^2\sigma_{Ai}^2+\pi_i^2\sigma_{Bi}^2\). On Bayesian CAMS, \(\tau\) / \(\tau_\gamma\) are DIRECT posterior supports, so the pooled IF is a distribution. On frequentist CAMS (engine = "metafor"), pooling uses the fitted \(\tau\) or \(\tau_\gamma\). See argument details below and examples.

yi

Either a numeric vector of subgroup effect estimates, or a data frame / escalc object containing columns yi and vi. When a data frame is supplied as x or yi, vi must not be passed separately; trial and subgroup name columns (defaults "trial" and "subgroup").

ifrac

For pooling only: "interaction" (default) or "overall".

fit, tau, tau_gamma, ifrac_var, summary, prob

Pooling options when x is a interactmeta or design data with ifrac_* columns (fit or tau / tau_gamma required for data-only pooling).

Value

For the design method, a tibble with one row per trial-by-subgroup combination (subgroup levels and contrast rows when requested), including trial, subgroup (a factor with the reference subgroup as the first level on subgroup rows), yi, vi, and information-fraction columns. Columns yi, vi, precision (when present), and all ifrac_<...> columns are numeric.

For pooling, a interactmeta_overall_ifrac object (draws with metadata), or a summary data frame when summary = TRUE.

Details

Each component precision is defined as 1 / vi.

By default (contrast = "all"), all non-reference-vs-reference contrasts are added per trial. Set contrast = NULL to return only subgroup rows with wide ifrac_<subgroup> columns (one fraction per subgroup label).

When contrast is provided, the information fraction for each comparison is computed as the non-reference subgroup precision divided by the total subgroup precision within the trial. By convention, the reference subgroup is the label after contrast_sep, i.e. in a label like "g2-g1", "g1" is the reference subgroup.

By default, components are the observed subgroup labels. When include_combined = TRUE, one precision-weighted combined row per trial is appended with subgroup = "Combined" (contribution-weighted mean $m_j$ on the chosen scale). When include_interaction = TRUE, contrast rows are stacked below subgroup rows with subgroup labels like "g2-g1" (reference after contrast_sep), using yi and vi for the contrast estimate and variance. Wide columns ifrac_<non-reference> are filled on every row (no NA), plus precision, and a reference column (last column). For each non-reference subgroup k, ifrac_k is the trial-level information fraction. On combined and contrast rows, precision is the sum of subgroup precisions in the trial (or in that comparison for a single contrast).

Examples

yi <- c(0.2, 0.1, 0.3, 0.15)
vi <- c(0.01, 0.04, 0.0225, 0.09)
trial <- c("A", "A", "B", "B")
subgroup <- c("g1", "g2", "g1", "g2")

# Default: all non-reference vs reference contrasts (reference = first
# factor level, or first sorted label for character subgroups).
# Name `subgroup`: the fourth positional argument is `modifier`.
ifrac(yi = yi, vi = vi, trial = trial, subgroup = subgroup)
#> # A tibble: 4 × 7
#>   study level    yi     vi precision ifrac_g2 reference
#>   <chr> <fct> <dbl>  <dbl>     <dbl>    <dbl> <chr>    
#> 1 A     g1     0.2  0.01       100        0.2 g1       
#> 2 A     g2     0.1  0.04        25        0.2 g1       
#> 3 B     g1     0.3  0.0225      44.4      0.2 g1       
#> 4 B     g2     0.15 0.09        11.1      0.2 g1       

# Subgroup rows only, wide ifrac_<subgroup> for every label
ifrac(yi = yi, vi = vi, trial = trial, subgroup = subgroup, contrast = NULL)
#> # A tibble: 4 × 6
#>   study level    yi     vi ifrac_g1 ifrac_g2
#>   <chr> <chr> <dbl>  <dbl>    <dbl>    <dbl>
#> 1 A     g1     0.2  0.01        0.8      0.2
#> 2 A     g2     0.1  0.04        0.8      0.2
#> 3 B     g1     0.3  0.0225      0.8      0.2
#> 4 B     g2     0.15 0.09        0.8      0.2

# Single contrast (g1 - g2, reference g2)
ifrac(
  yi = yi, vi = vi, trial = trial, subgroup = subgroup,
  contrast = c("g1", "g2")
)
#> # A tibble: 4 × 7
#>   study level    yi     vi precision ifrac_g1 reference
#>   <chr> <fct> <dbl>  <dbl>     <dbl>    <dbl> <chr>    
#> 1 A     g1     0.2  0.01       100        0.8 g2       
#> 2 A     g2     0.1  0.04        25        0.8 g2       
#> 3 B     g1     0.3  0.0225      44.4      0.8 g2       
#> 4 B     g2     0.15 0.09        11.1      0.8 g2       

# Specify reference subgroup explicitly
ifrac(yi = yi, vi = vi, trial = trial, subgroup = subgroup, reference = "g1")
#> # A tibble: 4 × 7
#>   study level    yi     vi precision ifrac_g2 reference
#>   <chr> <fct> <dbl>  <dbl>     <dbl>    <dbl> <chr>    
#> 1 A     g1     0.2  0.01       100        0.2 g1       
#> 2 A     g2     0.1  0.04        25        0.2 g1       
#> 3 B     g1     0.3  0.0225      44.4      0.2 g1       
#> 4 B     g2     0.15 0.09        11.1      0.2 g1       

# Append combined rows (one per trial)
ifrac(
  yi = yi, vi = vi, trial = trial, subgroup = subgroup,
  include_combined = TRUE
)
#> # A tibble: 6 × 7
#>   study level       yi     vi precision ifrac_g2 reference
#>   <chr> <chr>    <dbl>  <dbl>     <dbl>    <dbl> <chr>    
#> 1 A     g1        0.2  0.01       100        0.2 g1       
#> 2 A     g2        0.1  0.04        25        0.2 g1       
#> 3 B     g1        0.3  0.0225      44.4      0.2 g1       
#> 4 B     g2        0.15 0.09        11.1      0.2 g1       
#> 5 A     Combined  0.18 0.008      125        0.2 g1       
#> 6 B     Combined  0.27 0.018       55.6      0.2 g1       

# Append interaction rows at the bottom
ifrac(
  yi = yi, vi = vi, trial = trial, subgroup = subgroup,
  include_interaction = TRUE
)
#> # A tibble: 6 × 7
#>   study level    yi     vi precision ifrac_g2 reference
#>   <chr> <chr> <dbl>  <dbl>     <dbl>    <dbl> <chr>    
#> 1 A     g1     0.2  0.01       100        0.2 g1       
#> 2 A     g2     0.1  0.04        25        0.2 g1       
#> 3 B     g1     0.3  0.0225      44.4      0.2 g1       
#> 4 B     g2     0.15 0.09        11.1      0.2 g1       
#> 5 A     g2-g1 -0.1  0.05       125        0.2 g1       
#> 6 B     g2-g1 -0.15 0.112       55.6      0.2 g1       

if (FALSE) { # \dontrun{
library(interactmeta)
e <- escalc(measure = "IRR", yi = edss$yi, vi = edss$vi, data = edss)
d <- ifrac(e, reference = "Lower", include_interaction = TRUE)
fit <- cams(d, reference = "Lower")
forestplot(fit)
plot_contribution(fit)

# Pool across trials (interaction-IF, the default)
ifrac(fit)
ifrac(fit, ifrac = "overall")
} # }