/usr/include/JAGS/distribution/ArrayDist.h is in jags 4.1.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | #ifndef ARRAY_DIST_H_
#define ARRAY_DIST_H_
#include <distribution/Distribution.h>
#include <vector>
#include <string>
namespace jags {
struct RNG;
/**
* @short Matrix- or array-valued distribution
*
* This is the most general sub-class for distributions and is used
* whenever a distribution takes values in a matrix or
* higher-dimensional array (e.g. Wishart) or has parameters that are
* array-valued (e.g. multivariate normal).
*/
class ArrayDist : public Distribution
{
public:
/**
* Constructor.
* @param name name of the distribution as used in the BUGS language
* @param npar number of parameters, excluding upper and lower bounds
*/
ArrayDist(std::string const &name, unsigned int npar);
/**
* @param x Value at which to evaluate the density.
*
* @param type Indicates whether the full probability density
* function is required (PDF_FULL) or whether partial calculations
* are permitted (PDF_PRIOR, PDF_LIKELIHOOD). See PDFType for
* details.
*
* @param length Size of the array x.
*
* @param parameters Vector of parameter values of the
* distribution.
*
* @param dims Dimensions of the parameters.
*
* @returns The log probability density. If the density should be
* zero because x is inconsistent with the parameters then -Inf is
* returned. If the parameters are invalid
* (i.e. checkParameterValue returns false), then the return value
* is undefined.
*/
virtual double
logDensity(double const *x, unsigned int length, PDFType type,
std::vector<double const *> const ¶meters,
std::vector<std::vector<unsigned int> > const &dims,
double const *lbound, double const *ubound) const = 0;
/**
* Draws a random sample from the distribution.
*
* @param x Array to which the sample values are written
*
* @param length Size of the array x.
*
* @param parameters Parameters for the distribution. This vector
* should be of length npar(). Each element is a pointer to the
* start of an array containing the parameters. The size of the
* array should correspond to the dims parameter.
*
* @param dims Dimensions of the parameters
*
* @param lbound pointer to array containing the lower boundary of
* the distribution. This should be of size length or may be NULL if
* there is no lower boundary.
*
* @param lbound pointer to array containing the upper boundary of
* the distribution. This should be of size length or may be NULL if
* there is no upper boundary.
*
* @param rng pseudo-random number generator to use.
*
* @exception length_error
*/
virtual void
randomSample(double *x, unsigned int length,
std::vector<double const *> const ¶meters,
std::vector<std::vector<unsigned int> > const &dims,
double const *lbound, double const *ubound,
RNG *rng) const = 0;
/**
* Returns a typical value from the distribution. The meaning of
* this will depend on the distribution, but it will normally be a
* mean, median or mode.
*
* @param x Array to which the sample values are written
*
* @param length Size of the array x.
*
* @param parameters Vector of parameter values for the distribution.
* This vector should be of length npar().
*
* @param dims Vector of parameter dimensions.
*
* @exception length_error
*/
virtual void
typicalValue(double *x, unsigned int length,
std::vector<double const *> const ¶meters,
std::vector<std::vector<unsigned int> > const &dims,
double const *lbound, double const *ubound)
const = 0;
/**
* Checks that dimensions of the parameters are correct.
*/
virtual bool
checkParameterDim (std::vector<std::vector<unsigned int> > const ¶meters)
const = 0;
/**
* Checks that the values of the parameters are consistent with
* the distribution. For example, some distributions require than
* certain parameters are positive, or lie in a given range.
*
* This function assumes that checkParameterDim returns true.
*/
virtual bool
checkParameterValue(std::vector<double const *> const ¶meters,
std::vector<std::vector<unsigned int> > const &dims) const = 0;
/**
* Calculates what the dimension of the distribution should be,
* based on the dimensions of its parameters.
*/
virtual std::vector<unsigned int>
dim (std::vector <std::vector<unsigned int> > const &args) const = 0;
/**
* Returns the number of degrees of freedom of the distribution
* given the dimensions of the parameters. By default this is the
* product of the elements of the dimension vector returned by
* ArrayDist#dim. However, some distributions are constrained: and
* the support occupies a lower dimensional subspace. In this
* case, the df member function must be overrideen.
*/
virtual unsigned int df(std::vector<std::vector<unsigned int> > const &dims)
const;
/**
* Returns the support of an unbounded distribution
*/
virtual void
support(double *lower, double *upper, unsigned int length,
std::vector<double const *> const &support,
std::vector<std::vector<unsigned int> > const &dims) const = 0;
/**
* Returns a Monte Carlo estimate of the Kullback-Leibler
* divergence between distributions with two different parameter
* values. This is done by drawing random samples from the
* distribution with the first set of parameters and then
* calculating the log-likelihood ratio with respect to the second
* set of parameters.
*
* A subclass of ArrayDist can overload this function if the
* Kullback-Leibler divergence for the distribution it represents
* can be expressed in closed form.
*
* @param par1 First set of parameters
* @param par2 Second set of parameter values
* @param dims Vector of parameter dimensions, common to both par1 and par2
* @param rng Random number generator
* @param nrep Number of replicates on which to base the estimate
*/
double KL(std::vector<double const *> const &par1,
std::vector<double const *> const &par2,
std::vector<std::vector<unsigned int> > const &dims,
double const *lower, double const *upper,
RNG *rng, unsigned int nrep) const;
/**
* Returns the Kullback-Leibler divergence between distributions
* with two different parameter values.
*
* This is a virtual function that must be overloaded for any
* distribution that allows exact Kullback-Leibler divergence
* calculations. The default method returns JAGS_NA, indicating that
* the method is not implemented.
*/
virtual double KL(std::vector<double const *> const &par1,
std::vector<double const *> const &par2,
std::vector<std::vector<unsigned int> > const &dims)
const;
};
} /* namespace jags */
#endif /* ARRAY_DIST_H_ */
|