B: 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

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()

`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.

`Details`

FunctionB()is the user-friendly version.  It accesses
    theNCslot.  If notNA, the value is returned; ifNA, the normalizing constant is calculated using theadapt()package, viacalculate_B().
FunctionNC()is not intended for the user.  It is used
    internally as an accessor method for theNCslot, and this
    value is returned indiscriminately.
Functioncalculate_B()is the engine which actually
    does the work.  Observe how$p$is converted toe(bye_to_p()) and the integral proceeds over a hypercube.
    Functiondirichlet()andgd()do not use this as the
    normalizing constant has an analytical expression and this is used
    instead.
Functionprobability()gives the probability of an
    observation from a hyperdirichlet distribution satisfying!disallowed(p).
Functionmgf()is the moment generating function,
    taking an argument that specifies the powers ofpneeded: the
    expectation of$\prod_{i=1}^n {p_i}^{{\rm powers}[i]}$is returned.
Functionmean()returns the mean value of the
    hyperdirichlet distribution.  This is computationally slow (considermaximum_likelihood()for a measure of central tendency).  The
    function takes anormalizeargument, not passed toadapt(): this is Boolean withFALSEmeaning to return
    the value found by integration directly, and defaultTRUEmeaning to normalize so the sum is exactly 1
Functionis.proper()checks a hyperdirichlet
    distribution for being normalizable: aproperhyperdirichlet object has a finite integral and therefore can be
    normalized.  This function is quite time-consuming for
    hyperdirichlet distributions of large dimension.
    Theirregardlessargument to functionis.proper()is
    Boolean, withTRUEmeaning to carry out the checks whatever
    the value of slot@validated[that is,validated(x)].
    DefaultFALSEmeans that functionis.proper()returnsTRUEif@validatedisTRUEand to carry out the
    check otherwise.  Use this argument to forceis.proper()to
    carry out a check even if not strictly necessary.
Functionvalidated()is an accessor method for the@validatedslot of hyperdirichlet object.  It returns a
    Boolean variable withTRUEmeaning that the object isknownto beproper(ieis.proper(x)returnsTRUE), so it is normalizable, even if the normalization
    constant is not known.  This flag is present because many
    hyperdirichlet objects of interest are knowna priorito be
    proper, so executingis.proper()would be unnecessary.

`See Also`

hyperdirichlet

`Examples`

Run this codea <- hyperdirichlet(c(4,3,6,5,4,3,2,1))
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
Run the code above in your browser using DataLab