VGAM (version 1.1-2)

Gaitpois.mlm: Generally-Altered, -Inflated and -Truncated Poisson Distribution (GAIT--Pois--MLM--MLM)

Description

Density, distribution function, quantile function and random generation for the generally-altered, -inflated and -truncated Poisson distribution, based on the multinomial logit model (MLM). This distribution is sometimes abbreviated as GAIT--Pois--MLM--MLM.

Usage

dgaitpois.mlm(x, lambda, alter = NULL, inflate = NULL, truncate = NULL,
              max.support = Inf, pobs.a = 0, pstr.i = 0, byrow.arg = FALSE,
              log.arg = FALSE)
pgaitpois.mlm(q, lambda, alter = NULL, inflate = NULL, truncate = NULL,
              max.support = Inf, pobs.a = 0, pstr.i = 0, byrow.arg = FALSE)
qgaitpois.mlm(p, lambda, alter = NULL, inflate = NULL, truncate = NULL,
              max.support = Inf, pobs.a = 0, pstr.i = 0, byrow.arg = FALSE)
rgaitpois.mlm(n, lambda, alter = NULL, inflate = NULL, truncate = NULL,
              max.support = Inf, pobs.a = 0, pstr.i = 0, byrow.arg = FALSE)

Arguments

x, q, p, n, log.arg

Same meaning as in rpois.

lambda

Same meaning as in rpois, i.e., for an ordinary Poisson distribution. Short vectors are recycled.

alter, inflate, truncate

Vectors of nonnegative integers; the altered, inflated and truncated values. Each argument must have unique values only. The default value of NULL means an empty set. Values in the upper tail of the distribution may be truncated by using max.support.

pstr.i, byrow.arg

The first argument can be a length(inflate)-vector of probabilities; else a matrix of dimension n x length(inflate) of probabilities. If a vector then this matrix is constructed from the vector using byrow.arg to determine the enumeration of the elements (similar to matrix). These arguments are not used unless inflate is assigned.

pobs.a

This argument is similar to pstr.i but is used when alter is assigned a vector. The argument byrow.arg is used similarly to construct a matrix of dimension n x length(alter) of probabilities. This argument is not used unless alter is assigned.

max.support

numeric; the maximum support value so that any value larger has been truncated. This argument is necessary because truncate = (max.support + 1):Inf is impractical, so this is the way to truncate the upper tail of the distribution. Note that max(truncate) < max.support must be satisfied otherwise an error message will be issued.

Value

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

Details

These functions allow any combination of 3 operator types: truncation, alteration and inflation. The precedence of these are 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.a and the remaining probabilities are rescaled up. Then another different set of probabilities is inflated by an amount pstr.i so that individual elements in this set have two sources. Then the remainder of all the probabilities are left unchanged apart from further rescaling.

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 has not made it decrease in the first case.

These functions do what dgapois, dgipois, dgtpois, pgapois, pgipois, pgtpois, qgapois, qgipois, qgtpois, rgapois, rgipois, rgtpois collectively did because the arguments alter, inflate and truncate have been included in one function. The old functions may be relegated to VGAMdata in the future.

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

gatpoisson.mlm, Gaitpois.mix, Gaitnbinom.mlm, Pospois, Poisson.

Examples

# NOT RUN {
avec <- 5:6    # Alter these (special) values
ivec <- 9:10   # Inflate these (special) values
tvec <- 12:14  # Truncate these (special) values
pobs.a <- c(0.1, 0.2)
pstr.i <- (1:2) / 10
lambda <- 15; xx <- 0:22
y <- rgaitpois.mlm(1000, lambda, alter = avec, inflate = ivec,
                     truncate = tvec, max.support = 20,
                     pstr.i = pstr.i, pobs.a = pobs.a, byrow = TRUE)
table(y)
(ii <- dgaitpois.mlm(xx, lambda, alter = avec, inflate = ivec,
                       truncate = tvec, max.support = 20,
                       pstr.i = pstr.i, pobs.a = pobs.a, byrow = TRUE))
# }