Package 'gkwdist'

Generalized Kumaraswamy Distribution Family

Description

The gkwdist package provides a comprehensive, high-performance implementation of the five-parameter Generalized Kumaraswamy (GKw) distribution and its seven nested sub-families for modeling bounded continuous data on the unit interval $(0,1)$. All distribution and likelihood functions are implemented in C++ via RcppArmadillo for maximum computational efficiency.

Details

Overview

The Generalized Kumaraswamy distribution, proposed by Carrasco, Ferrari and Cordeiro (2010), extends the Kumaraswamy distribution (Jones, 2009) by incorporating three additional shape parameters. This generalization provides remarkable flexibility in accommodating various density shapes including unimodality, asymmetry, J-shapes, inverted J-shapes, U-shapes, bathtub shapes, and heavy or light tails.

That flexibility stops short of bimodality. Across roughly 330,000 parameter vectors spanning $(10^{-3}, 300)$ in each of the five parameters, no density with two interior modes was found: every shape was monotone, unimodal, or U-shaped. A second peak arises only as a divergence at $x = 0$ or $x = 1$ — see the boundary limits documented in dgkw — never as a second interior hump. Data with two separated interior modes calls for a mixture, not a larger member of this family.

Mathematical Specification

The probability density function (PDF) of the GKw distribution with parameters $\theta = (\alpha, \beta, \gamma, \delta, \lambda)$ (all positive) is:

$f(x; \theta) = \frac{\lambda\alpha\beta x^{\alpha-1}}{B(\gamma, \delta + 1)} (1 - x^\alpha)^{\beta-1} [1 - (1 - x^\alpha)^\beta]^{\gamma\lambda-1} \{1 - [1 - (1 - x^\alpha)^\beta]^\lambda\}^\delta$

for $0 < x < 1$, where $B(a,b) = \Gamma(a)\Gamma(b)/\Gamma(a+b)$ is the beta function.

The cumulative distribution function (CDF) is:

$F(x; \theta) = I_{[1-(1-x^\alpha)^\beta]^\lambda}(\gamma, \delta + 1)$

where $I_y(a,b)$ denotes the regularized incomplete beta function ratio.

Distribution Family Hierarchy

The GKw distribution nests seven important sub-models:

Beta-Kumaraswamy (BKw)

4 parameters: $(\alpha, \beta, \gamma, \delta)$. Set $\lambda = 1$ in GKw.

Kumaraswamy-Kumaraswamy (KKw)

4 parameters: $(\alpha, \beta, \delta, \lambda)$. Set $\gamma = 1$ in GKw.

Exponentiated Kumaraswamy (EKw)

3 parameters: $(\alpha, \beta, \lambda)$. Set $\gamma = 1, \delta = 0$ in GKw. Has closed-form quantile function.

McDonald (Mc)

3 parameters: $(\gamma, \delta, \lambda)$. Set $\alpha = \beta = 1$ in GKw. Also known as Beta-Power distribution.

Kumaraswamy (Kw)

2 parameters: $(\alpha, \beta)$. Set $\gamma = 1$, $\delta = 0$ and $\lambda = 1$ in GKw. Has closed-form CDF and quantile function.

Beta

2 parameters: $(\gamma, \delta)$. Set $\alpha = \beta = \lambda = 1$ in GKw. Classical beta distribution with shape1 = gamma, shape2 = delta + 1.

Uniform

0 parameters. Set $\alpha = \beta = \gamma = \lambda = 1$ and $\delta = 0$ in GKw. Note that $\delta = 0$, not $\delta = 1$, is the neutral value: $\delta$ enters the density through $B(\gamma, \delta+1)$ and $z^{\delta}$.

Distribution Functions

The package provides the standard R distribution function API for all seven distributions. Each distribution has four core functions with prefix d, p, q, r:

Generalized Kumaraswamy (GKw):

• dgkw: Density function

• pgkw: Distribution function (CDF)

• qgkw: Quantile function (inverse CDF)

• rgkw: Random generation

Beta-Kumaraswamy (BKw): dbkw, pbkw, qbkw, rbkw

Kumaraswamy-Kumaraswamy (KKw): dkkw, pkkw, qkkw, rkkw

Exponentiated Kumaraswamy (EKw): dekw, pekw, qekw, rekw

McDonald (Mc): dmc, pmc, qmc, rmc

Kumaraswamy (Kw): dkw, pkw, qkw, rkw

Beta: dbeta_, pbeta_, qbeta_, rbeta_

All distribution functions are implemented in C++ for optimal performance.

Likelihood Functions

High-performance analytical log-likelihood, gradient, and Hessian functions are provided for maximum likelihood estimation. These functions return negative values to facilitate direct use with optimization routines like optim, which perform minimization by default.

Function signature: function(par, data) where par is a numeric vector of parameters and data is the observed sample.

ll*

Negative log-likelihood: $-\ell(\theta) = -\sum_{i=1}^n \log f(x_i; \theta)$

gr*

Negative gradient (negative score vector): $-\nabla_\theta \ell(\theta)$

hs*

Negative Hessian matrix: $-\nabla^2_\theta \ell(\theta)$

Available for all distributions:

• GKw: llgkw, grgkw, hsgkw

• BKw: llbkw, grbkw, hsbkw

• KKw: llkkw, grkkw, hskkw

• EKw: llekw, grekw, hsekw

• Mc: llmc, grmc, hsmc

• Kw: llkw, grkw, hskw

• Beta: llbeta, grbeta, hsbeta

These analytical derivatives are exact (up to floating-point precision) and provide substantial performance gains over numerical approximations.

Utility Functions

• gkwgetstartvalues: Compute starting values for optimization using method of moments or quantile matching

Applications

The GKw distribution family is particularly suitable for modeling:

• Proportions and rates: Bounded continuous data in $(0,1)$

• Percentages: Economic indices, market shares, conversion rates

• Fractions: Parts of a whole, concentration measures

• Scores and indices: Normalized measurements, standardized tests

• Reliability data: Component lifetimes on bounded domains

• Hydrological phenomena: Reservoir levels, soil moisture content

• Financial ratios: Debt-to-equity, current ratio, profit margins

• Quality metrics: Defect rates, efficiency scores, purity levels

• Biostatistics: Survival probabilities, dose-response curves

Advantages Over Standard Distributions

Compared to the classical Beta distribution, the GKw family offers:

• Greater flexibility in density shapes (U-shaped, bathtub, J and reverse J)

• Better accommodation of asymmetry and tail behavior

• Closed-form CDF and quantile for some sub-models (Kw, EKw, KKw)

• Computational efficiency via C++ implementation

• Easy parameter interpretation through nested structure

• Superior performance for extreme parameter values

Performance

All functions are implemented in C++ using RcppArmadillo, providing:

• 10-100× speedup over pure R implementations

• Linear scaling with sample size

• Optimized memory allocation

• Numerical stability for extreme parameter values

• Efficient vectorized operations

Typical benchmarks on modern hardware:

