VGAM: gaitpoisUC – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

gaitpoisUC

Generally–Altered, –Inflated and –Truncated Poisson Distribution

Description

Density, distribution function, quantile function and random generation for the generally–altered, –inflated and –truncated Poisson distribution. Both parametric and nonparametric variants are supported; these are based on finite mixtures of the parent with itself and the multinomial logit model (MLM) respectively. Altogether it can be abbreviated as GAAIIT–Pois(lambda.p)–Pois(lambda.a)–MLM–Pois(lambda.i)–MLM, and it is also known as the GAIT-Pois PNP combo where PNP stands for parametric and nonparametric.

Usage

dgaitpois(x, lambda.p, alt.mix = NULL, alt.mlm = NULL,
          inf.mix = NULL, inf.mlm = NULL, truncate = NULL,
          max.support = Inf, pobs.mix = 0, pobs.mlm = 0,
          pstr.mix = 0, pstr.mlm = 0, byrow.ai = FALSE,
          lambda.a = lambda.p, lambda.i = lambda.p,
          deflation = FALSE, log = FALSE)
pgaitpois(q, lambda.p, alt.mix = NULL, alt.mlm = NULL,
          inf.mix = NULL, inf.mlm = NULL, truncate = NULL,
          max.support = Inf, pobs.mix = 0, pobs.mlm = 0,
          pstr.mix = 0, pstr.mlm = 0, byrow.ai = FALSE,
          lambda.a = lambda.p, lambda.i = lambda.p, lower.tail = TRUE)
qgaitpois(p, lambda.p, alt.mix = NULL, alt.mlm = NULL,
          inf.mix = NULL, inf.mlm = NULL, truncate = NULL,
          max.support = Inf, pobs.mix = 0, pobs.mlm = 0,
          pstr.mix = 0, pstr.mlm = 0, byrow.ai = FALSE,
          lambda.a = lambda.p, lambda.i = lambda.p)
rgaitpois(n, lambda.p, alt.mix = NULL, alt.mlm = NULL,
          inf.mix = NULL, inf.mlm = NULL, truncate = NULL,
          max.support = Inf, pobs.mix = 0, pobs.mlm = 0,
          pstr.mix = 0, pstr.mlm = 0, byrow.ai = FALSE,
          lambda.a = lambda.p, lambda.i = lambda.p)

Arguments

`x, q, p, n`	Same meaning as in `Poisson`.
`log, lower.tail`	Same meaning as in `Poisson`.
`lambda.p, lambda.a, lambda.i`	Same meaning as in `Poisson`, i.e., for an ordinary Poisson distribution. The first is for the main parent (inner) distribution. The other two concern the parametric variant and these outer distributions (usually spikes) may be altered and/or inflated. Short vectors are recycled.
`truncate, max.support`	numeric; these specify the set of truncated values. The default value of `NULL` means an empty set for the former. The latter is the maximum support value so that any value larger has been truncated (necessary because `truncate = (max.support + 1):Inf` is not allowed), hence is needed for truncating the upper tail of the distribution. Note that `max(truncate) < max.support` must be satisfied otherwise an error message will be issued.
`alt.mix, inf.mix`	Vectors of nonnegative integers; the altered, inflated and truncated values for the parametric variant. Each argument must have unique values only. Assigning argument `alt.mix` means that `pobs.mix` will be used. Assigning argument `inf.mix` means that `pstr.mix` will be used. If `alt.mix` is of unit length then the default probability mass function (PMF) evaluated at `alt.mix` will be `pobs.mix`. So having `alt.mix = 0` corresponds to the zero-inflated Poisson distribution (see `Zipois`).
`alt.mlm, inf.mlm`	Similar to the above, but for the nonparametric (MLM) variant. Assigning argument `alt.mlm` means that `pobs.mlm` will be used. Assigning argument `inf.mlm` means that `pstr.mlm` will be used. Collectively, the above 6 arguments represent 5 disjoint sets of special values and they are a proper subset of the support of the distribution.
`pobs.mlm, pstr.mlm, byrow.ai`	The first two arguments are coerced into a matrix of probabilities using `byrow.ai` to determine the order of the elements (similar to `byrow` in `matrix`, and the `.ai` reinforces the behaviour that it applies to both altered and inflated cases). The first argument is recycled if necessary to become `n x length(alt.mlm)`. The second argument becomes `n x length(inf.mlm)`. Thus these arguments are not used unless `alt.mlm` and `inf.mlm` are assigned. If `deflation = TRUE` then `pstr.mlm` may be negative.
`pobs.mix, pstr.mix`	Vectors of probabilities that are recycled if necessary to length n. The first argument is used when `alt.mix` is not `NULL`. The second argument is used when `inf.mix` is not `NULL`.
`deflation`	Logical. If `TRUE` then `pstr.mlm` is allowed to have negative values, however, not too negative so that the final PMF becomes negative. Of course, if the values are negative then they cannot be interpreted as probabilities. In theory, one could also allow `pstr.mix` to be negative, but currently this is disallowed.

