Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

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.

See Also

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

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.