R: Generally-Altered Binomial Regression Family Function...

gabinomial.mlm {VGAM} | R Documentation

## Generally-Altered Binomial Regression Family Function (multinomial logit model based; GA-binom-MLM)

### Description

Fits a generally-altered binomial regression (using a multinomial logit model for the altered values).

### Usage

    gabinomial.mlm(alter = 0, zero = NULL, lprob = "logitlink",
        type.fitted = c("mean", "prob", "pobs.a", "Pobs.a"),
        imethod = 1, iprob = NULL)

### Arguments

`alter` | Vector of altered values, i.e., nonnegative integers. Must have unique values only. May be a `NULL`, which stands for empty set (same as `binomialff`). The default is the 0-altered binomial
`lprob` | See `Links` for more choices and information.
`type.fitted` | See `CommonVGAMffArguments` for information. The choice `"pobs.a"` is the probability of an altered value. See `gaitpoisson.mlm` for more details.
`imethod, iprob` | See `CommonVGAMffArguments` for information.

`zero` | See `CommonVGAMffArguments` for information. Setting `zero = "pobs"` will model the multinomial probabilities as simple as possible (intercept-only), hence should be more numerically stable than the default, and this is recommended for many analyses especially when there are many explanatory variables..

### Details

The generally-altered binomial distribution is the ordinary binomial distribution with the probability of certain values (`alter` argument) being modelled using a multinomial logit model. The other values are modelled using a generally-truncated binomial distribution. The 0-altered binomial distribution is a special case and is the default (it is called a hurdle model by some people).

This function implements Fisher scoring and currently does not handle multiple responses. Compared to `gibinomial` (not complete yet) this family function handles deflation and inflation, therefore handles a wider range of data.

### Value

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

The `fitted.values` slot of the fitted object, which should be extracted by the generic function `fitted`, returns the mean mu (default). The choice `type.fitted = "pobs.a"` returns the sum of all the altered probabilities. See `gaitpoisson.mlm` for more details.

### Note

This family function does not yet have the robustness of `multinomial` when computing the working weight matrices. Several improvements are needed, e.g., better labelling and initial values and handling multiple responses.

The default value of `zero` is not the best for most data sets; so assign it a value (see above).

This family function effectively combines `gtbinomial` and `multinomial` into one family function.

### Author(s)

T. W. Yee and Chenchen Ma

### See Also

`Gaitbinom.mlm`, `gtbinomial`, `zabinomial`, `multinomial`, `rposbinom`, `CommonVGAMffArguments`, `simulate.vlm`.

### Examples

    avec <- c(0, 5)  # Alter these values
    Size <- 10
    gdata <- data.frame(x2 = runif(nn <- 1000))
    gdata <- transform(gdata, x3 = runif(nn))
    gdata <- transform(gdata,
               prob1 = logitlink(1 + 2 * x2 + .5 * x3, inverse = TRUE),
               prob2 = logitlink(1 - 1 * x2 + .5 * x3, inverse = TRUE),
               prob3 = logitlink(1, inverse = TRUE))
    gdata <- transform(gdata,
      y1 = rgaitbinom.mlm(nn, prob = prob1, Size, pobs.a = c(0.2, 0.3),
                          byrow = TRUE, alter = avec),
      y2 = rgaitbinom.mlm(nn, prob = prob2, Size, pobs.a = c(0.2, 0.3),
                          byrow = TRUE, alter = avec),
      y3 = rgaitbinom.mlm(nn, prob = prob3, Size, pobs.a = c(0.2, 0.3),
                          byrow = TRUE, alter = avec))
    gabinomial.mlm(alter = avec)
    with(gdata, table(y1))
    with(gdata, table(y2))
    with(gdata, table(y3))

    fit1 <- vglm(cbind(y1, Size-y1) ~ x2 + x3, gabinomial.mlm(alter = avec),
                 crit = "coef", trace = TRUE, data = gdata)
    head(fitted(fit1))
    head(predict(fit1))
    coef(fit1, matrix = TRUE)
    summary(fit1)

    # Another example ------------------------------
    fit3 <- vglm(cbind(y3, Size-y3) ~ 1, gabinomial.mlm(alter = avec),
                 gdata, trace = TRUE)
    coef(fit3, matrix = TRUE)

[Package VGAM version 1.1-3 Index]