Gaitdpois {VGAM}

Generally Altered, Inflated, Truncated and Deflated Poisson Distribution

Description

Density, distribution function, quantile function and random generation for the generally altered, inflated, truncated and deflated 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.

Usage

dgaitdpois(x, lambda.p, a.mix = NULL, a.mlm = NULL, i.mix = NULL,
       i.mlm = NULL, d.mix = NULL, d.mlm = NULL, truncate = NULL,
       max.support = Inf, pobs.mix = 0, pobs.mlm = 0, pstr.mix = 0,
       pstr.mlm = 0, pdip.mix = 0, pdip.mlm = 0, byrow.aid = FALSE,
       lambda.a = lambda.p, lambda.i = lambda.p,
       lambda.d = lambda.p, log = FALSE)
pgaitdpois(q, lambda.p, a.mix = NULL, a.mlm = NULL, i.mix = NULL,
       i.mlm = NULL, d.mix = NULL, d.mlm = NULL, truncate = NULL,
       max.support = Inf, pobs.mix = 0, pobs.mlm = 0, pstr.mix = 0,
       pstr.mlm = 0, pdip.mix = 0, pdip.mlm = 0, byrow.aid = FALSE,
       lambda.a = lambda.p, lambda.i = lambda.p,
       lambda.d = lambda.p, lower.tail = TRUE, checkd = FALSE)
qgaitdpois(p, lambda.p, a.mix = NULL, a.mlm = NULL, i.mix = NULL,
       i.mlm = NULL, d.mix = NULL, d.mlm = NULL, truncate = NULL,
       max.support = Inf, pobs.mix = 0, pobs.mlm = 0, pstr.mix = 0,
       pstr.mlm = 0, pdip.mix = 0, pdip.mlm = 0, byrow.aid = FALSE,
       lambda.a = lambda.p, lambda.i = lambda.p, lambda.d = lambda.p)
