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. Each state variable must occur on the left side only once. 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. Similarly, the 'dist-dgen' program knows how to sample from the distribution of target variables when it is specified as a sum of terms of the form v~D(...), with v being one of t, t0, ..., t9. Each target variable must occur on the left side exactly once (noting that t and t0 are actually the same target variable). Copyright (c) 1995-2004 by Radford M. Neal