Package 'bgev' reference manual

Title:	Bimodal GEV Distribution with Location Parameter
Description:	Density, distribution function, quantile function random generation and estimation of bimodal GEV distribution given in Otiniano et al. (2023) <doi:10.1007/s10651-023-00566-7>. This new generalization of the well-known GEV (Generalized Extreme Value) distribution is useful for modeling heterogeneous bimodal data from different areas.
Authors:	Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]
Maintainer:	Thiago Sousa Developer <[email protected]>
License:	GPL-3
Version:	0.1
Built:	2024-11-11 03:59:02 UTC
Source:	https://github.com/cran/bgev

Bimodal GEV Distribution with Location Parameter

Description

Density, distribution function, quantile function random generation and estimation of bimodal GEV distribution given in Otiniano et al. (2023) <doi:10.1007/s10651-023-00566-7>. This new generalization of the well-known GEV (Generalized Extreme Value) distribution is useful for modeling heterogeneous bimodal data from different areas.

Usage

dbgev(y, mu = 1, sigma = 1, xi = 0.3, delta = 2)
pbgev(y, mu = 1, sigma = 1, xi = 0.3, delta = 2)
qbgev(p, mu = 1, sigma = 1, xi = 0.3, delta = 2)
rbgev(n, mu = 1, sigma = 1, xi = 0.3, delta = 2)
dbgev(y, mu = 1, sigma = 1, xi = 0.3, delta = 2)
pbgev(y, mu = 1, sigma = 1, xi = 0.3, delta = 2)
qbgev(p, mu = 1, sigma = 1, xi = 0.3, delta = 2)
rbgev(n, mu = 1, sigma = 1, xi = 0.3, delta = 2)

Arguments

`y`	a unidimensional vector containing the points to compute the density (dbgev) or the probability (pbgev) froma bimodal GEV distribution with parameters `mu`, `sigma`, `xi` and `delta`.
`p`	a unidimensional vector containing the probabilities used to compute the quantiles
`n`	an integer describing the number of observations to generate random bimodal GEV observations
`mu`	location parameter
`sigma`	shape parameter
`xi`	shape parameter
`delta`	bimodality parameter

Details

Density, distribution function, quantile function and random generation of bimodal GEV distribution with location parameter. In addition, maximum likelihood estimation based on real data is also provided.

Value

dbgev gives the density, pbgev gives the distribution function, qbgev gives the quantile function, and rbgev generates random bimodal GEV observations.

Note

The probability density of a GEV random variable; $Y \sim F_{\xi, \sigma, \mu}$ is given by:

$f_{\xi, \mu, \sigma}(y)= \begin{cases} \dfrac{1}{\sigma} \left[ 1+ \xi \left(\dfrac{y-\mu}{\sigma}\right) \right]^{(-1/\xi) -1} \exp\left\{- \left[1+\xi\left(\dfrac{y-\mu}{\sigma}\right)\right]^{-1/\xi}\right\} ,& \text{if } \xi \ne 0 \\ \dfrac{1}{\sigma} \exp \left\{ - \left( \dfrac{y-\mu}{\sigma}\right) - \exp \left[ - \left( \dfrac{y-\mu}{\sigma}\right) \right] \right\}, & \text{if } \xi = 0 , \end{cases}$

where $\xi$ and $\sigma$ are the shape parameters and $\mu$ is the location parameter.

The bimodal Generalized Extreme Value (GEV) model, denoted as BGEV, consists of composing the distribution of a random variable following the GEV distribution with a location parameter $\mu=0$ , i.e., $Y \sim F_{\xi, 0, \sigma}$ , with the transformation $T_{\mu, \delta}$ defined below. Thus, the cumulative distribution function (CDF) of a random variable BGEV, denoted as $X \sim F_{BG_{\xi, \mu, \sigma, \delta}}$ , is given by:

$F_{BG_{\xi,\mu,\sigma, \delta}}(x) = F_{\xi, 0, \sigma}(T_{\mu, \delta}(x)),$

