    DIST-SPEC:  Specify a distribution to sample from.

    Dist-spec creates a log file containing the formulas that specify a
    distribution to sample from.  The distribution may be specified by
    giving a formula for the energy (minus the log probability density).
    Alternatively, the distribution may be the Bayesian posterior
    distribution resulting from a specified prior and likelihood.  When
    invoked with just the log file as argument, dist-spec displays the
    specification stored in an existing log file.

    Usage:

        dist-spec log-file { var=formula } energy [ -zero-temper ]

    or:

        dist-spec log-file { var=formula } prior likelihood [ -read-prior ]

    or:

        dist-spec log-file

    Distributions are over a set of real-valued state variables, which
    consist of one of the letters 'u', 'v', 'w', 'x', 'y', or 'z',
    possibly followed by a single digit ('0' to '9').

    Constants may be defined immediately after the log-file argument.
    These have names of the same form as state variables, but starting
    with other lower-case letters.  They may be used in the formulas for
    the energy, minus-log-prior, or minus-log-likelihood.  Constant
    definitions must not refer to state variables, or to inputs or
    targets, but may refer to constants defined earlier.

    In the first form of the dist-spec command, the distribution is given
    by an "energy" function, specified by an arithmetic formula involving
    the state variables that evaluates to minus the log of the probability
    density (plus any arbitrary constant).

    In the second form, the energy function is minus the log of the
    posterior density for a Bayesian model, whose parameters are a subset
    of the state variables (of the same form as described above).  The
    model is specified by giving formulas for minus the log of the prior
    density and for minus the log likelihood for a single observation, or
    for the entire data set.  For both the log prior and the log
    likelihood, constants can be omitted if the objective is only to find
    expectations with respect to the posterior (but constants in the log
    likelihood cannot be omitted if the marginal likelihood is desired).

    The likelihood may be given as a single formula, in which any data
    values are written explicitly, as constants.  In this case, no
    data-spec command should be given later.  More typically, the formula
    given for the likelihood is for one of a set of independent
    observations, which are read from the files specified by a later
    data-spec command (see data-spec.doc).  The inputs for an observation
    are referred to by the names i0, i1, etc., with i being a synonym for
    i0.  The targets are referred to by t0, t1, etc., with t being a
    synonym for t0.  There can be at most ten inputs or targets (ie, up to
    i9 and t9).  These variables are rebound to the inputs and targets for
    each observation in turn, and the formula for minus the log likelihood
    is re-evaluated for each observation.  Note that, by convention, the
    model describes the conditional distribution of the targets (aka the
    response variables), given values for the inputs (aka the predictor
    variables, or covariates), if any.  If no data-spec command is given
    when the likelihood refers to "i" or "t" variables, it is assumed that
    there are no observations, in which case the posterior distribution is
    the same as the prior.

    For the syntax of formulas, see formula.doc.  Although all state
    variables are unbounded real values, the effect of a non-negative
    variable can be obtained by always referring to an appropriately
    transformed version of the variable (eg, Abs(x) or Exp(x)), but note
    that one must then include a term in the energy equal to minus the log
    of the Jacobian of the transformation (though this term is zero for
    Abs(x)).

    For distributions specified by a single energy function, the behaviour
    of tempering methods is controlled by whether the -zero-temper option
    is specified.  If -zero-temper is not specified, the energy at inverse
    temperature b is b*E + (1-b)*N, where E is the specified energy, and N
    is minus the log of the Gaussian probability density function for the
    state variables, with all variables being independent, and having mean
    zero and variance one.  That is,

        N = (D/2) * log(2*Pi) + (1/2) * SUM_i q_i^2

    where D is the number of state variables, and q_i is the value of the
    i'th variable.  If -zero-temper is specified the energy at an inverse
    temperature other than one is found by simply multiplying the energy
    specified in dist-spec by the inverse temperature - ie, it is what
    would be obtained if N above were zero rather than minus the log of
    the Gaussian probability density.  Note that annealed importance
    sampling cannot be used when -zero-temper is specified, since the
    distribution at inverse temperature zero is improper.

    For Bayesian posterior distributions, the various distributions used
    in tempering methods are found by multiplying the log likelihood terms
    by the inverse temperature.  The distribution at inverse temperature
    one is thus the usual posterior, whereas that at inverse temperature
    zero is the prior.

    The 'dist' programs know how to sample from the prior distribution
    only when it is specified as a sum of terms of the form v~D(...),
    where D is one of the parameterized distributions as described in
    formula.doc, and where the parameters of the distribution refer only
    to variables whose distributions are given in earlier terms.  Sampling
    from the prior is needed to perform Annealed Importance Sampling, and
    for sampling initial states in xxx-circ.  Sampling from the prior can
    also be done just for its own interest, or to initialize an ordinary
    Markov chain sampling run.  See dist-gen.doc for how to do this.  If
    the prior does not have the form that allows automatic sampling, prior
    generation can be done only if the -read-prior option is given, in
    which case points from the prior are obtained by reading from standard
    input, which must be a file of points, or a pipe from a separate
    program for sampling from the prior.  See dist-mc.doc for details.

                Copyright (c) 1995-2003 by Radford M. Neal