• Density evaluation: $>10^7$ evaluations per second

• Log-likelihood: $n = 10^6$ observations in $<100$ms

• Gradient computation: $<5$× slower than log-likelihood

Model Selection Workflow

Recommended strategy for choosing among distributions:

1. Exploratory Analysis: Examine histograms, kernel density estimates, and summary statistics of your data.

2. Start Simple: Fit Beta and Kumaraswamy distributions (2 parameters). Use optim with method = "BFGS" and analytical gradients.

3. Diagnostic Checking: Assess fit quality using Q-Q plots, probability plots, and goodness-of-fit tests (e.g., Kolmogorov-Smirnov).

4. Progressive Complexity: If simple models inadequate, try 3-parameter models (EKw or Mc), then 4-parameter models (BKw or KKw).

5. Information Criteria: Use AIC, BIC, or AICc to balance goodness-of-fit and model parsimony. Lower values indicate better models.

6. Nested Testing: Perform likelihood ratio tests when comparing nested models (e.g., Kw vs. EKw).

7. Cross-Validation: Validate final model on held-out data or via bootstrap procedures.

8. Residual Analysis: Examine probability integral transform residuals for uniformity and independence.

Statistical Inference

Maximum likelihood estimation is performed using numerical optimization:

1. Obtain starting values via gkwgetstartvalues or manual specification based on sample moments

2. Minimize negative log-likelihood using optim with method = "BFGS" or "L-BFGS-B"

3. Provide analytical gradient via gr argument for faster convergence and improved accuracy

4. Set hessian = TRUE to obtain observed information matrix

5. Compute standard errors as sqrt(diag(solve(hessian)))

6. Construct confidence intervals using normal approximation or profile likelihood

7. Perform hypothesis tests using Wald, score, or likelihood ratio statistics

For large samples ($n > 10^4$), consider using method = "L-BFGS-B" with box constraints to prevent parameter estimates from drifting to boundary values or becoming numerically unstable.

Author(s)

Lopes, J. E. [email protected] ORCID: 0009-0007-5887-4084

LEG - Laboratory of Statistics and Geoinformation

PPGMNE - Graduate Program in Numerical Methods in Engineering

Federal University of Paraná (UFPR), Brazil

References

Carrasco, J. M. F., Ferrari, S. L. P., and Cordeiro, G. M. (2010). A new generalized Kumaraswamy distribution. arXiv preprint arXiv:1004.0911. doi:10.48550/arXiv.1004.0911

Jones, M. C. (2009). Kumaraswamy's distribution: A beta-type distribution with some tractability advantages. Statistical Methodology, 6(1), 70-81. doi:10.1016/j.stamet.2008.04.001

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

Cordeiro, G. M., and de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

McDonald, J. B. (1984). Some generalized functions for the size distribution of income. Econometrica, 52(3), 647-663. doi:10.2307/1913469

Eddelbuettel, D., and Francois, R. (2011). Rcpp: Seamless R and C++ Integration. Journal of Statistical Software, 40(8), 1-18. doi:10.18637/jss.v040.i08

Eddelbuettel, D., and Sanderson, C. (2014). RcppArmadillo: Accelerating R with high-performance C++ linear algebra. Computational Statistics & Data Analysis, 71, 1054-1063. doi:10.1016/j.csda.2013.02.005

See Also

Beta for the standard beta distribution, optim for numerical optimization, dbeta for beta distribution functions

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dgkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2)

## Every sub-family is GKw with some parameters fixed
all.equal(dkw(x, alpha = 2, beta = 3), dgkw(x, alpha = 2, beta = 3))
all.equal(dekw(x, 2, 3, 1.2), dgkw(x, 2, 3, gamma = 1, delta = 0, lambda = 1.2))

## Maximum likelihood with the analytic gradient
set.seed(123)
y <- rkw(300, alpha = 2, beta = 3)
optim(c(alpha = 1, beta = 1), llkw, grkw, data = y, method = "L-BFGS-B",
    lower = 1e-04)$par

---

Density of the Beta Distribution (gamma, delta+1 Parameterization)

Description

Computes the probability density function (PDF) for the standard Beta distribution, using a parameterization common in generalized distribution families. The distribution is parameterized by gamma ($\gamma$) and delta ($\delta$), corresponding to the standard Beta distribution with shape parameters shape1 = gamma and shape2 = delta + 1. The distribution is defined on the interval (0, 1).

Usage

dbeta_(x, gamma = 1, delta = 0, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
gamma	First shape parameter (shape1), $\gamma > 0$. Can be a scalar or a vector. Default: 1.0.
delta	Second shape parameter is delta + 1 (shape2), requires $\delta \ge 0$ so that shape2 >= 1. Can be a scalar or a vector. Default: 0.0 (leading to shape2 = 1).
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The probability density function (PDF) calculated by this function corresponds to a standard Beta distribution $Beta(\gamma, \delta+1)$:

$f(x; \gamma, \delta) = \frac{x^{\gamma-1} (1-x)^{(\delta+1)-1}}{B(\gamma, \delta+1)} = \frac{x^{\gamma-1} (1-x)^{\delta}}{B(\gamma, \delta+1)}$

for $0 < x < 1$, where $B(a,b)$ is the Beta function (beta).

This specific parameterization arises as a special case of the five-parameter Generalized Kumaraswamy (GKw) distribution (dgkw) obtained by setting the parameters $\alpha = 1$, $\beta = 1$, and $\lambda = 1$. It is therefore equivalent to the McDonald (Mc)/Beta Power distribution (dmc) with $\lambda = 1$.

Note the difference in the second parameter compared to dbeta, where dbeta(x, shape1, shape2) uses shape2 directly. Here, shape1 = gamma and shape2 = delta + 1.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, gamma, delta). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, matching dbeta with shape1 = gamma and shape2 = delta + 1; depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Johnson, N. L., Kotz, S., & Balakrishnan, N. (1995). Continuous Univariate Distributions, Volume 2 (2nd ed.). Wiley.

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

See Also

dbeta (standard R implementation), dgkw (parent distribution density), dmc (McDonald/Beta Power density), pbeta_, qbeta_, rbeta_.

Other density functions: dbkw(), dekw(), dgkw(), dkkw(), dkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dbeta_(x, gamma = 2, delta = 3)
dbeta_(x, gamma = 2, delta = 3, log = TRUE)

## The package's Beta(gamma, delta) is stats::dbeta with shapes gamma, delta + 1
all.equal(dbeta_(x, 2, 3), stats::dbeta(x, 2, 4))

## The density integrates to one
integrate(dbeta_, 0, 1, gamma = 2, delta = 3, rel.tol = 1e-10)

curve(dbeta_(x, gamma = 2, delta = 3), from = 0, to = 1, ylab = "density")

---

Density of the Beta-Kumaraswamy (BKw) Distribution

Description

Computes the probability density function (PDF) for the Beta-Kumaraswamy (BKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), gamma ($\gamma$), and delta ($\delta$). This distribution is defined on the interval (0, 1).