where the function $T_{\mu, \delta}$ is defined as:

$T_{\mu, \delta}(x)=\left( x - \mu \right) \left| x -\mu \right| ^{\delta}, \quad \delta > -1, \quad \mu \in \mathbb{R}.$

Moreover, the function $T$ is invertible, with the inverse given by:

$T^{-1}_{\mu, \delta}(x) = \text{sng}(x) |x|^{\dfrac{1}{\left( \delta +1 \right) }} + \mu.$

Additionally, it is differentiable, and its derivative has the following form:

$T'_{\mu, \delta}(x) = (\delta + 1 ) |x - \mu|^{\delta}.$

Its probability density function $X\sim F_{BG_{\xi,\mu,\sigma, \delta}}$ is given by

$f_{BG_{\xi,\mu,\sigma, \delta}} (x)= \begin{cases} \dfrac{1}{\sigma} \left[ 1+ \xi \left(\dfrac{T_{\mu, \delta}(x)}{\sigma}\right) \right]^{(-1/\xi) -1} \exp\left[- \left[1+\xi\left(\dfrac{T_{\mu, \delta}(x)} {\sigma}\right)\right]^{-1/\xi}\right] T'_{\mu, \delta}(x) , & \xi \neq 0 \\ \dfrac{1}{\sigma} \exp \left( - \dfrac{T_{\mu, \delta}(x)}{\sigma} \right) \exp \left[- \exp \left( - \dfrac{T_{\mu, \delta}(x)}{\sigma}\right) \right] T'_{\mu, \delta}(x), & \xi=0. \end{cases}$

Author(s)

Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]

Maintainer: Thiago Sousa Developer <[email protected]>

References

Otiniano, Cira EG, et al. (2023). A bimodal model for extremes data. Environmental and Ecological Statistics, 1-28. http://dx.doi.org/10.1007/s10651-023-00566-7

Examples

# generate 100 values distributed according to a bimodal GEV
x = rbgev(50, mu = 0.2, sigma = 1, xi = 0.5, delta = 0.2) 
# estimate the bimodal GEV parameters using the generated data
bgev.mle(x)
# generate 100 values distributed according to a bimodal GEV
x = rbgev(50, mu = 0.2, sigma = 1, xi = 0.5, delta = 0.2) 
# estimate the bimodal GEV parameters using the generated data
bgev.mle(x)

Parameter estimation of bimodal GEV distribution based on real data that appears to be bimodal.

Description

Finds the maximum likelihood estimators of the bimodal GEV distribution parameters by minimizing the log-likelihood function of the data.

Usage

bgev.mle(x, lower = c(-3, 0.1, -3, -0.9), upper = c(3, 3, 3,3), itermax = 50)
bgev.mle(x, lower = c(-3, 0.1, -3, -0.9), upper = c(3, 3, 3,3), itermax = 50)

Arguments

`x`	a unidimensional vector containing observations to estimate a bimodal GEV distribution
`lower`	a vector of dimension 4 containing the lower limit for each of the bimodal GEV parameters where the search is going to take place.
`upper`	a vector of dimension 4 containing the upper limit for each of the bimodal GEV parameters where the search is going to take place.
`itermax`	maximum number of interations when finding a good starting value for the optimization algorithm.

Value

A list with components returned by the optim R function for which the main values are

`par`	best parameters of bimodal gev fitting the data
`value`	value of the log-likelihood corresponding to 'par'

Author(s)

Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]

References

OTINIANO, Cira EG, et al. (2023). A bimodal model for extremes data. Environmental and Ecological Statistics, 1-28. http://dx.doi.org/10.1007/s10651-023-00566-7

Examples

# generate 100 values distributed according to a bimodal GEV
x = rbgev(50, mu = 0.2, sigma = 1, xi = 0.5, delta = 0.2) 
# estimate the bimodal GEV parameters using the generated data
bgev.mle(x)
# generate 100 values distributed according to a bimodal GEV
x = rbgev(50, mu = 0.2, sigma = 1, xi = 0.5, delta = 0.2) 
# estimate the bimodal GEV parameters using the generated data
bgev.mle(x)

