Type: Package
Title: Generalized Fiducial Inference for Extremes
Version: 1.0.1
Maintainer: Stéphane Laurent <laurent_step@outlook.fr>
Description: Fiducial framework to perform inference on the quantiles for a generalized Pareto distribution model and on the parameters of the Pareto exceedance distribution, assuming the exceedance threshold is a known or unknown parameter. Reference: Damian V. Wandler & Jan Hannig (2012) <doi:10.1007/s10687-011-0127-9>.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Depends: coda
Imports: Rcpp (≥ 1.0.5), parallel, doParallel, foreach, stats
LinkingTo: Rcpp, BH, RcppArmadillo
Encoding: UTF-8
RoxygenNote: 7.1.1
URL: https://github.com/stla/gfiExtremes
BugReports: https://github.com/stla/gfiExtremes/issues
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
SystemRequirements: C++ 17
NeedsCompilation: yes
Packaged: 2024-01-25 16:01:49 UTC; SDL96354
Author: Stéphane Laurent [aut, cre], Jan Hannig [aut], Damian V. Wandler [aut]
Repository: CRAN
Date/Publication: 2024-01-25 17:00:09 UTC

Generalized Pareto distribution

Description

Density, distribution function, quantile function, and random generation for the generalized Pareto distribution.

Usage

dgpareto(x, mu, gamma, sigma, log = FALSE)

pgpareto(q, mu, gamma, sigma)

rgpareto(n, mu, gamma, sigma)

qgpareto(p, mu, gamma, sigma)

Arguments

x

numeric vector

mu

location parameter

gamma

shape parameter

sigma

scale parameter, strictly positive

log

logical, whether to return the log-density

q

numeric vector of quantiles

n

positive integer, the desired number of simulations

p

numeric vector of probabilities

Fiducial inference for the generalized Pareto model with known threshold

Description

Runs the MCMC sampler of the fiducial distribution for the generalized Pareto model with known threshold.

Usage

gfigpd1(
  X,
  beta,
  threshold,
  gamma.init = NA,
  sigma.init = NA,
  sd.gamma = NA,
  sd.sigma = NA,
  Jnumb = 50L,
  iter = 10000L,
  burnin = 2000L,
  thin = 6L,
  nchains = 4L,
  nthreads = parallel::detectCores(),
  seeds = NULL
)

Arguments

X

numeric vector of data

beta

vector of probabilities corresponding to the quantiles to be estimated

threshold

value of the known threshold, must be smaller than the maximum of X

gamma.init

starting value for gamma in the MCMC

sigma.init

starting value for sigma in the MCMC

sd.gamma

standard deviation for the proposed gamma in the MCMC

sd.sigma

standard deviation for the proposed sigma in the MCMC

Jnumb

number of subsamples that are taken from the Jacobian

iter

number of iterations per chain (burnin excluded)

burnin

number of the first MCMC iterations discarded

thin

thinning number for the MCMC chain. (e.g. if it is 1 no iteration is skipped)

nchains

number of MCMC chains to run

nthreads

number of threads to run the chains in parallel

seeds

the seeds used for the MCMC sampler; one seed per chain, or NULL to use random seeds

Value

An object of class mcmc if nchains=1, otherwise an object of class mcmc.list.

References

Damian V. Wandler & Jan Hannig. Generalized fiducial confidence intervals for extremes. Extremes (2012) 15:67–87. <doi:10.1007/s10687-011-0127-9>

Examples

set.seed(666L)
X <- rgpareto(200L, mu = 10, gamma = 0.5, sigma = 1)
gf <- gfigpd1(
  X, beta = c(0.98, 0.99), threshold = 10, 
  iter = 2000L, nchains = 2L, nthreads = 2L
) # note: 2*2000 iterations is not enough, I'm using these settings because 
  # of CRAN constraints (elapsed time must be < 5s)
summary(gf)
qgpareto(c(0.98, 0.99), mu = 10, gamma = 0.5, sigma = 1)
rejectionRate(gf)
HPDinterval(gf)
HPDinterval(joinMCMCchains(gf))

Fiducial inference for the generalized Pareto model with unknown threshold

Description

Runs the MCMC sampler of the fiducial distribution for the generalized Pareto model with unknown threshold.

Usage

gfigpd2(
  X,
  beta,
  threshold.init = NA,
  gamma.init = NA,
  sigma.init = NA,
  sd.gamma = NA,
  sd.sigma = NA,
  p1 = 0.9,
  p2 = 0.5,
  lambda1 = 2,
  lambda2 = 10,
  Jnumb = 50L,
  iter = 10000L,
  burnin = 2000L,
  thin = 6L,
  nchains = 4L,
  nthreads = parallel::detectCores(),
  seeds = NULL,
  allParameters = FALSE
)

Arguments

X

numeric vector of data

beta

vector of probabilities corresponding to the quantiles to be estimated

threshold.init

a guess of the unknown threshold, must be in the range of X

gamma.init

starting value for gamma in the MCMC

sigma.init

starting value for sigma in the MCMC

sd.gamma

standard deviation for the proposed gamma in the MCMC

sd.sigma

standard deviation for the proposed sigma in the MCMC

p1

probability that the MCMC will propose a new (gamma,sigma); (1-p1) would be the probability that the MCMC chain will propose a new index for a new threshold

p2

probability that the new index proposed will be larger than the current index

lambda1

the small jump the index variable will make

lambda2

the large jump the index variable will make; happens 1 of every 10 iterations

Jnumb

number of subsamples that are taken from the Jacobian

iter

number of iterations per chain (burnin excluded)

burnin

number of the first MCMC iterations discarded

thin

thinning number for the MCMC chain. (e.g. if it is 1 no iteration is skipped)

nchains

number of MCMC chains to run

nthreads

number of threads to run the chains in parallel

seeds

the seeds used for the MCMC sampler; one seed per chain, or NULL to use random seeds

allParameters

logical, whether to return the MCMC chains of all parameters (pretty useless) or only the ones of the quantiles

Value

An object of class mcmc if nchains=1, otherwise an object of class mcmc.list.

References

Damian V. Wandler & Jan Hannig. Generalized fiducial confidence intervals for extremes. Extremes (2012) 15:67–87. <doi:10.1007/s10687-011-0127-9>

Examples

set.seed(31415L)
X <- rgamma(350L, shape = 10, rate = 1)
gf <- gfigpd2(X, beta = c(0.98, 0.99), iter = 3000L, nthreads = 2L)
summary(gf)
qgamma(c(0.98, 0.99), shape = 10, rate = 1)
traceplot(gf[,"beta1"])
traceplot(gf[,"beta2"])
thresholdEstimate(gf)
rejectionRate(gf)
HPDinterval(gf)
HPDinterval(joinMCMCchains(gf))

Join MCMC chains

Description

Joins multiple MCMC chains into a single chain.

Usage

joinMCMCchains(gfi)

Arguments

gfi

an output of gfigpd1 or gfigpd2 containing more than one chain

Value

A mcmc object.

Threshold estimate

Description

Returns the estimate of the threshold.

Usage

thresholdEstimate(gfi)

Arguments

gfi

an output of gfigpd2

Value

The estimated threshold.