Details

These functions allow any combination of 3 operator types: truncation, alteration and inflation. The precedence is truncation, then alteration and lastly inflation. This order minimizes the potential interference among the operators. Loosely, a set of probabilities is set to 0 by truncation and the remaining probabilities are scaled up. Then a different set of probabilities are set to some values pobs.mix and/or pobs.mlm and the remaining probabilities are rescaled up. Then another different set of probabilities is inflated by an amount pstr.mlm and/or proportional to pstr.mix so that individual elements in this set have two sources. Then all the probabilities are rescaled so that they sum to unity.

Both parametric and nonparametric variants are implemented. They usually have arguments with suffix .mix and .mlm respectively. The MLM is a loose coupling that effectively separates the parent (or base) distribution from the altered values. Values inflated nonparametrically effectively have their spikes shaved off. The .mix variant has associated with it lambda.a and lambda.i because it is mixture of 3 Poisson distributions with partitioned or nested support.

Any value of the support of the distribution that is altered, inflated or truncated is called a special value. A special value that is altered may mean that its probability increases or decreases relative to the parent distribution. An inflated special value means that its probability has increased, provided alteration elsewhere has not made it decrease in the first case. There are five types of special values and they are represented by alt.mix, alt.mlm, inf.mix, inf.mlm, truncate.

Jargonwise, the outer distributions concern those special values which are altered or inflated, and the inner distribution concerns the remaining support points that correspond directly to the parent distribution. These functions do what Zapois, Zipois, Pospois collectively did plus much more.

In the notation of Yee and Ma (2020) these functions allow for the special cases: (i) GAIT–Pois(lambda.p)–Pois(lambda.a, alt.mix, pobs.mix)–Pois(lambda.i, inf.mix, pstr.mix); (ii) GAIT–Pois(lambda.p)–MLM(alt.mlm, pobs.mlm)–MLM(inf.mlm, pstr.mlm). Model (i) is totally parametric while model (ii) is the most nonparametric possible.

Value

dgaitpois gives the density, pgaitpois gives the distribution function, qgaitpois gives the quantile function, and rgaitpois generates random deviates. The default values of the arguments correspond to ordinary dpois, ppois, qpois, rpois respectively.

Note

Functions Pospois and those similar have been moved to VGAMdata. It is better to use dgaitpois(x, lambda, truncate = 0) instead of dposbinom(x, lambda), etc.

Author(s)

T. W. Yee.

References

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

Examples

ivec <- c(6, 14); avec <- c(8, 11); lambda <- 10; xgrid <- 0:25
tvec <- 15; max.support <- 20; pobs.a <- 0.05; pstr.i <- 0.25
(ddd <- dgaitpois(xgrid, lambda, lambda.a = lambda + 5,
   truncate = tvec, max.support = max.support, pobs.mix = pobs.a,
   pobs.mlm = pobs.a, alt.mlm = avec,
   pstr.mix = pstr.i, inf.mix = ivec))
## Not run: plot(xgrid, ddd, type = "n", ylab = "Probability", xlab = "x",
              main = "GAIT PNP Combo PMF---Poisson Parent")
mylwd <- 1
abline(v = avec, col = 'blue', lwd = mylwd)
abline(v = ivec, col = 'purple', lwd = mylwd)
abline(v = tvec, col = 'tan', lwd = mylwd)
abline(v = max.support, col = 'magenta', lwd = mylwd)
abline(h = c(pobs.a, pstr.i, 0:1), col = 'gray', lty = "dashed")
lines(xgrid, dpois(xgrid, lambda), col = 'gray', lty = "dashed")  # f_{\pi}
lines(xgrid, ddd, type = "h", col = "pink", lwd = 7)  # GAIT PNP combo PMF
points(xgrid[ddd == 0], ddd[ddd == 0], pch = 16, col = 'tan', cex = 2)  
## End(Not run)

VGAM

Vector Generalized Linear and Additive Models

v1.1-5

GPL-3

Authors

Thomas Yee [aut, cre], Cleve Moler [ctb] (author of several LINPACK routines)

Initial release

2021-01-13