Visual predictive check of a treatment contrast
Description
A VPC of the difference between each active arm and the reference arm of the same study, at the same time - the quantity a model-based meta-analysis (MBMA), an active-comparator trial or a crossover is about (see time in the Pairing section). Every other ferx diagnostic works on arm-level DV / PRED, and an arm-based model can fit every arm well while describing the contrast poorly.
Usage
ferx_contrast_vpc(
fit,
by,
ref,
within = "ID",
arm = NULL,
time = "TIME",
cmt = NULL,
n_sim = 500L,
seed = 42L,
scale = c("observed", "log", "logit", "expit"),
probs = c(0.05, 0.5, 0.95),
model = NULL,
data = NULL,
...
)
# S3 method for ferx_contrast_vpc
plot(x, y = NULL, facet = c("by", "none"), ...)Arguments
fit: Aferx_fitresult. Itsmodel_pathanddata_pathsupply the model and the design unlessmodel/dataare given.by: Name of the column that identifies the treatment (e.g."DOSE"or"TRT").ref: The value ofbythat marks the reference arm (e.g.0for placebo). Must occur in the data.within: Name of the column contrasts are formed within - the study. Default"ID".arm: Optional name of a column that identifies the arm within a study (e.g."OCC"in data from[ferx_mbma_data](ferx_mbma_data.qmd)). Needed only when two arms of one study share abyvalue.time: Name of the column arms are paired on. Default"TIME"; a crossover passes time since the start of the period, or a visit.cmt: TheCMTof the endpoint to contrast, when the observation records hold more than one. DefaultNULL: the data must hold one endpoint.n_sim: Number of simulated replicates. Default 500.seed: Random seed passed to[ferx_simulate](ferx_simulate.qmd).scale: The scale the contrast is formed on:"observed"(default),"log","logit"or"expit". See the Scale section.probs: Lower, middle and upper quantile of the simulated contrast. Defaultc(0.05, 0.5, 0.95): the median and a 90 percent band.model, data: Optional model file path and data (a CSV path or a data.frame, as in[ferx_fit](ferx_fit.qmd)), overridingfit$model_path/fit$data_path. The data are the design the simulation runs on and the observations the contrast is taken from....: Forferx_contrast_vpc(), further arguments to[ferx_simulate](ferx_simulate.qmd)(e.g.match); forplot(), graphical parameters passed toplot().x: Aferx_contrast_vpcobject.y: Ignored.facet:"by"(default) draws one panel per activebyvalue (e.g. per dose);"none"pools every active arm in one panel.
Details
Within each level of within (the study) and each TIME, the function forms DV[by != ref] - DV[by == ref] on the observed data and, identically, on every replicate of [ferx_simulate](ferx_simulate.qmd)(..., fit = fit). It returns the paired data frame and the VPC of the difference; plot() draws it.
Why it is sharper than the arm-level VPC
The contrast is taken within a study, so anything the arms of one study share cancels: the between-study random effect (an omega on the baseline), and the study-by-visit placebo levels. What is left is the structural drug effect plus the variability that differs between arms (between-arm kappa, residual error). The between-study spread that dominates an arm-level VPC is differenced away, so a misspecified dose- or time-response is not hidden behind it. What cancels is whatever the arms of one within level share. That is the between-study random effect only when the model’s random-effect unit (the data’s ID) is the study, as with within = "ID" in arm-level MBMA data. When each arm is its own ID and within names a study column, the omega is between-arm and stays in the contrast.
Pairing
Arms are matched within a level of within and a TIME. Each active arm gets its own contrast against the reference arm; there is one row of $pairs per study, time and active arm.
- A study, or a time within a study, with no reference arm contributes nothing. They are reported together in one warning that names the count and the studies.
- A study with more than one reference arm is refused: there is no single difference to form, and ferx does not pick one.
- An arm is identified by its
byvalue, or by thearmcolumn when given. Two arms of one study with the samebyvalue at the same time (two placebo arms, two arms at one dose) are refused unlessarmtells them apart. - Arms pair on an identical value of the
timecolumn (TIMEby default). For a design whose arms are observed at different clock times - the periods of a crossover - pass a column of time since the start of the period, or a nominal visit. - One endpoint per call. When the observation records span more than one
CMT, passcmt =; without it the call is refused, since pairing on study and time would difference one endpoint against another. The simulation still runs on the whole data file; only the chosen endpoint’s records are paired. - A censored record (
CENS != 0) is left out, counted in one warning: itsDVis a limit, not a measurement, and the simulation does not censor.
Scale
scale says on which scale the difference is formed. It is an argument, never inferred from the model, and it is a transform of the DV column as the data file holds it: the default contrast is in the units the arm-level readout was reported in.
"observed": (default)DV_active - DV_refon the data file’s scale: score points, percent, concentration. For a readout the data already hold transformed - a weighted logitDV = logit(p), a pre-loggedDV ~ log_additive(...)- this is the contrast on that scale (a log odds ratio, a log ratio)."log":log(DV_active) - log(DV_ref), the log ratio of a positiveDV."logit":logit(DV_active) - logit(DV_ref), the log odds ratio of a proportion held in (0, 1)."expit":expit(DV_active) - expit(DV_ref), the difference in proportions for data holdingDV = logit(p).
The observed DV and every simulated DV_SIM are put on the data file’s scale first, then transformed the same way. They differ in one case: under log(DV) ~ ... the engine logs DV at load and simulates on the log scale, so DV_SIM is exponentiated back before scale is applied ("log" then gives the contrast on the model’s own scale). A simulated value outside the transform’s domain gives a non-finite contrast, which is dropped from the quantiles and counted in a warning.
Plot
plot() draws the VPC of the contrast per time, in the style of a VPC: the shaded band is the probs interval of the simulated median contrast, the solid line its median, the points the observed contrasts (one per study and arm) and the dashed line their median. It returns x invisibly.
Seealso
Other simulation: [ferx_calc_npde](ferx_calc_npde.qmd), [ferx_predict](ferx_predict.qmd), [ferx_predict_survival](ferx_predict_survival.qmd), [ferx_sim_parameters](ferx_sim_parameters.qmd), [ferx_simulate](ferx_simulate.qmd), [ferx_simulate_adaptive](ferx_simulate_adaptive.qmd), [ferx_simulate_with_uncertainty](ferx_simulate_with_uncertainty.qmd), [ferx_vpc_tte](ferx_vpc_tte.qmd)
Concept
simulation
Value
An object of class ferx_contrast_vpc, a list with:
pairs: One row per study, time and active arm: thewithincolumn,TIME(the value of thetimecolumn the pair was formed at),ARM(the arm’sarmvalue, or itsbyvalue), thebycolumn (the active arm’s treatment),DV_REFandDV_ACTIVE(observed, untransformed),CONTRAST(observed, onscale),SIM_LO,SIM_MED,SIM_HI(theprobsquantiles of that pair’s simulated contrast) andPCTL, the fraction of simulated contrasts below the observed one - near 0 or 1 is a pair the model does not reproduce.vpc: The VPC summary: one row perbyvalue andTIME, withN(pairs),OBS_MED(median observed contrast) andSIM_LO,SIM_MED,SIM_HI, theprobsquantiles of the median over pairs, across replicates - the band the observed median should fall in.sim: The simulated contrasts, long:SIM, thewithincolumn,TIME,ARM, thebycolumn andCONTRAST.excluded: Thewithinvalues with no reference arm at one or more times, as warned.sim_exponentiated:TRUEwhenDV_SIMwas exponentiated back to the data’s scale (alog(DV) ~ ...readout; see the Scale section).within,by,ref,time,cmt,scale,probs,n_sim: The settings used.
Examples
ex <- ferx_example("mbma_placebo")
fit <- ferx_fit(ex$model, ex$data)
cv <- ferx_contrast_vpc(fit, within = "ID", by = "DOSE", ref = 0,
n_sim = 200)
head(cv$pairs)
cv$vpc
plot(cv)