gkwdist: Generalized Kumaraswamy Distribution Family gkwdist logo

Overview

gkwdist implements the Generalized Kumaraswamy (GKw) distribution and its seven nested sub-models for bounded continuous data on $(0,1)$ — proportions, rates, shares, indices. It provides density, distribution, quantile and random generation functions, and analytical log-likelihood, score and Hessian functions, all written in C++ via RcppArmadillo.

Cheat sheet

gkwdist cheat sheet (PDF) · view in the browser

Two pages covering the whole package: the nesting tree, all 49 functions in one matrix, the d/p/q/r contract, a gallery of the shapes the family reaches, the maximum-likelihood recipe, the per-family par ordering, and the nested-model map with likelihood-ratio degrees of freedom.

Installation

# From CRAN
install.packages("gkwdist")

# Development version
# install.packages("devtools")
# devtools::install_github("evandeilton/gkwdist")
install.packages("gkwdist", repos = c('https://evandeilton.r-universe.dev', 'https://cloud.r-project.org'))

The distribution family

Every model below is GKw with parameters held fixed. Follow an edge to fix a parameter and drop to a simpler model.

                           GKw(α, β, γ, δ, λ)
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          │                         │                         │
        λ = 1                   α = β = 1                   γ = 1
          │                         │                         │
   BKw(α, β, γ, δ)             MC(γ, δ, λ)             KKw(α, β, δ, λ)
          │                         │                         │
      α = β = 1                   λ = 1                     δ = 0
          │                         │                         │
     Beta(γ, δ)                Beta(γ, δ)               EKw(α, β, λ)
                                                              │
                                                            λ = 1
                                                              │
                                                          Kw(α, β)

Note: The Beta distribution is obtained from MC by setting $\lambda = 1$, or from GKw by setting $\alpha = \beta = \lambda = 1$. The Kumaraswamy distribution is obtained from EKw by setting $\lambda = 1$, or from GKw by setting $\gamma = 1$, $\delta = 0$, $\lambda = 1$.

All 49 functions

Distribution Code Parameters Functions
Generalized Kumaraswamy gkw $\alpha, \beta, \gamma, \delta, \lambda$ dgkw, pgkw, qgkw, rgkw, llgkw, grgkw, hsgkw
Beta-Kumaraswamy bkw $\alpha, \beta, \gamma, \delta$ dbkw, pbkw, qbkw, rbkw, llbkw, grbkw, hsbkw
Kumaraswamy-Kumaraswamy kkw $\alpha, \beta, \delta, \lambda$ dkkw, pkkw, qkkw, rkkw, llkkw, grkkw, hskkw
Exponentiated Kumaraswamy ekw $\alpha, \beta, \lambda$ dekw, pekw, qekw, rekw, llekw, grekw, hsekw
McDonald (Beta Power) mc $\gamma, \delta, \lambda$ dmc, pmc, qmc, rmc, llmc, grmc, hsmc
Kumaraswamy kw $\alpha, \beta$ dkw, pkw, qkw, rkw, llkw, grkw, hskw
Beta beta_ $\gamma, \delta$ dbeta_, pbeta_, qbeta_, rbeta_, llbeta, grbeta, hsbeta
Uniform — (none) (none — degenerate case)

Note: Uniform is the degenerate 0-parameter case $\alpha = \beta = \gamma = \lambda = 1$, $\delta = 0$. It has no dedicated functions in this package; use base R’s dunif, punif, qunif, runif, or call the GKw functions directly, e.g. dgkw(x, 1, 1, 1, 0, 1).

d*, p*, q* and r* follow the base R convention. ll*, gr* and hs* take (par, data) and return the negative log-likelihood, score and Hessian, so they minimise directly under optim() and hs*() at the estimate is the observed information.

Note the one irregular name: the Beta d/p/q/r keep a trailing underscore so they do not mask stats::dbeta, but the likelihood trio does not — llbeta, not llbeta_.

Quick start

library(gkwdist)

x <- seq(0.01, 0.99, length.out = 100)

dgkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 2, lambda = 1.2)  # density
pgkw(x, 2, 3, 1.5, 2, 1.2)                                          # CDF
qgkw(c(0.25, 0.5, 0.75), 2, 3, 1.5, 2, 1.2)                         # quantiles

set.seed(123)
sample <- rgkw(1000, 2, 3, 1.5, 2, 1.2)                             # simulate

Maximum likelihood, with the analytical gradient and the observed information:

set.seed(2024)
data <- rkw(2000, alpha = 2.5, beta = 3.5)

fit <- optim(
  par     = gkwgetstartvalues(data, family = "kw"),
  fn      = llkw,   # negative log-likelihood
  gr      = grkw,   # negative score
  data    = data,
  method  = "BFGS",
  hessian = TRUE
)

est <- fit$par
se  <- sqrt(diag(solve(fit$hessian)))
cbind(Estimate = est, Lower = est - 1.96 * se, Upper = est + 1.96 * se)

gkwgetstartvalues() returns a named vector already in the order that family’s ll* expects — which differs between families, and is worth checking on the cheat sheet before writing par by hand.

Learn more

References

Citation

citation("gkwdist")

Author

José Evandeilton Lopes LEG - Laboratory of Statistics and Geoinformation PPGMNE - Graduate Program in Numerical Methods in Engineering Federal University of Paraná (UFPR), Brazil Email: evandeilton@gmail.com

License

MIT License. See LICENSE file for details.