Skip to main content

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: A ferx_fit result. Its model_path and data_path supply the model and the design unless model / data are given.
  • by: Name of the column that identifies the treatment (e.g. "DOSE" or "TRT").
  • ref: The value of by that marks the reference arm (e.g. 0 for 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 a by value.
  • 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: The CMT of the endpoint to contrast, when the observation records hold more than one. Default NULL: 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. Default c(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)), overriding fit$model_path / fit$data_path. The data are the design the simulation runs on and the observations the contrast is taken from.
  • ...: For ferx_contrast_vpc(), further arguments to [ferx_simulate](ferx_simulate.qmd) (e.g. match); for plot(), graphical parameters passed to plot().
  • x: A ferx_contrast_vpc object.
  • y: Ignored.
  • facet: "by" (default) draws one panel per active by value (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 by value, or by the arm column when given. Two arms of one study with the same by value at the same time (two placebo arms, two arms at one dose) are refused unless arm tells them apart.
  • Arms pair on an identical value of the time column (TIME by 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, pass cmt =; 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: its DV is 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_ref on the data file’s scale: score points, percent, concentration. For a readout the data already hold transformed - a weighted logit DV = logit(p), a pre-logged DV ~ 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 positive DV.
  • "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 holding DV = 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: the within column, TIME (the value of the time column the pair was formed at), ARM (the arm’s arm value, or its by value), the by column (the active arm’s treatment), DV_REF and DV_ACTIVE (observed, untransformed), CONTRAST (observed, on scale), SIM_LO, SIM_MED, SIM_HI (the probs quantiles of that pair’s simulated contrast) and PCTL, 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 per by value and TIME, with N (pairs), OBS_MED (median observed contrast) and SIM_LO, SIM_MED, SIM_HI, the probs quantiles of the median over pairs, across replicates - the band the observed median should fall in.
  • sim: The simulated contrasts, long: SIM, the within column, TIME, ARM, the by column and CONTRAST.
  • excluded: The within values with no reference arm at one or more times, as warned.
  • sim_exponentiated: TRUE when DV_SIM was exponentiated back to the data’s scale (a log(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)