JAVADOC_AUTOBRIEF      = NO

TAB_SIZE               = 4

/*! \brief Basic MCMC options.

 *

/*! \brief Check if file exists.

 *

  \note Source: http://www.techbytes.ca/techbyte103.html.

/*! \brief Shows command line usage.

/*! \brief Parses command line options.

  \see ShowUsage.

  \see mcmc_options.

  \see myrng.

/*! \brief Main parameter class. 

 *

  /*! \brief Base class constructor

/*! \defgroup steps Implemented MCMC Step Types

 *

 * MCMC algorithms typically consist of many steps.  While users will often want

 * to implement their own step types, Scythe MCMC has implemented several that arise

 * over and over.  MetropStep and SliceStep in particular only require specification of

 * a log density function (minus an unknown constant).

 *

 */

/*! \brief Base step class.

 *

 * \ingroup steps

 *

 *

 * \see GibbsStep

 * \see FunctionStep

 * \see MetropStep

 * \see SliceStep

 * \see Sampler

  /*! \brief Take step.

   *

  /*! \brief Set starting value.

   *

  /*! \brief Return parameter value

   *

   * \return The value of the parameter associated with the step instance.

   * \see Parameter::Value

   */

  /*! \brief Return parameter label

   *

   * \return The label of the parameter associated with the step instance.

   * \see Parameter::Label

   */

  /*! Return the tracking status

   *

   * \return The tracking status of the parameter associated with the step instance.

   * \see Parameter::Track

   */

/*! \brief Gibbs step.

 *

 * \ingroup steps

 *

  /*! \brief Main constructor taking a Parameter object.

  /*! \brief Take a Gibbs step for the parameter.

   *

/*! \brief Deterministic function step.

 *

 * \ingroup steps

 * 

 * Deterministic nodes can be helpful to track summary statistics or to reduce computations through intermediate use

 * of sufficient statistics across multiple parameters.  FunctionStep calls the parameters Parameter::Function method

 * and saves the result using Parameter::Save.

 */

  /*! \brief Main constructor taking a Parameter object.

   *

  /*! \brief Take a function step for the parameter.

   *

  /*! \brief Set function step starting value.

   *

/*! \defgroup proposals Metropolis-Hastings Proposals

 * 

 * The MetropStep Metropolis-Hastings class requires both a Parameter instance

 * and a Proposal instance.  Proposal instances define a Draw and LogDensity method.

 * The constructor should set a tuning parameter.

 *

 * MetroStep::DoStep uses the Draw method to draw new proposed values for the parameter

 * and the LogDensity to calculate the proposal terms in the acceptance \f$\alpha\f$.  For 

 * symmetric proposal distributions returning 0.0 is enough.

 */

/*! \brief Normal proposal for Metropolis-Hastings.

 *

 *  \ingroup proposals

 *

  /*! \brief Constructor

   *

   * \param standard_deviation Tuning parameter for normal proposal.

  /*! \brief Draw from normal proposal

   *

  /*! \brief Log probability of proposal new value, given starting value.

   *

/*! \brief Beta proposal for Metropolis-Hastings.

 *  

 * \ingroup proposals

 *

 * Useful proposal type for parameters with support between 0 and 1.

 *

 * The beta proposal is parameterized using the mean and the inverse denominator.  The denominator

 * is a measure a scale and can be thought of as the number of observed trials bernoulli.  We use the inverse

 * of the denominator so that larger values imply bigger steps, consistent with NormalProposal.  For the Beta distribution

 * the mean is

 * \f[ m = \frac{\alpha}{\alpha + \beta} \f]

 * and the denominator is

 * \f[ d = \alpha + \beta. \f]

 * Therefore

 * \f[ \alpha = m \cdot d \f]

 * and

 * \f[ \beta = d \cdot (1-m). \f]

 *

 */

class BetaProposal {

public:

  /*! \brief Empy constructor */

  BetaProposal() {}

  /*! \brief Main constructor

   *

   * Scale of steps are parameterized using the inverse denominator of a Beta distribution:

   * \f[ \frac{1}{d} = \frac{1}{\alpha + \beta} \f]

   *

   * \param idenominator Tuning parameter equal to the inverse denominator \f$1/d\f$ of a Beta distribution.

   */