Usage

dbkw(x, alpha = 1, beta = 1, gamma = 1, delta = 0, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
alpha	Shape parameter alpha > 0. Can be a scalar or a vector. Default: 1.0.
beta	Shape parameter beta > 0. Can be a scalar or a vector. Default: 1.0.
gamma	Shape parameter gamma > 0. Can be a scalar or a vector. Default: 1.0.
delta	Shape parameter delta >= 0. Can be a scalar or a vector. Default: 0.0.
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The probability density function (PDF) of the Beta-Kumaraswamy (BKw) distribution is given by:

$f(x; \alpha, \beta, \gamma, \delta) = \frac{\alpha \beta}{B(\gamma, \delta+1)} x^{\alpha - 1} \bigl(1 - x^\alpha\bigr)^{\beta(\delta+1) - 1} \bigl[1 - \bigl(1 - x^\alpha\bigr)^\beta\bigr]^{\gamma - 1}$

for $0 < x < 1$, where $B(a,b)$ is the Beta function (beta).

The BKw distribution is a special case of the five-parameter Generalized Kumaraswamy (GKw) distribution (dgkw) obtained by setting the parameter $\lambda = 1$. Numerical evaluation is performed using algorithms similar to those for dgkw, ensuring stability.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, alpha, beta, gamma, delta). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

dgkw (parent distribution density), pbkw, qbkw, rbkw (other BKw functions),

Other density functions: dbeta_(), dekw(), dgkw(), dkkw(), dkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dbkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5)
dbkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, log = TRUE)

## BKw is GKw with lambda = 1
all.equal(dbkw(x, 2, 3, 1.5, 0.5), dgkw(x, 2, 3, 1.5, 0.5, lambda = 1))

## The density integrates to one
integrate(dbkw, 0, 1, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5,
    rel.tol = 1e-10)

curve(dbkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5), from = 0,
    to = 1, ylab = "density")

---

Density of the Exponentiated Kumaraswamy (EKw) Distribution

Description

Computes the probability density function (PDF) for the Exponentiated Kumaraswamy (EKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), and lambda ($\lambda$). This distribution is defined on the interval (0, 1).

Usage

dekw(x, alpha = 1, beta = 1, lambda = 1, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
alpha	Shape parameter alpha > 0. Can be a scalar or a vector. Default: 1.0.
beta	Shape parameter beta > 0. Can be a scalar or a vector. Default: 1.0.
lambda	Shape parameter lambda > 0 (exponent parameter). Can be a scalar or a vector. Default: 1.0.
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The probability density function (PDF) of the Exponentiated Kumaraswamy (EKw) distribution is given by:

$f(x; \alpha, \beta, \lambda) = \lambda \alpha \beta x^{\alpha-1} (1 - x^\alpha)^{\beta-1} \bigl[1 - (1 - x^\alpha)^\beta \bigr]^{\lambda - 1}$

for $0 < x < 1$.

The EKw distribution is a special case of the five-parameter Generalized Kumaraswamy (GKw) distribution (dgkw) obtained by setting the parameters $\gamma = 1$ and $\delta = 0$. When $\lambda = 1$, the EKw distribution reduces to the standard Kumaraswamy distribution.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, alpha, beta, lambda). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Nadarajah, S., Cordeiro, G. M., & Ortega, E. M. (2012). The exponentiated Kumaraswamy distribution. Journal of the Franklin Institute, 349(3),

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

dgkw (parent distribution density), pekw, qekw, rekw (other EKw functions),

Other density functions: dbeta_(), dbkw(), dgkw(), dkkw(), dkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dekw(x, alpha = 2, beta = 3, lambda = 1.2)
dekw(x, alpha = 2, beta = 3, lambda = 1.2, log = TRUE)

## EKw is GKw with gamma = 1, delta = 0
all.equal(dekw(x, 2, 3, 1.2), dgkw(x, 2, 3, gamma = 1, delta = 0, lambda = 1.2))

## The density integrates to one
integrate(dekw, 0, 1, alpha = 2, beta = 3, lambda = 1.2, rel.tol = 1e-10)

curve(dekw(x, alpha = 2, beta = 3, lambda = 1.2), from = 0, to = 1, ylab = "density")

---

Density of the Generalized Kumaraswamy Distribution

Description

Computes the probability density function (PDF) for the five-parameter Generalized Kumaraswamy (GKw) distribution, defined on the interval (0, 1).

Usage

dgkw(x, alpha = 1, beta = 1, gamma = 1, delta = 0, lambda = 1, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
alpha	Shape parameter alpha > 0. Can be a scalar or a vector. Default: 1.0.
beta	Shape parameter beta > 0. Can be a scalar or a vector. Default: 1.0.
gamma	Shape parameter gamma > 0. Can be a scalar or a vector. Default: 1.0.
delta	Shape parameter delta >= 0. Can be a scalar or a vector. Default: 0.0.
lambda	Shape parameter lambda > 0. Can be a scalar or a vector. Default: 1.0.
log	Logical; if TRUE, the logarithm of the density is returned. Default: FALSE.

Details

The probability density function of the Generalized Kumaraswamy (GKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), gamma ($\gamma$), delta ($\delta$), and lambda ($\lambda$) is given by:

$f(x; \alpha, \beta, \gamma, \delta, \lambda) = \frac{\lambda \alpha \beta x^{\alpha-1}(1-x^{\alpha})^{\beta-1}} {B(\gamma, \delta+1)} [1-(1-x^{\alpha})^{\beta}]^{\gamma\lambda-1} [1-[1-(1-x^{\alpha})^{\beta}]^{\lambda}]^{\delta}$

for $x \in (0,1)$, where $B(a, b)$ is the Beta function beta.

This distribution was proposed by Carrasco, Ferrari & Cordeiro (2010) and includes several other distributions as special cases:

• Kumaraswamy (Kw): gamma = 1, delta = 0, lambda = 1

• Exponentiated Kumaraswamy (EKw): gamma = 1, delta = 0

• Beta-Kumaraswamy (BKw): lambda = 1

• Generalized Beta type 1 (GB1 - implies McDonald): alpha = 1, beta = 1

• Beta distribution: alpha = 1, beta = 1, lambda = 1

The function includes checks for valid parameters and input values x. It uses numerical stabilization for x close to 0 or 1.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, alpha, beta, gamma, delta, lambda). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Carrasco, J. M. F., Ferrari, S. L. P., & Cordeiro, G. M. (2010). A new generalized Kumaraswamy distribution. arXiv preprint arXiv:1004.0911. doi:10.48550/arXiv.1004.0911

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

pgkw, qgkw, rgkw, dbeta, integrate

Other density functions: dbeta_(), dbkw(), dekw(), dkkw(), dkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dgkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2)
dgkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2, log = TRUE)

## Kumaraswamy is GKw with gamma = 1, delta = 0, lambda = 1 (the defaults)
all.equal(dgkw(x, alpha = 2, beta = 3), dkw(x, alpha = 2, beta = 3))

