R: Perform inference under model gamma = 1 conditional on mode...

bevimed_m {BeviMed}

R Documentation

Perform inference under model gamma = 1 conditional on mode of inheritance

Description

Sample from posterior distribution of parameters under model gamma = 1 and conditional on mode of inheritance, set via the min_ac argument.

Usage

bevimed_m(
  y,
  G,
  min_ac = 1L,
  tau_shape = c(1, 1),
  pi_shape = c(6, 1),
  omega_shape = if (max(min_ac) == 1L) c(2, 8) else c(2, 2),
  samples_per_chain = 1000,
  stop_early = FALSE,
  blocks = 5,
  burn = as.integer(samples_per_chain/10),
  temperatures = (0:6/6)^2,
  tune_temps = 0,
  vec_sums = FALSE,
  return_z_trace = TRUE,
  return_x_trace = TRUE,
  raw_only = FALSE,
  swaps = as.integer(length(temperatures)/2),
  optimise_z0 = FALSE,
  tune_omega_and_phi_proposal_sd = FALSE,
  tune_block_size = 100,
  variant_weights = NULL,
  standardise_weights = TRUE,
  log_phi_mean = -0.15,
  log_phi_sd = sqrt(0.3),
  tandem_variant_updates = if (max(min_ac) == 1) 0 else min(sum(y), ncol(G)),
  ...
)

Arguments

`y`	Logical vector of case (`TRUE`) control (`FALSE`) status.
`G`	Integer matrix of variant counts per individual, one row per individual and one column per variant.
`min_ac`	Integer vector with a length equalling the number of individuals or length `1` (in which case the given value is used for all individuals) giving the minimum number of alleles at pathogenic variant sites each individual requires in order to classify as having a ‘pathogenic allele configuration’. Thus, this parameter encodes the mode of inheritance. For instance, setting this parameter to `1` corresponds to dominant inheritance. If there are differences in ploidy between individuals in the locus, it is necessary to set it on an sample level basis - e.g. to ensure sex is accounted for if the locus lies on the X chromosome.
`tau_shape`	Beta shape hyper-priors for prior on rate of affection (i.e. being a case) amongst individuals with non-pathogenic variant combinations (i.e. they have less than `min_ac` variants.
`pi_shape`	Beta shape hyper-priors for prior on rate of affection (i.e. being a case) amongst individuals with pathogenic variant combinations (i.e. they have at least `min_ac` variants.
`omega_shape`	Beta shape hyper-priors for prior on rate of pathogenicity amongst variants.
`samples_per_chain`	Number of samples to draw from each chain.
`stop_early`	Logical value determining whether to attempt to stop the sampling as soon as certain conditions are met (i.e. either the estimated marginal log likelihood lies within a certain confidence interval, or we are sufficiently confidence that the log Bayes factor against of model gamma = 1 over model gamma = 0 is sufficiently low).
`blocks`	Maximum number of blocks of `samples_per_chain` samples to draw before either the confidence interval for the marginal likelihood under the model gamma = 1 is sufficiently small or terminating the sampling. This parameter is ignored if unless `stop_early==TRUE`.
`burn`	Number of samples to drop from the start of the chain.
`temperatures`	Numeric vector of temperatures of power posteriors. One chain will be created for each element of the vector at the corresponding temperature.
`tune_temps`	Integer value - if greater than 0, the `temperatures` argument is ignored, and instead `tune_temps` tuned temperatures are used instead.
`vec_sums`	Logical value determining whether to calculate vector summary statistics.
`return_z_trace`	Logical value determining whether to store the z-vectors for each chain, which uses alot of memory, particularly if `samples_per_chain`, k and `length(temperatures)` are large.
`return_x_trace`	Logical value determining whether to store the x variable determined by success samples of z. Potentially uses alot of memory, particularly if `samples_per_chain`, k and `length(temperatures)` are large.
`raw_only`	Logical value determining whether to return raw output of MCMC routine only.
`swaps`	Number of swaps between adjacent tempered chains to perform per update cycle.
`optimise_z0`	Logical value determining whether to use a simulated annealing optimisation run to tune the initial values of `z`.
`tune_omega_and_phi_proposal_sd`	Logical value determining whether the proposal SDs of the Metropolis-Hastings estimated parameters should be tuned for a target acceptance range.
`tune_block_size`	Integer value giving number of samples to draw when estimatating the acceptance rate of the omega/phi proposals.
`variant_weights`	Vector of log-odds off-sets for rates of pathogenicity of individual variants relative to the global rate, omega.
`standardise_weights`	Boolean value determining whether weights should be standardised by subtracting their mean and dividing by their sample standard deviation. If `FALSE`, weights are untransformed.
`log_phi_mean`	Mean for normal prior on scaling factor phi.
`log_phi_sd`	SD for normal prior on scaling factor phi. Setting to 0 causes the weights to be fixed and not estimated.
`tandem_variant_updates`	Number of tandem variant updates to make per update cycle.
`...`	Other arguments to be passed to `stop_chain` and/or `tune_proposal_sds`.

Details

A BeviMed_m object is a list containing elements:

‘parameters’: a list containing arguments used in the function call, including the adjusted weights used in the inference in the ‘c_weights’ slot,
‘traces’: a list of traces of model parameters from all MCMC chains for each parameter. Parameters sampled are z, omega, phi and x (the indicator of having a pathogenic configuration of alleles). The list of traces is named by parameter name, and each is a matrix where the rows correspond to samples. $z has k columns for each temperature, with the samples from the true posterior (i.e. with temperature equal to 1) of z corresponding to the final k columns. Likewise, the true posterior is given by the final column for the traces of phi and omega. The trace of x is only given for temperature equal to 1 to reduce memory usage.
‘final’: a list named by model parameter giving the final sample of each,
‘swaps’: a list with an element named ‘accept’ which is a logical vector whose ith element indicates whether the ith swap between adjacent tempered chains was accepted or not, and an element named 'at_temperature', an integer vector whose ith element indicates which pair of consecutive temperatures was the ith to be proposed for swapping (giving the lowest one).

Value

An object of class BeviMed_m.

References

Greene et al., A Fast Association Test for Identifying Pathogenic Variants Involved in Rare Diseases, The American Journal of Human Genetics (2017), http://dx.doi.org/10.1016/j.ajhg.2017.05.015.