Support of the bimodal GEV distribution

Description

When the shape parameter xi is different from zero, the support is truncated either at the left or at the right side of the real. Considering the support is particularly useful to estimating momoments and to compute the likelihood function.

Usage

bgev.support(mu, sigma, xi, delta)
bgev.support(mu, sigma, xi, delta)

Arguments

`mu`	location parameter
`sigma`	shape parameter
`xi`	shape parameter
`delta`	bimodality parameter

Value

It returns a vector representing the interval for which the density function is not null.

Note

The Support of the bimodal GEV distribution is given by the following equation:

$\begin{cases} x \in \mathbb {R} : x \geq \mathbf{sng} \left(-\frac{\sigma}{\xi}\right) | \frac{\sigma}{\xi}| ^{\frac{1}{\delta+1}}+\mu, & \xi \neq 0 \\ x \in \mathbb {R}, & \xi =0. \end{cases}$

Author(s)

Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]

References

Otiniano, Cira EG, et al. (2023). A bimodal model for extremes data. Environmental and Ecological Statistics, 1-28. http://dx.doi.org/10.1007/s10651-023-00566-7

Examples

# Computes the support of a specific bimodal GEV distribution
support = bgev.support(mu=1, sigma=10, xi=0.3, delta=2)
# Computes the support of a specific bimodal GEV distribution
support = bgev.support(mu=1, sigma=10, xi=0.3, delta=2)

Check implementation of a distribution in R.

Description

This is just a refactorization of the original R function distCheck to allow customization for heavy tailed distributions and distribution with constrained support. Assumes one has implemented density, probability, quantile and random generation for a new distribution. Originally implemented to be used with the bimodal GEV distribution

Usage

distCheck(fun = "norm", n = 1000, robust = FALSE, subdivisions = 1500, 
support.lower = -Inf, support.upper = Inf, 
var.exists = TRUE, print.result = TRUE, ...)
distCheck(fun = "norm", n = 1000, robust = FALSE, subdivisions = 1500, 
support.lower = -Inf, support.upper = Inf, 
var.exists = TRUE, print.result = TRUE, ...)

Arguments

`fun`	Name of distribution. E.g, "bgev" for bimodal GEV, "gev" for GEV, "norm" for normal.
`n`	size of the sample when generating random values through "rfun"
`robust`	Boolean. Used for computing mean and variance in a robust way when evaluating mean and variance.
`subdivisions`	used for numerical integration when using "dfun"
`support.lower`	lower limit of the support of the distribution
`support.upper`	upper limit of the support of the distribution
`var.exists`	Boolean indicating if variance exists (useful for gev, bimodal gev, stable etc)
`print.result`	Boolean indicating weather to print results of the tests on screen.
`...`	parameters passed to the distribution, e.g., mu and sd for normal, mu, sigma, xi and delta for bimodal GEV.

Details

All tests results are organized into a list to make it easier to find where results went wrong and to make it scalable for testing distributions for several parameters.

Value

A list of lists with test results

list( functionTested = fun, functionParam = list(...),
test1.density = list(computed = NULL, expected = NULL, error.check = NULL),
test2.quantile.cdf = list(computed = NULL, expected = NULL, error.check = NULL),
test3.mean.var = list(computed = list(mean = NULL, var = NULL, log = NULL),
expected = list(mean = NULL, var = NULL, log = NULL),
error.check = NULL,
condition.is.var.finite = TRUE))