  BetaProposal(double idenominator) : {

    denom_ = 1/idenominator;

  }

  /*! \brief Draw from Beta proposal

   *

   * \param starting_value Starting value (mean of Beta distribution).

   */

  double Draw(double starting_value) {

    double alpha_ = starting_value * denom_;

    double beta_ = alpha - denom_;

    return myrng.rbeta(alpha, beta);

  }

  /*! \brief Log probability of proposal new value, given starting value.

   * 

   * \param starting_value Starting value.

   * \param new_value Proposed new value.

   */

  double LogDensity(double new_value, double starting_value) {

    double alpha = starting_value * denom_;

    double beta = alpha - denom_;

    return myrng.dbeta(new_value, alpha, beta);

  }

private:

  double denom_;

};

/*! \brief Log normal proposal for Metropolis-Hastings.

 *  

 * \ingroup proposals

 *

 * Useful proposal type for parameters with support between 0 and positive infinity.

 *

 * For convenience, the log normal proposal is parameterized using the unlogged mean (starting value) 

 * and the (positive) log standard deviation.  This differs from how scythe::dlnorm is parameterized.

 *

 */

class LogNormalProposal {

public:

  /*! \brief Empy constructor */

  LogNormalProposal() {}

  /*! \brief Main constructor

   *

   * Scale of steps are standard deviation of the logged parameter value:

   *

   * \param logsd Tuning parameter equal to the log standard deviation.

   */

  LogNormalProposal(double logsd) : logsd_(logsd) {}

  /*! \brief Draw from log normal proposal

   *

   * \param starting_value Starting value (unlogged mean of log normal).

   */

  double Draw(double starting_value) {

    double logmean = log(starting_value);

    return myrng.rlnorm(logmean, logsd_);

  }

  /*! \brief Log probability of proposal new value, given starting value.

   * 

   * \param starting_value Starting value.

   * \param new_value Proposed new value.

   */

  double LogDensity(double new_value, double starting_value) {

    double logmean = log(starting_value);

    return myrng.dbeta(new_value, logmean, logsd_);

  }

private:

  double logsd_;

};

/*! \brief Metropolis Hastings step

 *

 * \ingroup steps

 * 

 * Basic univariate Metropolis-Hastings step.  Requires both a Parameter and Proposal instance.

 */

  /*! \brief Default constructor, for copy assignments, etc.

   */

  /*! \brief Main constructor taking a Parameter and Proposal object.

   *

  /*! \brief Take a function step for the parameter.

   *

 *

 * \ingroup steps

 *

 * Basic univariate slice sampling step with stepping out and shrinkage. Performs a slice sampling update from an initial

 * point to a new point that leaves invariant the distribution with the specifified log density functions.

 * 

 * The log desnity function may return -Inf for points outside the support of the distribution.

 * If a lower and/or upper bound is specified for the support, the log density function will not be called outside

 * such limits.

 *

 * \note See Neal, R. M (2003) "Slice Sampling" (with discussion), <i>Annals of Statistics</i>,

 * vol. 31, no. 3, pp. 705-767.

 * \note Code and description based on Neal's R code (March 17, 2008): http://www.cs.toronto.edu/~radford/ftp/slice-R-prog

 * \note With poor initial values or choice of w, slice sampling can get take a very long time to find

 * a suitable slice.  This may appear like a crash.  Experimenting with w may speed sampling, but things tends

 * to work pretty well with default values in many cases.

 */

  /*! \brief Main constructor for slice sampling step.

   *

  /*! \brief Take a slice sampling step for the parameter.

   *

 *

  /*! \brief  Constructor to initialize sampler.

   *

   *

  /*! \brief Run sampler for a specific number of iterations.

   *

  /*! \brief Run sampler.

   *

  /*! \brief Number of steps in one sampler iteration.

   *

  /*! \brief Number of tracked steps in one sampler iteration.

   *

/*! \brief Approximately equal.

 *