## Beta(gamma, delta + 1) is GKw with alpha = beta = lambda = 1
all.equal(dgkw(x, gamma = 2, delta = 3), stats::dbeta(x, 2, 4))

## The density integrates to one
integrate(dgkw, 0, 1, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5,
    lambda = 1.2, rel.tol = 1e-10)

curve(dgkw(x, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2),
    from = 0, to = 1, ylab = "density")

---

Density of the Kumaraswamy-Kumaraswamy (KKw) Distribution

Description

Computes the probability density function (PDF) for the Kumaraswamy-Kumaraswamy (KKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), delta ($\delta$), and lambda ($\lambda$). This distribution is defined on the interval (0, 1).

Usage

dkkw(x, alpha = 1, beta = 1, delta = 0, lambda = 1, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
alpha	Shape parameter alpha > 0. Can be a scalar or a vector. Default: 1.0.
beta	Shape parameter beta > 0. Can be a scalar or a vector. Default: 1.0.
delta	Shape parameter delta >= 0. Can be a scalar or a vector. Default: 0.0.
lambda	Shape parameter lambda > 0. Can be a scalar or a vector. Default: 1.0.
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The Kumaraswamy-Kumaraswamy (KKw) distribution is a special case of the five-parameter Generalized Kumaraswamy distribution (dgkw) obtained by setting the parameter $\gamma = 1$.

The probability density function is given by:

$f(x; \alpha, \beta, \delta, \lambda) = (\delta + 1) \lambda \alpha \beta x^{\alpha - 1} (1 - x^\alpha)^{\beta - 1} \bigl[1 - (1 - x^\alpha)^\beta\bigr]^{\lambda - 1} \bigl\{1 - \bigl[1 - (1 - x^\alpha)^\beta\bigr]^\lambda\bigr\}^{\delta}$

for $0 < x < 1$. Note that $1/(\delta+1)$ corresponds to the Beta function term $B(1, \delta+1)$ when $\gamma=1$.

Numerical evaluation follows similar stability considerations as dgkw.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, alpha, beta, delta, lambda). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

dgkw (parent distribution density), pkkw, qkkw, rkkw, dbeta

Other density functions: dbeta_(), dbkw(), dekw(), dgkw(), dkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dkkw(x, alpha = 2, beta = 3, delta = 0.5, lambda = 1.2)
dkkw(x, alpha = 2, beta = 3, delta = 0.5, lambda = 1.2, log = TRUE)

## KKw is GKw with gamma = 1
all.equal(dkkw(x, 2, 3, 0.5, 1.2), dgkw(x, 2, 3, gamma = 1, delta = 0.5,
    lambda = 1.2))

## The density integrates to one
integrate(dkkw, 0, 1, alpha = 2, beta = 3, delta = 0.5, lambda = 1.2,
    rel.tol = 1e-10)

curve(dkkw(x, alpha = 2, beta = 3, delta = 0.5, lambda = 1.2), from = 0,
    to = 1, ylab = "density")

---

Density of the Kumaraswamy (Kw) Distribution

Description

Computes the probability density function (PDF) for the two-parameter Kumaraswamy (Kw) distribution with shape parameters alpha ($\alpha$) and beta ($\beta$). This distribution is defined on the interval (0, 1).

Usage

dkw(x, alpha = 1, beta = 1, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
alpha	Shape parameter alpha > 0. Can be a scalar or a vector. Default: 1.0.
beta	Shape parameter beta > 0. Can be a scalar or a vector. Default: 1.0.
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The probability density function (PDF) of the Kumaraswamy (Kw) distribution is given by:

$f(x; \alpha, \beta) = \alpha \beta x^{\alpha-1} (1 - x^\alpha)^{\beta-1}$

for $0 < x < 1$, $\alpha > 0$, and $\beta > 0$.

The Kumaraswamy distribution is identical to the Generalized Kumaraswamy (GKw) distribution (dgkw) with parameters $\gamma = 1$, $\delta = 0$, and $\lambda = 1$. It is also a special case of the Exponentiated Kumaraswamy (dekw) with $\lambda = 1$, and the Kumaraswamy-Kumaraswamy (dkkw) with $\delta = 0$ and $\lambda = 1$.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, alpha, beta). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

Jones, M. C. (2009). Kumaraswamy's distribution: A beta-type distribution with some tractability advantages. Statistical Methodology, 6(1), 70-81. doi:10.1016/j.stamet.2008.04.001

See Also

dgkw (parent distribution density), dekw, dkkw, pkw, qkw, rkw (other Kw functions), dbeta

Other density functions: dbeta_(), dbkw(), dekw(), dgkw(), dkkw(), dmc()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dkw(x, alpha = 2, beta = 3)
dkw(x, alpha = 2, beta = 3, log = TRUE)

## Closed form: alpha * beta * x^(alpha - 1) * (1 - x^alpha)^(beta - 1)
all.equal(dkw(x, 2, 3), 2 * 3 * x * (1 - x^2)^2)

## The density integrates to one
integrate(dkw, 0, 1, alpha = 2, beta = 3, rel.tol = 1e-10)

curve(dkw(x, alpha = 2, beta = 3), from = 0, to = 1, ylab = "density")

---

Density of the McDonald (Mc)/Beta Power Distribution

Description

Computes the probability density function (PDF) for the McDonald (Mc) distribution (also previously referred to as Beta Power) with parameters gamma ($\gamma$), delta ($\delta$), and lambda ($\lambda$). This distribution is defined on the interval (0, 1).

Usage

dmc(x, gamma = 1, delta = 0, lambda = 1, log = FALSE)

Arguments

x	Vector of quantiles (values between 0 and 1).
gamma	Shape parameter gamma > 0. Can be a scalar or a vector. Default: 1.0.
delta	Shape parameter delta >= 0. Can be a scalar or a vector. Default: 0.0.
lambda	Shape parameter lambda > 0. Can be a scalar or a vector. Default: 1.0.
log	Logical; if TRUE, the logarithm of the density is returned ($\log(f(x))$). Default: FALSE.

Details

The probability density function (PDF) of the McDonald (Mc) distribution is given by:

$f(x; \gamma, \delta, \lambda) = \frac{\lambda}{B(\gamma,\delta+1)} x^{\gamma \lambda - 1} (1 - x^\lambda)^\delta$

for $0 < x < 1$, where $B(a,b)$ is the Beta function (beta).

The Mc distribution is a special case of the five-parameter Generalized Kumaraswamy (GKw) distribution (dgkw) obtained by setting the parameters $\alpha = 1$ and $\beta = 1$. It was introduced by McDonald (1984) and is related to the Generalized Beta distribution of the first kind (GB1). When $\lambda=1$, it simplifies to the standard Beta distribution with parameters $\gamma$ and $\delta+1$.

Value

