B {hyperdirichlet} | R Documentation

## Normalizing constant for the hyperdirichlet distribution

### Description

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

### Usage

    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)

### Arguments

`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 `adapt()`
`...` | Further arguments passed to `adapt()`

### Details

- 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 the `adapt()` 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 `adapt()`: 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.

### Value

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.

### Note

The adapt package is no longer available on CRAN: so the `adapt()` function is not available either.

You may be able to install the adapt package notwithstanding its availability on CRAN or is license. If you are happy with this (I am), install the adapt package and everything should work.

I am working on providing a replacement for adapt(), but this is low on my list of priorities. Sorry about this.

### Author(s)

Robin K. S. Hankin

### See Also

`hyperdirichlet`

### Examples

    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)

[Package hyperdirichlet version 1.3-8 Index]