1. Home
2. BBINOMIAL procedure

# BBINOMIAL procedure

Estimates the parameters of the beta binomial distribution (D.M. Smith).

### Options

`PRINT` = string tokens Controls printed output (`estimates`, `loglikelihood`); default `esti` Maximum number of iterations; default 50 Convergence criterion; default 10-5

### Parameters

`RBINOMIAL` = variates Numerator of binomial data Denominator of binomial data or scalars Mean, expectation of underlying beta distribution Shape-determining parameter of underlying beta distribution Standard error of mu Standard error of theta Log likelihood Number of iterations Indicator of faults

### Description

`BBINOMIAL` estimates the two parameters of the beta binomial distribution by maximum likelihood, using the methods of Smith (1983) and Smith & Ridout (1995).

The parameters mu and theta are estimated instead of the standard alpha and beta, as they are more “stable” i.e. reliable to estimate. (See Williams 1975.) The relationship is that
mu = alpha / (alpha + beta)
theta = 1 / (alpha + beta)
or
alpha = mu / theta
beta = (1 – mu) / theta

(Note: in the descriptions of the probability functions, `PRBETA` etc, alpha and beta are represented as `a` and `b`.)

The numbers responding are specified in a variate using the `RBINOMIAL` parameter, and the corresponding total numbers are specified by the `NBINOMIAL` parameter in either a variate or a scalar.

Printed output is controlled by the `PRINT` option, with settings:

    `estimates` to print the estimated values of mu and theta, together with the corresponding values, and to print the log-likelihood.

The estimates of the two parameters of the distribution can be saved by the parameters `MU` and `THETA`, and their standard errors can be saved by parameters `SEMU` and `SETHETA`. The `LOGLIKELIHOOD` parameter can save the value of the log-likelihood.

The `NCYCLES` parameter can save the number of iterations that were needed. The `MAXCYCLE` option sets a limit on the total number of iterations (default 50), and the `TOLERANCE` option sets the convergence criterion (default 10-5). The `EXIT` parameter can save a scalar to indicate the success or failure of the estimation, as follows.

0    success.
1    a value of `NBINOMIAL` is less than or equal to 1.
2    all values of `RBINOMIAL` are zero.
3    all values of `RBINOMIAL` are equal to `NBINOMIAL`.
4    a value of `RBINOMIAL` is greater than `NBINOMIAL`.
5    some values of either `RBINOMIAL` or `NBINOMIAL` are less than zero.
6    if either `MU` went outside range 0 to 1 or `THETA` went outside range 0 to infinity, where infinity is the value (106) set inside `BBINOMIAL` to represent infinity.
7    if the maximum number of iterations (`MAXCYCLE`) was exceeded.
8    if the damped Newton-Raphson procedure failed.
9    if the minimum value for `THETA` has been reached and the maximum likelihood estimate of `MU` found, but moving `THETA` away from the minimum value slightly increases the log likelihood. The estimate of `MU` returned is the estimate on the minimum value of `THETA`. The estimates are not then the overall maximum likelihood estimates.

When `EXIT` = 1, 2, 3, 4 or 5 `BBINOMIAL` gives a fault, and `MU`, `THETA`, `SEMU`, `SETHETA` and `LOGLIKELIHOOD` are undefined. When `EXIT` = 6, 7, 8 or 9 `BBINOMIAL` gives a warning, and `MU`, `THETA` and `LOGLIKELIHOOD` are returned with their current values, while `SEMU` and `SETHETA` contain missing values. When `EXIT` = 6 the out-of-range parameter is set to the appropriate limiting value.

Options: `PRINT`, `MAXCYCLE`, `TOLERANCE`.
Parameters: `RBINOMIAL`, `NBINOMIAL`, `MU`, `THETA`, `SEMU`, `SETHETA`, `LOGLIKELIHOOD`, `NCYCLES`, `EXIT`.

### Method

For full details of the methods implemented in these procedures see Smith (1983) and Smith & Ridout (1995). `BBINOMIAL` has four associated procedures `_BBSET`, `_BBME`, `_BBL` and `_BBGDER` that are Genstat implementations of various Fortran subroutines of Smith (1983) and Smith & Ridout (1995). They can also be run independently if desired. `_BBSET` calculates the integer arrays of counts required by `_BBL` and `_BBGDER`. `_BBME` calculates moment estimates of mu and theta. `_BBL` calculates the log likelihood given mu and theta.

### Action with `RESTRICT`

If either `RBINOMIAL` or `NBINOMIAL` are restricted, the analysis will exclude the restricted units.

Kupper, L.L. & Haseman, J.K. (1978). The use of a correlated binomial model for the analysis of toxicological experiments. Biometrics, 34, 69-76.

Smith, D.M. (1983). AS 189. Maximum Likelihood Estimation of the Parameters of the Beta Binomial Distribution. Applied Statistics, 32, 196-204.

Smith, D.M. & Ridout, M.S. (1995). AS R93. A remark on AS 189. Maximum Likelihood Estimation of the Parameters of the Beta Binomial Distribution. Applied Statistics, 44, 545-547.

Williams, D.A. (1975). The analysis of binary responses from toxicological experiments involving reproduction and teratogenicity. Biometrics, 31, 949-952.

Directive: `DISTRIBUTION`.
Procedure: `DPROBABILITY`.
Commands for: Basic and nonparametric statistics.

### Example

```CAPTION   'BBINOMIAL example',\
!t('Data from Smith AS189 (1983) Applied Statistics Algorithm:',\
'1) control data from Kupper & Haseman (1978), Biometrics, 34,',\
'69-76.'); STYLE=meta,plain
VARIATE   rc,nc,rt,nt; values=\
!(0,2,5(0),1,2,1),!(5,6,2(7),3(8),2(9),10),\
!(0,2,1,0,2,3,0,4,1,6),!(2(5),7,3(8),2(9,10))
BBINOMIAL RBINOMIAL=rc; NBINOMIAL=nc; MU=mu; THETA=theta; SEMU=sem;\
SETHETA=seth; LOGLIKELIHOOD=logl; NCYCLES=iter; EXIT=ifault
CAPTION   '2) treatment data from Kupper & Haseman.'
BBINOMIAL RBINOMIAL=rt; NBINOMIAL=nt; MU=mu; THETA=theta; SEMU=sem;\
SETHETA=seth; LOGLIKELIHOOD=logl; NCYCLES=iter; EXIT=ifault
```