rgaitdpois(n, lambda.p, a.mix = NULL, a.mlm = NULL, i.mix = NULL,
       i.mlm = NULL, d.mix = NULL, d.mlm = NULL, truncate = NULL,
       max.support = Inf, pobs.mix = 0, pobs.mlm = 0, pstr.mix = 0,
       pstr.mlm = 0, pdip.mix = 0, pdip.mlm = 0, byrow.aid = FALSE,
       lambda.a = lambda.p, lambda.i = lambda.p, lambda.d = 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, lambda.d

Same meaning as in Poisson, i.e., for an ordinary Poisson distribution. The first is for the main parent (or base) distribution. The next two concern the parametric variant and these distributions (usually spikes) may be altered and/or inflated. The last one concerns the deflated variant. 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.

a.mix, i.mix, d.mix

Vectors of nonnegative integers; the altered, inflated and deflated values for the parametric variant. Each argument must have unique values only. Assigning argument a.mix means that pobs.mix will be used. Assigning i.mix means that pstr.mix will be used. Assigning d.mix means that pdip.mix will be used. If a.mix is of unit length then the default probability mass function (PMF) evaluated at a.mix will be pobs.mix. So having a.mix = 0 corresponds to the zero-inflated Poisson distribution (see Zipois).

a.mlm, i.mlm, d.mlm

Similar to the above, but for the nonparametric (MLM) variant. For example, assigning a.mlm means that pobs.mlm will be used. Collectively, the above 7 arguments represent 7 disjoint sets of special values and they are a proper subset of the support of the distribution.

pobs.mlm, pstr.mlm, pdip.mlm, byrow.aid

The first three arguments are coerced into a matrix of probabilities using byrow.aid to determine the order of the elements (similar to byrow in matrix, and the .aid reinforces the behaviour that it applies to both altered, inflated and deflated cases). The first argument is recycled if necessary to become n x length(a.mlm). The second argument becomes n x length(i.mlm). The third argument becomes n x length(d.mlm). Thus these arguments are not used unless a.mlm, i.mlm and d.mlm are assigned. For deflated models, pdip.mix and pdip.mlm are positive-valued and VGAM will subtract these quantities; the argument deflation has been deprecated.

pobs.mix, pstr.mix, pdip.mix

Vectors of probabilities that are recycled if necessary to length n. The first argument is used when a.mix is not NULL. The second argument is used when i.mix is not NULL. The third argument is used when d.mix is not NULL.

checkd

Logical. If TRUE then the density is computed at floor(q) with the same parameters. This can help detect whether the PMF is invalid. If so, then NaNs are returned. See Example 2 below.

Details

These functions allow any combination of 4 operator types: truncation, alteration, inflation and deflation. The precedence is truncation, then alteration and lastly inflation and deflation. Informally, deflation can be thought of as the opposite of 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 another different set of probabilities is deflated by an amount pdip.mlm and/or proportional to pdip.mix. 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 and lambda.d because it is mixture of 4 Poisson distributions with partitioned or nested support.

Any value of the support of the distribution that is altered, inflated, truncated or deflated 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 seven types of special values and they are represented by a.mix, a.mlm, i.mix, i.mlm, d.mix, d.mlm, truncate.

Terminology-wise, special values are altered or inflated or truncated or deflated, and the remaining support points that correspond directly to the parent distribution are nonspecial or ordinary. These functions do what Zapois, Zipois, Pospois collectively did plus much more.

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

Value

dgaitdpois gives the density, pgaitdpois gives the distribution function, qgaitdpois gives the quantile function, and rgaitdpois generates random deviates. The default values of the arguments correspond to ordinary dpois, ppois, qpois, rpois respectively.

Warning

It is possible that the GAITD PMF is invalid because of too much inflation and/or deflation. This would result in some probabilities exceeding unity or being negative. Hence x should ideally contain these types of special values so that this can be detected. If so then a NaN is returned and a warning is issued, e.g., same as dnorm(0, 0, sd = -1). To help checking, pgaitdpois(q, ...) calls dgaitdpois(floor(q), ...) if checkd is TRUE.

That is, given the parameters, it is impractical to determine whether the PMF is valid. To do this, one would have to compute the PMF at all values of its support and check that they are nonnegative and sum to unity. Hence one must be careful to input values from the parameter space, especially for inflation and deflation. See Example 2 below.

Note

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

Author(s)

T. W. Yee.

References

Yee, T. W. and Ma, C. (2024). Generally altered, inflated, truncated and deflated regression. Statistical Science, 39 (in press).

See Also

gaitdpoisson, multinomial, specials, spikeplot, dgaitdplot, Zapois, Zipois, Pospois Poisson; Gaitdbinom, Gaitdnbinom, Gaitdlog, Gaitdzeta.

Examples

 # Example 1
ivec <- c(6, 14); avec <- c(8, 11); lambda <- 10; xgrid <- 0:25
tvec <- 15; max.support <- 20; pobs.mix <- 0.05; pstr.i <- 0.25
dvec <- 13; pdip.mlm <- 0.05; pobs.mlm <- 0.05
(ddd <- dgaitdpois(xgrid, lambda, lambda.a = lambda + 5,
   truncate = tvec, max.support = max.support, pobs.mix = pobs.mix,
   pobs.mlm = pobs.mlm, a.mlm = avec,
   pdip.mlm = pdip.mlm, d.mlm = dvec,
   pstr.mix = pstr.i, i.mix = ivec))
## Not run:  dgaitdplot(lambda, ylab = "Probability", xlab = "x",
   truncate = tvec, max.support = max.support, pobs.mix = pobs.mix,
   pobs.mlm = pobs.mlm, a.mlm = avec, all.lwd = 3,
   pdip.mlm = pdip.mlm, d.mlm = dvec,
   pstr.mix = pstr.i, i.mix = ivec, deflation = TRUE,
   main = "GAITD Combo PMF---Poisson Parent")   
## End(Not run)

# Example 2: detection of an invalid PMF
xgrid <- 1:3  # Does not cover the special values purposely
(ddd <- dgaitdpois(xgrid, 1, pdip.mlm = 0.1, d.mlm = 5,
                  pstr.mix = 0.95, i.mix = 0))  # Undetected
xgrid <- 0:13  # Wider range so this detects the problem
(ddd <- dgaitdpois(xgrid, 1, pdip.mlm = 0.1, d.mlm = 5,
                   pstr.mix = 0.95, i.mix = 0))  # Detected
sum(ddd, na.rm = TRUE)  # Something gone awry