II Oncology Trials

bayesian_isotonic

R Documentation

Function to fit a Bayesian isotonic regression

Description

This function fits a Bayesian isotonic regression: it calculates the posterior distribution of a set of probabilities that are order constrained but each a priori marginally distributed as beta random variables.

Usage

bayesian_isotonic(
  data_grouped = NULL,
  stan_args = list(local_dof_stan = 1, global_dof_stan = 1, alpha_scale_stan = 1),
  sample_from_prior_only = F,
  conf_level = 0.5,
  conf_level_direction = "both",
  verbose = F,
  n_mc_warmup = 1000,
  n_mc_samps = 2000,
  mc_chains = 4,
  mc_thin = 1,
  mc_stepsize = 0.1,
  mc_adapt_delta = 0.8,
  mc_max_treedepth = 15,
  ntries = 2,
  return_as_stan_object = F,
  tol = .Machine$double.eps^0.5,
  seed = 1
)

Arguments

`data_grouped`	A data.frame or tibble that contain columns x (used as category labels), y (the number of successes or events), and n (the number of trials).
`stan_args`	A named list of arguments to pass to the stan function. It should include the named elements: local_dof_stan This has default value 1. global_dof_stan This has default value 1. alpha_scale_stan This has default value 1. For more information on these arguments, please see rstan documentation.
`sample_from_prior_only`	A logical value. If TRUE, then the provided values of 'x' and 'n' will be ignored and draws will only be sampled from the prior distribution. Defaults to FALSE.
`conf_level`	Numeric in (0, 1). This level credible interval will be returned based upon the empirical quantiles. The default is 0.5.
`conf_level_direction`	This is a string equal to 'both', 'upper', or 'lower' indicating the desired direction of the credible interval. The default is 'both'.
`verbose`	A logical value. If TRUE, then all posterior draws will be returned by the function. Defaults to FALSE.
`n_mc_warmup`	A positive integer giving the number of desired warmup runs; the default is 1000.
`n_mc_samps`	A positive integer giving the number of additional samples to run after warmup is completed; the default is 2000.
`mc_chains`	A positive integer indicating the number of chains to run in parallel, which will multiply the final number of samples; the default is 4.
`mc_thin`	A positive integer indicating the number of iterations to thin by (increasing thinning will decrease the final number of samples); the default is 1.
`mc_stepsize`	A numeric value between 0 and 1 that is passed to control in the call to stan() as the stepsize argument; the default is 0.1.
`mc_adapt_delta`	A numeric value between 0 and 1 that is passed to control in the call to stan() as the adapt_delta argument; the default is 0.8.
`mc_max_treedepth`	A positive integer passed to control in the call to stan() as the max_treedepth argument; the default is 15.
`ntries`	A positive integer. The stan algorithm throws warnings about divergent transitions, which are indicative of an inability to fully explore the posterior space. Sometimes this number can be extremely large, which suggests that the fitted model needs to be reparametrized. However, in this case, divergent transitions seem to be sporadic. ntries indicates how many reruns of the algorithm should be tried when > 0 divergent transitions are encountered. The run with the fewest such transitions is kept. The default is 2.
`return_as_stan_object`	A logical value. If TRUE, then the function returns an object of class 'stanfit'. If FALSE, then a summary of results will be returned. Defaults to FALSE.
`tol`	A small positive number (double). The default is the square root of the machine precision.
`seed`	A positive integer used to set the random starting point for Stan sampling.

Value

If return_as_stan_object = TRUE, then an object of class stanfit is returned. This is useful for the initial compilation of the stan model. Otherwise, the function returns the following named list containing the arguments:

data_grouped: The provided argument of the same name but with more columns added that provide summaries of the efficacy probability for each row.
conf_level, conf_level_direction: Arguments provided by the user for the confidence interval.
stan_args: The list of arguments that were passed to the stan function.
accepted_divergences: The number of divergent transitions from the model.
max_divergences: The maximum observed number of divergent transitions from the ntries number of model fits that were attempted.
rhat: The largest value of the Gelman-Rubin diagnostic across all parameters.
number_nan: The number of draws that were 0/0, e.g. due to underflow.
all_draws: NA if verbose == FALSE, otherwise all_draws is a matrix of draws from the posterior distribution, which may be large.
chain_run_times_secs, total_run_time_secs: Length of time (seconds) for chain runs and total runs.