R: Generally-Altered and -Truncated Negative Binomial Regression...

gatnbinomial.mix {VGAM} | R Documentation

## Generally-Altered and -Truncated Negative Binomial Regression Family Function (GAT–NB–NB Mixture Variant)

### Description

Fits a generally-altered and -truncated negative binomial regression (mixture of 2 NBs on differing support). The truncation may include values in the upper tail.

### Usage

    gatnbinomial.mix(alter = NULL, truncate = NULL,
        zero = c("pobs.a", "size"), parallel = FALSE,
        lmunb.p = "loglink", lsize.p = "loglink", lpobs.a = "logitlink",
        lmunb.a = "loglink", lsize.a = "loglink",
        type.fitted =  c("mean", "pobs.a", "Pobs.a",
          "prob.a", "prob.i", "prob.t", "lhs.prob"),
        imethod = 1, imunb.p = NULL, isize.p = NULL,
        ipobs.a = NULL, imunb.a = imunb.p, isize.a = isize.p,
        ishrinkage = 0.95, probs.y = 0.35, cutoff.prob = 0.999,
        eps.trig = 1e-7, max.chunk.MB = 30)

### Arguments

`alter, truncate` | Very similar to `gaitpoisson.mix`. Note: `alter` must be assigned a vector of length 3 or more for this function to work properly. The default settings are effectively equivalent to `negbinomial`. If `length(alter) == 2` then this function will not work due to identifiability problems. In general, the regression tends to be more stable when `length(alter)` is not too small and the values of `alter` are spread out over the entire support.
`lpobs.a, lmunb.p, lmunb.a` | Link functions; the `.p` and `.a` refer to the parent and altered distributions respectively. See `Links` for more choices and information.
`lsize.p, lsize.a` | Same as above.
`parallel, type.fitted` | the latter is Very similar to `gaitpoisson.mix`; the former concerns: constrain the mean and size parameters to be equal? Setting `parallel = TRUE` is probably a good idea for many data sets, especially when `length(alter)` is low and the values of `alter` are not spread out.
`imethod, imunb.p, isize.p` | See `CommonVGAMffArguments` for information.
`imunb.a, isize.a, ipobs.a` | See `CommonVGAMffArguments` for information.
`probs.y, ishrinkage` | See `CommonVGAMffArguments` for information.
`zero` | See `CommonVGAMffArguments` and `gaitpoisson.mix` for information.
`cutoff.prob, eps.trig, max.chunk.MB` | See `negbinomial` for information.

### Details

This distribution, also known as the GAT–NB–NB mixture, is an alternative to `gaitpoisson.mix` and allows for overdispersion relative to the Poisson distribution. Because the `size` parameters are estimated this family function is more difficult to fit and is numerically fraught, in comparison.

The distribution is also a more structured model compared to `gatnbinomial.mlm` because the (outer) distribution of the altered values is also an NB too.

Apart from the ordering of the linear/additive predictors, here are some special cases: `gatnbinomial.mix()` is the same as `negbinomial`, `gatnbinomial.mix(alter = 0)` is the same as `zanegbinomial`, `gatnbinomial.mix(truncate = 0)` is the same as `posnegbinomial`. See `gatnbinomial.mlm` for similar information.

### 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`, are similar to `gatnbinomial.mlm`.

### Warning

The same caution needed for `gatnbinomial.mlm` and `gaitpoisson.mix` applies here, however this function is a bit more parametric (structured) in comparison to `.mlm` functions, especially when `parallel = TRUE`.

### Note

Convergence is rather slow because of an infinite series that is approximated with finite terms. This family function is quite expensive. See also `gaitpoisson.mix`. This family function offers potential for regressing heaped count data.

### Author(s)

T. W. Yee

### References

Yee, T. W. and Ma, C. (2020). Generally–altered, –inflated and –truncated regression, with application to heaped and seeped count data. In preparation.

### See Also

`Gaitnbinom.mix`, `gatnbinomial.mlm`, `gaitpoisson.mix`, `negbinomial`, `posnegbinomial`, `zanegbinomial`, `CommonVGAMffArguments`, `rootogram4`, `simulate.vlm`.

### Examples

    avec <- seq(5, 25, by = 5)  # Alter these values
    tvec <- c(4, 7, 22)   # Truncate these values
    pobs.a <- logitlink(-0.5, inverse = TRUE)  # About 0.5
    gdata <- data.frame(x2 = runif(nn <- 1000))
    gdata <- transform(gdata, munb.p = exp(2 + 0 * x2), size.p = exp(1))
    gdata <- transform(gdata,
      y1 = rgaitnbinom.mix(nn, size.p = size.p, munb.p = munb.p,
             pobs.a = pobs.a, truncate = tvec, alter = avec))
    gatnbinomial.mix(alter = avec)
    (ty1 <- with(gdata, table(y1)))
    ## Not run:
    plot(as.numeric(names(ty1)), c(ty1) / sum(ty1), xlab = "y",
         ylab = "Proportion", las = 1, type = "h", col = "blue")
    fit1 <- vglm(y1 ~ 1, trace = TRUE, data = gdata,
                 gatnbinomial.mix(alter = avec, truncate = tvec,
                                  parallel = TRUE))
    head(fitted(fit1, type.fitted = "Pobs.a"))
    head(predict(fit1))
    coef(fit1, matrix = TRUE)
    summary(fit1)
    ## End(Not run)

[Package VGAM version 1.1-3 Index]