A vector of density values ($f(x)$) or log-density values ($\log(f(x))$). The length of the result is determined by the recycling rule applied to the arguments (x, gamma, delta, lambda). Returns 0 (or -Inf if log = TRUE) for x strictly outside the interval [0, 1]. At the closed boundaries x = 0 and x = 1 the limiting density is returned rather than 0, following the convention of base R's density functions (compare dbeta); depending on the parameters that limit is 0, a finite positive value, or Inf. An out-of-bound or missing parameter is an error, not a return value: the wrapper stops with a message naming the parameter. An infinite parameter is not currently intercepted there and reaches the C++ layer, which treats it as invalid.

Author(s)

Lopes, J. E.

References

McDonald, J. B. (1984). Some generalized functions for the size distribution of income. Econometrica, 52(3), 647-663. doi:10.2307/1913469

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

dgkw (parent distribution density), pmc, qmc, rmc (other Mc functions), dbeta

Other density functions: dbeta_(), dbkw(), dekw(), dgkw(), dkkw(), dkw()

Examples

x <- c(0.1, 0.3, 0.5, 0.7, 0.9)
dmc(x, gamma = 0.5, delta = 5, lambda = 3)
dmc(x, gamma = 0.5, delta = 5, lambda = 3, log = TRUE)

## Mc is GKw with alpha = beta = 1
all.equal(dmc(x, 0.5, 5, 3), dgkw(x, 1, 1, 0.5, 5, 3))

## The density integrates to one
integrate(dmc, 0, 1, gamma = 0.5, delta = 5, lambda = 3, rel.tol = 1e-10)

curve(dmc(x, gamma = 0.5, delta = 5, lambda = 3), from = 0, to = 1, ylab = "density")

---

Estimate Distribution Parameters Using Method of Moments

Description

Estimates parameters for various distribution families from the Generalized Kumaraswamy family using the method of moments. The implementation is optimized for numerical stability and computational efficiency through Nelder-Mead optimization and adaptive numerical integration.

Usage

gkwgetstartvalues(x, family = "gkw", n_starts = 5L)

Arguments

x	Numeric vector of observations. All values must be in the open interval (0,1). Values outside it – including exact 0 and exact 1 – are truncated to the interval so that a single boundary observation does not abort a fit, and a warning naming the number of truncated observations and their observed range is issued. Truncation shifts every sample moment and therefore every estimate returned, so treat the warning as a signal to check the scale of the data rather than as noise: values such as 5 or -3 usually mean a percentage or 0-100 scale that has to be rescaled first. NA and non-finite values are dropped without a warning.
family	Character string specifying the distribution family. Valid options are: "gkw" (Generalized Kumaraswamy - 5 parameters), "bkw" (Beta-Kumaraswamy - 4 parameters), "kkw" (Kumaraswamy-Kumaraswamy - 4 parameters), "ekw" (Exponentiated Kumaraswamy - 3 parameters), "mc" (McDonald - 3 parameters), "kw" (Kumaraswamy - 2 parameters), "beta" (Beta - 2 parameters). The string is case-insensitive. Default is "gkw".
n_starts	Integer specifying the number of different initial parameter values to try during optimization. Every starting point is optimized and the candidate with the smallest objective is returned, so more starting points can only improve the fit, at a cost that grows linearly in n_starts. Default is 5. Four fixed, family-specific starting points are always used, so values below 4 behave as 4.

Details

The function uses the method of moments to estimate distribution parameters by minimizing the weighted sum of squared relative errors between theoretical and sample moments (orders 1 through 5). The optimization employs the Nelder-Mead simplex algorithm, which is derivative-free and particularly robust for this problem.

Key implementation features: logarithmic calculations for numerical stability, adaptive numerical integration using Simpson's rule with fallback to trapezoidal rule, multiple starting points to avoid local minima, decreasing weights for higher-order moments (1.0, 0.8, 0.6, 0.4, 0.2), and automatic parameter constraint enforcement.

Multiple starts: the grid of starting points is built from four fixed, family-specific points – one of them derived from the sample moments – plus n_starts - 4 further points drawn over the family's parameter box. Nelder-Mead is run from every point in the grid, each result is clipped to the parameter box, and the clipped candidate with the smallest objective is returned. Because the candidate set grows with n_starts, the returned objective is non-increasing in n_starts.

Determinism: the extra starting points are drawn from a generator with a fixed internal seed, deliberately not from R's random number stream. The function is therefore deterministic – two calls with the same x, family and n_starts return the same vector, so a fit seeded by these values is reproducible without any further precaution. Two consequences are worth stating explicitly: set.seed has no effect on gkwgetstartvalues, and the function neither reads nor advances .Random.seed, so it cannot perturb simulations running alongside it. To widen the search, raise n_starts rather than looking for a seed argument.

Parameter Constraints: All parameters are constrained to positive values. Additionally, family-specific constraints are enforced: alpha and beta in (0.1, 50.0), gamma in (0.1, 10.0) for GKw-related families or (0.1, 50.0) for Beta, delta in (0.01, 10.0), and lambda in (0.1, 20.0).

The function will issue warnings for empty input vectors, observations outside the open interval (0,1) (truncated to it), sample sizes less than 10 (unreliable estimation), or failure to find valid parameter estimates (returns defaults).

Value

Named numeric vector containing the estimated parameters for the specified distribution family. Parameter names correspond to the distribution specification. If estimation fails, returns a vector of NA values with appropriate parameter names.

References

Jones, M. C. (2009). Kumaraswamy's distribution: A beta-type distribution with some tractability advantages. Statistical Methodology, 6(1), 70-81. doi:10.1016/j.stamet.2008.04.001

See Also

llgkw, llbkw, llkkw, llekw, llmc, llkw, llbeta (the objectives these values are meant to seed), optim

Examples

# Generate sample data from a Beta distribution. set.seed() here makes the
# SAMPLE reproducible; gkwgetstartvalues() itself is deterministic and is
# unaffected by the seed (see the Determinism note in Details).
set.seed(123)
x <- rbeta(100, shape1 = 2, shape2 = 3)

# Estimate Beta parameters
params_beta <- gkwgetstartvalues(x, family = "beta")
print(params_beta)

# Estimate Kumaraswamy parameters
params_kw <- gkwgetstartvalues(x, family = "kw")
print(params_kw)

# Estimate GKw parameters with more starting points
params_gkw <- gkwgetstartvalues(x, family = "gkw", n_starts = 10)
print(params_gkw)

# Deterministic: the seed in force does not change the answer, and the
# function does not consume draws from R's stream.
set.seed(1)
identical(gkwgetstartvalues(x, family = "kw"), params_kw)
set.seed(9999)
identical(gkwgetstartvalues(x, family = "kw"), params_kw)

before <- .Random.seed
invisible(gkwgetstartvalues(x, family = "kw"))
identical(before, .Random.seed)

---

Gradient of the Negative Log-Likelihood for the Beta Distribution (gamma, delta+1 Parameterization)

Description

