Skip to main content

Build and validate a summary-level (MBMA) dataset

Description

Turns a table of published arm-level summaries - one row per study, arm and timepoint, with the arm mean, its precision and the arm size - into the record layout a model-based meta-analysis (MBMA) model is fitted on, and checks it on the way. Every check below catches a data-preparation mistake that otherwise fits without complaint: a percentage read as a proportion, a standard deviation read as a standard error, an arm whose size changes between visits, a study that contributes a single arm.

Usage

ferx_mbma_data(
  data,
  study,
  arm,
  time,
  mean,
  se = NULL,
  sd = NULL,
  n,
  scale = c("continuous", "proportion", "percent"),
  covariates = NULL,
  levels = NULL,
  index = NULL
)

Arguments

  • data: A data.frame with one row per study, arm and timepoint.
  • study, arm, time, mean, n: Names of the columns in data holding the study, the arm within the study, the timepoint, the arm mean and the arm size. study and arm may be numeric, character or factor; time, mean and n must be numeric.
  • se, sd: Name of the column holding the standard error of the arm mean, or the between-subject standard deviation. Give exactly one; sd is converted to a standard error as sd / sqrt(n).
  • scale: The scale mean is reported on. "continuous" (default) accepts any value; "proportion" requires values in [0, 1]; "percent" requires values in [0, 100] and divides mean and se by 100.
  • covariates: Optional names of further columns to carry through. Character and factor columns are coded as integers 1..K (factor levels order, or sorted values), with the codes kept in attr(d, "codes"); logical columns become 0/1.
  • levels: Optional output column names - "STUDY", "TIME" or a covariate - to build the LEVEL_IDX level index from.
  • index: Optional name of a column in data holding your own 1-based level index for a counted theta NAME[N] block. It is checked (whole numbers, 1..N, no level left out) and carried through under its own name. Not combined with levels.

Details

Each study becomes one subject (ID), so a random effect on IDis between-study variability, and each arm becomes one occasion (OCC), so a kappa is between-treatment-arm variability. The study is also written to a separate STUDY column: a theta NAME[COL, ...] level block reads its columns from the covariates, and ID is not one. The result is a data.frame, passed as it is as the data of [ferx_fit](ferx_fit.qmd) and the other fitting and simulation functions.

Checks

  • Errors: A se (or sd) that is missing, zero, negative or infinite where mean is present, an n that is missing, non-positive or infinite, an infinite mean or one outside the range of scale, a missing study or arm, a missing or infinite time, a repeated (study, arm, time) row, a missing value in a levels column, and an index column that is not 1..N without gaps. Each message names the offending rows.
  • Warnings: An arm whose n changes between timepoints (the per-row n is kept in NARM), a study with a single arm, and an arm without a time == 0 record.
  • Accepted: A negative mean: change from baseline is negative by nature.

Rows whose mean is missing are dropped, with a message; if that leaves no row, the call is refused.

Levels for a theta level block

levels = c("STUDY", "TIME") adds a LEVEL_IDX column numbering the observed (STUDY, TIME) combinations 1..N, in the order the engine discovers the levels of theta NAME[STUDY, TIME]: ascending by the first column, then the next. The counted form theta NAME[N] with NAME[LEVEL_IDX] then estimates the same levels as the data-driven form with contrast = none. The counted form is what lets you define the cells yourself (for example, pooled visit windows, via index). The table mapping each index to its cell is kept in attr(d, "levels"), labelled as the engine labels a level (STUDY=7,TIME=4). The levels are built from the level columns rounded to 15 significant digits, the text utils::write.csv()writes, and the level columns in the result hold those rounded values: 0.1 + 0.2 and 0.3 are one level. A rounded value is written back exactly, so the engine sees the same levels whether the result is passed to [ferx_fit](ferx_fit.qmd) as it is or written with utils::write.csv().

Value

A ferx_mbma_data data.frame, sorted by study, arm and time, with columns ID (the study), STUDY, OCC (the arm, 1..K within each study), TIME, DV (the arm mean), MDV (0), NARM (the arm size), SE, the covariates, and LEVEL_IDX or the index column. Attributes:

  • arms: A data.frame mapping each (STUDY, OCC) to the original study and arm values.
  • codes: A named list of the integer codes given to each character or factor column (study included).
  • levels: With levels: a data.frame of index, label and one column per level column.
  • scale: The scale argument.

Examples

arms <- data.frame(
  trial = rep(c("A", "B"), each = 4),
  treatment = rep(rep(c("placebo", "drug"), each = 2), 2),
  week = rep(c(0, 12), 4),
  change = c(0, -1.1, 0, -2.4, 0, -0.8, 0, -2.0),
  sd = c(2.1, 2.3, 2.0, 2.4, 1.9, 2.2, 2.1, 2.5),
  n = c(120, 120, 118, 118, 95, 95, 97, 97)
)
d <- ferx_mbma_data(arms,
  study = "trial", arm = "treatment", time = "week",
  mean = "change", sd = "sd", n = "n",
  levels = c("STUDY", "TIME")
)
d
attr(d, "levels")
# `d` is the `data` of a fit as it is: ferx_fit(model, d)