VGAM (version 1.1-2)

gatpoisson.mlm: Generally-Altered and -Truncated Poisson Regression Family Function (GAT--Pois--MLM Variant)

Description

Fits a generally-altered and -truncated Poisson regression (using a multinomial logit model for the altered values). The truncation may include values in the upper tail.

Usage

gatpoisson.mlm(alter = NULL, truncate = NULL, max.support = Inf,
    zero = NULL, llambda = "loglink", type.fitted = c("mean",
    "lambda", "pobs.a", "Pobs.a", "prob.a", "prob.t"), imethod = 1,
    ilambda = NULL, ishrinkage = 0.95, probs.y = 0.35)

Arguments

alter, truncate

Vector of altered and/or truncated values, i.e., nonnegative integers. Must have unique values only. May be a NULL, which stands for an empty set.

llambda

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 below for more details.

max.support

See Gaitpois.mlm for information. This enables RHS-truncation, i.e., something equivalent to truncate = (U+1):Inf for some upper support point U.

imethod, ilambda

See CommonVGAMffArguments for information.

probs.y, ishrinkage

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.

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 (Greek symbol omegas). The choice type.fitted = "Pobs.a" returns the individual altered probabilities, as a matrix. The choice "prob.a" means the probability of having an altered value, given the estimate of lambda from an ordinary Poisson distribution; it is summed over alter and evaluated at the parent PMF. The choice "prob.t" is similar to "prob.a" but summed over truncate. The use of "prob.a" and "prob.t" is likely to be much less than the use of type.fitted = "pobs.a".

Warning

Due to its flexibility, it is easy to misuse this function; the truncate vector should ideally be not very long and have values that can be justified by the application on hand. Likewise, the alter vector should be short too, and each value should have good justification for being included. Adding unnecessary values to these two arguments willy-nilly is a recipe for disaster.

Regarding truncation, under- or over-flow may occur if the data is ill-conditioned. The response is checked to see that no values equal any values of the truncate vector.

Details

The generally-truncated (GT) Poisson distribution is the ordinary Poisson distribution with the probability of certain values (truncate argument) being zero. Thus the other probabilities are scaled up. The (0-truncated) positive-Poisson distribution is a special case (pospoisson).

This variant of the generally-altered (GA) Poisson distribution is the ordinary Poisson distribution with the probability of certain values (alter argument) being modelled using a multinomial logit model (MLM; see multinomial). The 0-altered Poisson distribution is a special case (zapoisson) and it is called a hurdle model by some people.

This function can fit both the GA and GT models simultaneously, and is called the GAT-Pois--MLM model. That is, each special value is altered or truncated but not both. The default settings make this family function equivalent to poissonff. The probabilities for the altered values are unstructured (nonparametric)---see gatpoisson.mix for an alternative variant that is more structured (parametric).

This function currently does not handle multiple responses. Compared to gipoisson.mlm this family function handles deflation and inflation, therefore handles a wider range of data. For further details please see Gaitpois.mlm.

References

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

See Also

Gaitpois.mlm, gatpoisson.mix, gatnbinomial.mlm, gatnbinomial.mix, gipoisson.mlm, zapoisson, multinomial, rpospois, CommonVGAMffArguments, simulate.vlm.

Examples

# NOT RUN {
avec <- 3    # Alter this value
tvec <- c(5, 7)  # Truncate these values
pobs.a <- logitlink(-2, inverse = TRUE)  # About 0.12
max.support <- 20
gdata <- data.frame(x2 = runif(nn <- 1000))
gdata <- transform(gdata, lambda1 = exp(1 + 0.5 * x2))
gdata <- transform(gdata,
  y1 = rgaitpois.mlm(nn, lambda = lambda1, pobs.a = pobs.a,
                     truncate = tvec, max.support = max.support,
                     byrow = TRUE, alter = avec))
gatpoisson.mlm(alter = avec)
with(gdata, table(y1))
fit1 <- vglm(y1 ~ x2, crit = "coef", trace = TRUE, data = gdata,
             gatpoisson.mlm(alter = avec, truncate = tvec,
                            max.support = max.support))
fit2 <- vglm(y1 ~ x2, crit = "coef", trace = TRUE, data = gdata,
             gatpoisson.mlm(alter = avec, truncate = tvec, zero = "pobs",
                            max.support = max.support))             
head(fitted(fit2))
head(predict(fit2))
coef(fit2, matrix = TRUE)
summary(fit2)
# }