Computes the gradient vector (vector of first partial derivatives) of the negative log-likelihood function for the standard Beta distribution, using a parameterization common in generalized distribution families. The distribution is parameterized by gamma ($\gamma$) and delta ($\delta$), corresponding to the standard Beta distribution with shape parameters shape1 = gamma and shape2 = delta + 1. The gradient is useful for optimization algorithms.

Usage

grbeta(par, data)

Arguments

par	A numeric vector of length 2 containing the distribution parameters in the order: gamma ($\gamma > 0$), delta ($\delta \ge 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

This function calculates the gradient of the negative log-likelihood for a Beta distribution with parameters shape1 = gamma ($\gamma$) and shape2 = delta + 1 ($\delta+1$). The components of the gradient vector ($-\nabla \ell(\theta | \mathbf{x})$) are:

$-\frac{\partial \ell}{\partial \gamma} = n[\psi(\gamma) - \psi(\gamma+\delta+1)] - \sum_{i=1}^{n}\ln(x_i)$

$-\frac{\partial \ell}{\partial \delta} = n[\psi(\delta+1) - \psi(\gamma+\delta+1)] - \sum_{i=1}^{n}\ln(1-x_i)$

where $\psi(\cdot)$ is the digamma function (digamma). These formulas represent the derivatives of $-\ell(\theta)$, consistent with minimizing the negative log-likelihood. They correspond to the relevant components of the general GKw gradient (grgkw) evaluated at $\alpha=1, \beta=1, \lambda=1$. Note the parameterization: the standard Beta shape parameters are $\gamma$ and $\delta+1$.

Value

Returns a numeric vector of length 2 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \gamma, -\partial \ell/\partial \delta)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Johnson, N. L., Kotz, S., & Balakrishnan, N. (1995). Continuous Univariate Distributions, Volume 2 (2nd ed.). Wiley.

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

(Note: Specific gradient formulas might be derived or sourced from additional references).

See Also

grgkw, grmc (related gradients), llbeta (negative log-likelihood function), hsbeta (Hessian), dbeta_, pbeta_, qbeta_, rbeta_, optim, grad (for numerical gradient comparison), digamma.

Other gradient functions: grbkw(), grekw(), grgkw(), grkkw(), grkw(), grmc()

Examples

set.seed(123)
x <- rbeta_(200, gamma = 2, delta = 3)
par <- c(gamma = 2, delta = 3)

## Gradient of the negative log-likelihood llbeta(), not of the log-likelihood
g <- grbeta(par, x)
g

## A small step against the gradient lowers llbeta()
llbeta(par - 1e-4 * g, x) < llbeta(par, x)

## Agrees with a numerical derivative of llbeta()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llbeta, par, data = x), tolerance = 1e-6)

---

Gradient of the Negative Log-Likelihood for the BKw Distribution

Description

Computes the gradient vector (vector of first partial derivatives) of the negative log-likelihood function for the Beta-Kumaraswamy (BKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), gamma ($\gamma$), and delta ($\delta$). This distribution is the special case of the Generalized Kumaraswamy (GKw) distribution where $\lambda = 1$. The gradient is typically used in optimization algorithms for maximum likelihood estimation.

Usage

grbkw(par, data)

Arguments

par	A numeric vector of length 4 containing the distribution parameters in the order: alpha ($\alpha > 0$), beta ($\beta > 0$), gamma ($\gamma > 0$), delta ($\delta \ge 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

The components of the gradient vector of the negative log-likelihood ($-\nabla \ell(\theta | \mathbf{x})$) for the BKw ($\lambda=1$) model are:

$-\frac{\partial \ell}{\partial \alpha} = -\frac{n}{\alpha} - \sum_{i=1}^{n}\ln(x_i) + \sum_{i=1}^{n}\left[x_i^{\alpha} \ln(x_i) \left(\frac{\beta(\delta+1)-1}{v_i} - \frac{(\gamma-1) \beta v_i^{\beta-1}}{w_i}\right)\right]$

$-\frac{\partial \ell}{\partial \beta} = -\frac{n}{\beta} - (\delta+1)\sum_{i=1}^{n}\ln(v_i) + \sum_{i=1}^{n}\left[\frac{(\gamma-1) v_i^{\beta} \ln(v_i)}{w_i}\right]$

$-\frac{\partial \ell}{\partial \gamma} = n[\psi(\gamma) - \psi(\gamma+\delta+1)] - \sum_{i=1}^{n}\ln(w_i)$

$-\frac{\partial \ell}{\partial \delta} = n[\psi(\delta+1) - \psi(\gamma+\delta+1)] - \beta\sum_{i=1}^{n}\ln(v_i)$

where:

• $v_i = 1 - x_i^{\alpha}$

• $w_i = 1 - v_i^{\beta} = 1 - (1-x_i^{\alpha})^{\beta}$

• $\psi(\cdot)$ is the digamma function (digamma).

These formulas represent the derivatives of $-\ell(\theta)$, consistent with minimizing the negative log-likelihood. They correspond to the general GKw gradient (grgkw) components for $\alpha, \beta, \gamma, \delta$ evaluated at $\lambda=1$. Note that the component for $\lambda$ is omitted. Numerical stability is maintained through careful implementation.

Value

Returns a numeric vector of length 4 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \alpha, -\partial \ell/\partial \beta, -\partial \ell/\partial \gamma, -\partial \ell/\partial \delta)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

(Note: Specific gradient formulas might be derived or sourced from additional references).

See Also

grgkw (parent distribution gradient), llbkw (negative log-likelihood for BKw), hsbkw (Hessian for BKw), dbkw (density for BKw), optim, grad (for numerical gradient comparison), digamma.

Other gradient functions: grbeta(), grekw(), grgkw(), grkkw(), grkw(), grmc()

Examples

set.seed(123)
x <- rbkw(200, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5)
par <- c(alpha = 2, beta = 3, gamma = 1.5, delta = 0.5)

## Gradient of the negative log-likelihood llbkw(), not of the log-likelihood
g <- grbkw(par, x)
g

## A small step against the gradient lowers llbkw()
llbkw(par - 1e-4 * g, x) < llbkw(par, x)

## Agrees with a numerical derivative of llbkw()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llbkw, par, data = x), tolerance = 1e-6)

---

Gradient of the Negative Log-Likelihood for the EKw Distribution

Description

Computes the gradient vector (vector of first partial derivatives) of the negative log-likelihood function for the Exponentiated Kumaraswamy (EKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), and lambda ($\lambda$). This distribution is the special case of the Generalized Kumaraswamy (GKw) distribution where $\gamma = 1$ and $\delta = 0$. The gradient is useful for optimization.

Usage

grekw(par, data)

Arguments

