hbl_summary {historicalborrowlong}R Documentation

Model summary

Description

Summarize a fitted model in a table.

Usage

hbl_summary(
  mcmc,
  data,
  response = "response",
  response_type = "raw",
  study = "study",
  study_reference = max(data[[study]]),
  group = "group",
  group_reference = min(data[[group]]),
  patient = "patient",
  rep = "rep",
  rep_reference = min(data[[rep]]),
  covariates = grep("^covariate", colnames(data), value = TRUE),
  constraint = FALSE,
  eoi = 0,
  direction = "<"
)

Arguments

mcmc

A wide data frame of posterior samples returned by hbl_mcmc_hierarchical() or similar MCMC function.

data

Tidy data frame with one row per patient per rep, indicator columns for the response variable, study, group, patient, rep, and covariates. All columns must be atomic vectors (e.g. not lists).

response

Character of length 1, name of the column in data with the response/outcome variable. data[[response]] must be a continuous variable, and it should be the change from baseline of a clinical endpoint of interest, as opposed to just the raw response. Treatment differences are computed directly from this scale, please supply change from baseline unless you are absolutely certain that treatment differences computed directly from this quantity are clinically meaningful.

response_type

Character of length 1: "raw" if the response column in the data is the raw response, "change" if the response columns is change from baseline. In the latter case, the ⁠change_*⁠ columns in the output table are omitted because the response is already a change from baseline. Must be one of "raw" or "change".

study

Character of length 1, name of the column in data with the study ID.

study_reference

Atomic of length 1, element of the study column that indicates the current study. (The other studies are historical studies.)

group

Character of length 1, name of the column in data with the group ID.

group_reference

Atomic of length 1, element of the group column that indicates the control group. (The other groups may be treatment groups.)

patient

Character of length 1, name of the column in data with the patient ID.

rep

Character of length 1, name of the column in data with the rep ID.

rep_reference

Atomic of length 1, element of the rep column that indicates baseline, i.e. the first rep chronologically. (The other reps may be post-baseline study visits or time points.)

covariates

Character vector of column names in data with the columns with baseline covariates. These can be continuous, categorical, or binary. Regardless, historicalborrowlong derives the appropriate model matrix.

Each baseline covariate column must truly be a baseline covariate: elements must be equal for all time points within each patient (after the steps in the "Data processing" section). In other words, covariates must not be time-varying.

A large number of covariates, or a large number of levels in a categorical covariate, can severely slow down the computation. Please consider carefully if you really need to include such complicated baseline covariates.

constraint

Logical of length 1, whether to pool all study arms at baseline (first rep). Appropriate when the response is the raw response (as opposed to change from baseline) and the first rep (i.e. time point) is prior to treatment.

eoi

Numeric of length at least 1, vector of effects of interest (EOIs) for critical success factors (CSFs).

direction

Character of length length(eoi) indicating how to compare the treatment effect to each EOI. ">" means Prob(treatment effect > EOI), and "<" means Prob(treatment effect < EOI). All elements of direction must be either ">" or "<".

Details

The hbl_summary() function post-processes the results from the model. It accepts MCMC samples of parameters and returns interpretable group-by-rep posterior summaries such as change from baseline response and treatment effect. To arrive at these summaries, hbl_summary() computes marginal posteriors of transformed parameters. The transformations derive patient-level fitted values from model parameters, then derive group-by-rep responses as averages of fitted values. We refer to this style of estimation as "unconditional estimation", as opposed to "conditional estimation", which takes each group mean to be the appropriate linear combination of the relevant alpha and delta parameters, without using beta components or going through fitted values. If the baseline covariates are balanced across studies, unconditional and conditional estimation should produce similar estimates of placebo and treatment effects.

Value

A tidy data frame with one row per group (e.g. treatment arm) and the columns in the following list. Unless otherwise specified, the quantities are calculated at the group-by-rep level. Some are calculated for the current (non-historical) study only, while others pertain to the combined dataset which includes all historical studies.

See Also

Other summary: hbl_metrics()

Examples

if (!identical(Sys.getenv("HBL_TEST", unset = ""), "")) {
set.seed(0)
data <- hbl_sim_pool(
  n_study = 2,
  n_group = 2,
  n_patient = 5,
  n_rep = 3
)$data
tmp <- utils::capture.output(
  suppressWarnings(
    mcmc <- hbl_mcmc_hierarchical(
      data,
      chains = 1,
      warmup = 10,
      iter = 20,
      seed = 0
    )
  )
)
hbl_summary(mcmc, data)
}

[Package historicalborrowlong version 0.0.8 Index]