`functionParam`	Additional parameters passed to the distribution with the ... argument
`test1.density`	results for the density function test. A list with the 'computed' value using the density function and numerical integration, the 'expected' value (which is 1) and the result of the 'error.check' comparing both values.
`test2.quantile.cdf`	results for the quantile function test. A list with the 'computed' value using the quantile function at chosen probabilites on [0,1], the 'expected' value (which is 1) and the result of the 'error.check' comparing both values.
`test3.mean.var`	results for the random generation and the density function. A list with the 'computed' values using the random quantities (computes mean(X), variance(X) and E(log(abs(X))) where X follows the distribution being tested. The 'expected' is a list containing the same quantities computed using numerical integration
`error.check`	check if expected variance and computed variance are close enough.
`condition.is.var.finite`	For some distributions there are known conditions for the variance to be finite. This quantity is expected to be evaluated outside the DistCheck function and passed through the argument 'var.exists'.

Author(s)

Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]

References

Otiniano, Cira EG, et al. (2023). A bimodal model for extremes data. Environmental and Ecological Statistics, 1-28. http://dx.doi.org/10.1007/s10651-023-00566-7

Examples

# generate random values for the parameters and test the 
# bimodal gev distribution implementation
set.seed(1)
mu = runif(1,-2,2)
sigma = runif(1,0.1,2)
xi = runif(1,0.3,0.9) * sign(runif(1,-1,1))
delta = 1#runif(1,-0.6,2)
support = bgev.support(mu, sigma, xi, delta)
var.exists = ( xi != 0) & (xi < (delta + 1)/2)
ret = distCheck(fun="bgev", n = 2000, 
      support.lower = support[1], support.upper = support[2], 
      subdivisions = 5000, mu = mu, sigma = sigma, xi = xi, 
      delta = delta, var.exists = var.exists, print.result = TRUE)
# generate random values for the parameters and test the 
# bimodal gev distribution implementation
set.seed(1)
mu = runif(1,-2,2)
sigma = runif(1,0.1,2)
xi = runif(1,0.3,0.9) * sign(runif(1,-1,1))
delta = 1#runif(1,-0.6,2)
support = bgev.support(mu, sigma, xi, delta)
var.exists = ( xi != 0) & (xi < (delta + 1)/2)
ret = distCheck(fun="bgev", n = 2000, 
      support.lower = support[1], support.upper = support[2], 
      subdivisions = 5000, mu = mu, sigma = sigma, xi = xi, 
      delta = delta, var.exists = var.exists, print.result = TRUE)

Log likelihood function for the bimodal GEV distribution.

Description

Uses the density function to evaluate the likelihood. This is useful for the 'bgev.mle' function.

Usage

likbgev(y, theta = c(1, 1, 0.3, 2))
likbgev(y, theta = c(1, 1, 0.3, 2))

Arguments

`y`	a unidimensional vector containing the points to compute the log likelihood
`theta`	bimodal GEV parameters as an ordered pair `theta = (mu,sigma,xi,delta)`

Value

a unidimensional vector containing the computed log likelihood for y.

Author(s)

Cira Otiniano Author [aut], Yasmin Lirio Author [aut], Thiago Sousa Developer [cre]

References

Otiniano, Cira EG, et al. (2023). A bimodal model for extremes data. Environmental and Ecological Statistics, 1-28. http://dx.doi.org/10.1007/s10651-023-00566-7

Examples

# get random points from bimodal GEV
y = rbgev(100, mu = 1, sigma = 1, xi = 0.3, delta = 2)

# compute log-likelihood
likbgev (y, theta = c(1, 1, 0.3, 2)) 
# get random points from bimodal GEV
y = rbgev(100, mu = 1, sigma = 1, xi = 0.3, delta = 2)

# compute log-likelihood
likbgev (y, theta = c(1, 1, 0.3, 2))

Package 'bgev'

Help Index

Bimodal GEV Distribution with Location Parameter

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

Examples

Parameter estimation of bimodal GEV distribution based on real data that appears to be bimodal.

Description

Usage

Arguments

Value

Author(s)

References

Examples

Support of the bimodal GEV distribution

Description

Usage

Arguments

Value

Note

Author(s)

References

Examples

Check implementation of a distribution in R.

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Log likelihood function for the bimodal GEV distribution.

Description

Usage

Arguments

Value

Author(s)

References

Examples