par	A numeric vector of length 3 containing the distribution parameters in the order: alpha ($\alpha > 0$), beta ($\beta > 0$), lambda ($\lambda > 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

The components of the gradient vector of the negative log-likelihood ($-\nabla \ell(\theta | \mathbf{x})$) for the EKw ($\gamma=1, \delta=0$) model are:

$-\frac{\partial \ell}{\partial \alpha} = -\frac{n}{\alpha} - \sum_{i=1}^{n}\ln(x_i) + \sum_{i=1}^{n}\left[x_i^{\alpha} \ln(x_i) \left(\frac{\beta-1}{v_i} - \frac{(\lambda-1) \beta v_i^{\beta-1}}{w_i}\right)\right]$

$-\frac{\partial \ell}{\partial \beta} = -\frac{n}{\beta} - \sum_{i=1}^{n}\ln(v_i) + \sum_{i=1}^{n}\left[\frac{(\lambda-1) v_i^{\beta} \ln(v_i)}{w_i}\right]$

$-\frac{\partial \ell}{\partial \lambda} = -\frac{n}{\lambda} - \sum_{i=1}^{n}\ln(w_i)$

where:

• $v_i = 1 - x_i^{\alpha}$

• $w_i = 1 - v_i^{\beta} = 1 - (1-x_i^{\alpha})^{\beta}$

These formulas represent the derivatives of $-\ell(\theta)$, consistent with minimizing the negative log-likelihood. They correspond to the relevant components of the general GKw gradient (grgkw) evaluated at $\gamma=1, \delta=0$.

Value

Returns a numeric vector of length 3 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \alpha, -\partial \ell/\partial \beta, -\partial \ell/\partial \lambda)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Nadarajah, S., Cordeiro, G. M., & Ortega, E. M. (2012). The exponentiated Kumaraswamy distribution. Journal of the Franklin Institute, 349(3),

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

(Note: Specific gradient formulas might be derived or sourced from additional references).

See Also

grgkw (parent distribution gradient), llekw (negative log-likelihood for EKw), hsekw (Hessian for EKw), dekw (density for EKw), optim, grad (for numerical gradient comparison).

Other gradient functions: grbeta(), grbkw(), grgkw(), grkkw(), grkw(), grmc()

Examples

set.seed(123)
x <- rekw(200, alpha = 2, beta = 3, lambda = 1.2)
par <- c(alpha = 2, beta = 3, lambda = 1.2)

## Gradient of the negative log-likelihood llekw(), not of the log-likelihood
g <- grekw(par, x)
g

## A small step against the gradient lowers llekw()
llekw(par - 1e-4 * g, x) < llekw(par, x)

## Agrees with a numerical derivative of llekw()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llekw, par, data = x), tolerance = 1e-6)

---

Gradient of the Negative Log-Likelihood for the GKw Distribution

Description

Computes the gradient vector (vector of partial derivatives) of the negative log-likelihood function for the five-parameter Generalized Kumaraswamy (GKw) distribution. This provides the analytical gradient, often used for efficient optimization via maximum likelihood estimation.

Usage

grgkw(par, data)

Arguments

par	A numeric vector of length 5 containing the distribution parameters in the order: alpha ($\alpha > 0$), beta ($\beta > 0$), gamma ($\gamma > 0$), delta ($\delta \ge 0$), lambda ($\lambda > 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

The components of the gradient vector of the negative log-likelihood ($-\nabla \ell(\theta | \mathbf{x})$) are:

$-\frac{\partial \ell}{\partial \alpha} = -\frac{n}{\alpha} - \sum_{i=1}^{n}\ln(x_i) + \sum_{i=1}^{n}\left[x_i^{\alpha} \ln(x_i) \left(\frac{\beta-1}{v_i} - \frac{(\gamma\lambda-1) \beta v_i^{\beta-1}}{w_i} + \frac{\delta \lambda \beta v_i^{\beta-1} w_i^{\lambda-1}}{z_i}\right)\right]$

$-\frac{\partial \ell}{\partial \beta} = -\frac{n}{\beta} - \sum_{i=1}^{n}\ln(v_i) + \sum_{i=1}^{n}\left[v_i^{\beta} \ln(v_i) \left(\frac{\gamma\lambda-1}{w_i} - \frac{\delta \lambda w_i^{\lambda-1}}{z_i}\right)\right]$

$-\frac{\partial \ell}{\partial \gamma} = n[\psi(\gamma) - \psi(\gamma+\delta+1)] - \lambda\sum_{i=1}^{n}\ln(w_i)$

$-\frac{\partial \ell}{\partial \delta} = n[\psi(\delta+1) - \psi(\gamma+\delta+1)] - \sum_{i=1}^{n}\ln(z_i)$

$-\frac{\partial \ell}{\partial \lambda} = -\frac{n}{\lambda} - \gamma\sum_{i=1}^{n}\ln(w_i) + \delta\sum_{i=1}^{n}\frac{w_i^{\lambda}\ln(w_i)}{z_i}$

where:

• $v_i = 1 - x_i^{\alpha}$

• $w_i = 1 - v_i^{\beta} = 1 - (1-x_i^{\alpha})^{\beta}$

• $z_i = 1 - w_i^{\lambda} = 1 - [1-(1-x_i^{\alpha})^{\beta}]^{\lambda}$

• $\psi(\cdot)$ is the digamma function (digamma).

Numerical stability is ensured through careful implementation, including checks for valid inputs and handling of intermediate calculations involving potentially small or large numbers, often leveraging the Armadillo C++ library for efficiency.

Value

Returns a numeric vector of length 5 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \alpha, -\partial \ell/\partial \beta, -\partial \ell/\partial \gamma, -\partial \ell/\partial \delta, -\partial \ell/\partial \lambda)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Carrasco, J. M. F., Ferrari, S. L. P., & Cordeiro, G. M. (2010). A new generalized Kumaraswamy distribution. arXiv preprint arXiv:1004.0911. doi:10.48550/arXiv.1004.0911

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

llgkw (negative log-likelihood), hsgkw (Hessian matrix), dgkw (density), optim, grad (for numerical gradient comparison), digamma

Other gradient functions: grbeta(), grbkw(), grekw(), grkkw(), grkw(), grmc()

Examples

set.seed(123)
x <- rgkw(200, alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2)
par <- c(alpha = 2, beta = 3, gamma = 1.5, delta = 0.5, lambda = 1.2)

## Gradient of the negative log-likelihood llgkw(), not of the log-likelihood
g <- grgkw(par, x)
g

## A small step against the gradient lowers llgkw()
llgkw(par - 1e-4 * g, x) < llgkw(par, x)

## Agrees with a numerical derivative of llgkw()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llgkw, par, data = x), tolerance = 1e-6)

---

Gradient of the Negative Log-Likelihood for the KKw Distribution

Description

Computes the gradient vector (vector of first partial derivatives) of the negative log-likelihood function for the Kumaraswamy-Kumaraswamy (KKw) distribution with parameters alpha ($\alpha$), beta ($\beta$), delta ($\delta$), and lambda ($\lambda$). This distribution is the special case of the Generalized Kumaraswamy (GKw) distribution where $\gamma = 1$. The gradient is typically used in optimization algorithms for maximum likelihood estimation.

