stfamily: Families for spatio-temporal GLMs

Description

These functions create family objects for various distributions used in spatio-temporal generalized linear models (STGLMs). Each function returns an object of class "stfamily" describing a (conditional) marginal distribution, a link function, and optional dispersion values. The output is intended only for use within this package and is processed internally in the functions of this package.

Usage

vpoisson(
  link = c("log", "identity", "sqrt", "softplus"),
  const = 1,
  copula = NULL,
  copula_param = NULL,
  sampling_method = c("inversion", "poisson_process")
)
vquasipoisson(
  link = c("log", "identity", "sqrt", "softplus"),
  dispersion = NULL,
  const = 1,
  copula = NULL,
  copula_param = NULL,
  sampling_method = c("build_up", "chop_down", "branching", "negbin")
)
vnegative.binomial(
  link = c("log", "identity", "sqrt", "softplus"),
  dispersion = NULL,
  const = 1,
  copula = NULL,
  copula_param = NULL
)
vbinomial(
  link = c("softclipping", "identity", "logit", "probit"),
  size = 1,
  const = 1,
  copula = NULL,
  copula_param = NULL
)
vquasibinomial(
  link = c("softclipping", "identity", "logit", "probit"),
  size = 1,
  dispersion = NULL,
  const = 1,
  copula = NULL,
  copula_param = NULL
)
vgamma(
  link = c("inverse", "log", "identity"),
  dispersion = NULL,
  copula = NULL,
  copula_param = NULL
)
vinverse.gaussian(
  link = c("1/mu^2", "inverse", "identity", "log"),
  dispersion = NULL,
  copula = NULL,
  copula_param = NULL
)
vnormal(
  link = c("identity", "log", "inverse"),
  dispersion = NULL,
  copula = NULL,
  copula_param = NULL
)

Value

An object of class "stfamily" containing elements such as link, distribution, variance, dev.resids.

Arguments

link: Character string specifying the link function. Options depend on the distribution (see Details).
const: Optional numeric constant used in some link functions.
copula: Optional copula family to model dependence between responses. Has no effect on parameter estimation, but only on situations in which data is generated with this family.
copula_param: Parameter for the copula. (Numeric scalar of length 1)
sampling_method: Sampling algorithm for Poisson and quasi-Poisson.
dispersion: Optional dispersion parameter(s). Can be either a numerical scalar describing a global, time-invariant dispersion parameter, a vector with (temporal) constant dispersion parameters for each location, or a matrix with dispersion parameters for each location and time. (Rows are locations, columns are time points) If NULL, dispersion will be estimated as a scalar where applicable.
size: Number of trials for binomial-type families.

Details

The link argument specifies the link function to be used for the family. The available link functions depend on the distribution:

Poisson, Quasi-Poisson, Negative-Binomial: "log", "identity", "sqrt", "softplus"
Binomial, Quasi-Binomial: "softclipping", "identity", "logit", "probit"
Gamma: "inverse", "log", "identity"
Inverse Gaussian: "1/mu^2", "inverse", "identity", "log"
Gaussian/Normal: "identity", "log", "inverse"

The following families are available:

vpoisson() – Poisson distribution
vquasipoisson() – Quasi-Poisson, i.e. Poisson like, but dispersion can differ from 1
vnegative.binomial() – Negative binomial distribution
vbinomial() – Binomial distribution
vquasibinomial() – Quasi-Binomial, i.e. Binomial like, but dispersion can differ from 1
vgamma() – Gamma distribution
vinverse.gaussian() – Inverse Gaussian distribution
vnormal() – Gaussian distribution
vgarch() – GARCH distribution

The following copulas are available:

"normal" – Gaussian copula
"t" – t copula
"clayton" – Clayton copula
"frank" – Frank copula
"gumbel" – Gumbel copula
"joe" – Joe copula

The data generating processes of each distribution rely on (sequences of) uniform marginals, which are transformed to obtain the observed data. The copula specifies the dependence structure between these uniform marginals. If no copula (copula = NULL) is specified, the uniform marginals are generated independent.

For most distributions, the data generation is based on inversion of the cumulative distribution function (CDF). For the Poisson distribution, two different sampling methods are implemented: sampling_method = "inversion" results in the inversion method using qpois and sampling_method = "poisson_process" implements the Poisson process method described in Fokianos et al. (2020). For a quasi-Poisson model, four different sampling methods are implemented: sampling_method = "build_up", sampling_method = "chop_down", sampling_method = "branching" and sampling_method = "negbin". The first three methods generate data from a generalized Poisson distribution, see Consul and Jain (1973) and are described in Demirtas (2017). The sampling_method = "negbin" uses the Inversion method on properly parameterized negative binomial distribution to generate the data. If the "branching" or "negbin" method is used, only overdispersion can be generated. Dispersion values resulting in underdispersion will be set to 1, i.e. a standard Poisson case. For Quasi-Binomial models, in case of overdispersion, the data is generated from a sequence of positive correlated Bernoulli trials, see Ahn and Chen (1995) for a discussion. In case of underdispersion, data is generated using a normal approximation. In case of the inverse Gaussian distribution, data is generated using the Michael-Schucany-Haas method, see Michael et al. (1976).

Note that for the negative binomial family, the dispersion parameter corresponds to the shape parameter of the negative binomial distribution.

References

Ahn, H., & Chen, J. J. (1995). Generation of Over-Dispersed and Under-Dispersed Binomial Variates. Journal of Computational and Graphical Statistics, 4(1), 55–64. tools:::Rd_expr_doi("10.1080/10618600.1995.10474665")
Consul, P. C., & Jain, G. C. (1973). A Generalization of the Poisson Distribution. Technometrics, 15(4), 791–799. tools:::Rd_expr_doi("10.1080/00401706.1973.10489112")
Demirtas, H. (2017). On accurate and precise generation of generalized Poisson variates. Communications in Statistics - Simulation and Computation, 46(1), 489–499. tools:::Rd_expr_doi("10.1080/03610918.2014.968725")
Fokianos, K., Støve, B., Tjøstheim, D., & Doukhan, P. (2020). Multivariate count autoregression. Bernoulli, 26(1), 471–499. tools:::Rd_expr_doi("10.3150/19-BEJ1132")
Michael, J. R., Schucany, W. R., & Haas, R. W. (1976). Generating Random Variates Using Transformations with Multiple Roots. The American Statistician, 30(2), 88–90. tools:::Rd_expr_doi("10.1080/00031305.1976.10479147")

Examples

Run this code

fam <- vpoisson(link = "log")
print(fam)

fam2 <- vbinomial(link = "logit", size = 10)
print(fam2)

Run the code above in your browser using DataLab