binomialff {VGAM} | R Documentation

## Binomial Family Function

### Description

Family function for fitting generalized linear models to binomial responses, where the dispersion parameter may be known or unknown.

### Usage

    binomialff(link = "logit", earg = list(),
               dispersion = 1, mv = FALSE, onedpar = !mv,
               parallel = FALSE, zero = NULL)

### Arguments

The notation M is used to denote the number of linear/additive predictors.

`link` | Link function. See `Links` for more choices.
`earg` | Extra argument optionally used by the link function. See `Links` for more information.
`dispersion` | Dispersion parameter. By default, maximum likelihood is used to estimate the model because it is known. However, the user can specify `dispersion = 0` to have it estimated, or else specify a known positive value (or values if `mv` is `TRUE`).
`mv` | Multivariate response? If `TRUE`, then the response is interpreted as M independent binary responses, where M is the number of columns of the response matrix. In this case, the response matrix should have zero/one values only. If `FALSE` and the response is a (2-column) matrix, then the number of successes is given in the first column, and the second column is the number of failures.
`onedpar` | One dispersion parameter? If `mv`, then a separate dispersion parameter will be computed for each response (column), by default. Setting `onedpar=TRUE` will pool them so that there is only one dispersion parameter to be estimated.
`parallel` | A logical or formula. Used only if `mv` is `TRUE`. This argument allows for the parallelism assumption whereby the regression coefficients for a variable is constrained to be equal over the M linear/additive predictors.
`zero` | An integer-valued vector specifying which linear/additive predictors are modelled as intercepts only. The values must be from the set {1,2,...,M}, where M is the number of columns of the matrix response.

### Details

If the dispersion parameter is unknown, then the resulting estimate is not fully a maximum likelihood estimate (see pp.124–8 of McCullagh and Nelder, 1989).

A dispersion parameter that is less/greater than unity corresponds to under-/over-dispersion relative to the binomial model. Over-dispersion is more common in practice.

Setting `mv=TRUE` is necessary when fitting a Quadratic RR-VGLM (see `cqo`) because the response is a matrix of M columns (e.g., one column per species). Then there will be M dispersion parameters (one per column of the response matrix).

When used with `cqo` and `cao`, it may be preferable to use the `cloglog` link.

### Value

An object of class `"vglmff"` (see `vglmff-class`). The object is used by modelling functions such as `vglm`, `vgam`, `rrvglm`, `cqo`, and `cao`.

### Warning

With a multivariate response, assigning a known dispersion parameter for each response is not handled well yet. Currently, only a single known dispersion parameter is handled well.

The maximum likelihood estimate will not exist if the data is completely separable or quasi-completely separable. See Chapter 10 of Altman et al. (2004) for more details. Yet to do: add a `sepcheck=TRUE`, say, argument to detect this problem and give an appropriate warning.

### Note

If `mv` is `FALSE` (default), then the response can be of one of three formats: a factor (first level taken as success), a vector of proportions of success, or a 2-column matrix (first column = successes) of counts. The argument `weights` in the modelling function can also be specified. In particular, for a general vector of proportions, you will need to specify `weights` because the number of trials is needed.

If `mv` is `TRUE`, then the matrix response can only be of one format: a matrix of 1's and 0's (1=success).

The call `binomialff(dispersion=0, ...)` is equivalent to `quasibinomialff(...)`. The latter was written so that R users of `quasibinomial()` would only need to add a ```ff`'' to the end of the family function name.

Regardless of whether the dispersion parameter is to be estimated or not, its value can be seen from the output from the `summary()` of the object.

### Author(s)

Thomas W. Yee

### References

McCullagh, P. and Nelder, J. A. (1989) Generalized Linear Models, 2nd ed. London: Chapman & Hall.

Altman, M. and Gill, J. and McDonald, M. P. (2004) Numerical Issues in Statistical Computing for the Social Scientist, Hoboken, NJ: Wiley-Interscience.

### See Also

`quasibinomialff`, `Links`, `rrvglm`, `cqo`, `cao`, `betabinomial`, `zibinomial`, `dexpbinomial`, `mbinomial`, `seq2binomial`, `amlbinomial`, `binomial`.

### Examples

    quasibinomialff()
    quasibinomialff(link="probit")

    fit = vgam(agaaus ~ poly(altitude, 2), binomialff(link=cloglog), hunua)
    ## Not run:
    with(hunua, plot(altitude, agaaus, col="blue", ylab="P(agaaus=1)",
                     main="Presence/absence of Agathis australis", las=1))
    o = with(hunua, order(altitude))
    with(hunua, lines(altitude[o], fitted(fit)[o], col="red", lwd=2))
    ## End(Not run)

[Package VGAM version 0.7-9 Index]