Usage

grkkw(par, data)

Arguments

par	A numeric vector of length 4 containing the distribution parameters in the order: alpha ($\alpha > 0$), beta ($\beta > 0$), delta ($\delta \ge 0$), lambda ($\lambda > 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

The components of the gradient vector of the negative log-likelihood ($-\nabla \ell(\theta | \mathbf{x})$) for the KKw ($\gamma=1$) model are:

$-\frac{\partial \ell}{\partial \alpha} = -\frac{n}{\alpha} - \sum_{i=1}^{n}\ln(x_i) + (\beta-1)\sum_{i=1}^{n}\frac{x_i^{\alpha}\ln(x_i)}{v_i} - (\lambda-1)\sum_{i=1}^{n}\frac{\beta v_i^{\beta-1} x_i^{\alpha}\ln(x_i)}{w_i} + \delta\sum_{i=1}^{n}\frac{\lambda w_i^{\lambda-1} \beta v_i^{\beta-1} x_i^{\alpha}\ln(x_i)}{z_i}$

$-\frac{\partial \ell}{\partial \beta} = -\frac{n}{\beta} - \sum_{i=1}^{n}\ln(v_i) + (\lambda-1)\sum_{i=1}^{n}\frac{v_i^{\beta}\ln(v_i)}{w_i} - \delta\sum_{i=1}^{n}\frac{\lambda w_i^{\lambda-1} v_i^{\beta}\ln(v_i)}{z_i}$

$-\frac{\partial \ell}{\partial \delta} = -\frac{n}{\delta+1} - \sum_{i=1}^{n}\ln(z_i)$

$-\frac{\partial \ell}{\partial \lambda} = -\frac{n}{\lambda} - \sum_{i=1}^{n}\ln(w_i) + \delta\sum_{i=1}^{n}\frac{w_i^{\lambda}\ln(w_i)}{z_i}$

where:

• $v_i = 1 - x_i^{\alpha}$

• $w_i = 1 - v_i^{\beta} = 1 - (1-x_i^{\alpha})^{\beta}$

• $z_i = 1 - w_i^{\lambda} = 1 - [1-(1-x_i^{\alpha})^{\beta}]^{\lambda}$

These formulas represent the derivatives of $-\ell(\theta)$, consistent with minimizing the negative log-likelihood. They correspond to the general GKw gradient (grgkw) components for $\alpha, \beta, \delta, \lambda$ evaluated at $\gamma=1$. Note that the component for $\gamma$ is omitted. Numerical stability is maintained through careful implementation.

Value

Returns a numeric vector of length 4 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \alpha, -\partial \ell/\partial \beta, -\partial \ell/\partial \delta, -\partial \ell/\partial \lambda)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Cordeiro, G. M., & de Castro, M. (2011). A new family of generalized distributions. Journal of Statistical Computation and Simulation, 81(7), 883-898. doi:10.1080/00949650903530745

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

See Also

grgkw (parent distribution gradient), llkkw (negative log-likelihood for KKw), hskkw (Hessian for KKw), dkkw (density for KKw), optim, grad (for numerical gradient comparison).

Other gradient functions: grbeta(), grbkw(), grekw(), grgkw(), grkw(), grmc()

Examples

set.seed(123)
x <- rkkw(200, alpha = 2, beta = 3, delta = 0.5, lambda = 1.2)
par <- c(alpha = 2, beta = 3, delta = 0.5, lambda = 1.2)

## Gradient of the negative log-likelihood llkkw(), not of the log-likelihood
g <- grkkw(par, x)
g

## A small step against the gradient lowers llkkw()
llkkw(par - 1e-4 * g, x) < llkkw(par, x)

## Agrees with a numerical derivative of llkkw()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llkkw, par, data = x), tolerance = 1e-6)

---

Gradient of the Negative Log-Likelihood for the Kumaraswamy (Kw) Distribution

Description

Computes the gradient vector (vector of first partial derivatives) of the negative log-likelihood function for the two-parameter Kumaraswamy (Kw) distribution with parameters alpha ($\alpha$) and beta ($\beta$). This provides the analytical gradient often used for efficient optimization via maximum likelihood estimation.

Usage

grkw(par, data)

Arguments

par	A numeric vector of length 2 containing the distribution parameters in the order: alpha ($\alpha > 0$), beta ($\beta > 0$).
data	A numeric vector of observations. All values must be strictly between 0 and 1 (exclusive).

Details

The components of the gradient vector of the negative log-likelihood ($-\nabla \ell(\theta | \mathbf{x})$) for the Kw model are:

$-\frac{\partial \ell}{\partial \alpha} = -\frac{n}{\alpha} - \sum_{i=1}^{n}\ln(x_i) + (\beta-1)\sum_{i=1}^{n}\frac{x_i^{\alpha}\ln(x_i)}{v_i}$

$-\frac{\partial \ell}{\partial \beta} = -\frac{n}{\beta} - \sum_{i=1}^{n}\ln(v_i)$

where $v_i = 1 - x_i^{\alpha}$. These formulas represent the derivatives of $-\ell(\theta)$, consistent with minimizing the negative log-likelihood. They correspond to the relevant components of the general GKw gradient (grgkw) evaluated at $\gamma=1, \delta=0, \lambda=1$.

Value

Returns a numeric vector of length 2 containing the partial derivatives of the negative log-likelihood function $-\ell(\theta | \mathbf{x})$ with respect to each parameter: $(-\partial \ell/\partial \alpha, -\partial \ell/\partial \beta)$. Returns a vector of NaN if any parameter values are invalid according to their constraints, or if any value in data is not in the interval (0, 1).

Author(s)

Lopes, J. E.

References

Kumaraswamy, P. (1980). A generalized probability density function for double-bounded random processes. Journal of Hydrology, 46(1-2), 79-88. doi:10.1016/0022-1694(80)90036-0

Jones, M. C. (2009). Kumaraswamy's distribution: A beta-type distribution with some tractability advantages. Statistical Methodology, 6(1), 70-81. doi:10.1016/j.stamet.2008.04.001

(Note: Specific gradient formulas might be derived or sourced from additional references).

See Also

grgkw (parent distribution gradient), llkw (negative log-likelihood for Kw), hskw (Hessian for Kw), dkw (density for Kw), optim, grad (for numerical gradient comparison).

Other gradient functions: grbeta(), grbkw(), grekw(), grgkw(), grkkw(), grmc()

Examples

set.seed(123)
x <- rkw(200, alpha = 2, beta = 3)
par <- c(alpha = 2, beta = 3)

## Gradient of the negative log-likelihood llkw(), not of the log-likelihood
g <- grkw(par, x)
g

## A small step against the gradient lowers llkw()
llkw(par - 1e-4 * g, x) < llkw(par, x)

## Agrees with a numerical derivative of llkw()
if (requireNamespace("numDeriv", quietly = TRUE))
  all.equal(g, numDeriv::grad(llkw, par, data = x), tolerance = 1e-6)

---