B: Normalizing constant for the hyperdirichlet distribution
In hyperdirichlet: A Generalization of the Dirichlet Distribution

Description Usage Arguments Details Value Note Author(s) See Also Examples

Uses numerical techniques for calculating the normalizing constant for the hyperdirichlet distribution

B(x, ...)
NC(x)
calculate_B(x, disallowed=NULL, give=FALSE, ...)
probability(x, disallowed, ...)
mgf(x, powers, ...)
mean(x, ...)
is.proper(x,irregardless)
validated(x)

`x`	Object of class “hyperdirichlet” (or coerced thereto)
`powers`	Vector of length `dim(x)` whose elements are the powers of the expectation; see details section
`irregardless`	Boolean; see details section
`disallowed`	Function specifying a subset of the simplex over which to integrate; default `NULL` means to integrate over the whole simplex. The integration proceeds over `p` with `disallowed(p)` evaluating to `FALSE`
`give`	Boolean, with default `FALSE` meaning to return the value of the integral and `TRUE` meaning to return the full output of `adaptIntegrate()`
`...`	Further arguments passed to `adaptIntegrate()`

Function B() is the user-friendly version. It accesses the NC slot. If not NA, the value is returned; if NA, the normalizing constant is calculated using adaptIntegrate() of the cubature() package, via calculate_B().
Function NC() is not intended for the user. It is used internally as an accessor method for the NC slot, and this value is returned indiscriminately.
Function calculate_B() is the engine which actually does the work. Observe how p is converted to e (by e_to_p()) and the integral proceeds over a hypercube. Function dirichlet() and gd() do not use this as the normalizing constant has an analytical expression and this is used instead.
Function probability() gives the probability of an observation from a hyperdirichlet distribution satisfying !disallowed(p).
Function mgf() is the moment generating function, taking an argument that specifies the powers of p needed: the expectation of prod p^powers is returned.
Function mean() returns the mean value of the hyperdirichlet distribution. This is computationally slow (consider maximum_likelihood() for a measure of central tendency). The function takes a normalize argument, not passed to adaptIntegrate(): this is Boolean with FALSE meaning to return the value found by integration directly, and default TRUE meaning to normalize so the sum is exactly 1
Function is.proper() checks a hyperdirichlet distribution for being normalizable: a “proper” hyperdirichlet object has a finite integral and therefore can be normalized. This function is quite time-consuming for hyperdirichlet distributions of large dimension.

The irregardless argument to function is.proper() is Boolean, with TRUE meaning to carry out the checks whatever the value of slot @validated [that is, validated(x)]. Default FALSE means that function is.proper() returns TRUE if @validated is TRUE and to carry out the check otherwise. Use this argument to force is.proper() to carry out a check even if not strictly necessary.
Function validated() is an accessor method for the @validated slot of hyperdirichlet object. It returns a Boolean variable with TRUE meaning that the object is known to be “proper” (ie is.proper(x) returns TRUE), so it is normalizable, even if the normalization constant is not known. This flag is present because many hyperdirichlet objects of interest are known a priori to be proper, so executing is.proper() would be unnecessary.

Functions B(), NC(), calculate_NC() notionally return a scalar: the normalization constant

Functions mean() and mgf() return a k-tuple

Functions is.proper() and validated() return a Boolean

Function probability() returns a scalar, a probability.

The adapt package is no longer available on CRAN; from 1.4-3, the package uses adaptIntegrate of the cubature package.

Robin K. S. Hankin

hyperdirichlet

a <- hyperdirichlet(c(4,3,6,5,4,3,2,1))
## Not run: 
B(a)                                    # Not recommended
a <- as.hyperdirichlet(a,TRUE)          # Recommended

is.proper(a)

mgf(a,powers=1:3)    # expectation of p1^1 * p2^2 * p3^3

## End(Not run)