bhpm.cluster.1a.hier3 {bhpm}

A Three-Level Hierarchical Model for Grouped Data with Clusters and without Point-Mass.

Description

Implementation of a Three-Level Hierarchical for Grouped Data with Clusters and without Point-Mass.

Usage

	bhpm.cluster.1a.hier3(cluster.data, sim_type = "SLICE", burnin = 10000,
	iter = 40000, nchains = 3,
	global.sim.params = data.frame(type = c("MH", "SLICE"),
	param = c("sigma_MH", "w"), value = c(0.2,1), control = c(0,6),
	stringsAsFactors = FALSE),
	sim.params = NULL,
	monitor = data.frame(variable = c("theta", "gamma", "mu.gamma",
	"mu.theta", "sigma2.theta", "sigma2.gamma",
	"mu.theta.0", "mu.gamma.0", "tau2.theta.0", "tau2.gamma.0"),
	monitor = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
	stringsAsFactors = FALSE),
	initial_values = NULL,
	level = 1,
	hyper_params = list(mu.gamma.0.0 = 0, tau2.gamma.0.0 = 10,
	mu.theta.0.0 = 0, tau2.theta.0.0 = 10, alpha.gamma.0.0 = 3,
	beta.gamma.0.0 = 1, alpha.theta.0.0 = 3, beta.theta.0.0 = 1,
	alpha.gamma = 3, beta.gamma = 1,
	alpha.theta = 3, beta.theta = 1),
	memory_model = "HIGH")

Arguments

cluster.data

A file or data frame containing the cluster data. It must contain the columns Cluster, Outcome.Grp, Outcome, Trt.Grp (1 - control, 2,... comparator treatments), Count (total number of events), Exposure (total exposure of time of all patients for the Trt.Grp in the Cluster).

sim_type

The type of MCMC method to use for simulating from non-standard distributions. Allowed values are "MH" and "SLICE" for Metropis_Hastings and Slice sampling respectively.

burnin

The burnin period for the monte-carlo simulation. These are discarded from the returned samples.

iter

The total number of iterations for which the monte-carlo simulation is run. This includes the burnin period. The total number of samples returned is iter - burnin

nchains

The number of independent chains to run.

global.sim.params

A data frame containing the parameters for the simuation type sim_type. For "MH" the parameter is the variance of the normal distribution used to simulate the next candidate value centred on the current value. For "SLICE" the parameters are the estimated width of the slice and a value limiting the search for the next sample.

sim.params

A dataframe containing simulation parameters which override the global simulation parameters (global.sim.params) for particular model parameters. sim.params must contain the following columns: type: the simulation type ("MH" or "SLICE"); variable: the model parameter for which the simulation parameters are being overridden; Outcome.Grp (if applicable); Outcome (if applicable); param: the simulation parameter; value: the overridden value; control: the overridden control value.

The function bhpm.sim.control.params generates a template for sim.params which can be edited by the user.

monitor

A dataframe indicating which sets of variables to monitor.

initial_values

The initial values for starting the chains. If NULL (the default) is passed the function generates the initial values for the chains. initial_values is a list with the following format:

list(gamma, theta, mu.gamma, mu.theta, sigma2.gamma,
	sigma2.theta, mu.gamma.0, mu.theta.0, tau2.gamma.0,
	tau2.theta.0)

where each element of the list is either a dataframe or array. The function bhpm.gen.initial.values can be used to generate a template for the list which can be updated by the user if required.

level

The level of dependancy between the clusters. 0 - independent clusters, 1 - common cluster means, 2 - weak dependancy between clusters.

hyper_params

The hyperparameters for the model.

memory_model

Allowed values are "HIGH" and "LOW". "HIGH" means use as much memory as possible. "LOW" means use the minimum amount of memory.

Details

The model is fitted by a Gibbs sampler. The posterior distributions for gamma and theta are sampled with either a Metropolis-Hastings step or a slice sampler.

Value

The output from the simulation including all the sampled values is as follows:

list(id, sim_type, chains, nClusters, Clusters, nOutcome.Grp, maxOutcome.Grps,
	maxOutcomes, nOutcome, Outcome, Outcome.Grp, burnin, iter, monitor,
	mu.gamma.0, mu.theta.0, tau2.gamma.0, tau2.theta.0,
	mu.gamma, mu.theta, sigma2.gamma, sigma2.theta, gamma,
	theta, gamma_acc, theta_acc)

where

id - a string identifying the verion of the function

sim_type - an string identifying the samlping method used for non-standard distributions, either "MH" or "SLICE"

chains - the number of chains for which the simulation was run.

nClusters - the number of clusters in the simulation

Clusters - an array. The clusters.

nOutcome.Grp - the number of outcome groupings.

maxOutcome.Grps - the maximum number of outcome groupings in a cluster.

maxOutcomes - the maximum number of outcomes in an outcome grouping.

nOutcome - an array. The number of outcomes in each outcome grouping.

Outcome - an array of dimension nOutcome.Grp, maxOutcomes. The outcomes.

Outcome.Grp - an array. The outcome groupings.

burnin - burnin used for the simulation.

iter - the total number of iterations in the simulation.

monitor - the variables being monitored. A dataframe.

mu.gamma.0 - array of generated samples.

mu.theta.0 - array of generated samples.

tau2.gamma.0 - array of generated samples.

tau2.theta.0 - array of generated samples.

mu.gamma - array of generated samples.

mu.theta - array of generated samples.

sigma2.gamma - array of generated samples.

sigma2.theta - array of generated samples.

gamma - array of generated samples.

theta - array of generated samples.

gamma_acc - the acceptance rate for the gamma samples if a Metropolis-Hastings method is used.

theta_acc - the acceptance rate for the theta samples if a Metropolis-Hastings method is used.

Note

The function performs the simulation and returns the raw output. No checks for convergence are performed.

Author(s)

R. Carragher

Examples

data(bhpm.cluster.data1)
raw = bhpm.cluster.1a.hier3(bhpm.cluster.data1, level = 1, burnin = 100, iter = 200)

data(bhpm.cluster.data1)
raw = bhpm.cluster.1a.hier3(bhpm.cluster.data1, level = 1)