R: Generally-Altered, -Inflated and -Truncated Poisson...

Gaitpois {VGAM} | R Documentation

## 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.

### Usage

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

### Arguments

`x, q, p, n, log.arg` | Same meaning as in `rpois`.
`lambda.p, lambda.a, lambda.i` | Same meaning as in `rpois`, 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.
`alter.mix, inflate.mix` | Vectors of nonnegative integers; the altered, inflated and truncated values for the parametric variant. Each argument must have unique values only. Assigning argument `alter.mix` means that `pobs.mix.a` will be used. Assigning argument `inflate.mix` means that `pstr.mix.i` will be used. If `alter.mix` is of unit length then the default probability mass function (PMF) evaluated at `alter.mix` will be `pobs.mix.a`. So having `alter.mix = 0` corresponds to the zero-inflated Poisson distribution (see `Zipois`).
`alter.mlm, inflate.mlm` | Similar to the above, but for the nonparametric (MLM) variant. Assigning argument `alter.mlm` means that `pobs.mlm.a` will be used. Assigning argument `inflate.mlm` means that `pstr.mlm.i` 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.a, pstr.mlm.i, byrow.arg` | These arguments are coerced into a matrix of probabilities using `byrow.arg` to determine the order of the elements (similar to `matrix`). The first argument is recycled if necessary to become `n x length(alter.mlm)`. The second argument becomes `n x length(inflate.mlm)`. Thus these arguments are not used unless `alter.mlm` and `inflate.mlm` are assigned. If `deflation = TRUE` then `pstr.mlm.i` may be negative.
`pobs.mix.a, pstr.mix.i` | Vectors of probabilities that are recycled if necessary to length n. The first argument is used when `alter.mix` is not `NULL`. The second argument is used when `inflate.mix` is not `NULL`.
`deflation` | Logical. If `TRUE` then `pstr.mlm.i` 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.i` 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.a` and/or `pobs.mlm.a` and the remaining probabilities are rescaled up. Then another different set of probabilities is inflated by an amount `pstr.mlm.i` and/or proportional to `pstr.mix.i` 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 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.

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`, `alter.mix`, `pobs.mix.a`)–Pois(`lambda.i`, `inflate.mix`, `pstr.mix.i`); (ii) GAIT–Pois(`lambda.p`)–MLM(`alter.mlm`, `pobs.mlm.a`)–MLM(`inflate.mlm`, `pstr.mlm.i`). 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.

### Author(s)

T. W. Yee.

### References

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

### See Also

`multinomial`, `gaitpoisson.mlm`, `gaitpoisson.mix`, `Zapois`, `Zipois`, `Pospois` `Poisson`; `Gaitlog`, `Gaitzeta`.

### 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.a = pobs.a,
       pobs.mlm.a = pobs.a, alter.mlm = avec,
       pstr.mix.i = pstr.i, inflate.mix = ivec))
    ## Not run: plot(xgrid, ddd, type = "n", ylab = "Probability", xlab = "x",
                  main = "GAIT PNP Combo PMF---Poisson Parent")
    mylwd <- 0.5
    abline(v = avec, col = 'green', lwd = mylwd)
    abline(v = ivec, col = 'red', 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 = "blue", lwd = 3)  # GAIT PNP combo PMF
    points(xgrid[ddd == 0], ddd[ddd == 0], pch = 16)
    ## End(Not run)

[Package VGAM version 1.1-3 Index]