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 indataholding the study, the arm within the study, the timepoint, the arm mean and the arm size.studyandarmmay be numeric, character or factor;time,meanandnmust 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;sdis converted to a standard error assd / sqrt(n).scale: The scalemeanis reported on."continuous"(default) accepts any value;"proportion"requires values in[0, 1];"percent"requires values in[0, 100]and dividesmeanandseby 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 inattr(d, "codes"); logical columns become 0/1.levels: Optional output column names -"STUDY","TIME"or a covariate - to build theLEVEL_IDXlevel index from.index: Optional name of a column indataholding your own 1-based level index for a countedtheta NAME[N]block. It is checked (whole numbers, 1..N, no level left out) and carried through under its own name. Not combined withlevels.
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(orsd) that is missing, zero, negative or infinite wheremeanis present, annthat is missing, non-positive or infinite, an infinitemeanor one outside the range ofscale, a missingstudyorarm, a missing or infinitetime, a repeated (study, arm, time) row, a missing value in alevelscolumn, and anindexcolumn that is not 1..N without gaps. Each message names the offending rows. - Warnings: An arm whose
nchanges between timepoints (the per-rownis kept inNARM), a study with a single arm, and an arm without atime == 0record. - 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 originalstudyandarmvalues.codes: A named list of the integer codes given to each character or factor column (studyincluded).levels: Withlevels: a data.frame ofindex,labeland one column per level column.scale: Thescaleargument.
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)