dsp: MCMC sampler for day-specific probabilities of conception...

In dpritchLibre/DSP_Package: Immplementation of Dunson day-specific probabilities methodology

Description

dsp is an MCMC sampler for the methodology proposed by Dunson and Stanford in Bayesian Inferences on Predictors of Conception Probabilities (2005).

Usage

dsp(dspDat, nSamp = 10000, nBurn = 0, nThin = 1, hypGam = NULL,
  tuningGam = NULL, hypPhi = NULL, tuningPhi = 0.3,
  trackProg = "percent", progQuants = seq(0.1, 1, 0.1),
  saveToFile = FALSE, outPath = NULL)

Arguments

dspDat	An object of class dspDat.
nSamp	The number of post-burn-in scans for which to perform the sampler.
nBurn	Number of sampler scans included in the burn-in phase.
nThin	Value such that during the post-burn-in phase, only every nThin-th scan is recorded for use in posterior inference. Default of 1 corresponds to every scan being retained.
hypGam	Either NULL or a list containing hyperparameters to be specified for the exponentiated model regression coefficients. None, some, or all of the hyperparameters can be/need be specified. Each exponentiated regression coefficient has a prior defined in terms of 5 hyperparameters. These hyperparameters are the (i) prior probability of the point mass state, the (ii) shape and (iii) rate of the gamma distribution state, and the (iv) lower (v) and upper bounds of the gamma distribution state. If not specified by the function input, then a default value is provided for each of the hyperparameters. These default parameters, correponding to their description in the preceeding paragraph, are (i) 0.5, (ii) 1, (iii) 1, (iv) 0, and (v) Inf. Exponentiated regression coefficient hyperparameter specifications must be provided as follows. If the input to hypGam is NULL, then every hyperparameter is taken to be the default value. If some of the hyperparameters are to be specified, then hypGam must be a list containing a sub-hierarchy of lists; each of these second-level lists must have the name of one of model design matrix variables. Thus if non-NULL, then hypGam is a list containing between 1 and q lists, where q is the number of covariates in the model (after recoding categorical variables to dummy-variable form). Each second-level list in hypGam must contain between 1 and 5 numeric values with possible names (i) p, (ii) a, (iii) b, (iv) bndL, or (v) bndU corresponding to the hyperparameter description from before with matching index. The order of the objects in either level of hypGam does not matter.
tuningGam	Either NULL or a list containing one or more numeric objects each with the name of one of the model design matrix variables; the values are used as tuning parameters for the Metropolis step for regression coeffients corresponding to continuous predictor variables. Categorical variables do not have a Metropolis step and values provided for them are ignored. If NULL, then default values are provided for every regression coefficient (that corresponds to a continuous predictor variable). If some but not all of the tuning parameters for regression coefficients corresponding to continuous predictor variables are provided, then default values are provided for the remaining. The default tuning value for any regression coefficient is 0.25.
hypPhi	Either NULL or a list containing one or two numeric objects with names c1 and/or c2. If supplied, then these values correspond (respectively) to the shape and rate parameters of the prior (gamma) distribution for the variance parameter of the woman-specific fecundability multipliers. If NULL, then default values are provided for both c1 and c2, and if exactly one of either c1 or c2 are provided, then a default value is provided for the other. The default values for c1 and c2 are 1 and 1, respectively.
tuningPhi	Metropolis tuning parameter for the variance parameter of the woman-specific fecundability mulitpliers. The proposal value for this variance parameter is sampled from a uniform distribution with support as determined by the tuning parameter.
trackProg	One of either "none", "percent", or "verbose"; partial matching is supported.
progQuants	Vector with values in (0,1]. Ignored if trackProg is specified as "none". If trackProg is one of "percent" or "verbose" then the specified output is printed whenever the post-burn-in progress of the sampler reaches one of the quantiles specified by progQuants.
saveToFile	logical specifying whether the samples from the post-burn-in phase are to be either written to file or returned as data.frame objects. Note that in either case output characterizing the model is returned by the sampler.
outPath	String specifying the local path into which output files containing the MCMC samples are to be placed. Ignored if saveToFile is FALSE.

Details

Takes preprocessed fertility data in the form of a dspDat object and performs an MCMC sampling algorithm for the Dunson and Stanford day-specific probabilities of conception methodology.

Selection of the covariates to include in the model is performed when creating the dspDat object.

Value

dsp returns a list containing the following objects

formula

Model formula, as passed to the dsp sampler through the input to the dspDat parameter.

hypGam

list containing a sub-hierarchy of lists, each containing the hyperparameter values used for the sampler for the regression coefficients.

tuningGam

********

hypPhi

Hyperparameters for the variance parameter of the woman-specific fecundability multipliers.

tuningPhi

Metropolis tuning parameter used for sampling the variance parameter of the woman-specific fecundability multipliers.

nSamp

Input to nSamp parameter.

nBurn

Input to nBurn parameter.

nThin

Input to nThin parameter.

outPath

If saveToFile specified as TRUE, then the input to outPath parameter.

phi

If saveToFile specified as FALSE, then a vector containing the post-burn-in samples for the variance parameter of the woman-specific fecundability multipliers.

xi

If saveToFile specified as FALSE, then a data.frame containing the post-burn-in samples for the woman-specific fecundability multipliers.

gam

If saveToFile specified as FALSE, then a data.frame containing the post-burn-in samples for the regression coefficients.

Author(s)

David A. Pritchard and Sam Berchuck, 2015

References

Dunson, David B., and Joseph B. Stanford. "Bayesian inferences on predictors of conception probabilities." Biometrics 61.1 (2005): 126-133.

dpritchLibre/DSP_Package documentation built on May 15, 2019, 1:49 p.m.