-------------------------------------------------------------------------------
help for mcmcreg
-------------------------------------------------------------------------------

Syntax

        mcmcreg depvar [indepvars] [if] [in] [weight] , saving(filename)
            d0(#) [options]

    options               Description
    -------------------------------------------------------------------------
    Model
      d0(#)               prior variance of regression error
      noconstant          suppress constant term

    Results
      saving(filename)    filename where results should be stored
      replace             overwrite existing filename

    Markov chain
      iterate(#)          number of iterations in chain; default is
                            iterate(100)
      seed(#)             random number generator seed; default is
                            seed(12345)
      nolog               suppress iteration log
    -------------------------------------------------------------------------

    aweights and fweights are allowed; see weight.

Description

    mcmcreg uses Markov chain Monte Carlo (MCMC) to sample from the posterior
    distribution of a normal linear regression model of depvar on indepvars.

    mcmcreg produces a file of draws from the posterior distribution of the
    model parameters.  Each observation in the file corresponds to an
    iteration of the sampler; each variable represents a different scalar
    parameter.  These variables are named as follows:

      beta_*               Coefficient on independent variable *.
      beta__cons           Intercept (omitted if noconstant is specified).
      sigma2               Variance of regression error.

    The variable iter in the output file keeps track of iterations; iter=0 is
    the initial condition used to start the chain.

Options

        +-------+
    ----+ Model +------------------------------------------------------------

    d0(#) sets the prior variance of the regression errors. Because results
        are potentially sensitive to this prior, you are required to specify
        it yourself; there is no default value.

    noconstant; see [R] estimation options. If noconstant is specified, there
        must be at least one independent variable.

        +---------+
    ----+ Results +----------------------------------------------------------

    saving(filename) designates the location where the results should be
        saved.

    replace specifies that you want to overwrite filename if it already
        exists.

        +--------------+
    ----+ Markov chain +-----------------------------------------------------

    iterate(#) specifies how many iterations the chain should continue for.

    seed(#) sets the random number generator seed. Random numbers are used to
        initialize the sampler; thus, multiple independent chains can be
        obtained by running mcmcreg with different values of seed.

    nolog suppresses printing of an iteration log.

Methods

    mcmcreg uses the Gibbs sampler. Standard uninformative conjugate priors
    are used: The prior for the regression coefficients is uninformative,
    while the prior for the error variance sigma^2 is InverseGamma(1/2,
    d0/2).  See Chib (2001, algorithm 5) for a textbook exposition.

    The sampler is initialized with a guess for sigma^2 drawn from
    InverseGamma((1+df)/2,(d0+SSR)/2), where df is the number of observations
    (or the sum of weights if you use fweights) and SSR is the sum of squared
    residuals from the frequentist least squares regression of depvar on 
    indepvars.

Examples

        . sysuse auto
        . mcmcreg mpg weight foreign, saving(mcmcreg_auto.dta) d0(0.01)
        . use mcmcreg_auto.dta, clear
        . list in 1/5
        . summarize *

    When estimating models by MCMC, it is good practice to check for
    convergence by running multiple independent chains. mcmcreg will generate
    different chains when run repeatedly with different values of seed(#).

        . sysuse auto
        . tempfile temp
        . mcmcreg mpg weight foreign, saving(`temp') d0(0.01) seed(12345)
        . use `temp', clear
        . gen byte chain=1
        . save mcmcreg_auto.dta
        . sysuse auto, clear
        . mcmcreg mpg weight foreign, saving(`temp') d0(0.01) seed(54321)
            replace
        . use `temp', clear
        . gen byte chain=2
        . append using mcmcreg_auto.dta
        . save mcmcreg_auto.dta, replace
        . by chain, sort: summarize *

    See mcmcconverge, available in the SSC package mcmcstats, for useful
    statistics for checking convergence once you have run multiple chains.

    It is also good practice to drop early iterations, before convergence was
    achieved, when describing the posterior distribution.  See mcmcsummarize,
    available in the SSC package mcmcstats, for a convenient way to describe
    the posterior distribution.

Saved results

    mcmcreg saves the following in e():

    Scalars        
      e(N)                number of observations

    Macros         
      e(cmd)              mcmcreg
      e(cmdline)          command as typed
      e(depvar)           name of dependent variable
      e(wtype)            weight type
      e(wexp)             weight expression

    Functions      
      e(sample)           marks estimation sample


Author

    Sam Schulhofer-Wohl, Federal Reserve Bank of Minneapolis,
    sschulh1.work@gmail.com.  The views expressed herein are those of the
    author and not necessarily those of the Federal Reserve Bank of
    Minneapolis or the Federal Reserve System.

Reference

    Chib, Siddhartha, 2001. "Markov Chain Monte Carlo Methods: Computation
        and Inference." In Handbook of Econometrics, vol. 5, ed. James J.
        Heckman and Edward Leamer, 3569-649. Amsterdam: Elsevier.