OncoBayes2 (version 0.9-1)

summary.blrm_trial: Summarise trial

Description

Provides model summaries for blrm_trial analyses.

Usage

# S3 method for blrm_trial
summary(
  object,
  summarize = c("blrmfit", "blrm_exnex_call", "data", "drug_info", "dose_info",
    "dose_prediction", "data_prediction", "newdata_prediction", "dimensionality",
    "interval_prob", "interval_max_mass", "ewoc_check"),
  ...
)

Arguments

object

blrm_trial object

summarize

one of the following options:

blrmfit

summary of the underlying blrmfit object with further arguments ...

blrm_exnex_call

blrm_exnex call used to create the blrmfit object

drug_info

drug_info for the trial, contains drugs, reference doses and units

dose_info

dose_info that were defined

dose_prediction

prediction for the defined dose_info

data

data that were observed

data_prediction

prediction for the observed data

newdata_prediction

prediction for data provided with the newdata argument

dimensionality

numeric vector with entries "num_components", "num_interaction_terms", "num_groups", "num_strata"

interval_prob

interval probabilities reported in the standard outputs

interval_max_mass

named vector defining for each interval of the interval_prob vector a maxmimal admissable probability mass for a given dose level

ewoc_check

MCMC diagnostic and precision estimates of ewoc defining metrics for the defined doses in dose_info (default) or for the doses provided in the newdata argument. Please refer to the details for reported diagnostics.

...

further arguments for summary.blrmfit

Details

The ewoc_check summary routine allows to assess the accuracy and reliability of the ewoc criterion with respect to MCMC sampling noise. The returned summary provides detailled MCMC convergence and precision estimates for all criteria defined by interval_prob and interval_max_mass which contribute to EWOC metric. That is, for each interval probability with a maximal mass of less than unity the routine will return these columns:

est

the MCMC estimate defining the critical value. For intervals defined by a tail probability this corresponds to the respective critical quantile while for interval probabilites this is equal to the interval probability.

stat

centered and standardized test quantity. The estimate is centered by the critical value and scaled by the Monte-Carlo standard error (MCSE) of the estimate. Hence, negative (positive) values correspond to the constraint being (not) fulfilled. The standardization with the MCSE allows to compare the values to standard normal quantiles accordingly.

mcse

the Monte-Carlo standard error of the estimate determined with mcse_quantile (tail probability) or mcse_mean (interval probability) functions.

ess

the Monte-Carlo effective sample size of the estimate determined with ess_quantile (tail probability) or ess_mean (interval probability) functions.

rhat

the Monte-Carlo non-convergence diagnostic Rhat as determined with the rhat function.

For the common case of requiring that 33\ exceeded by more than 25\ estimate column est contains the 75\ \(q_{75\%}\) and the standardized statistic stat is defined as:

$$\mbox{stat} = \frac{q_{75\%} - 33\%}{\mbox{mcse}_{q_{75\%}}}$$

The statistic is approximately distributed as a standard normal variate. The ewoc_check summary can be used to ensure that the MCMC estimation accuracy is sufficient.

Examples

## Setting up dummy sampling for fast execution of example
## Please use 4 chains and 100x more warmup & iter in practice
.user_mc_options <- options(
  OncoBayes2.MC.warmup = 10, OncoBayes2.MC.iter = 20, OncoBayes2.MC.chains = 1,
  OncoBayes2.MC.save_warmup = FALSE
)

# construct initial blrm_trial object from built-in example datasets
combo2_trial_setup <- blrm_trial(
  data = hist_combo2,
  dose_info = dose_info_combo2,
  drug_info = drug_info_combo2,
  simplified_prior = TRUE
)

# extract blrm_call to see setup of the prior as passed to blrm_exnex
summary(combo2_trial_setup, "blrm_exnex_call")

# extract ewoc precision accuracy
ec <- summary(combo2_trial_setup, "ewoc_check")

# find any ewoc metrics which are within 95% MCMC error of the threshold
# these are counted as "imprecise" when printing blrm_trial objects
subset(ec, abs(prob_overdose_stat) < qnorm(0.975))

# ensure that the ewoc metric only flags "ok" whenever the MCMC error
# is with 95% below the threshold
ewoc_ok <- ec$prob_overdose_stat < qnorm(0.025)

## Recover user set sampling defaults
options(.user_mc_options)