gkwdist: Generalized Kumaraswamy Distribution Family gkwdist logo

CRAN status R-CMD-check Downloads License:MIT

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")

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.