| Title: | Distribution Fitting with Calibrating Priors for Commonly Used Distributions |
|---|---|
| Description: | Generates predictive distributions based on calibrating priors for various commonly used statistical models, including models with predictors. Routines for densities, probabilities, quantiles, random deviates and the parameter posterior are provided. The predictions are generated from the Bayesian prediction integral, with priors chosen to give good reliability (also known as calibration). For homogeneous models, the prior is set to the right Haar prior, giving predictions which are exactly reliable. As a result, in repeated testing, the frequencies of out-of-sample outcomes and the probabilities from the predictions agree. For other models, the prior is chosen to give good reliability. Where possible, the Bayesian prediction integral is solved exactly. Where exact solutions are not possible, the Bayesian prediction integral is solved using the Datta-Mukerjee-Ghosh-Sweeting (DMGS) asymptotic expansion. Optionally, the prediction integral can also be solved using posterior samples generated using Paul Northrop's ratio of uniforms sampling package ('rust'). Results are also generated based on maximum likelihood, for comparison purposes. Various model selection diagnostics and testing routines are included. Based on "Reducing reliability bias in assessments of extreme weather risk using calibrating priors", Jewson, S., Sweeting, T. and Jewson, L. (2024); <doi:10.5194/ascmo-11-1-2025>. |
| Authors: | Stephen Jewson [aut, cre] (ORCID: <https://orcid.org/0000-0002-6011-6262>) |
| Maintainer: | Stephen Jewson <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.3 |
| Built: | 2026-05-24 08:50:43 UTC |
| Source: | https://github.com/stephenjewson/fitdistcp |
Generates a comment about the method
adhoc_dmgs_cpmethod()adhoc_dmgs_cpmethod()
String
Generates a comment about the method
analytic_cpmethod()analytic_cpmethod()
String
Evaluate DMGS equation 3.3
bayesian_dq_4terms_v1(lddi, lddd, mu1, pidopi1, pidopi2, mu2, dim)bayesian_dq_4terms_v1(lddi, lddd, mu1, pidopi1, pidopi2, mu2, dim)
lddi |
inverse of second derivative of observed log-likelihood |
lddd |
third derivative of observed log-likelihood |
mu1 |
DMGS mu1 vector |
pidopi1 |
first part of the prior term |
pidopi2 |
second part of the prior term |
mu2 |
DMGS mu2 matrix |
dim |
number of parameters |
Vector
determine revert2ml or not
calc_revert2ml(v5h, v6h, t3)calc_revert2ml(v5h, v6h, t3)
v5h |
fifth parameter |
v6h |
sixth parameter |
t3 |
a vector of predictors for the shape |
Logical
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qcauchy_cp( x, p = seq(0.1, 0.9, 0.1), d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rcauchy_cp( n, x, d1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dcauchy_cp( x, y = x, d1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pcauchy_cp( x, y = x, d1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tcauchy_cp(n, x, d1 = 0.01, fd2 = 0.01, debug = FALSE)qcauchy_cp( x, p = seq(0.1, 0.9, 0.1), d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rcauchy_cp( n, x, d1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dcauchy_cp( x, y = x, d1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pcauchy_cp( x, y = x, d1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tcauchy_cp(n, x, d1 = 0.01, fd2 = 0.01, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
d1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Cauchy distribution has probability density function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d042cauchy_example_data_v1 p=c(1:9)/10 q=qlogis_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qcauchy_cp)", main="Cauchy: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d042cauchy_example_data_v1 p=c(1:9)/10 q=qlogis_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qcauchy_cp)", main="Cauchy: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
cauchy_f1f(y, v1, d1, v2, fd2)cauchy_f1f(y, v1, d1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density
cauchy_f1fa(x, v1, v2)cauchy_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
DMGS equation 3.3, f2 term
cauchy_f2f(y, v1, d1, v2, fd2)cauchy_f2f(y, v1, d1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density
cauchy_f2fa(x, v1, v2)cauchy_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_fd(x, v1, v2)cauchy_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_fdd(x, v1, v2)cauchy_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
cauchy_ldd(x, v1, d1, v2, fd2)cauchy_ldd(x, v1, d1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
cauchy_ldda(x, v1, v2)cauchy_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
cauchy_lddd(x, v1, d1, v2, fd2)cauchy_lddd(x, v1, d1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
cauchy_lddda(x, v1, v2)cauchy_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
One component of the second derivative of the normalized log-likelihood
cauchy_lmn(x, v1, d1, v2, fd2, mm, nn)cauchy_lmn(x, v1, d1, v2, fd2, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the third derivative of the normalized log-likelihood
cauchy_lmnp(x, v1, d1, v2, fd2, mm, nn, rr)cauchy_lmnp(x, v1, d1, v2, fd2, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
cauchy_logf(params, x)cauchy_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_logfdd(x, v1, v2)cauchy_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_logfddd(x, v1, v2)cauchy_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
cauchy_loglik(vv, x)cauchy_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
cauchy_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, aderivs = TRUE)cauchy_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
DMGS equation 3.3, mu1 term
cauchy_mu1f(alpha, v1, d1, v2, fd2)cauchy_mu1f(alpha, v1, d1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
cauchy_mu2f(alpha, v1, d1, v2, fd2)cauchy_mu2f(alpha, v1, d1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qcauchy_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), d1 = 0.01, d2 = 0.01, fd3 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) rcauchy_p1_cp( n, x, t, t0 = NA, n0 = NA, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dcauchy_p1_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) pcauchy_p1_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) tcauchy_p1_cp(n, x, t, d1 = 0.01, d2 = 0.01, fd3 = 0.01, debug = FALSE)qcauchy_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), d1 = 0.01, d2 = 0.01, fd3 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) rcauchy_p1_cp( n, x, t, t0 = NA, n0 = NA, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dcauchy_p1_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) pcauchy_p1_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) tcauchy_p1_cp(n, x, t, d1 = 0.01, d2 = 0.01, fd3 = 0.01, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
d1 |
if |
d2 |
if |
fd3 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Cauchy distribution with a predictor has probability density function
where
is the random variable,
is the location parameter as a function of parameters ,
and is the scale parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d064cauchy_p1_example_data_v1_x tt=fitdistcp::d064cauchy_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qcauchy_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qcauchy_p1_cp)", main="Cauchy w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d064cauchy_p1_example_data_v1_x tt=fitdistcp::d064cauchy_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qcauchy_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qcauchy_p1_cp)", main="Cauchy w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 2.1, f1 term
cauchy_p1_f1f(y, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_f1f(y, t0, v1, d1, v2, d2, v3, fd3)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density for DMGS
cauchy_p1_f1fa(x, t0, v1, v2, v3)cauchy_p1_f1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
cauchy_p1_f1fw(x, t, v1, v2, v3)cauchy_p1_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
DMGS equation 2.1, f2 term
cauchy_p1_f2f(y, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_f2f(y, t0, v1, d1, v2, d2, v3, fd3)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density for DMGS
cauchy_p1_f2fa(x, t0, v1, v2, v3)cauchy_p1_f2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
cauchy_p1_f2fw(x, t, v1, v2, v3)cauchy_p1_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_p1_fd(x, t, v1, v2, v3)cauchy_p1_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_p1_fdd(x, t, v1, v2, v3)cauchy_p1_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Matrix
Second derivative matrix of the normalized log-likelihood
cauchy_p1_ldd(x, t, v1, d1, v2, d2, v3, fd3)cauchy_p1_ldd(x, t, v1, d1, v2, d2, v3, fd3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
cauchy_p1_ldda(x, t, v1, v2, v3)cauchy_p1_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
cauchy_p1_lddd(x, t, v1, d1, v2, d2, v3, fd3)cauchy_p1_lddd(x, t, v1, d1, v2, d2, v3, fd3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
cauchy_p1_lddda(x, t, v1, v2, v3)cauchy_p1_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
One component of the second derivative of the normalized log-likelihood
cauchy_p1_lmn(x, t, v1, d1, v2, d2, v3, fd3, mm, nn)cauchy_p1_lmn(x, t, v1, d1, v2, d2, v3, fd3, mm, nn)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the second derivative of the normalized log-likelihood
cauchy_p1_lmnp(x, t, v1, d1, v2, d2, v3, fd3, mm, nn, rr)cauchy_p1_lmnp(x, t, v1, d1, v2, d2, v3, fd3, mm, nn, rr)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
cauchy_p1_logf(params, x, t)cauchy_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_p1_logfdd(x, t, v1, v2, v3)cauchy_p1_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
cauchy_p1_logfddd(x, t, v1, v2, v3)cauchy_p1_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Cauchy-with-p1 observed log-likelihood function
cauchy_p1_loglik(vv, x, t)cauchy_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
cauchy_p1_logscores(logscores, x, t, d1, d2, fd3, aderivs = TRUE)cauchy_p1_logscores(logscores, x, t, d1, d2, fd3, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
Cauchy distribution: RHP mean
cauchy_p1_means(t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)cauchy_p1_means(t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
DMGS equation 3.3, mu1 term
cauchy_p1_mu1f(alpha, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_mu1f(alpha, t0, v1, d1, v2, d2, v3, fd3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
cauchy_p1_mu2f(alpha, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_mu2f(alpha, t0, v1, d1, v2, d2, v3, fd3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
DMGS equation 2.1, p1 term
cauchy_p1_p1f(y, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_p1f(y, t0, v1, d1, v2, d2, v3, fd3)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 2.1, p2 term
cauchy_p1_p2f(y, t0, v1, d1, v2, d2, v3, fd3)cauchy_p1_p2f(y, t0, v1, d1, v2, d2, v3, fd3)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Predicted Parameter and Generalized Residuals
cauchy_p1_predictordata(predictordata, x, t, t0, params)cauchy_p1_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
cauchy_p1_waic( waicscores, x, t, v1hat, d1, v2hat, d2, v3hat, fd3, lddi, lddd, lambdad, aderivs )cauchy_p1_waic( waicscores, x, t, v1hat, d1, v2hat, d2, v3hat, fd3, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3hat |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
DMGS equation 3.3, p1 term
cauchy_p1f(y, v1, d1, v2, fd2)cauchy_p1f(y, v1, d1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, p2 term
cauchy_p2f(y, v1, d1, v2, fd2)cauchy_p2f(y, v1, d1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Waic
cauchy_waic(waicscores, x, v1hat, d1, v2hat, fd2, lddi, lddd, lambdad, aderivs)cauchy_waic(waicscores, x, v1hat, d1, v2hat, fd2, lddi, lddd, lambdad, aderivs)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
Generates a comment about the method
crhpflat_dmgs_cpmethod()crhpflat_dmgs_cpmethod()
String
Cauchy-with-p1 density function
dcauchy_p1(x, t0, ymn, slope, scale, log = FALSE)dcauchy_p1(x, t0, ymn, slope, scale, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dcauchy_p1sub(x, t, y, t0, d1, d2, fd3, aderivs = TRUE)dcauchy_p1sub(x, t, y, t0, d1, d2, fd3, aderivs = TRUE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dcauchysub(x, y, d1 = 0.01, fd2 = 0.01, aderivs = TRUE)dcauchysub(x, y, d1 = 0.01, fd2 = 0.01, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Extract the results from derivatives and put them into f2
deriv_copyfdd(temp1, nx, dim)deriv_copyfdd(temp1, nx, dim)
temp1 |
output from derivative calculations |
nx |
number of x values |
dim |
number of parameters |
3d array
Extract the results from derivatives and put them into ldd
deriv_copyld2(temp1, nx, dim)deriv_copyld2(temp1, nx, dim)
temp1 |
output from derivative calculations |
nx |
number of x values |
dim |
number of parameters |
3d array
Extract the results from derivatives and put them into ldd
deriv_copyldd(temp1, nx, dim)deriv_copyldd(temp1, nx, dim)
temp1 |
output from derivative calculations |
nx |
number of x values |
dim |
number of parameters |
Matrix
Extract the results from derivatives and put them into lddd
deriv_copylddd(temp1, nx, dim)deriv_copylddd(temp1, nx, dim)
temp1 |
output from derivative calculations |
nx |
number of x values |
dim |
number of parameters |
3d array
Exponential-with-p1 density function
dexp_p1(x, t0, ymn, slope, log = FALSE)dexp_p1(x, t0, ymn, slope, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dexp_p1sub(x, t, y, t0)dexp_p1sub(x, t, y, t0)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dexpsub(x, y)dexpsub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Frechet_k1-with-p2 density function
dfrechet_p2k1(x, t0, ymn, slope, lambda, log = FALSE, kloc)dfrechet_p2k1(x, t0, ymn, slope, lambda, log = FALSE, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
lambda |
the lambda parameter of the distribution |
log |
logical for the density evaluation |
kloc |
the known location parameter |
Vector
Densities from MLE and RHP
dfrechet_p2k1sub(x, t, y, t0, kloc)dfrechet_p2k1sub(x, t, y, t0, kloc)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
kloc |
the known location parameter |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dfrechetsub(x, y, kloc)dfrechetsub(x, y, kloc)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
kloc |
the known location parameter |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dgammasub(x, y, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)dgammasub(x, y, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dgev_k3sub(x, y, kshape)dgev_k3sub(x, y, kshape)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
kshape |
the known shape parameter |
A vector of parameter estimates, two pdf vectors, two cdf vectors
GEVD-with-p1: Density function
dgev_p1(x, t0, ymn, slope, sigma, xi, log = FALSE)dgev_p1(x, t0, ymn, slope, sigma, xi, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
log |
logical for the density evaluation |
Vector
GEVD-with-p1: Density function
dgev_p12(x, t1, t2, ymn, slope, sigma1, sigma2, xi, log = FALSE)dgev_p12(x, t1, t2, ymn, slope, sigma1, sigma2, xi, log = FALSE)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
log |
logical for the density evaluation |
Vector
GEVD-with-p1: Density function
dgev_p123(x, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2, log = FALSE)dgev_p123(x, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2, log = FALSE)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi1 |
first coefficient for the shape parameter of the distribution |
xi2 |
second coefficient for the shape parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities for 5 predictions
dgev_p123sub(x, t1, t2, t3, y, t01, t02, t03, ics, extramodels, debug)dgev_p123sub(x, t1, t2, t3, y, t01, t02, t03, ics, extramodels, debug)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
y |
a vector of values at which to calculate the density and distribution functions |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
ics |
initial conditions for the maximum likelihood search |
extramodels |
logical that indicates whether to add three additional prediction models |
debug |
debug flag |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities for 5 predictions
dgev_p12sub( x, t1, t2, y, t01, t02, ics, minxi, maxxi, debug, extramodels = FALSE )dgev_p12sub( x, t1, t2, y, t01, t02, ics, minxi, maxxi, debug, extramodels = FALSE )
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
y |
a vector of values at which to calculate the density and distribution functions |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ics |
initial conditions for the maximum likelihood search |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
debug |
debug flag |
extramodels |
logical that indicates whether to add three additional prediction models |
A vector of parameter estimates, two pdf vectors, two cdf vectors
GEV-with-known-shape-with-p1 density function
dgev_p1k3(x, t0, ymn, slope, sigma, log = FALSE, kshape)dgev_p1k3(x, t0, ymn, slope, sigma, log = FALSE, kshape)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
log |
logical for the density evaluation |
kshape |
the known shape parameter |
Vector
Densities from MLE and RHP
dgev_p1k3sub(x, t, y, t0, kshape)dgev_p1k3sub(x, t, y, t0, kshape)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
kshape |
the known shape parameter |
A vector of parameter estimates, two pdf vectors, two cdf vectors
GEVD-with-p1: Density function
dgev_p1n(x, t0, params, log = FALSE)dgev_p1n(x, t0, params, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
log |
logical for the density evaluation |
Vector
Densities for 5 predictions
dgev_p1nsub(x, t, y, t0, ics, minxi, maxxi, extramodels = FALSE)dgev_p1nsub(x, t, y, t0, ics, minxi, maxxi, extramodels = FALSE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
ics |
initial conditions for the maximum likelihood search |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
extramodels |
logical that indicates whether to add three additional prediction models |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities for 5 predictions
dgev_p1sub(x, t, y, t0, ics, minxi, maxxi, extramodels = FALSE)dgev_p1sub(x, t, y, t0, ics, minxi, maxxi, extramodels = FALSE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
ics |
initial conditions for the maximum likelihood search |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
extramodels |
logical that indicates whether to add three additional prediction models |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities for 5 predictions
dgevsub(x, y, ics, minxi, maxxi)dgevsub(x, y, ics, minxi, maxxi)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
ics |
initial conditions for the maximum likelihood search |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dgnorm_k3sub(x, y, d1 = 0.01, fd2 = 0.01, kbeta, aderivs = TRUE)dgnorm_k3sub(x, y, d1 = 0.01, fd2 = 0.01, kbeta, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities for 5 predictions
dgpdsub(x, y, ics, kloc = 0, dlogpi = 0, minxi, maxxi, extramodels = FALSE)dgpdsub(x, y, ics, kloc = 0, dlogpi = 0, minxi, maxxi, extramodels = FALSE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
ics |
initial conditions for the maximum likelihood search |
kloc |
the known location parameter |
dlogpi |
gradient of the log prior |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
extramodels |
logical that indicates whether to add three additional prediction models |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Gumbel-with-p1 density function
dgumbel_p1(x, t0, ymn, slope, sigma, log = FALSE)dgumbel_p1(x, t0, ymn, slope, sigma, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dgumbel_p1sub(x, t, y, t0)dgumbel_p1sub(x, t, y, t0)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dgumbelsub(x, y)dgumbelsub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dhalfnormsub(x, y, fd1 = 0.01, aderivs = TRUE)dhalfnormsub(x, y, fd1 = 0.01, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and cp
dinvgammasub(x, y, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)dinvgammasub(x, y, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dinvgausssub(x, y, prior, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)dinvgausssub(x, y, prior, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
prior |
logical indicating which prior to use |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dlnorm_dmgssub(x, y)dlnorm_dmgssub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Normal-with-p1 density function
dlnorm_p1(x, t0, ymn, slope, sigma, log = FALSE)dlnorm_p1(x, t0, ymn, slope, sigma, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dlnorm_p1sub(x, t, y, t0, debug = FALSE)dlnorm_p1sub(x, t, y, t0, debug = FALSE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
debug |
debug flag |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dlnormsub(x, y)dlnormsub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Logistic-with-p1 density function
dlogis_p1(x, t0, ymn, slope, scale, log = FALSE)dlogis_p1(x, t0, ymn, slope, scale, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dlogis_p1sub(x, t, y, t0)dlogis_p1sub(x, t, y, t0)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dlogis2sub(x, y)dlogis2sub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dlst_k3sub(x, y, d1 = 0.01, fd2 = 0.01, kdf, aderivs = TRUE)dlst_k3sub(x, y, d1 = 0.01, fd2 = 0.01, kdf, aderivs = TRUE)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
LST-with-p1 density function
dlst_p1k3(x, t0, ymn, slope, sigma, log = FALSE, kdf)dlst_p1k3(x, t0, ymn, slope, sigma, log = FALSE, kdf)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
log |
logical for the density evaluation |
kdf |
the known degrees of freedom parameter |
Vector
Densities from MLE and RHP
dlst_p1k3sub(x, t, y, t0, d1, d2, fd3, kdf, aderivs = TRUE)dlst_p1k3sub(x, t, y, t0, d1, d2, fd3, kdf, aderivs = TRUE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Evaluate DMGS equation 3.3
dmgs(lddi, lddd, mu1, pidopi, mu2, dim)dmgs(lddi, lddd, mu1, pidopi, mu2, dim)
lddi |
inverse of second derivative of observed log-likelihood |
lddd |
third derivative of observed log-likelihood |
mu1 |
DMGS mu1 vector |
pidopi |
derivative of log prior |
mu2 |
DMGS mu2 matrix |
dim |
number of parameters |
Vector
Densities from MLE and RHP
dnorm_dmgssub(x, y)dnorm_dmgssub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Normal-with-p1 density function
dnorm_p1(x, t0, ymn, slope, sigma, log = FALSE)dnorm_p1(x, t0, ymn, slope, sigma, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
log |
logical for the density evaluation |
Vector
Linear regression formula, densities
dnorm_p1_formula(y, tresid, tresid0, nx, muhat0, v3hat)dnorm_p1_formula(y, tresid, tresid0, nx, muhat0, v3hat)
y |
a vector of values at which to calculate the density and distribution functions |
tresid |
predictor residuals |
tresid0 |
predictor residual at the point being predicted |
nx |
length of training data |
muhat0 |
muhat at the point being predicted |
v3hat |
third parameter |
Vector
Normal-with-p12: Density function
dnorm_p12(x, t01, t02, ymn, slope, sigma1, sigma2, log = FALSE)dnorm_p12(x, t01, t02, ymn, slope, sigma1, sigma2, log = FALSE)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
log |
logical for the density evaluation |
Vector
Densities for 5 predictions
dnorm_p12dmgs(x, t1, t2, y, t01, t02, ics)dnorm_p12dmgs(x, t1, t2, y, t01, t02, ics)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
y |
a vector of values at which to calculate the density and distribution functions |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ics |
initial conditions for the maximum likelihood search |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dnorm_p1sub(x, t, y, t0)dnorm_p1sub(x, t, y, t0)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dnormsub(x, y)dnormsub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dpareto_k2_sub(x, y, kscale)dpareto_k2_sub(x, y, kscale)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
kscale |
the known scale parameter |
A vector of parameter estimates, two pdf vectors, two cdf vectors
pareto_k1-with-p2 density function
dpareto_p1k2(x, t0, ymn, slope, kscale, log = FALSE)dpareto_p1k2(x, t0, ymn, slope, kscale, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
kscale |
the known scale parameter |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dpareto_p1k2sub(x, t, y, t0, kscale, debug = FALSE)dpareto_p1k2sub(x, t, y, t0, kscale, debug = FALSE)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
kscale |
the known scale parameter |
debug |
debug flag |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Predictive PDFs
dunif_formula(x, y)dunif_formula(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
Two vectors
Weibull-with-p1 density function
dweibull_p2(x, t0, shape, ymn, slope, log = FALSE)dweibull_p2(x, t0, shape, ymn, slope, log = FALSE)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
shape |
the shape parameter of the distribution |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
log |
logical for the density evaluation |
Vector
Densities from MLE and RHP
dweibull_p2sub(x, t, y, t0)dweibull_p2sub(x, t, y, t0)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
A vector of parameter estimates, two pdf vectors, two cdf vectors
Densities from MLE and RHP
dweibullsub(x, y)dweibullsub(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
A vector of parameter estimates, two pdf vectors, two cdf vectors
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qexp_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rexp_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dexp_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pexp_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) texp_cp(n, x, debug = FALSE)qexp_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rexp_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dexp_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pexp_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) texp_cp(n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The exponential distribution has exceedance distribution function
where
is the random variable
and
is the rate parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d010exp_example_data_v1 p=c(1:9)/10 q=qexp_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qexp_cp)", main="Exponential: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d010exp_example_data_v1 p=c(1:9)/10 q=qexp_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qexp_cp)", main="Exponential: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
The first derivative of the density
exp_f1fa(x, v1) exp_f1fa(x, v1)exp_f1fa(x, v1) exp_f1fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
The second derivative of the density
The second derivative of the density
exp_f2fa(x, v1) exp_f2fa(x, v1)exp_f2fa(x, v1) exp_f2fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_fd(x, v1) exp_fd(x, v1)exp_fd(x, v1) exp_fd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_fdd(x, v1) exp_fdd(x, v1)exp_fdd(x, v1) exp_fdd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
The second derivative of the normalized log-likelihood
The second derivative of the normalized log-likelihood
exp_ldda(x, v1) exp_ldda(x, v1)exp_ldda(x, v1) exp_ldda(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
The third derivative of the normalized log-likelihood
The third derivative of the normalized log-likelihood
exp_lddda(x, v1) exp_lddda(x, v1)exp_lddda(x, v1) exp_lddda(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
3d array
3d array
Logf for RUST
exp_logf(params, x)exp_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_logfdd(x, v1) exp_logfdd(x, v1)exp_logfdd(x, v1) exp_logfdd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_logfddd(x, v1) exp_logfddd(x, v1)exp_logfddd(x, v1) exp_logfddd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
3d array
3d array
Log scores for MLE and RHP predictions calculated using leave-one-out
exp_logscores(logscores, x)exp_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qexp_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rexp_p1_cp(n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE) dexp_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pexp_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) texp_p1_cp(n, x, t, debug = FALSE)qexp_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rexp_p1_cp(n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE) dexp_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pexp_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) texp_p1_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The exponential distribution with a predictor has exceedance distribution function
where
is the random variable
and
is the rate parameter, modelled as a function
of the parameters and a predictor .
The calibrating prior is given by the right Haar prior, which is
. as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d055exp_p1_example_data_v1_x tt=fitdistcp::d055exp_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qexp_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qexp_p1_cp)", main="Exponential w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d055exp_p1_example_data_v1_x tt=fitdistcp::d055exp_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qexp_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qexp_p1_cp)", main="Exponential w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
exp_p1_f1fa(x, t0, v1, v2)exp_p1_f1fa(x, t0, v1, v2)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Vector
The first derivative of the density for WAIC
exp_p1_f1fw(x, t, v1, v2)exp_p1_f1fw(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density for DMGS
exp_p1_f2fa(x, t0, v1, v2)exp_p1_f2fa(x, t0, v1, v2)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the density for WAIC
exp_p1_f2fw(x, t, v1, v2)exp_p1_f2fw(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_fd(x, t, v1, v2)exp_p1_fd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_fdd(x, t, v1, v2)exp_p1_fdd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
exp_p1_ldda(x, t, v1, v2)exp_p1_ldda(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
exp_p1_lddda(x, t, v1, v2)exp_p1_lddda(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
exp_p1_logf(params, x, t)exp_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_logfdd(x, t, v1, v2)exp_p1_logfdd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_logfddd(x, t, v1, v2)exp_p1_logfddd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
3d array
observed log-likelihood function
exp_p1_loglik(vv, x, t)exp_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
exp_p1_logscores(logscores, x, t)exp_p1_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
exp distribution: RHP means
exp_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)exp_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
exp_p1_mu1fa(alpha, t0, v1, v2)exp_p1_mu1fa(alpha, t0, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
exp_p1_mu2fa(alpha, t0, v1, v2)exp_p1_mu2fa(alpha, t0, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The first derivative of the cdf
exp_p1_p1fa(x, t0, v1, v2)exp_p1_p1fa(x, t0, v1, v2)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the cdf
exp_p1_p2fa(x, t0, v1, v2)exp_p1_p2fa(x, t0, v1, v2)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_pd(x, t, v1, v2)exp_p1_pd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_p1_pdd(x, t, v1, v2)exp_p1_pdd(x, t, v1, v2)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Predicted Parameter and Generalized Residuals
exp_p1_predictordata(predictordata, x, t, t0, params)exp_p1_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
exp_p1_waic(waicscores, x, t, v1hat, v2hat, lddi, lddd, lambdad)exp_p1_waic(waicscores, x, t, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the cdf
The first derivative of the cdf
exp_p1fa(x, v1) exp_p1fa(x, v1)exp_p1fa(x, v1) exp_p1fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
The second derivative of the cdf
The second derivative of the cdf
exp_p2fa(x, v1) exp_p2fa(x, v1)exp_p2fa(x, v1) exp_p2fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_pd(x, v1) exp_pd(x, v1)exp_pd(x, v1) exp_pd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
exp_pdd(x, v1) exp_pdd(x, v1)exp_pdd(x, v1) exp_pdd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
Waicscores
exp_waic(waicscores, x, v1hat)exp_waic(waicscores, x, v1hat)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
Two numeric values.
Find the number of predictors in the predictor
findnt(t)findnt(t)
t |
a vector or matrix of predictors |
Vector
Deal with situations in which the user wants d or p outside the GEV range
fixgevrange(y, v1, v2, v3)fixgevrange(y, v1, v2, v3)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Deal with situations in which the user wants d or p outside the GPD range
fixgpdrange(y, v1, v2, v3)fixgpdrange(y, v1, v2, v3)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qfrechet_k1_cp( x, p = seq(0.1, 0.9, 0.1), kloc = 0, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rfrechet_k1_cp(n, x, kloc = 0, rust = FALSE, mlcp = TRUE, debug = FALSE) dfrechet_k1_cp(x, y = x, kloc = 0, rust = FALSE, nrust = 1000, debug = FALSE) pfrechet_k1_cp(x, y = x, kloc = 0, rust = FALSE, nrust = 1000, debug = FALSE) tfrechet_k1_cp(n, x, kloc = 0, debug = FALSE)qfrechet_k1_cp( x, p = seq(0.1, 0.9, 0.1), kloc = 0, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rfrechet_k1_cp(n, x, kloc = 0, rust = FALSE, mlcp = TRUE, debug = FALSE) dfrechet_k1_cp(x, y = x, kloc = 0, rust = FALSE, nrust = 1000, debug = FALSE) pfrechet_k1_cp(x, y = x, kloc = 0, rust = FALSE, nrust = 1000, debug = FALSE) tfrechet_k1_cp(n, x, kloc = 0, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
kloc |
the known location parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Frechet distribution has distribution function
where
is the random variable,
are the parameters
and we consider to be known (hence the k1 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d051frechet_k1_example_data_v1 p=c(1:9)/10 q=qfrechet_k1_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qfrechet_k1_cp)", main="Frechet: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d051frechet_k1_example_data_v1 p=c(1:9)/10 q=qfrechet_k1_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qfrechet_k1_cp)", main="Frechet: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
frechet_k1_f1fa(x, v1, v2, kloc)frechet_k1_f1fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
The second derivative of the density
frechet_k1_f2fa(x, v1, v2, kloc)frechet_k1_f2fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_fd(x, v1, v2, v3)frechet_k1_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_fdd(x, v1, v2, v3)frechet_k1_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
frechet_k1_ldda(x, v1, v2, kloc)frechet_k1_ldda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
The third derivative of the normalized log-likelihood
frechet_k1_lddda(x, v1, v2, kloc)frechet_k1_lddda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
3d array
Logf for RUST
frechet_k1_logf(params, x, kloc)frechet_k1_logf(params, x, kloc)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kloc |
the known location parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_logfdd(x, v1, v2, v3)frechet_k1_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_logfddd(x, v1, v2, v3)frechet_k1_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Minus the first derivative of the cdf, at alpha
frechet_k1_mu1fa(alpha, v1, v2, kloc)frechet_k1_mu1fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
Minus the second derivative of the cdf, at alpha
frechet_k1_mu2fa(alpha, v1, v2, kloc)frechet_k1_mu2fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
The first derivative of the cdf
frechet_k1_p1fa(x, v1, v2, kloc)frechet_k1_p1fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
The second derivative of the cdf
frechet_k1_p2fa(x, v1, v2, kloc)frechet_k1_p2fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_pd(x, v1, v2, v3)frechet_k1_pd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_k1_pdd(x, v1, v2, v3)frechet_k1_pdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Waic
frechet_k1_waic(waicscores, x, v1hat, v2hat, kloc, lddi, lddd, lambdad)frechet_k1_waic(waicscores, x, v1hat, v2hat, kloc, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
kloc |
the known location parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
log-likelihood function
frechet_loglik(vv, x, kloc)frechet_loglik(vv, x, kloc)
vv |
parameters |
x |
a vector of training data values |
kloc |
the known location parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
frechet_logscores(logscores, x, kloc)frechet_logscores(logscores, x, kloc)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
kloc |
the known location parameter |
Two scalars
MLE and RHP predictive means
frechet_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kloc)frechet_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kloc)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
kloc |
the known location parameter |
Two scalars
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, kloc = 0, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rfrechet_p2k1_cp( n, x, t, t0 = NA, n0 = NA, kloc = 0, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, y = x, kloc = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, y = x, kloc = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tfrechet_p2k1_cp(n, x, t, kloc = 0, debug = FALSE)qfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, kloc = 0, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rfrechet_p2k1_cp( n, x, t, t0 = NA, n0 = NA, kloc = 0, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, y = x, kloc = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pfrechet_p2k1_cp( x, t, t0 = NA, n0 = NA, y = x, kloc = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tfrechet_p2k1_cp(n, x, t, kloc = 0, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
kloc |
the known location parameter |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Frechet distribution with predictor has distribution function
where
is the random variable,
is the scale parameter, modelled as a function of
parameters and predictor ,
and is the shape parameter.
We consider to be known (hence the k1 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d071frechet_p2k1_example_data_v1_x tt=fitdistcp::d071frechet_p2k1_example_data_v1_t p=c(1:9)/10 n0=10 q=qfrechet_p2k1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qfrechet_p2k1_cp)", main="Frechet w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d071frechet_p2k1_example_data_v1_x tt=fitdistcp::d071frechet_p2k1_example_data_v1_t p=c(1:9)/10 n0=10 q=qfrechet_p2k1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qfrechet_p2k1_cp)", main="Frechet w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
frechet_p2k1_f1fa(x, t0, v1, v2, v3, kloc)frechet_p2k1_f1fa(x, t0, v1, v2, v3, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Vector
The first derivative of the density for WAIC
frechet_p2k1_f1fw(x, t, v1, v2, v3, kloc)frechet_p2k1_f1fw(x, t, v1, v2, v3, kloc)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Vector
The second derivative of the density for DMGS
frechet_p2k1_f2fa(x, t0, v1, v2, v3, kloc)frechet_p2k1_f2fa(x, t0, v1, v2, v3, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Matrix
The second derivative of the density for WAIC
frechet_p2k1_f2fw(x, t, v1, v2, v3, kloc)frechet_p2k1_f2fw(x, t, v1, v2, v3, kloc)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_fd(x, t, v1, v2, v3, v4)frechet_p2k1_fd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_fdd(x, t, v1, v2, v3, v4)frechet_p2k1_fdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the normalized log-likelihood
frechet_p2k1_ldda(x, t, v1, v2, v3, kloc)frechet_p2k1_ldda(x, t, v1, v2, v3, kloc)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Matrix
The third derivative of the normalized log-likelihood
frechet_p2k1_lddda(x, t, v1, v2, v3, kloc)frechet_p2k1_lddda(x, t, v1, v2, v3, kloc)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
3d array
Logf for RUST
frechet_p2k1_logf(params, x, t, kloc)frechet_p2k1_logf(params, x, t, kloc)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kloc |
the known location parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_logfdd(x, t, v1, v2, v3, v4)frechet_p2k1_logfdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_logfddd(x, t, v1, v2, v3, v4)frechet_p2k1_logfddd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
observed log-likelihood function
frechet_p2k1_loglik(vv, x, t, kloc)frechet_p2k1_loglik(vv, x, t, kloc)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kloc |
the known location parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
frechet_p2k1_logscores(logscores, x, t, kloc)frechet_p2k1_logscores(logscores, x, t, kloc)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kloc |
the known location parameter |
Two scalars
frechet_k1 distribution: RHP mean
frechet_p2k1_means( means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim, kloc )frechet_p2k1_means( means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim, kloc )
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
kloc |
the known location parameter |
Two scalars
Minus the first derivative of the cdf, at alpha
frechet_p2k1_mu1fa(alpha, t0, v1, v2, v3, kloc)frechet_p2k1_mu1fa(alpha, t0, v1, v2, v3, kloc)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Vector
Minus the second derivative of the cdf, at alpha
frechet_p2k1_mu2fa(alpha, t0, v1, v2, v3, kloc)frechet_p2k1_mu2fa(alpha, t0, v1, v2, v3, kloc)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Matrix
The first derivative of the cdf
frechet_p2k1_p1fa(x, t0, v1, v2, v3, kloc)frechet_p2k1_p1fa(x, t0, v1, v2, v3, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Vector
The second derivative of the cdf
frechet_p2k1_p2fa(x, t0, v1, v2, v3, kloc)frechet_p2k1_p2fa(x, t0, v1, v2, v3, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kloc |
the known location parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_pd(x, t, v1, v2, v3, v4)frechet_p2k1_pd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
frechet_p2k1_pdd(x, t, v1, v2, v3, v4)frechet_p2k1_pdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Predicted Parameter and Generalized Residuals
frechet_p2k1_predictordata(predictordata, x, t, t0, params, kloc)frechet_p2k1_predictordata(predictordata, x, t, t0, params, kloc)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
kloc |
the known location parameter |
Two vectors
Waic
frechet_p2k1_waic( waicscores, x, t, v1hat, v2hat, v3hat, kloc, lddi, lddd, lambdad )frechet_p2k1_waic( waicscores, x, t, v1hat, v2hat, v3hat, kloc, lddi, lddd, lambdad )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
kloc |
the known location parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgamma_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rgamma_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tgamma_cp(n, x, fd1 = 0.01, fd2 = 0.01, debug = FALSE)qgamma_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rgamma_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tgamma_cp(n, x, fd1 = 0.01, fd2 = 0.01, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
fd1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
prior |
logical indicating which prior to use |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Gamma distribution has probability density function
where
is the random variable and
are the parameters.
The calibrating prior we use is
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d100gamma_example_data_v1 p=c(1:9)/10 q=qgamma_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgamma_cp)", main="Gamma: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d100gamma_example_data_v1 p=c(1:9)/10 q=qgamma_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgamma_cp)", main="Gamma: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
gamma_f1f(y, v1, fd1, v2, fd2)gamma_f1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density
gamma_f1fa(x, v1, v2)gamma_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
DMGS equation 3.3, f2 term
gamma_f2f(y, v1, fd1, v2, fd2)gamma_f2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density
gamma_f2fa(x, v1, v2)gamma_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gamma_fd(x, v1, v2)gamma_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gamma_fdd(x, v1, v2)gamma_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Second derivative matrix of the expected log-likelihood
gamma_gg(v1, fd1, v2, fd2)gamma_gg(v1, fd1, v2, fd2)
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
One component of the second derivative of the expected log-likelihood
gamma_gmn(alpha, v1, fd1, v2, fd2, mm, nn)gamma_gmn(alpha, v1, fd1, v2, fd2, mm, nn)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
Second derivative matrix of the normalized log-likelihood
gamma_ldd(x, v1, fd1, v2, fd2)gamma_ldd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
gamma_ldda(x, v1, v2)gamma_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
gamma_lddd(x, v1, fd1, v2, fd2)gamma_lddd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
gamma_lddda(x, v1, v2)gamma_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
One component of the second derivative of the normalized log-likelihood
gamma_lmn(x, v1, fd1, v2, fd2, mm, nn)gamma_lmn(x, v1, fd1, v2, fd2, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the second derivative of the normalized log-likelihood
gamma_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)gamma_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
gamma_logf(params, x)gamma_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gamma_logfdd(x, v1, v2)gamma_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gamma_logfddd(x, v1, v2)gamma_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
gamma_loglik(vv, x)gamma_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
gamma_logscores(logscores, x, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)gamma_logscores(logscores, x, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
MLE and RHP predictive means
gamma_means(means, ml_params, lddi, lddd, lambdad_cp, nx, dim = 2)gamma_means(means, ml_params, lddi, lddd, lambdad_cp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_cp |
derivative of the log prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
DMGS equation 3.3, mu1 term
gamma_mu1f(alpha, v1, fd1, v2, fd2)gamma_mu1f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
gamma_mu2f(alpha, v1, fd1, v2, fd2)gamma_mu2f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
DMGS equation 3.3, p1 term
gamma_p1f(y, v1, fd1, v2, fd2)gamma_p1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, p2 term
gamma_p2f(y, v1, fd1, v2, fd2)gamma_p2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Waic
gamma_waic(waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs)gamma_waic(waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
Bootstrap
gev_boot(x, n)gev_boot(x, n)
x |
a vector of training data values |
n |
number of random samples required |
A list containing a matrix of simulated parameter values
Check MLE
gev_checkmle(ml_params, minxi = -1, maxxi = 1)gev_checkmle(ml_params, minxi = -1, maxxi = 1)
ml_params |
parameters |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_cp( x, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, customprior = 0, dmgs = TRUE, rust = FALSE, nrust = 1e+05, pwm = FALSE, debug = FALSE ) rgev_cp( n, x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, method = "rust", extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_cp( x, y = x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) pgev_cp( x, y = x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) tgev_cp(method, n, x, ics = c(0, 0, 0), extramodels = FALSE, debug = FALSE)qgev_cp( x, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, customprior = 0, dmgs = TRUE, rust = FALSE, nrust = 1e+05, pwm = FALSE, debug = FALSE ) rgev_cp( n, x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, method = "rust", extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_cp( x, y = x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) pgev_cp( x, y = x, ics = c(0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) tgev_cp(method, n, x, ics = c(0, 0, 0), extramodels = FALSE, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
ics |
initial conditions for the maximum likelihood search |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
customprior |
a custom value for the slope of the log prior at the maxlik estimate |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
pwm |
logical for whether to include PWM results (longer runtime) |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
method |
character string that indicates whether to use
rust |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
boot |
logical that indicates whether bootstrap-based posterior sampling calculations should be run or not (longer run time) |
nboot |
the number of posterior samples used in the bootstrap calculations |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution has distribution function
where
where
is the random variable and
are the parameters.
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will stop with an error if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
Such values seldom occur
in real observed data for maxima.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
q**** optionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_quantiles: predictive quantiles
calculated from Bayesian integration with a flat prior.
rh_ml_quantiles: predictive quantiles
calculated from Bayesian integration with the calibrating prior, and the maximmum
likelihood estimate for the shape parameter.
jp_quantiles: predictive quantiles
calculated from Bayesian integration with Jeffreys' prior.
r**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_deviates: predictive random deviates calculated using a
Bayesian analysis with a flat prior.
rh_ml_deviates: predictive random deviates calculated using a
Bayesian analysis with the RHP-MLE prior.
jp_deviates: predictive random deviates calculated using a
Bayesian analysis with the JP.
d**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_pdf: predictive density function from a Bayesian analysis
with the flat prior.
rh_ml_pdf: predictive density function from a Bayesian analysis
with the RHP-MLE prior.
jp_pdf: predictive density function from a Bayesian analysis
with the JP.
p**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_cdf: predictive distribution function from a Bayesian analysis
with the flat prior.
rh_ml_cdf: predictive distribution function from a Bayesian analysis
with the RHP-MLE prior.
jp_cdf: predictive distribution function from a Bayesian analysis
with the JP.
These additional predictive distributions are included for comparison with the calibrating prior model. They generally give less good reliability than the calibrating prior.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 shape=-0.4 x=fitdistcp::d110gev_example_data_v1 p=c(1:9)/10 q=qgev_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_cp)", main="GEVD: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# # example 1 shape=-0.4 x=fitdistcp::d110gev_example_data_v1 p=c(1:9)/10 q=qgev_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_cp)", main="GEVD: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
The first derivative of the density
gev_f1fa(x, v1, v2, v3)gev_f1fa(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density
gev_f2fa(x, v1, v2, v3)gev_f2fa(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_fd(x, v1, v2, v3)gev_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_fdd(x, v1, v2, v3)gev_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Temporary dummy for one of the ppm models
gev_k12_ppm_minusloglik(x)gev_k12_ppm_minusloglik(x)
x |
a vector of training data values |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_k3_cp( x, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, kshape = 0, means = FALSE, waicscores = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgev_k3_cp(n, x, kshape = 0, rust = FALSE, mlcp = TRUE, debug = FALSE) dgev_k3_cp(x, y = x, kshape = 0, rust = FALSE, nrust = 1000, debug = FALSE) pgev_k3_cp(x, y = x, kshape = 0, rust = FALSE, nrust = 1000, debug = FALSE) tgev_k3_cp(n, x, kshape = 0, debug = FALSE)qgev_k3_cp( x, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, kshape = 0, means = FALSE, waicscores = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgev_k3_cp(n, x, kshape = 0, rust = FALSE, mlcp = TRUE, debug = FALSE) dgev_k3_cp(x, y = x, kshape = 0, rust = FALSE, nrust = 1000, debug = FALSE) pgev_k3_cp(x, y = x, kshape = 0, rust = FALSE, nrust = 1000, debug = FALSE) tgev_k3_cp(n, x, kshape = 0, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
fdalpha |
if |
kshape |
the known shape parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution with known shape has distribution function
where
where
is the random variable,
are the parameters
and is known (hence the k3 in the name).
The calibrating prior we use is given by
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 kshape=-0.4 x=fitdistcp::d053gev_k3_example_data_v1 p=c(1:9)/10 q=qgev_k3_cp(x,p,kshape=kshape,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_k3_cp)", main="GEV: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue") muhat=q$ml_params[1] sghat=q$ml_params[2] xi=kshape qmax=ifelse(xi<0,muhat-sghat/xi,Inf) cat(" ml_params=",q$ml_params,",") cat(" qmax=",qmax,"\n")# # example 1 kshape=-0.4 x=fitdistcp::d053gev_k3_example_data_v1 p=c(1:9)/10 q=qgev_k3_cp(x,p,kshape=kshape,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_k3_cp)", main="GEV: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue") muhat=q$ml_params[1] sghat=q$ml_params[2] xi=kshape qmax=ifelse(xi<0,muhat-sghat/xi,Inf) cat(" ml_params=",q$ml_params,",") cat(" qmax=",qmax,"\n")
The first derivative of the density
gev_k3_f1fa(x, v1, v2, kshape)gev_k3_f1fa(x, v1, v2, kshape)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
Vector
The second derivative of the density
gev_k3_f2fa(x, v1, v2, kshape)gev_k3_f2fa(x, v1, v2, kshape)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_fd(x, v1, v2, v3)gev_k3_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_fdd(x, v1, v2, v3)gev_k3_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_k3_ldda(x, v1, v2, kshape)gev_k3_ldda(x, v1, v2, kshape)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_k3_lddda(x, v1, v2, kshape)gev_k3_lddda(x, v1, v2, kshape)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
3d array
Logf for RUST
gev_k3_logf(params, x, kshape)gev_k3_logf(params, x, kshape)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kshape |
the known shape parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_logfdd(x, v1, v2, v3)gev_k3_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_logfddd(x, v1, v2, v3)gev_k3_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
log-likelihood function
gev_k3_loglik(vv, x, kshape)gev_k3_loglik(vv, x, kshape)
vv |
parameters |
x |
a vector of training data values |
kshape |
the known shape parameter |
Scalar
MLE and RHP means
gev_k3_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kshape)gev_k3_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kshape)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
kshape |
the known shape parameter |
Two scalars
Minus the first derivative of the cdf, at alpha
gev_k3_mu1fa(alpha, v1, v2, kshape)gev_k3_mu1fa(alpha, v1, v2, kshape)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_k3_mu2fa(alpha, v1, v2, kshape)gev_k3_mu2fa(alpha, v1, v2, kshape)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_pd(x, v1, v2, v3)gev_k3_pd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_k3_pdd(x, v1, v2, v3)gev_k3_pdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Waic
gev_k3_waic(waicscores, x, v1hat, v2hat, kshape, lddi, lddd, lambdad)gev_k3_waic(waicscores, x, v1hat, v2hat, kshape, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
kshape |
the known shape parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The combined derivative of the normalized log-likelihood
gev_ld12a(x, v1, v2, v3)gev_ld12a(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
The first derivative of the normalized log-likelihood
gev_lda(x, v1, v2, v3)gev_lda(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the normalized log-likelihood
gev_ldda(x, v1, v2, v3)gev_ldda(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_lddda(x, v1, v2, v3)gev_lddda(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
gev_logf(params, x)gev_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
First derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_logfd(x, v1, v2, v3)gev_logfd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_logfdd(x, v1, v2, v3)gev_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_logfddd(x, v1, v2, v3)gev_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
log-likelihood function
gev_loglik(vv, x)gev_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Analytical Expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_means( means, ml_params, lddi, lddd, lambdad_rh_flat, lambdad_custom, nx, dim = 3 )gev_means( means, ml_params, lddi, lddd, lambdad_rh_flat, lambdad_custom, nx, dim = 3 )
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rh_flat |
derivative of the log CRHP-FLAT prior |
lambdad_custom |
custom value of the derivative of the log prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
gev_mu1fa(alpha, v1, v2, v3)gev_mu1fa(alpha, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_mu2fa(alpha, v1, v2, v3)gev_mu2fa(alpha, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Check MLE
gev_p1_checkmle(ml_params, minxi = -1, maxxi = 1)gev_p1_checkmle(ml_params, minxi = -1, maxxi = 1)
ml_params |
parameters |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1_cp( n, x, t, t0 = NA, n0 = NA, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_p1_cp( x, t, t0 = NA, n0 = NA, y = x, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1_cp( x, t, t0 = NA, n0 = NA, y = x, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1_cp(n, x, t, ics = c(0, 0, 0, 0), extramodels = FALSE, debug = FALSE)qgev_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1_cp( n, x, t, t0 = NA, n0 = NA, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_p1_cp( x, t, t0 = NA, n0 = NA, y = x, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1_cp( x, t, t0 = NA, n0 = NA, y = x, ics = c(0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1_cp(n, x, t, ics = c(0, 0, 0, 0), extramodels = FALSE, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
ics |
initial conditions for the maximum likelihood search |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution with a predictor has distribution function
where
where
is the random variable,
is the location parameter,
modelled as a function of parameters and predictor ,
and are the scale and shape parameters.
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will switch to maximum likelihood prediction if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
If this happens, it is reported in the revert2ml flag.
Such values seldom occur
in real observed data for maxima.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
q**** optionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_quantiles: predictive quantiles
calculated from Bayesian integration with a flat prior.
rh_ml_quantiles: predictive quantiles
calculated from Bayesian integration with the calibrating prior, and the maximmum
likelihood estimate for the shape parameter.
jp_quantiles: predictive quantiles
calculated from Bayesian integration with Jeffreys' prior.
r**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_deviates: predictive random deviates calculated using a
Bayesian analysis with a flat prior.
rh_ml_deviates: predictive random deviates calculated using a
Bayesian analysis with the RHP-MLE prior.
jp_deviates: predictive random deviates calculated using a
Bayesian analysis with the JP.
d**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_pdf: predictive density function from a Bayesian analysis
with the flat prior.
rh_ml_pdf: predictive density function from a Bayesian analysis
with the RHP-MLE prior.
jp_pdf: predictive density function from a Bayesian analysis
with the JP.
p**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_cdf: predictive distribution function from a Bayesian analysis
with the flat prior.
rh_ml_cdf: predictive distribution function from a Bayesian analysis
with the RHP-MLE prior.
jp_cdf: predictive distribution function from a Bayesian analysis
with the JP.
These additional predictive distributions are included for comparison with the calibrating prior model. They generally give less good reliability than the calibrating prior.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# example 1 x=fitdistcp::d150gev_p1_example_data_v1_x tt=fitdistcp::d150gev_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgev_p1_cp(x=x,t=tt,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# example 1 x=fitdistcp::d150gev_p1_example_data_v1_x tt=fitdistcp::d150gev_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgev_p1_cp(x=x,t=tt,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
Logf for RUST
gev_p1_logf(params, x, t)gev_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
observed log-likelihood function
gev_p1_loglik(vv, x, t)gev_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Analytical expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rh_flat, nx, dim = 4)gev_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rh_flat, nx, dim = 4)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rh_flat |
derivative of the log CRHP-FLAT prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Predicted Parameter and Generalized Residuals
gev_p1_predictordata(predictordata, x, t, t0, params)gev_p1_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Set initial conditions
gev_p1_setics(x, t, ics)gev_p1_setics(x, t, ics)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
gev_p1_waic(waicscores, x, t0, v1hat, v2hat, v3hat, v4hat, lddi, lddd, lambdad)gev_p1_waic(waicscores, x, t0, v1hat, v2hat, v3hat, v4hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
v4hat |
fourth parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
Check MLE
gev_p12_checkmle(ml_params, minxi = -1, maxxi = 1)gev_p12_checkmle(ml_params, minxi = -1, maxxi = 1)
ml_params |
parameters |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p12_cp( n, x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 10, centering = TRUE, debug = FALSE ) pgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p12_cp( n, x, t1, t2, ics = c(0, 0, 0, 0, 0), extramodels = FALSE, debug = FALSE )qgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p12_cp( n, x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 10, centering = TRUE, debug = FALSE ) pgev_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p12_cp( n, x, t1, t2, ics = c(0, 0, 0, 0, 0), extramodels = FALSE, debug = FALSE )
x |
a vector of training data values |
t1 |
a vector of predictors for the mean,
such that |
t2 |
a vector of predictors for the sd,
such that |
t01 |
a single value of the predictor
(specify either |
t02 |
a single value of the predictor
(specify either |
n01 |
an index for the predictor
(specify either |
n02 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
ics |
initial conditions for the maximum likelihood search |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution with two predictors has distribution function
where
where
is the random variable,
is the location parameter,
modelled as a function of parameters and predictor ,
is the scale parameter,
modelled as a function of parameters and predictor ,
and is the shape parameter.
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will switch to maximum likelihood prediction if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
If this happens, it is reported in the revert2ml flag.
Such values seldom occur
in real observed data for maxima.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# example 1 x=fitdistcp::d151gev_p12_example_data_v1_x tt=fitdistcp::d151gev_p12_example_data_v1_t t1=tt[,1] t2=tt[,2] p=c(1:9)/10 n01=10 n02=10 q=qgev_p12_cp(x=x,t1=t1,t2=t2,n01=n01,n02=n02,t01=NA,t02=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p12_cp)", main="GEVD w/ p12: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# example 1 x=fitdistcp::d151gev_p12_example_data_v1_x tt=fitdistcp::d151gev_p12_example_data_v1_t t1=tt[,1] t2=tt[,2] p=c(1:9)/10 n01=10 n02=10 q=qgev_p12_cp(x=x,t1=t1,t2=t2,n01=n01,n02=n02,t01=NA,t02=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p12_cp)", main="GEVD w/ p12: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
The first derivative of the density for DMGS
gev_p12_f1fa(x, t01, t02, v1, v2, v3, v4, v5)gev_p12_f1fa(x, t01, t02, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
The first derivative of the density for WAIC
gev_p12_f1fw(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_f1fw(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
The second derivative of the density for DMGS
gev_p12_f2fa(x, t01, t02, v1, v2, v3, v4, v5)gev_p12_f2fa(x, t01, t02, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The second derivative of the density for WAIC
gev_p12_f2fw(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_f2fw(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_fd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_fd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_fdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_fdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p12_ldda(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_ldda(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p12_lddda(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_lddda(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
3d array
Logf for RUST
gev_p12_logf(params, x, t1, t2)gev_p12_logf(params, x, t1, t2)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_logfdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_logfdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_logfddd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_logfddd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
3d array
observed log-likelihood function
gev_p12_loglik(vv, x, t1, t2)gev_p12_loglik(vv, x, t1, t2)
vv |
parameters |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
Scalar
Analytical expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_p12_means(means, t01, t02, ml_params, nx)gev_p12_means(means, t01, t02, ml_params, nx)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ml_params |
parameters |
nx |
length of training data |
Two scalars
Minus the first derivative of the cdf, at alpha
gev_p12_mu1fa(alpha, t01, t02, v1, v2, v3, v4, v5)gev_p12_mu1fa(alpha, t01, t02, v1, v2, v3, v4, v5)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p12_mu2fa(alpha, t01, t02, v1, v2, v3, v4, v5)gev_p12_mu2fa(alpha, t01, t02, v1, v2, v3, v4, v5)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_pd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_pd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12_pdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12_pdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
Predicted Parameter and Generalized Residuals
gev_p12_predictordata(predictordata, x, t1, t2, t01, t02, params)gev_p12_predictordata(predictordata, x, t1, t2, t01, t02, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Set initial conditions
gev_p12_setics(x, t1, t2, ics)gev_p12_setics(x, t1, t2, ics)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
gev_p12_waic( waicscores, x, t1, t2, v1hat, v2hat, v3hat, v4hat, v5hat, lddi, lddd, lambdad )gev_p12_waic( waicscores, x, t1, t2, v1hat, v2hat, v3hat, v4hat, v5hat, lddi, lddd, lambdad )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
v4hat |
fourth parameter |
v5hat |
fifth parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
Check MLE
gev_p123_checkmle(ml_params, minxi = -1, maxxi = 1, t1, t2, t3)gev_p123_checkmle(ml_params, minxi = -1, maxxi = 1, t1, t2, t3)
ml_params |
parameters |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rgev_p123_cp( n, x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, y = x, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 10, centering = TRUE, debug = FALSE ) pgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, y = x, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p123_cp( n, x, t1, t2, t3, ics = c(0, 0, 0, 0, 0, 0), extramodels = FALSE, debug = FALSE )qgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0, 0, 0), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rgev_p123_cp( n, x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, y = x, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 10, centering = TRUE, debug = FALSE ) pgev_p123_cp( x, t1, t2, t3, t01 = NA, t02 = NA, t03 = NA, n01 = NA, n02 = NA, n03 = NA, y = x, ics = c(0, 0, 0, 0, 0, 0), minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p123_cp( n, x, t1, t2, t3, ics = c(0, 0, 0, 0, 0, 0), extramodels = FALSE, debug = FALSE )
x |
a vector of training data values |
t1 |
a vector of predictors for the mean,
such that |
t2 |
a vector of predictors for the sd,
such that |
t3 |
a vector of predictors for the shape,
such that |
t01 |
a single value of the predictor
(specify either |
t02 |
a single value of the predictor
(specify either |
t03 |
a single value of the predictor
(specify either |
n01 |
an index for the predictor
(specify either |
n02 |
an index for the predictor
(specify either |
n03 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
ics |
initial conditions for the maximum likelihood search |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution with three predictors has distribution function
where
where
is the random variable,
is the location parameter,
modelled as a function of parameters and predictor ,
is the scale parameter,
modelled as a function of parameters and predictor ,
and
is the shape parameter,
modelled as a function of parameters and predictor .
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will switch to maximum likelihood prediction if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
If this happens, it is reported in the revert2ml flag.
Such values seldom occur
in real observed data for maxima.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d152gev_p123_example_data_v1_x tt=fitdistcp::d152gev_p123_example_data_v1_t t1=tt[,1] t2=tt[,2] t3=tt[,3] p=c(1:9)/10 n01=10 n02=10 n03=10 q=qgev_p123_cp(x=x,t1=t1,t2=t2,t3=t3,n01=n01,n02=n02,n03=n03,t01=NA,t02=NA,t03=NA, p=p,rust=FALSE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p123_cp)", main="GEVD w/ p123: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) cat(" ml_params=",q$ml_params,"\n")# # example 1 x=fitdistcp::d152gev_p123_example_data_v1_x tt=fitdistcp::d152gev_p123_example_data_v1_t t1=tt[,1] t2=tt[,2] t3=tt[,3] p=c(1:9)/10 n01=10 n02=10 n03=10 q=qgev_p123_cp(x=x,t1=t1,t2=t2,t3=t3,n01=n01,n02=n02,n03=n03,t01=NA,t02=NA,t03=NA, p=p,rust=FALSE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p123_cp)", main="GEVD w/ p123: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) cat(" ml_params=",q$ml_params,"\n")
The first derivative of the density for DMGS
gev_p123_f1fa(x, t01, t02, t03, v1, v2, v3, v4, v5, v6)gev_p123_f1fa(x, t01, t02, t03, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
The first derivative of the density for WAIC
gev_p123_f1fw(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_f1fw(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
The second derivative of the density for DMGS
gev_p123_f2fa(x, t01, t02, t03, v1, v2, v3, v4, v5, v6)gev_p123_f2fa(x, t01, t02, t03, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The second derivative of the density for WAIC
gev_p123_f2fw(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_f2fw(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_fd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_fd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_fdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_fdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p123_ldda(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_ldda(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p123_lddda(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_lddda(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
3d array
Logf for RUST
gev_p123_logf(params, x, t1, t2, t3)gev_p123_logf(params, x, t1, t2, t3)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_logfdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_logfdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_logfddd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_logfddd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
3d array
observed log-likelihood function
gev_p123_loglik(vv, x, t1, t2, t3)gev_p123_loglik(vv, x, t1, t2, t3)
vv |
parameters |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
Scalar
Analytical expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_p123_means(means, t01, t02, t03, ml_params, nx)gev_p123_means(means, t01, t02, t03, ml_params, nx)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
ml_params |
parameters |
nx |
length of training data |
Two scalars
Minus the first derivative of the cdf, at alpha
gev_p123_mu1fa(alpha, t01, t02, t03, v1, v2, v3, v4, v5, v6)gev_p123_mu1fa(alpha, t01, t02, t03, v1, v2, v3, v4, v5, v6)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p123_mu2fa(alpha, t01, t02, t03, v1, v2, v3, v4, v5, v6)gev_p123_mu2fa(alpha, t01, t02, t03, v1, v2, v3, v4, v5, v6)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_pd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_pd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p123_pdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)gev_p123_pdd(x, t1, t2, t3, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
Predicted Parameter and Generalized Residuals
gev_p123_predictordata(x, t1, t2, t3, t01, t02, t03, params)gev_p123_predictordata(x, t1, t2, t3, t01, t02, t03, params)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Set initial conditions
gev_p123_setics(x, t1, t2, t3, ics)gev_p123_setics(x, t1, t2, t3, ics)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
gev_p123_waic( waicscores, x, t1, t2, t3, v1h, v2h, v3h, v4h, v5h, v6h, lddi, lddd, lambdad )gev_p123_waic( waicscores, x, t1, t2, t3, v1h, v2h, v3h, v4h, v5h, v6h, lddi, lddd, lambdad )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
v1h |
first parameter |
v2h |
second parameter |
v3h |
third parameter |
v4h |
fourth parameter |
v5h |
fifth parameter |
v6h |
sixth parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the density for DMGS
gev_p12k3_f1fa(x, t01, t02, v1, v2, v3, v4, kshape)gev_p12k3_f1fa(x, t01, t02, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Vector
The first derivative of the density for WAIC
gev_p12k3_f1fw(x, t1, t2, v1, v2, v3, v4, kshape)gev_p12k3_f1fw(x, t1, t2, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Vector
The second derivative of the density for DMGS
gev_p12k3_f2fa(x, t01, t02, v1, v2, v3, v4, kshape)gev_p12k3_f2fa(x, t01, t02, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Matrix
The second derivative of the density for WAIC
gev_p12k3_f2fw(x, t1, t2, v1, v2, v3, v4, kshape)gev_p12k3_f2fw(x, t1, t2, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_fd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_fd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_fdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_fdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p12k3_ldda(x, t1, t2, v1, v2, v3, v4, kshape)gev_p12k3_ldda(x, t1, t2, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p12k3_lddda(x, t1, t2, v1, v2, v3, v4, kshape)gev_p12k3_lddda(x, t1, t2, v1, v2, v3, v4, kshape)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
3d array
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_logfdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_logfdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_logfddd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_logfddd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
3d array
Minus the first derivative of the cdf, at alpha
gev_p12k3_mu1fa(alpha, t01, t02, v1, v2, v3, v4, kshape)gev_p12k3_mu1fa(alpha, t01, t02, v1, v2, v3, v4, kshape)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p12k3_mu2fa(alpha, t01, t02, v1, v2, v3, v4, kshape)gev_p12k3_mu2fa(alpha, t01, t02, v1, v2, v3, v4, kshape)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_pd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_pd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p12k3_pdd(x, t1, t2, v1, v2, v3, v4, v5)gev_p12k3_pdd(x, t1, t2, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The first derivative of the density for DMGS
gev_p1a_f1fa(x, t0, v1, v2, v3, v4)gev_p1a_f1fa(x, t0, v1, v2, v3, v4)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
The first derivative of the density for WAIC
gev_p1a_f1fw(x, t, v1, v2, v3, v4)gev_p1a_f1fw(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
The second derivative of the density for DMGS
gev_p1a_f2fa(x, t0, v1, v2, v3, v4)gev_p1a_f2fa(x, t0, v1, v2, v3, v4)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the density for WAIC
gev_p1a_f2fw(x, t, v1, v2, v3, v4)gev_p1a_f2fw(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_fd(x, t, v1, v2, v3, v4)gev_p1a_fd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_fdd(x, t, v1, v2, v3, v4)gev_p1a_fdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p1a_ldda(x, t, v1, v2, v3, v4)gev_p1a_ldda(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p1a_lddda(x, t, v1, v2, v3, v4)gev_p1a_lddda(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_logfdd(x, t, v1, v2, v3, v4)gev_p1a_logfdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_logfddd(x, t, v1, v2, v3, v4)gev_p1a_logfddd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
Minus the first derivative of the cdf, at alpha
gev_p1a_mu1fa(alpha, t0, v1, v2, v3, v4)gev_p1a_mu1fa(alpha, t0, v1, v2, v3, v4)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p1a_mu2fa(alpha, t0, v1, v2, v3, v4)gev_p1a_mu2fa(alpha, t0, v1, v2, v3, v4)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_pd(x, t, v1, v2, v3, v4)gev_p1a_pd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1a_pdd(x, t, v1, v2, v3, v4)gev_p1a_pdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The first derivative of the density for DMGS
gev_p1b_f1fa(x, t0a, t0b, v1, v2, v3, v4, v5)gev_p1b_f1fa(x, t0a, t0b, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
The first derivative of the density for WAIC
gev_p1b_f1fw(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_f1fw(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
The second derivative of the density for DMGS
gev_p1b_f2fa(x, t0a, t0b, v1, v2, v3, v4, v5)gev_p1b_f2fa(x, t0a, t0b, v1, v2, v3, v4, v5)
x |
a vector of training data values |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The second derivative of the density for WAIC
gev_p1b_f2fw(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_f2fw(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_fd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_fd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_fdd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_fdd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p1b_ldda(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_ldda(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p1b_lddda(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_lddda(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
3d array
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_logfdd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_logfdd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_logfddd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_logfddd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
3d array
Minus the first derivative of the cdf, at alpha
gev_p1b_mu1fa(alpha, t0a, t0b, v1, v2, v3, v4, v5)gev_p1b_mu1fa(alpha, t0a, t0b, v1, v2, v3, v4, v5)
alpha |
a vector of values of alpha (one minus probability) |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p1b_mu2fa(alpha, t0a, t0b, v1, v2, v3, v4, v5)gev_p1b_mu2fa(alpha, t0a, t0b, v1, v2, v3, v4, v5)
alpha |
a vector of values of alpha (one minus probability) |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_pd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_pd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1b_pdd(x, ta, tb, v1, v2, v3, v4, v5)gev_p1b_pdd(x, ta, tb, v1, v2, v3, v4, v5)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
Matrix
The first derivative of the density for DMGS
gev_p1c_f1fa(x, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)gev_p1c_f1fa(x, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
t0c |
a single value of the predictor, for the third column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
The first derivative of the density for WAIC
gev_p1c_f1fw(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_f1fw(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
The second derivative of the density for DMGS
gev_p1c_f2fa(x, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)gev_p1c_f2fa(x, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
t0c |
a single value of the predictor, for the third column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The second derivative of the density for WAIC
gev_p1c_f2fw(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_f2fw(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_fd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_fd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_fdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_fdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p1c_ldda(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_ldda(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p1c_lddda(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_lddda(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
3d array
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_logfdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_logfdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_logfddd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_logfddd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
3d array
Minus the first derivative of the cdf, at alpha
gev_p1c_mu1fa(alpha, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)gev_p1c_mu1fa(alpha, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)
alpha |
a vector of values of alpha (one minus probability) |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
t0c |
a single value of the predictor, for the third column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p1c_mu2fa(alpha, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)gev_p1c_mu2fa(alpha, t0a, t0b, t0c, v1, v2, v3, v4, v5, v6)
alpha |
a vector of values of alpha (one minus probability) |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
t0c |
a single value of the predictor, for the third column of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_pd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_pd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1c_pdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)gev_p1c_pdd(x, ta, tb, tc, v1, v2, v3, v4, v5, v6)
x |
a vector of training data values |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
v5 |
fifth parameter |
v6 |
sixth parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_p1k3_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, kshape = 0, means = FALSE, waicscores = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1k3_cp( n, x, t, t0 = NA, n0 = NA, kshape = 0, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, kshape = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, kshape = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1k3_cp(n, x, t, kshape = 0, debug = FALSE)qgev_p1k3_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, kshape = 0, means = FALSE, waicscores = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1k3_cp( n, x, t, t0 = NA, n0 = NA, kshape = 0, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dgev_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, kshape = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, kshape = 0, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1k3_cp(n, x, t, kshape = 0, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
fdalpha |
if |
kshape |
the known shape parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The GEV distribution with known shape with a predictor has distribution function
where
where
is the random variable,
is the location parameter,
is the shape parameter and
is known (hence the k3 in the name).
The calibrating prior we use is given by
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d150gev_p1_example_data_v1_x #use data for 150 tt=fitdistcp::d150gev_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgev_p1k3_cp(x=x,t=tt,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1k3_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# # example 1 x=fitdistcp::d150gev_p1_example_data_v1_x #use data for 150 tt=fitdistcp::d150gev_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgev_p1k3_cp(x=x,t=tt,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1k3_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
The first derivative of the density for DMGS
gev_p1k3_f1fa(x, t0, v1, v2, v3, kshape)gev_p1k3_f1fa(x, t0, v1, v2, v3, kshape)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Vector
The first derivative of the density for WAIC
gev_p1k3_f1fw(x, t, v1, v2, v3, kshape)gev_p1k3_f1fw(x, t, v1, v2, v3, kshape)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Vector
The second derivative of the density for DMGS
gev_p1k3_f2fa(x, t0, v1, v2, v3, kshape)gev_p1k3_f2fa(x, t0, v1, v2, v3, kshape)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Matrix
The second derivative of the density for WAIC
gev_p1k3_f2fw(x, t, v1, v2, v3, kshape)gev_p1k3_f2fw(x, t, v1, v2, v3, kshape)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_fd(x, t, v1, v2, v3, v4)gev_p1k3_fd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_fdd(x, t, v1, v2, v3, v4)gev_p1k3_fdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the normalized log-likelihood
gev_p1k3_ldda(x, t, v1, v2, v3, kshape)gev_p1k3_ldda(x, t, v1, v2, v3, kshape)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Matrix
The third derivative of the normalized log-likelihood
gev_p1k3_lddda(x, t, v1, v2, v3, kshape)gev_p1k3_lddda(x, t, v1, v2, v3, kshape)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
3d array
Logf for RUST
gev_p1k3_logf(params, x, t, kshape)gev_p1k3_logf(params, x, t, kshape)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kshape |
the known shape parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_logfdd(x, t, v1, v2, v3, v4)gev_p1k3_logfdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_logfddd(x, t, v1, v2, v3, v4)gev_p1k3_logfddd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
GEV-with-known-shape-with-p1 observed log-likelihood function
gev_p1k3_loglik(vv, x, t, kshape)gev_p1k3_loglik(vv, x, t, kshape)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kshape |
the known shape parameter |
Scalar
Analytical expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_p1k3_means(means, t0, ml_params, kshape, nx)gev_p1k3_means(means, t0, ml_params, kshape, nx)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
kshape |
the known shape parameter |
nx |
length of training data |
Two scalars
Minus the first derivative of the cdf, at alpha
gev_p1k3_mu1fa(alpha, t0, v1, v2, v3, kshape)gev_p1k3_mu1fa(alpha, t0, v1, v2, v3, kshape)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Vector
Minus the second derivative of the cdf, at alpha
gev_p1k3_mu2fa(alpha, t0, v1, v2, v3, kshape)gev_p1k3_mu2fa(alpha, t0, v1, v2, v3, kshape)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kshape |
the known shape parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_pd(x, t, v1, v2, v3, v4)gev_p1k3_pd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_p1k3_pdd(x, t, v1, v2, v3, v4)gev_p1k3_pdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Predicted Parameter and Generalized Residuals
gev_p1k3_predictordata(predictordata, x, t, t0, params, kshape)gev_p1k3_predictordata(predictordata, x, t, t0, params, kshape)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
kshape |
the known shape parameter |
Two vectors
Waic
gev_p1k3_waic( waicscores, x, t, v1hat, v2hat, v3hat, kshape, lddi, lddd, lambdad )gev_p1k3_waic( waicscores, x, t, v1hat, v2hat, v3hat, kshape, lddi, lddd, lambdad )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
kshape |
the known shape parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
Check MLE
gev_p1n_checkmle(ml_params, minxi = -1, maxxi = 1)gev_p1n_checkmle(ml_params, minxi = -1, maxxi = 1)
ml_params |
parameters |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgev_p1n_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1n_cp( n, x, t, t0 = NA, n0 = NA, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_p1n_cp( x, t, t0 = NA, n0 = NA, y = x, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1n_cp( x, t, t0 = NA, n0 = NA, y = x, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1n_cp(n, x, t, extramodels = FALSE, debug = FALSE)qgev_p1n_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), fdalpha = 0.01, minxi = -1, maxxi = 1, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgev_p1n_cp( n, x, t, t0 = NA, n0 = NA, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgev_p1n_cp( x, t, t0 = NA, n0 = NA, y = x, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgev_p1n_cp( x, t, t0 = NA, n0 = NA, y = x, minxi = -1, maxxi = 1, extramodels = FALSE, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgev_p1n_cp(n, x, t, extramodels = FALSE, debug = FALSE)
x |
a vector of training data values |
t |
predictors, which can be a vector, or a matrix with 1, 2 or 3 columns |
t0 |
a single value for each predictor, as 1, 2 or 3 scalars
(specify |
n0 |
an index for the each predictor, as 1, 2 or 3 integers
(specify |
p |
a vector of probabilities at which to generate predictive quantiles |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
1, 2 or 3 predictors on the location parameter are supported. For instance, the GEV distribution with 2 predictors has distribution function
where
where
is the random variable,
is the location parameter,
modelled as a function of parameters and predictor ,
and are the scale and shape parameters.
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will switch to maximum likelihood prediction if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
If this happens, it is reported in the revert2ml flag.
Such values seldom occur
in real observed data for maxima.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
q**** optionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_quantiles: predictive quantiles
calculated from Bayesian integration with a flat prior.
rh_ml_quantiles: predictive quantiles
calculated from Bayesian integration with the calibrating prior, and the maximmum
likelihood estimate for the shape parameter.
jp_quantiles: predictive quantiles
calculated from Bayesian integration with Jeffreys' prior.
r**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_deviates: predictive random deviates calculated using a
Bayesian analysis with a flat prior.
rh_ml_deviates: predictive random deviates calculated using a
Bayesian analysis with the RHP-MLE prior.
jp_deviates: predictive random deviates calculated using a
Bayesian analysis with the JP.
d**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_pdf: predictive density function from a Bayesian analysis
with the flat prior.
rh_ml_pdf: predictive density function from a Bayesian analysis
with the RHP-MLE prior.
jp_pdf: predictive density function from a Bayesian analysis
with the JP.
p**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_cdf: predictive distribution function from a Bayesian analysis
with the flat prior.
rh_ml_cdf: predictive distribution function from a Bayesian analysis
with the RHP-MLE prior.
jp_cdf: predictive distribution function from a Bayesian analysis
with the JP.
These additional predictive distributions are included for comparison with the calibrating prior model. They generally give less good reliability than the calibrating prior.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# example 1 x=fitdistcp::d150gev_p1_example_data_v1_x t1=fitdistcp::d150gev_p1_example_data_v1_t t2=sample(t1) t=cbind(t1,t2) p=c(1:9)/10 n0=c(10,10) q=qgev_p1n_cp(x=x,t=t,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1n_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# example 1 x=fitdistcp::d150gev_p1_example_data_v1_x t1=fitdistcp::d150gev_p1_example_data_v1_t t2=sample(t1) t=cbind(t1,t2) p=c(1:9)/10 n0=c(10,10) q=qgev_p1n_cp(x=x,t=t,n0=n0,t0=NA,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgev_p1n_cp)", main="GEVD w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
Logf for RUST
gev_p1n_logf(params, x, t)gev_p1n_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
observed log-likelihood function
gev_p1n_loglik(vv, x, t)gev_p1n_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Analytical expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gev_p1n_means( means, t0, ml_params, lddi, lddd, lambdad_rh_flat, nx, dim = (nt + 3) )gev_p1n_means( means, t0, ml_params, lddi, lddd, lambdad_rh_flat, nx, dim = (nt + 3) )
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rh_flat |
derivative of the log CRHP-FLAT prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
GEV_p1n n=1 example data
gev_p1n_n1_exampledata(iseed)gev_p1n_n1_exampledata(iseed)
iseed |
The random seed |
A list containing data to run an example
GEV_p1n n=2 example data
gev_p1n_n2_exampledata(iseed)gev_p1n_n2_exampledata(iseed)
iseed |
The random seed |
A list containing data to run an example
Predicted Parameter and Generalized Residuals
gev_p1n_predictordata(predictordata, x, t, t0, params)gev_p1n_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Set initial conditions
gev_p1n_setics(x, t)gev_p1n_setics(x, t)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Vector
Waic
gev_p1n_waic(waicscores, x, t0, vhat, lddi, lddd, lambdad)gev_p1n_waic(waicscores, x, t0, vhat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
vhat |
vector of all parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_pd(x, v1, v2, v3)gev_pd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gev_pdd(x, v1, v2, v3)gev_pdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
PWM parameter estimation
gev_pwm_params(x)gev_pwm_params(x)
x |
a vector of training data values |
Vector
Set initial conditions
gev_setics(x, ics)gev_setics(x, ics)
x |
a vector of training data values |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
gev_waic(waicscores, x, v1hat, v2hat, v3hat, lddi, lddd, lambdad)gev_waic(waicscores, x, v1hat, v2hat, v3hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgnorm_k3_cp( x, p = seq(0.1, 0.9, 0.1), kbeta = 4, d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rgnorm_k3_cp( n, x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dgnorm_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pgnorm_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tgnorm_k3_cp(n, x, d1 = 0.01, fd2 = 0.01, kbeta = 4, debug = FALSE)qgnorm_k3_cp( x, p = seq(0.1, 0.9, 0.1), kbeta = 4, d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rgnorm_k3_cp( n, x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dgnorm_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pgnorm_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kbeta = 4, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tgnorm_k3_cp(n, x, d1 = 0.01, fd2 = 0.01, kbeta = 4, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
kbeta |
the known beta parameter |
d1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The generalized normal distribution has probability density function
where
is the random variable,
are the parameters and we consider
to be known
(hence the k3 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d032gnorm_k3_example_data_v1 p=c(1:9)/10 q=qgnorm_k3_cp(x,p,kbeta=4,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgnorm_k3_cp)", main="gnorm: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d032gnorm_k3_example_data_v1 p=c(1:9)/10 q=qgnorm_k3_cp(x,p,kbeta=4,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgnorm_k3_cp)", main="gnorm: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
gnorm_k3_f1f(y, v1, d1, v2, fd2, kbeta)gnorm_k3_f1f(y, v1, d1, v2, fd2, kbeta)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
Matrix
The first derivative of the density
gnorm_k3_f1fa(x, v1, v2, kbeta)gnorm_k3_f1fa(x, v1, v2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kbeta |
the known beta parameter |
Vector
DMGS equation 3.3, f2 term
gnorm_k3_f2f(y, v1, d1, v2, fd2, kbeta)gnorm_k3_f2f(y, v1, d1, v2, fd2, kbeta)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
3d array
The second derivative of the density
gnorm_k3_f2fa(x, v1, v2, kbeta)gnorm_k3_f2fa(x, v1, v2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kbeta |
the known beta parameter |
Matrix
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gnorm_k3_fd(x, v1, v2, v3)gnorm_k3_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gnorm_k3_fdd(x, v1, v2, v3)gnorm_k3_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
gnorm_k3_ldd(x, v1, d1, v2, fd2, kbeta)gnorm_k3_ldd(x, v1, d1, v2, fd2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
gnorm_k3_ldda(x, v1, v2, kbeta)gnorm_k3_ldda(x, v1, v2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kbeta |
the known beta parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
gnorm_k3_lddd(x, v1, d1, v2, fd2, kbeta)gnorm_k3_lddd(x, v1, d1, v2, fd2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
gnorm_k3_lddda(x, v1, v2, kbeta)gnorm_k3_lddda(x, v1, v2, kbeta)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kbeta |
the known beta parameter |
3d array
One component of the second derivative of the normalized log-likelihood
gnorm_k3_lmn(x, v1, d1, v2, fd2, kbeta, mm, nn)gnorm_k3_lmn(x, v1, d1, v2, fd2, kbeta, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
Logf for RUST
gnorm_k3_logf(params, x, kbeta)gnorm_k3_logf(params, x, kbeta)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kbeta |
the known beta parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gnorm_k3_logfdd(x, v1, v2, v3)gnorm_k3_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gnorm_k3_logfddd(x, v1, v2, v3)gnorm_k3_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
log-likelihood function
gnorm_k3_loglik(vv, x, kbeta)gnorm_k3_loglik(vv, x, kbeta)
vv |
parameters |
x |
a vector of training data values |
kbeta |
the known beta parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
gnorm_k3_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, kbeta, aderivs)gnorm_k3_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, kbeta, aderivs)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
DMGS equation 3.3, mu1 term
gnorm_k3_mu1f(alpha, v1, d1, v2, fd2, kbeta)gnorm_k3_mu1f(alpha, v1, d1, v2, fd2, kbeta)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
Matrix
DMGS equation 3.3, mu2 term
gnorm_k3_mu2f(alpha, v1, d1, v2, fd2, kbeta)gnorm_k3_mu2f(alpha, v1, d1, v2, fd2, kbeta)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
3d array
DMGS equation 3.3, p1 term
gnorm_k3_p1f(y, v1, d1, v2, fd2, kbeta)gnorm_k3_p1f(y, v1, d1, v2, fd2, kbeta)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
Matrix
DMGS equation 3.3, p2 term
gnorm_k3_p2f(y, v1, d1, v2, fd2, kbeta)gnorm_k3_p2f(y, v1, d1, v2, fd2, kbeta)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
3d array
One component of the second derivative of the normalized log-likelihood
gnorm_lmnp(x, v1, d1, v2, fd2, kbeta, mm, nn, rr)gnorm_lmnp(x, v1, d1, v2, fd2, kbeta, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Waic for RUST
gnorm_waic( waicscores, x, v1hat, d1, v2hat, fd2, kbeta, lddi, lddd, lambdad, aderivs )gnorm_waic( waicscores, x, v1hat, d1, v2hat, fd2, kbeta, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kbeta |
the known beta parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
Check MLE
gpd_k1_checkmle(ml_params, kloc, minxi = -1, maxxi = 2)gpd_k1_checkmle(ml_params, kloc, minxi = -1, maxxi = 2)
ml_params |
parameters |
kloc |
the known location parameter |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgpd_k1_cp( x, p = seq(0.1, 0.9, 0.1), kloc = 0, ics = c(0, 0), fdalpha = 0.01, customprior = 0, minxi = -1, maxxi = 2, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgpd_k1_cp( n, x, kloc = 0, ics = c(0, 0), minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgpd_k1_cp( x, y = x, kloc = 0, ics = c(0, 0), customprior = 0, minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, nrust = 1000, debug = FALSE ) pgpd_k1_cp( x, y = x, kloc = 0, ics = c(0, 0), customprior = 0, minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, nrust = 1000, debug = FALSE ) tgpd_k1_cp(n, x, kloc = 0, ics = c(0, 0), extramodels = FALSE, debug = FALSE)qgpd_k1_cp( x, p = seq(0.1, 0.9, 0.1), kloc = 0, ics = c(0, 0), fdalpha = 0.01, customprior = 0, minxi = -1, maxxi = 2, means = FALSE, waicscores = FALSE, extramodels = FALSE, pdf = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgpd_k1_cp( n, x, kloc = 0, ics = c(0, 0), minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgpd_k1_cp( x, y = x, kloc = 0, ics = c(0, 0), customprior = 0, minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, nrust = 1000, debug = FALSE ) pgpd_k1_cp( x, y = x, kloc = 0, ics = c(0, 0), customprior = 0, minxi = -1, maxxi = 2, extramodels = FALSE, rust = FALSE, nrust = 1000, debug = FALSE ) tgpd_k1_cp(n, x, kloc = 0, ics = c(0, 0), extramodels = FALSE, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
kloc |
the known location parameter |
ics |
initial conditions for the maximum likelihood search |
fdalpha |
if |
customprior |
a custom value for the slope of the log prior at the maxlik estimate |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
The GP distribution has exceedcance distribution function
where
is the random variable and
are the parameters.
The calibrating prior we use is given by
as given in Jewson et al. (2025).
The code will stop with an error if the
input data gives a maximum likelihood
value for the shape parameter that lies outside the range (minxi,maxxi),
since outside this range there may be numerical problems.
Such values seldom occur
in real observed data for maxima.
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
q**** optionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_quantiles: predictive quantiles
calculated from Bayesian integration with a flat prior.
rh_ml_quantiles: predictive quantiles
calculated from Bayesian integration with the calibrating prior, and the maximmum
likelihood estimate for the shape parameter.
jp_quantiles: predictive quantiles
calculated from Bayesian integration with Jeffreys' prior.
r**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_deviates: predictive random deviates calculated using a
Bayesian analysis with a flat prior.
rh_ml_deviates: predictive random deviates calculated using a
Bayesian analysis with the RHP-MLE prior.
jp_deviates: predictive random deviates calculated using a
Bayesian analysis with the JP.
d**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_pdf: predictive density function from a Bayesian analysis
with the flat prior.
rh_ml_pdf: predictive density function from a Bayesian analysis
with the RHP-MLE prior.
jp_pdf: predictive density function from a Bayesian analysis
with the JP.
p**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_cdf: predictive distribution function from a Bayesian analysis
with the flat prior.
rh_ml_cdf: predictive distribution function from a Bayesian analysis
with the RHP-MLE prior.
jp_cdf: predictive distribution function from a Bayesian analysis
with the JP.
These additional predictive distributions are included for comparison with the calibrating prior model. They generally give less good reliability than the calibrating prior.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d120gpd_k1_example_data_v1 p=c(1:9)/10 q=qgpd_k1_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgpd_k1_cp)", main="GPD: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")# # example 1 x=fitdistcp::d120gpd_k1_example_data_v1 p=c(1:9)/10 q=qgpd_k1_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgpd_k1_cp)", main="GPD: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue",lwd=2) cat(" ml_params=",q$ml_params,"\n")
The first derivative of the density
gpd_k1_f1fa(x, v1, v2, kloc)gpd_k1_f1fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
The second derivative of the density
gpd_k1_f2fa(x, v1, v2, kloc)gpd_k1_f2fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_fd(x, v1, v2, v3)gpd_k1_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_fdd(x, v1, v2, v3)gpd_k1_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
gpd_k1_ldda(x, v1, v2, kloc)gpd_k1_ldda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
The third derivative of the normalized log-likelihood
gpd_k1_lddda(x, v1, v2, kloc)gpd_k1_lddda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
3d array
Logf for RUST
gpd_k1_logf(params, x, kloc)gpd_k1_logf(params, x, kloc)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kloc |
the known location parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_logfdd(x, v1, v2, v3)gpd_k1_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_logfddd(x, v1, v2, v3)gpd_k1_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
log-likelihood function
gpd_k1_loglik(vv, x, kloc)gpd_k1_loglik(vv, x, kloc)
vv |
parameters |
x |
a vector of training data values |
kloc |
the known location parameter |
Scalar
Analytical Expressions for Predictive Means RHP mean based on the expectation of DMGS equation 2.1
gpd_k1_means( means, ml_params, lddi, lddd, lambdad_rh_flat, lambdad_jp, nx, dim = 2, kloc = 0 )gpd_k1_means( means, ml_params, lddi, lddd, lambdad_rh_flat, lambdad_jp, nx, dim = 2, kloc = 0 )
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rh_flat |
derivative of the log CRHP-FLAT prior |
lambdad_jp |
derivative of the log JP prior |
nx |
length of training data |
dim |
number of parameters |
kloc |
the known location parameter |
Two scalars
Minus the first derivative of the cdf, at alpha
gpd_k1_mu1fa(alpha, v1, v2, kloc)gpd_k1_mu1fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
Minus the second derivative of the cdf, at alpha
gpd_k1_mu2fa(alpha, v1, v2, kloc)gpd_k1_mu2fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_pd(x, v1, v2, v3)gpd_k1_pd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k1_pdd(x, v1, v2, v3)gpd_k1_pdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Set initial conditions
gpd_k1_setics(x, ics)gpd_k1_setics(x, ics)
x |
a vector of training data values |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
gpd_k1_waic(waicscores, x, v1hat, v2hat, kloc, lddi, lddd, lambdad)gpd_k1_waic(waicscores, x, v1hat, v2hat, kloc, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
kloc |
the known location parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the density
gpd_k13_f1fa(x, v1, v2, kloc)gpd_k13_f1fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
The second derivative of the density
gpd_k13_f2fa(x, v1, v2, kloc)gpd_k13_f2fa(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_fd(x, v1, v2, v3)gpd_k13_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_fdd(x, v1, v2, v3)gpd_k13_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
gpd_k13_ldda(x, v1, v2, kloc)gpd_k13_ldda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
The third derivative of the normalized log-likelihood
gpd_k13_lddda(x, v1, v2, kloc)gpd_k13_lddda(x, v1, v2, kloc)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
3d array
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_logfdd(x, v1, v2, v3)gpd_k13_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_logfddd(x, v1, v2, v3)gpd_k13_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Minus the first derivative of the cdf, at alpha
gpd_k13_mu1fa(alpha, v1, v2, kloc)gpd_k13_mu1fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Vector
Minus the second derivative of the cdf, at alpha
gpd_k13_mu2fa(alpha, v1, v2, kloc)gpd_k13_mu2fa(alpha, v1, v2, kloc)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
kloc |
the known location parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_pd(x, v1, v2, v3)gpd_k13_pd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gpd_k13_pdd(x, v1, v2, v3)gpd_k13_pdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgumbel_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgumbel_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dgumbel_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pgumbel_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tgumbel_cp(n, x, debug = FALSE)qgumbel_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rgumbel_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dgumbel_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pgumbel_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tgumbel_cp(n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Gumbel distribution has distribution function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d050gumbel_example_data_v1 p=c(1:9)/10 q=qgumbel_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgumbel_cp)", main="Gumbel: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d050gumbel_example_data_v1 p=c(1:9)/10 q=qgumbel_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgumbel_cp)", main="Gumbel: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
gumbel_f1fa(x, v1, v2)gumbel_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density
gumbel_f2fa(x, v1, v2)gumbel_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_fd(x, v1, v2)gumbel_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_fdd(x, v1, v2)gumbel_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
gumbel_ldda(x, v1, v2)gumbel_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
gumbel_lddda(x, v1, v2)gumbel_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
gumbel_logf(params, x)gumbel_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_logfdd(x, v1, v2)gumbel_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_logfddd(x, v1, v2)gumbel_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
gumbel_loglik(vv, x)gumbel_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
gumbel_logscores(logscores, x)gumbel_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
MLE and RHP predictive means
gumbel_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)gumbel_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
gumbel_mu1fa(alpha, v1, v2)gumbel_mu1fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
gumbel_mu2fa(alpha, v1, v2)gumbel_mu2fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qgumbel_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgumbel_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgumbel_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgumbel_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgumbel_p1_cp(n, x, t, debug = FALSE)qgumbel_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rgumbel_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dgumbel_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pgumbel_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tgumbel_p1_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Gumbel distribution with a predictor has distribution function
where
is the random variable,
is the shape parameter as a function of parameters
and predictor ,
and is the scale parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d070gumbel_p1_example_data_v1_x tt=fitdistcp::d070gumbel_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgumbel_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgumbel_p1_cp)", main="Gumbel w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d070gumbel_p1_example_data_v1_x tt=fitdistcp::d070gumbel_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qgumbel_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qgumbel_p1_cp)", main="Gumbel w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
gumbel_p1_f1fa(x, t0, v1, v2, v3)gumbel_p1_f1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
gumbel_p1_f1fw(x, t, v1, v2, v3)gumbel_p1_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density for DMGS
gumbel_p1_f2fa(x, t0, v1, v2, v3)gumbel_p1_f2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
gumbel_p1_f2fw(x, t, v1, v2, v3)gumbel_p1_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_fd(x, t, v1, v2, v3)gumbel_p1_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_fdd(x, t, v1, v2, v3)gumbel_p1_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
gumbel_p1_ldda(x, t, v1, v2, v3)gumbel_p1_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
gumbel_p1_lddda(x, t, v1, v2, v3)gumbel_p1_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
gumbel_p1_logf(params, x, t)gumbel_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_logfdd(x, t, v1, v2, v3)gumbel_p1_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_logfddd(x, t, v1, v2, v3)gumbel_p1_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
observed log-likelihood function
gumbel_p1_loglik(vv, x, t)gumbel_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
gumbel_p1_logscores(logscores, x, t)gumbel_p1_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
Gumbel distribution: RHP mean
gumbel_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim)gumbel_p1_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
gumbel_p1_mu1fa(alpha, t0, v1, v2, v3)gumbel_p1_mu1fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
gumbel_p1_mu2fa(alpha, t0, v1, v2, v3)gumbel_p1_mu2fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The first derivative of the cdf
gumbel_p1_p1fa(x, t0, v1, v2, v3)gumbel_p1_p1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the cdf
gumbel_p1_p2fa(x, t0, v1, v2, v3)gumbel_p1_p2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_pd(x, t, v1, v2, v3)gumbel_p1_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_p1_pdd(x, t, v1, v2, v3)gumbel_p1_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
gumbel_p1_predictordata(predictordata, x, t, t0, params)gumbel_p1_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
gumbel_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)gumbel_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the cdf
gumbel_p1fa(x, v1, v2)gumbel_p1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the cdf
gumbel_p2fa(x, v1, v2)gumbel_p2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_pd(x, v1, v2)gumbel_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
gumbel_pdd(x, v1, v2)gumbel_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Waic
gumbel_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)gumbel_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qhalfnorm_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rhalfnorm_cp( n, x, fd1 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dhalfnorm_cp( x, y = x, fd1 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) phalfnorm_cp( x, y = x, fd1 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) thalfnorm_cp(n, x, fd1 = 0.01, debug = FALSE)qhalfnorm_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rhalfnorm_cp( n, x, fd1 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dhalfnorm_cp( x, y = x, fd1 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) phalfnorm_cp( x, y = x, fd1 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) thalfnorm_cp(n, x, fd1 = 0.01, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
fd1 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The half-normal distribution has probability density function
where
is the random variable
and
is the parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025). Some other authors may parametrize the half-normal differently.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d020halfnorm_example_data_v1 p=c(1:9)/10 q=qhalfnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles) xmax=max(q$ml_quantiles,q$cp_quantiles) plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qhalfnorm_cp)", main="Halfnorm: quantile estimates") points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d020halfnorm_example_data_v1 p=c(1:9)/10 q=qhalfnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles) xmax=max(q$ml_quantiles,q$cp_quantiles) plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qhalfnorm_cp)", main="Halfnorm: quantile estimates") points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 2.1, f1 term
halfnorm_f1f(y, v1, fd1)halfnorm_f1f(y, v1, fd1)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density
The first derivative of the density
halfnorm_f1fa(x, v1) halfnorm_f1fa(x, v1)halfnorm_f1fa(x, v1) halfnorm_f1fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
DMGS equation 2.1, f2 term
halfnorm_f2f(y, v1, fd1)halfnorm_f2f(y, v1, fd1)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density
The second derivative of the density
halfnorm_f2fa(x, v1) halfnorm_f2fa(x, v1)halfnorm_f2fa(x, v1) halfnorm_f2fa(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
halfnorm_fd(x, v1) halfnorm_fd(x, v1)halfnorm_fd(x, v1) halfnorm_fd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Vector
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
halfnorm_fdd(x, v1) halfnorm_fdd(x, v1)halfnorm_fdd(x, v1) halfnorm_fdd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
Expected information matrix
halfnorm_gg(v1, fd1)halfnorm_gg(v1, fd1)
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
Second derivative of the expected log-likelihood
halfnorm_gg11(alpha, v1, fd1)halfnorm_gg11(alpha, v1, fd1)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Scalar value
Third derivative of the normalized log-likelihood
halfnorm_l111(x, v1, fd1)halfnorm_l111(x, v1, fd1)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Scalar value
The second derivative of the normalized log-likelihood
halfnorm_ldd(x, v1, fd1)halfnorm_ldd(x, v1, fd1)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
The second derivative of the normalized log-likelihood
halfnorm_ldda(x, v1) halfnorm_ldda(x, v1)halfnorm_ldda(x, v1) halfnorm_ldda(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
Third derivative tensor of the log-likelihood
halfnorm_lddd(x, v1, fd1)halfnorm_lddd(x, v1, fd1)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
The third derivative of the normalized log-likelihood
halfnorm_lddda(x, v1) halfnorm_lddda(x, v1)halfnorm_lddda(x, v1) halfnorm_lddda(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
3d array
3d array
Logf for RUST
halfnorm_logf(params, x)halfnorm_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
halfnorm_logfdd(x, v1) halfnorm_logfdd(x, v1)halfnorm_logfdd(x, v1) halfnorm_logfdd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
Matrix
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
halfnorm_logfddd(x, v1) halfnorm_logfddd(x, v1)halfnorm_logfddd(x, v1) halfnorm_logfddd(x, v1)
x |
a vector of training data values |
v1 |
first parameter |
3d array
3d array
Log-likelihood function
halfnorm_loglik(vv, x)halfnorm_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
halfnorm_logscores(logscores, x, fd1 = 0.01, aderivs = TRUE)halfnorm_logscores(logscores, x, fd1 = 0.01, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
MLE and RHP predictive means RHP mean based on the expectation of DMGS equation 2.1
halfnorm_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 1)halfnorm_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 1)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
DMGS equation 3.3, mu1 term
halfnorm_mu1f(alpha, v1, fd1)halfnorm_mu1f(alpha, v1, fd1)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
halfnorm_mu2f(alpha, v1, fd1)halfnorm_mu2f(alpha, v1, fd1)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
DMGS equation 2.1, p1 term
halfnorm_p1f(y, v1, fd1)halfnorm_p1f(y, v1, fd1)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 2.1, p2 term
halfnorm_p2f(y, v1, fd1)halfnorm_p2f(y, v1, fd1)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Waic
halfnorm_waic(waicscores, x, v1hat, fd1, lddi, lddd, lambdad, aderivs)halfnorm_waic(waicscores, x, v1hat, fd1, lddi, lddd, lambdad, aderivs)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
If a variable is a vector, convert it to a matrix
ifvectorthenmatrix(t)ifvectorthenmatrix(t)
t |
a vector or matrix of predictors |
Vector
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qinvgamma_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rinvgamma_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dinvgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pinvgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tinvgamma_cp(n, x, fd1 = 0.01, fd2 = 0.01, debug = FALSE)qinvgamma_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rinvgamma_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dinvgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) pinvgamma_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tinvgamma_cp(n, x, fd1 = 0.01, fd2 = 0.01, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
fd1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
prior |
logical indicating which prior to use |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Inverse Gamma distribution has probability density function
where
is the random variable and
are the parameters.
The calibrating prior we use is
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d101invgamma_example_data_v1 p=c(1:9)/10 q=qinvgamma_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qinvgamma_cp)", main="Invgamma: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d101invgamma_example_data_v1 p=c(1:9)/10 q=qinvgamma_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qinvgamma_cp)", main="Invgamma: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
invgamma_f1f(y, v1, fd1, v2, fd2)invgamma_f1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density
invgamma_f1fa(x, v1, v2)invgamma_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
DMGS equation 3.3, f2 term
invgamma_f2f(y, v1, fd1, v2, fd2)invgamma_f2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density
invgamma_f2fa(x, v1, v2)invgamma_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgamma_fd(x, v1, v2)invgamma_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgamma_fdd(x, v1, v2)invgamma_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
invgamma_ldd(x, v1, fd1, v2, fd2)invgamma_ldd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
invgamma_ldda(x, v1, v2)invgamma_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
invgamma_lddd(x, v1, fd1, v2, fd2)invgamma_lddd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
invgamma_lddda(x, v1, v2)invgamma_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
One component of the second derivative of the normalized log-likelihood
invgamma_lmn(x, v1, fd1, v2, fd2, mm, nn)invgamma_lmn(x, v1, fd1, v2, fd2, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the second derivative of the normalized log-likelihood
invgamma_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)invgamma_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
invgamma_logf(params, x)invgamma_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgamma_logfdd(x, v1, v2)invgamma_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgamma_logfddd(x, v1, v2)invgamma_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
invgamma_loglik(vv, x)invgamma_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and cp predictions calculated using leave-one-out
invgamma_logscores(logscores, x, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)invgamma_logscores(logscores, x, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
DMGS equation 3.3, mu1 term
invgamma_mu1f(alpha, v1, fd1, v2, fd2)invgamma_mu1f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
invgamma_mu2f(alpha, v1, fd1, v2, fd2)invgamma_mu2f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
DMGS equation 3.3, p1 term
invgamma_p1f(y, v1, fd1, v2, fd2)invgamma_p1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, p2 term
invgamma_p2f(y, v1, fd1, v2, fd2)invgamma_p2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Waic
invgamma_waic( waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs )invgamma_waic( waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qinvgauss_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rinvgauss_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, prior = "type 1", mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dinvgauss_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, prior = "type 1", debug = FALSE, aderivs = TRUE ) pinvgauss_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, prior = "type 1", debug = FALSE, aderivs = TRUE ) tinvgauss_cp(n, x, fd1 = 0.01, fd2 = 0.01, prior = "type 1", debug = FALSE)qinvgauss_cp( x, p = seq(0.1, 0.9, 0.1), fd1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, prior = "type 1", debug = FALSE, aderivs = TRUE ) rinvgauss_cp( n, x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, prior = "type 1", mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dinvgauss_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, prior = "type 1", debug = FALSE, aderivs = TRUE ) pinvgauss_cp( x, y = x, fd1 = 0.01, fd2 = 0.01, rust = FALSE, nrust = 1000, prior = "type 1", debug = FALSE, aderivs = TRUE ) tinvgauss_cp(n, x, fd1 = 0.01, fd2 = 0.01, prior = "type 1", debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
fd1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
prior |
logical indicating which prior to use |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Inverse Gaussian distribution has probability density function
where
is the random variable and
are the parameters.
The calibrating prior we use by default is
The prior
is also available as an option with prior="type 2".
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
debug=FALSE # example 1 can go wrong for small sample sizes, so I've increased to 50 # # example 1 if(debug)cat("example 1\n") x=fitdistcp::d102invgauss_example_data_v1 if(debug)cat("x=",x,"\n") p=c(1:9)/10 q=qinvgauss_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qinvgauss_cp)", main="Invgauss: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")debug=FALSE # example 1 can go wrong for small sample sizes, so I've increased to 50 # # example 1 if(debug)cat("example 1\n") x=fitdistcp::d102invgauss_example_data_v1 if(debug)cat("x=",x,"\n") p=c(1:9)/10 q=qinvgauss_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qinvgauss_cp)", main="Invgauss: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
invgauss_f1f(y, v1, fd1, v2, fd2)invgauss_f1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
The first derivative of the density
invgauss_f1fa(x, v1, v2)invgauss_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
DMGS equation 3.3, f2 term
invgauss_f2f(y, v1, fd1, v2, fd2)invgauss_f2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
The second derivative of the density
invgauss_f2fa(x, v1, v2)invgauss_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgauss_fd(x, v1, v2)invgauss_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgauss_fdd(x, v1, v2)invgauss_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
invgauss_ldd(x, v1, fd1, v2, fd2)invgauss_ldd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
invgauss_ldda(x, v1, v2)invgauss_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
invgauss_lddd(x, v1, fd1, v2, fd2)invgauss_lddd(x, v1, fd1, v2, fd2)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
invgauss_lddda(x, v1, v2)invgauss_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
One component of the second derivative of the normalized log-likelihood
invgauss_lmn(x, v1, fd1, v2, fd2, mm, nn)invgauss_lmn(x, v1, fd1, v2, fd2, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the second derivative of the normalized log-likelihood
invgauss_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)invgauss_lmnp(x, v1, fd1, v2, fd2, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
invgauss_logf(params, x, prior)invgauss_logf(params, x, prior)
params |
model parameters for calculating logf |
x |
a vector of training data values |
prior |
logical indicating which prior to use |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgauss_logfdd(x, v1, v2)invgauss_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
invgauss_logfddd(x, v1, v2)invgauss_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
invgauss_loglik(vv, x)invgauss_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
invgauss_logscores(logscores, x, prior, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)invgauss_logscores(logscores, x, prior, fd1 = 0.01, fd2 = 0.01, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
prior |
logical indicating which prior to use |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
MLE and RHP predictive means
invgauss_means(means, ml_params, lddi, lddd, lambdad_cp, nx, dim = 2)invgauss_means(means, ml_params, lddi, lddd, lambdad_cp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_cp |
derivative of the log prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
DMGS equation 3.3, mu1 term
invgauss_mu1f(alpha, v1, fd1, v2, fd2)invgauss_mu1f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, mu2 term
invgauss_mu2f(alpha, v1, fd1, v2, fd2)invgauss_mu2f(alpha, v1, fd1, v2, fd2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
DMGS equation 3.3, p1 term
invgauss_p1f(y, v1, fd1, v2, fd2)invgauss_p1f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
Matrix
DMGS equation 3.3, p2 term
invgauss_p2f(y, v1, fd1, v2, fd2)invgauss_p2f(y, v1, fd1, v2, fd2)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
3d array
Waic
invgauss_waic( waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs )invgauss_waic( waicscores, x, v1hat, fd1, v2hat, fd2, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
Jeffreys' Prior with two parameters
jpf2p(ggd, detg, ggi)jpf2p(ggd, detg, ggi)
ggd |
gradient of the expected information matrix |
detg |
determinant of the expected information matrix |
ggi |
inverse of the expected information matrix |
Vector of 2 values
Jeffreys' Prior with three parameters
jpf3p(ggd, detg, ggi)jpf3p(ggd, detg, ggi)
ggd |
gradient of the expected information matrix |
detg |
determinant of the expected information matrix |
ggi |
inverse of the expected information matrix |
Vector of 3 values
Jeffreys' Prior with four parameters
jpf4p(ggd, detg, ggi)jpf4p(ggd, detg, ggi)
ggd |
gradient of the expected information matrix |
detg |
determinant of the expected information matrix |
ggi |
inverse of the expected information matrix |
Vector of 4 values
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlnorm_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rlnorm_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dlnorm_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) plnorm_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tlnorm_cp(n, x, debug = FALSE)qlnorm_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rlnorm_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dlnorm_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) plnorm_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tlnorm_cp(n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The log normal distribution has probability density function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d035lnorm_example_data_v1 p=c(1:9)/10 q=qlnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_cp)", main="Log-normal: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d035lnorm_example_data_v1 p=c(1:9)/10 q=qlnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_cp)", main="Log-normal: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlnorm_dmgs_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, debug = FALSE ) rlnorm_dmgs_cp(n, x, mlcp = TRUE, debug = FALSE) dlnorm_dmgs_cp(x, y = x, debug = FALSE) plnorm_dmgs_cp(x, y, debug = FALSE)qlnorm_dmgs_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, debug = FALSE ) rlnorm_dmgs_cp(n, x, mlcp = TRUE, debug = FALSE) dlnorm_dmgs_cp(x, y = x, debug = FALSE) plnorm_dmgs_cp(x, y, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The log normal distribution has probability density function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d035lnorm_example_data_v1 p=c(1:9)/10 q=qlnorm_dmgs_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_dmgs_cp)", main="Log-normal_DMGS: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)# # example 1 x=fitdistcp::d035lnorm_example_data_v1 p=c(1:9)/10 q=qlnorm_dmgs_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_dmgs_cp)", main="Log-normal_DMGS: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)
log-likelihood function
lnorm_dmgs_loglik(vv, x)lnorm_dmgs_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar value.
Log scores for MLE and RHP predictions calculated using leave-one-out
lnorm_dmgs_logscores(logscores, x)lnorm_dmgs_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
MLE and RHP predictive means
lnorm_dmgs_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)lnorm_dmgs_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Waic
lnorm_dmgs_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)lnorm_dmgs_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the density
lnorm_f1fa(x, v1, v2)lnorm_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density
lnorm_f2fa(x, v1, v2)lnorm_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_fd(x, v1, v2)lnorm_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_fdd(x, v1, v2)lnorm_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
lnorm_ldda(x, v1, v2)lnorm_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
lnorm_lddda(x, v1, v2)lnorm_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
lnorm_logf(params, x)lnorm_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_logfdd(x, v1, v2)lnorm_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_logfddd(x, v1, v2)lnorm_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Log scores for MLE and RHP predictions calculated using leave-one-out
lnorm_logscores(logscores, x)lnorm_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
Minus the first derivative of the cdf, at alpha
lnorm_mu1fa(alpha, v1, v2)lnorm_mu1fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
lnorm_mu2fa(alpha, v1, v2)lnorm_mu2fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlnorm_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rlnorm_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dlnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) plnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tlnorm_p1_cp(n, x, t, debug = FALSE)qlnorm_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rlnorm_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dlnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) plnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tlnorm_p1_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The log normal distribution with a predictor has probability density function
where
is the random variable,
is the location parameter of the log of the random variable,
modelled as a function
of parameters and predictor ,
and is the scale parameter of the log of the random variable.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d061lnorm_p1_example_data_v1_x tt=fitdistcp::d061lnorm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qlnorm_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_p1_cp)", main="Log-Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d061lnorm_p1_example_data_v1_x tt=fitdistcp::d061lnorm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qlnorm_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlnorm_p1_cp)", main="Log-Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
lnorm_p1_f1fa(x, t0, v1, v2, v3)lnorm_p1_f1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
lnorm_p1_f1fw(x, t, v1, v2, v3)lnorm_p1_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density for DMGS
lnorm_p1_f2fa(x, t0, v1, v2, v3)lnorm_p1_f2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
lnorm_p1_f2fw(x, t, v1, v2, v3)lnorm_p1_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_fd(x, t, v1, v2, v3)lnorm_p1_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_fdd(x, t, v1, v2, v3)lnorm_p1_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
lnorm_p1_ldda(x, t, v1, v2, v3)lnorm_p1_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
lnorm_p1_lddda(x, t, v1, v2, v3)lnorm_p1_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
lnorm_p1_logf(params, x, t)lnorm_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_logfdd(x, t, v1, v2, v3)lnorm_p1_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_logfddd(x, t, v1, v2, v3)lnorm_p1_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Log-normal-with-p1 observed log-likelihood function
lnorm_p1_loglik(vv, x, t)lnorm_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
lnorm_p1_logscores(logscores, x, t)lnorm_p1_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
Minus the first derivative of the cdf, at alpha
lnorm_p1_mu1fa(alpha, t0, v1, v2, v3)lnorm_p1_mu1fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
lnorm_p1_mu2fa(alpha, t0, v1, v2, v3)lnorm_p1_mu2fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The first derivative of the cdf
lnorm_p1_p1fa(x, t0, v1, v2, v3)lnorm_p1_p1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the cdf
lnorm_p1_p2fa(x, t0, v1, v2, v3)lnorm_p1_p2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_pd(x, t, v1, v2, v3)lnorm_p1_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_p1_pdd(x, t, v1, v2, v3)lnorm_p1_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
lnorm_p1_predictordata(x, t, t0, params)lnorm_p1_predictordata(x, t, t0, params)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
lnorm_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat)lnorm_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
Two numeric values.
The first derivative of the cdf
lnorm_p1fa(x, v1, v2)lnorm_p1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the cdf
lnorm_p2fa(x, v1, v2)lnorm_p2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_pd(x, v1, v2)lnorm_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lnorm_pdd(x, v1, v2)lnorm_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Waic for RUST
lnorm_waic(waicscores, x, v1hat, v2hat)lnorm_waic(waicscores, x, v1hat, v2hat)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlogis_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rlogis_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dlogis_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) plogis_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tlogis_cp(n, x, debug = FALSE)qlogis_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rlogis_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dlogis_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) plogis_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tlogis_cp(n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The logistic distribution has distribution function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d040logis_example_data_v1 p=c(1:9)/10 q=qlogis_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlogis_cp)", main="Logistic: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d040logis_example_data_v1 p=c(1:9)/10 q=qlogis_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlogis_cp)", main="Logistic: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
logis_f1fa(x, v1, v2)logis_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density
logis_f2fa(x, v1, v2)logis_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_fd(x, v1, v2)logis_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_fdd(x, v1, v2)logis_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
logis_ldda(x, v1, v2)logis_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
logis_lddda(x, v1, v2)logis_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
logis_logf(params, x)logis_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_logfdd(x, v1, v2)logis_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_logfddd(x, v1, v2)logis_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
logis_loglik(vv, x)logis_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
logis_logscores(logscores, x)logis_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
Minus the first derivative of the cdf, at alpha
logis_mu1fa(alpha, v1, v2)logis_mu1fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
logis_mu2fa(alpha, v1, v2)logis_mu2fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlogis_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rlogis_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dlogis_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) plogis_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tlogis_p1_cp(n, x, t, debug = FALSE)qlogis_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rlogis_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dlogis_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) plogis_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tlogis_p1_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The logistic distribution with a predictor has distribution function
where
is the random variable,
is the location paramter, and is
the scale parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d062logis_p1_example_data_v1_x tt=fitdistcp::d062logis_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qlogis_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlogis_p1_cp)", main="Logistic w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d062logis_p1_example_data_v1_x tt=fitdistcp::d062logis_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qlogis_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlogis_p1_cp)", main="Logistic w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
logis_p1_f1fa(x, t0, v1, v2, v3)logis_p1_f1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
logis_p1_f1fw(x, t, v1, v2, v3)logis_p1_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density for DMGS
logis_p1_f2fa(x, t0, v1, v2, v3)logis_p1_f2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
logis_p1_f2fw(x, t, v1, v2, v3)logis_p1_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_fd(x, t, v1, v2, v3)logis_p1_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_fdd(x, t, v1, v2, v3)logis_p1_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
logis_p1_ldda(x, t, v1, v2, v3)logis_p1_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
logis_p1_lddda(x, t, v1, v2, v3)logis_p1_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
logis_p1_logf(params, x, t)logis_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_logfdd(x, t, v1, v2, v3)logis_p1_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_logfddd(x, t, v1, v2, v3)logis_p1_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logistic-with-p1 observed log-likelihood function
logis_p1_loglik(vv, x, t)logis_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
logis_p1_logscores(logscores, x, t)logis_p1_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
Logistic distribution: RHP mean
logis_p1_means(t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)logis_p1_means(t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
logis_p1_mu1fa(alpha, t0, v1, v2, v3)logis_p1_mu1fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
logis_p1_mu2fa(alpha, t0, v1, v2, v3)logis_p1_mu2fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The first derivative of the cdf
logis_p1_p1fa(x, t0, v1, v2, v3)logis_p1_p1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the cdf
logis_p1_p2fa(x, t0, v1, v2, v3)logis_p1_p2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_pd(x, t, v1, v2, v3)logis_p1_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_p1_pdd(x, t, v1, v2, v3)logis_p1_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
logis_p1_predictordata(predictordata, x, t, t0, params)logis_p1_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
logis_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)logis_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the cdf
logis_p1fa(x, v1, v2)logis_p1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the cdf
logis_p2fa(x, v1, v2)logis_p2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_pd(x, v1, v2)logis_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
logis_pdd(x, v1, v2)logis_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Waic
logis_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)logis_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlst_k3_cp( x, p = seq(0.1, 0.9, 0.1), kdf = 5, d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rlst_k3_cp( n, x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dlst_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) plst_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tlst_k3_cp(n, x, d1 = 0.01, fd2 = 0.01, kdf = 5, debug = FALSE)qlst_k3_cp( x, p = seq(0.1, 0.9, 0.1), kdf = 5, d1 = 0.01, fd2 = 0.01, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE, aderivs = TRUE ) rlst_k3_cp( n, x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, mlcp = TRUE, debug = FALSE, aderivs = TRUE ) dlst_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) plst_k3_cp( x, y = x, d1 = 0.01, fd2 = 0.01, kdf = 5, rust = FALSE, nrust = 1000, debug = FALSE, aderivs = TRUE ) tlst_k3_cp(n, x, d1 = 0.01, fd2 = 0.01, kdf = 5, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
kdf |
the known degrees of freedom parameter |
d1 |
if |
fd2 |
if |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The t distribution
(also known as the location-scale t distribution, hence the name lst),
has probability density function
where
is the random variable,
are the parameters,
and we consider the degrees of freedom to be known
(hence the k3 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d041lst_k3_example_data_v1 p=c(1:9)/10 q=qlst_k3_cp(x,p,kdf=5,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlst_k3_cp)", main="t: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d041lst_k3_example_data_v1 p=c(1:9)/10 q=qlst_k3_cp(x,p,kdf=5,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlst_k3_cp)", main="t: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 3.3, f1 term
lst_k3_f1f(y, v1, d1, v2, fd2, kdf)lst_k3_f1f(y, v1, d1, v2, fd2, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Matrix
The first derivative of the density
lst_k3_f1fa(x, v1, v2, kdf)lst_k3_f1fa(x, v1, v2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kdf |
the known degrees of freedom parameter |
Vector
DMGS equation 3.3, f2 term
lst_k3_f2f(y, v1, d1, v2, fd2, kdf)lst_k3_f2f(y, v1, d1, v2, fd2, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
The second derivative of the density
lst_k3_f2fa(x, v1, v2, kdf)lst_k3_f2fa(x, v1, v2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kdf |
the known degrees of freedom parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_k3_fd(x, v1, v2, v3)lst_k3_fd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_k3_fdd(x, v1, v2, v3)lst_k3_fdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
lst_k3_ldd(x, v1, d1, v2, fd2, kdf)lst_k3_ldd(x, v1, d1, v2, fd2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
lst_k3_ldda(x, v1, v2, kdf)lst_k3_ldda(x, v1, v2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kdf |
the known degrees of freedom parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
lst_k3_lddd(x, v1, d1, v2, fd2, kdf)lst_k3_lddd(x, v1, d1, v2, fd2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
lst_k3_lddda(x, v1, v2, kdf)lst_k3_lddda(x, v1, v2, kdf)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
kdf |
the known degrees of freedom parameter |
3d array
One component of the second derivative of the normalized log-likelihood
lst_k3_lmn(x, v1, d1, v2, fd2, kdf, mm, nn)lst_k3_lmn(x, v1, d1, v2, fd2, kdf, mm, nn)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the third derivative of the normalized log-likelihood
lst_k3_lmnp(x, v1, d1, v2, fd2, kdf, mm, nn, rr)lst_k3_lmnp(x, v1, d1, v2, fd2, kdf, mm, nn, rr)
x |
a vector of training data values |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
lst_k3_logf(params, x, kdf)lst_k3_logf(params, x, kdf)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kdf |
the known degrees of freedom parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_k3_logfdd(x, v1, v2, v3)lst_k3_logfdd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_k3_logfddd(x, v1, v2, v3)lst_k3_logfddd(x, v1, v2, v3)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
log-likelihood function
lst_k3_loglik(vv, x, kdf)lst_k3_loglik(vv, x, kdf)
vv |
parameters |
x |
a vector of training data values |
kdf |
the known degrees of freedom parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
lst_k3_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, kdf, aderivs = TRUE)lst_k3_logscores(logscores, x, d1 = 0.01, fd2 = 0.01, kdf, aderivs = TRUE)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
DMGS equation 3.3, mu1 term
lst_k3_mu1f(alpha, v1, d1, v2, fd2, kdf)lst_k3_mu1f(alpha, v1, d1, v2, fd2, kdf)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Matrix
DMGS equation 3.3, mu2 term
lst_k3_mu2f(alpha, v1, d1, v2, fd2, kdf)lst_k3_mu2f(alpha, v1, d1, v2, fd2, kdf)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
DMGS equation 3.3, p1 term
lst_k3_p1f(y, v1, d1, v2, fd2, kdf)lst_k3_p1f(y, v1, d1, v2, fd2, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Matrix
DMGS equation 3.3, p2 term
lst_k3_p2f(y, v1, d1, v2, fd2, kdf)lst_k3_p2f(y, v1, d1, v2, fd2, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
Waic
lst_k3_waic( waicscores, x, v1hat, d1, v2hat, fd2, kdf, lddi, lddd, lambdad, aderivs )lst_k3_waic( waicscores, x, v1hat, d1, v2hat, fd2, kdf, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qlst_p1k3_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) rlst_p1k3_cp( n, x, t, t0 = NA, n0 = NA, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) dlst_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) plst_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) tlst_p1k3_cp( n, x, t, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, debug = FALSE )qlst_p1k3_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) rlst_p1k3_cp( n, x, t, t0 = NA, n0 = NA, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE, aderivs = TRUE ) dlst_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) plst_p1k3_cp( x, t, t0 = NA, n0 = NA, y = x, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE, aderivs = TRUE ) tlst_p1k3_cp( n, x, t, d1 = 0.01, d2 = 0.01, fd3 = 0.01, kdf = 10, debug = FALSE )
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
d1 |
if |
d2 |
if |
fd3 |
if |
kdf |
the known degrees of freedom parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The t distribution with a predictor
(also known as the location-scale t distribution with a predictor,
hence the name lst),
has probability density function
where
is the random variable,
is the location parameter,
and is the scale parameter.
We consider the degrees of freedom to be known
(hence the k3 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d063lst_p1k3_example_data_v1_x tt=fitdistcp::d063lst_p1k3_example_data_v1_t p=c(1:9)/10 n0=10 q=qlst_p1k3_cp(x,tt,n0=n0,p=p,kdf=5,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlst_p1k3_cp)", main="t w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d063lst_p1k3_example_data_v1_x tt=fitdistcp::d063lst_p1k3_example_data_v1_t p=c(1:9)/10 n0=10 q=qlst_p1k3_cp(x,tt,n0=n0,p=p,kdf=5,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qlst_p1k3_cp)", main="t w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
DMGS equation 2.1, f1 term
lst_p1k3_f1f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_f1f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Matrix
The first derivative of the density for DMGS
lst_p1k3_f1fa(x, t0, v1, v2, v3, kdf)lst_p1k3_f1fa(x, t0, v1, v2, v3, kdf)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
Vector
The first derivative of the densityfor WAIC
lst_p1k3_f1fw(x, t, v1, v2, v3, kdf)lst_p1k3_f1fw(x, t, v1, v2, v3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
Vector
DMGS equation 2.1, f2 term
lst_p1k3_f2f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_f2f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
The second derivative of the density for DMGS
lst_p1k3_f2fa(x, t0, v1, v2, v3, kdf)lst_p1k3_f2fa(x, t0, v1, v2, v3, kdf)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
Matrix
The second derivative of the density for WAIC
lst_p1k3_f2fw(x, t, v1, v2, v3, kdf)lst_p1k3_f2fw(x, t, v1, v2, v3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_p1k3_fd(x, t, v1, v2, v3, v4)lst_p1k3_fd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_p1k3_fdd(x, t, v1, v2, v3, v4)lst_p1k3_fdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Second derivative matrix of the normalized log-likelihood
lst_p1k3_ldd(x, t, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_ldd(x, t, v1, d1, v2, d2, v3, fd3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Square scalar matrix
The second derivative of the normalized log-likelihood
lst_p1k3_ldda(x, t, v1, v2, v3, kdf)lst_p1k3_ldda(x, t, v1, v2, v3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
Matrix
Third derivative tensor of the normalized log-likelihood
lst_p1k3_lddd(x, t, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_lddd(x, t, v1, d1, v2, d2, v3, fd3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Cubic scalar array
The third derivative of the normalized log-likelihood
lst_p1k3_lddda(x, t, v1, v2, v3, kdf)lst_p1k3_lddda(x, t, v1, v2, v3, kdf)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
kdf |
the known degrees of freedom parameter |
3d array
One component of the second derivative of the normalized log-likelihood
lst_p1k3_lmn(x, t, v1, d1, v2, d2, v3, fd3, kdf, mm, nn)lst_p1k3_lmn(x, t, v1, d1, v2, d2, v3, fd3, kdf, mm, nn)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
Scalar value
One component of the second derivative of the normalized log-likelihood
lst_p1k3_lmnp(x, t, v1, d1, v2, d2, v3, fd3, kdf, mm, nn, rr)lst_p1k3_lmnp(x, t, v1, d1, v2, d2, v3, fd3, kdf, mm, nn, rr)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
Scalar value
Logf for RUST
lst_p1k3_logf(params, x, t, kdf)lst_p1k3_logf(params, x, t, kdf)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kdf |
the known degrees of freedom parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_p1k3_logfdd(x, t, v1, v2, v3, v4)lst_p1k3_logfdd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
lst_p1k3_logfddd(x, t, v1, v2, v3, v4)lst_p1k3_logfddd(x, t, v1, v2, v3, v4)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
LST-with-p1 observed log-likelihood function
lst_p1k3_loglik(vv, x, t, kdf)lst_p1k3_loglik(vv, x, t, kdf)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kdf |
the known degrees of freedom parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
lst_p1k3_logscores(logscores, x, t, d1, d2, fd3, kdf, aderivs)lst_p1k3_logscores(logscores, x, t, d1, d2, fd3, kdf, aderivs)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two scalars
DMGS equation 3.3, mu1 term
lst_p1k3_mu1f(alpha, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_mu1f(alpha, t0, v1, d1, v2, d2, v3, fd3, kdf)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
Matrix
DMGS equation 3.3, mu2 term
lst_p1k3_mu2f(alpha, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_mu2f(alpha, t0, v1, d1, v2, d2, v3, fd3, kdf)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
DMGS equation 2.1, p1 term
lst_p1k3_p1f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_p1f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)
y |
value of random variable |
t0 |
value of predictor |
v1 |
first parameter |
d1 |
delta for numerical derivative |
v2 |
second parameter |
d2 |
delta for numerical derivative |
v3 |
third parameter |
fd3 |
fractional delta for numerical derivative |
kdf |
the known number of degrees of freedom |
Matrix
DMGS equation 2.1, p2 term
lst_p1k3_p2f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)lst_p1k3_p2f(y, t0, v1, d1, v2, d2, v3, fd3, kdf)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
3d array
Predicted Parameter and Generalized Residuals
lst_p1k3_predictordata(predictordata, x, t, t0, params, kdf)lst_p1k3_predictordata(predictordata, x, t, t0, params, kdf)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
kdf |
the known degrees of freedom parameter |
Two vectors
Set initial conditions
lst_p1k3_setics(x, t, ics)lst_p1k3_setics(x, t, ics)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
lst_p1k3_waic( waicscores, x, t, v1hat, d1, v2hat, d2, v3hat, fd3, kdf, lddi, lddd, lambdad, aderivs )lst_p1k3_waic( waicscores, x, t, v1hat, d1, v2hat, d2, v3hat, fd3, kdf, lddi, lddd, lambdad, aderivs )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
v2hat |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
v3hat |
third parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
kdf |
the known degrees of freedom parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
Two numeric values.
Make WAIC
make_cwaic(x, fhatx, lddi, lddd, f1f, lambdad, f2f, dim)make_cwaic(x, fhatx, lddi, lddd, f1f, lambdad, f2f, dim)
x |
the training data |
fhatx |
density of x at the maximum likelihood parameters |
lddi |
inverse of the second derivative log-likelihood matrix |
lddd |
the third derivative log-likelihood tensor |
f1f |
the f1 term from DMGS equation 2.1 |
lambdad |
the slope of the log prior |
f2f |
the f2 term from DMGS equation 2.1 |
dim |
number of free parameters |
Two scalars
Calculate MAIC
make_maic(ml_value, nparams)make_maic(ml_value, nparams)
ml_value |
maximum of the likelihood |
nparams |
number of parameters |
Vector of 3 values Returns the two compoments of MAIC, and their sum
Make Standard Errors from lddi
make_se(nx, lddi)make_se(nx, lddi)
nx |
length of training data |
lddi |
the inverse log-likelihood matrix |
Vector
Make WAIC
make_waic(x, fhatx, lddi, lddd, f1f, lambdad, f2f, dim)make_waic(x, fhatx, lddi, lddd, f1f, lambdad, f2f, dim)
x |
the training data |
fhatx |
density of x at the maximum likelihood parameters |
lddi |
inverse of the second derivative log-likelihood matrix |
lddd |
the third derivative log-likelihood tensor |
f1f |
the f1 term from DMGS equation 2.1 |
lambdad |
the slope of the log prior |
f2f |
the f2 term from DMGS equation 2.1 |
dim |
number of free parameters |
Two scalars
Calculate the location parameter when there are predictors (single time point)
makebetat0(nt, params, t0)makebetat0(nt, params, t0)
nt |
the number of columns in |
params |
model parameters for calculating logf |
t0 |
a single value of the predictor (specify either |
Vector
Calculate the location parameter when there are predictors (multiple time points)
makebetatm(nt, params, t)makebetatm(nt, params, t)
nt |
the number of columns in |
params |
model parameters for calculating logf |
t |
a vector or matrix of predictors |
Vector
Make muhat0
makemuhat0(t0, n0, t, mle_params)makemuhat0(t0, n0, t, mle_params)
t0 |
the value of the predictor vector at which to make the prediction (if n0 not specified) |
n0 |
the position in the predictor vector at which to make the prediction (positive integer less than or equal to the length of |
t |
predictor |
mle_params |
MLE params |
Scalar
Calculates quantiles from simulations by inverting the Hazen CDF
makeq(yy, pp)makeq(yy, pp)
yy |
vector of samples |
pp |
vector of probabilities |
Vector
Determine t0
maket0(t0, n0, t)maket0(t0, n0, t)
t0 |
a single value of the predictor (specify either |
n0 |
an index for the predictor (specify either |
t |
a vector or matrix of predictors |
Scalar
Make ta0
maketresid0(t0, n0, t)maketresid0(t0, n0, t)
t0 |
the value of the predictor vector at which to make the prediction (if n0 not specified) |
n0 |
the position in the predictor vector at which to make the prediction (positive integer less than or equal to the length of |
t |
predictor |
Scalar
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
man( x, t, t1, t2, t3, t0, t01, t02, t03, t10, t20, n0, n01, n02, n03, n10, n20, p, n, y, ics, kloc, kscale, kshape, kdf, kbeta, d1, fd1, d2, fd2, d3, fd3, d4, fd4, d5, fd5, d6, fd6, fdalpha, minxi, maxxi, dlogpi, means, waicscores, logscores, extramodels, pdf, customprior, dmgs, mlcp, predictordata, centering, method, nonnegslopesonly, rnonnegslopesonly, prior, debug, rust, nrust, boot, nboot, pwm, unbiasedv, aderivs )man( x, t, t1, t2, t3, t0, t01, t02, t03, t10, t20, n0, n01, n02, n03, n10, n20, p, n, y, ics, kloc, kscale, kshape, kdf, kbeta, d1, fd1, d2, fd2, d3, fd3, d4, fd4, d5, fd5, d6, fd6, fdalpha, minxi, maxxi, dlogpi, means, waicscores, logscores, extramodels, pdf, customprior, dmgs, mlcp, predictordata, centering, method, nonnegslopesonly, rnonnegslopesonly, prior, debug, rust, nrust, boot, nboot, pwm, unbiasedv, aderivs )
x |
a vector of training data values |
t |
a vector of predictors, such that |
t1 |
a vector of predictors for the mean,
such that |
t2 |
a vector of predictors for the sd,
such that |
t3 |
a vector of predictors for the shape,
such that |
t0 |
a single value of the predictor
(specify either |
t01 |
a single value of the predictor
(specify either |
t02 |
a single value of the predictor
(specify either |
t03 |
a single value of the predictor
(specify either |
t10 |
a single value of the predictor for the mean
(specify either |
t20 |
a single value of the predictor for the sd
(specify either |
n0 |
an index for the predictor
(specify either |
n01 |
an index for the predictor
(specify either |
n02 |
an index for the predictor
(specify either |
n03 |
an index for the predictor
(specify either |
n10 |
an index for the predictor for the mean
(specify either |
n20 |
an index for the predictor for the sd
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
n |
the number of random samples required |
y |
a vector of values at which to calculate the density and distribution functions |
ics |
initial conditions for the maximum likelihood search |
kloc |
the known location parameter |
kscale |
the known scale parameter |
kshape |
the known shape parameter |
kdf |
the known degrees of freedom parameter |
kbeta |
the known beta parameter |
d1 |
if |
fd1 |
if |
d2 |
if |
fd2 |
if |
d3 |
if |
fd3 |
if |
d4 |
if |
fd4 |
if |
d5 |
if |
fd5 |
if |
d6 |
if |
fd6 |
if |
fdalpha |
if |
minxi |
the minimum allowed value of the shape parameter (decrease with caution) |
maxxi |
the maximum allowed value of the shape parameter (increase with caution) |
dlogpi |
gradient of the log prior |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
pdf |
logical that indicates whether to run additional calculations and return density functions evaluated at quantiles specified by the input probabilities (longer runtime) |
customprior |
a custom value for the slope of the log prior at the maxlik estimate |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
method |
character string that indicates whether to use
rust |
nonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
rnonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
prior |
logical indicating which prior to use |
debug |
logical for turning on debug messages |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
boot |
logical that indicates whether bootstrap-based posterior sampling calculations should be run or not (longer run time) |
nboot |
the number of posterior samples used in the bootstrap calculations |
pwm |
logical for whether to include PWM results (longer runtime) |
unbiasedv |
logical for whether to include unbiased variance results in norm |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
q**** optionally returns the following, for EVT models only:
cp_pdf: the density function at quantiles corresponding to input
probabilities p.
We provide this for EVD models,
because direct estimation of the density function using the DMGS density
equation is not possible.
q**** optionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_quantiles: predictive quantiles
calculated from Bayesian integration with a flat prior.
rh_ml_quantiles: predictive quantiles
calculated from Bayesian integration with the calibrating prior, and the maximmum
likelihood estimate for the shape parameter.
jp_quantiles: predictive quantiles
calculated from Bayesian integration with Jeffreys' prior.
r**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_deviates: predictive random deviates calculated using a
Bayesian analysis with a flat prior.
rh_ml_deviates: predictive random deviates calculated using a
Bayesian analysis with the RHP-MLE prior.
jp_deviates: predictive random deviates calculated using a
Bayesian analysis with the JP.
d**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_pdf: predictive density function from a Bayesian analysis
with the flat prior.
rh_ml_pdf: predictive density function from a Bayesian analysis
with the RHP-MLE prior.
jp_pdf: predictive density function from a Bayesian analysis
with the JP.
p**** additionally returns the following, for some EVT models only:
If extramodels=TRUE:
flat_cdf: predictive distribution function from a Bayesian analysis
with the flat prior.
rh_ml_cdf: predictive distribution function from a Bayesian analysis
with the RHP-MLE prior.
jp_cdf: predictive distribution function from a Bayesian analysis
with the JP.
These additional predictive distributions are included for comparison with the calibrating prior model. They generally give less good reliability than the calibrating prior.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
This model is not homogeneous, i.e. it
does not have a transitive transformation group,
and so there is no right Haar prior and no method
for generating exactly reliable predictions.
The cp outputs are generated using a prior that has been shown
in tests to give reasonable reliability.
See Jewson et al. (2025a) for discussion of the prior and test results.
For non-homogeneous models, reliability is generally poor for small sample sizes (<20),
but is still much better than maximum likelihood.
For small sample sizes, it is advisable to check the level of reliability
using the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
Return message for f1f, p1f, mu1f
man1f()man1f()
Matrix
Return message for f2f, p2f, mu2f
man2f()man2f()
3d array
Return message for boot
manboot()manboot()
A list containing a matrix of simulated parameter values
Return message for checkmle
mancheckmle()mancheckmle()
No return value (just a message to the screen).
Return message for dsub
mandsub()mandsub()
A vector of parameter estimates, two pdf vectors, two cdf vectors
Blank function I use for setting up the man page information for the functions
manf( dim, vv, ml_params, nx, nxx, x, xx, t, nt, ta, tb, tc, t1, t2, t3, tt, tt1, tt2, tt3, tt2d, tt3d, t0, t0a, t0b, t0c, t01, t02, t03, t10, t20, t30, n0, n10, n20, p, n, y, ics, tresid, tresid0, muhat0, vhat, v1, v1hat, v1h, d1, fd1, v2, v2hat, v2h, d2, fd2, v3, v3hat, v3h, d3, fd3, v4, v4hat, v4h, d4, fd4, v5, v5hat, v5h, d5, v6, v6hat, v6h, d6, minxi, maxxi, ximin, ximax, fdalpha, kscale, kloc, kshape, kdf, kbeta, alpha, ymn, slope, mu, sigma, sigma1, sigma2, scale, shape, xi, xi1, xi2, lambda, log, mm, nn, rr, lddi, lddi_k2, lddi_k3, lddi_k4, lddd, lddd_k2, lddd_k3, lddd_k4, lambdad, lambdad_cp, lambdad_rhp, lambdad_flat, lambdad_rh_mle, lambdad_rh_flat, lambdad_jp, lambdad_custom, means, waicscores, logscores, extramodels, pdf, predictordata, nonnegslopesonly, rnonnegslopesonly, customprior, prior, params, yy, pp, dlogpi, debug, centering, aderivs )manf( dim, vv, ml_params, nx, nxx, x, xx, t, nt, ta, tb, tc, t1, t2, t3, tt, tt1, tt2, tt3, tt2d, tt3d, t0, t0a, t0b, t0c, t01, t02, t03, t10, t20, t30, n0, n10, n20, p, n, y, ics, tresid, tresid0, muhat0, vhat, v1, v1hat, v1h, d1, fd1, v2, v2hat, v2h, d2, fd2, v3, v3hat, v3h, d3, fd3, v4, v4hat, v4h, d4, fd4, v5, v5hat, v5h, d5, v6, v6hat, v6h, d6, minxi, maxxi, ximin, ximax, fdalpha, kscale, kloc, kshape, kdf, kbeta, alpha, ymn, slope, mu, sigma, sigma1, sigma2, scale, shape, xi, xi1, xi2, lambda, log, mm, nn, rr, lddi, lddi_k2, lddi_k3, lddi_k4, lddd, lddd_k2, lddd_k3, lddd_k4, lambdad, lambdad_cp, lambdad_rhp, lambdad_flat, lambdad_rh_mle, lambdad_rh_flat, lambdad_jp, lambdad_custom, means, waicscores, logscores, extramodels, pdf, predictordata, nonnegslopesonly, rnonnegslopesonly, customprior, prior, params, yy, pp, dlogpi, debug, centering, aderivs )
dim |
number of parameters |
vv |
parameters |
ml_params |
parameters |
nx |
length of training data |
nxx |
length of training data |
x |
a vector of training data values |
xx |
a vector of training data values |
t |
a vector or matrix of predictors |
nt |
the number of columns in |
ta |
a vector of predictors for the mean (first column) |
tb |
a vector of predictors for the mean (second column) |
tc |
a vector of predictors for the mean (third column) |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
tt |
a vector of predictors |
tt1 |
a vector of predictors for the mean |
tt2 |
a vector of predictors for the sd |
tt3 |
a vector of predictors for the shape |
tt2d |
a matrix of predictors (nx by 2) |
tt3d |
a matrix of predictors (nx by 3) |
t0 |
a single value of the predictor (specify either |
t0a |
a single value of the predictor, for the first column of the predictor (specify either |
t0b |
a single value of the predictor, for the second column of the predictor (specify either |
t0c |
a single value of the predictor, for the third column of the predictor (specify either |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
t03 |
a single value of the predictor (specify either |
t10 |
a single value of the predictor for the mean (specify either |
t20 |
a single value of the predictor for the sd (specify either |
t30 |
a single value of the predictor for the shape (specify either |
n0 |
an index for the predictor (specify either |
n10 |
an index for the predictor for the mean (specify either |
n20 |
an index for the predictor for the sd (specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
n |
number of random samples required |
y |
a vector of values at which to calculate the density and distribution functions |
ics |
initial conditions for the maximum likelihood search |
tresid |
predictor residuals |
tresid0 |
predictor residual at the point being predicted |
muhat0 |
muhat at the point being predicted |
vhat |
vector of all parameters |
v1 |
first parameter |
v1hat |
first parameter |
v1h |
first parameter |
d1 |
the delta used in the numerical derivatives with respect to the parameter |
fd1 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v2 |
second parameter |
v2hat |
second parameter |
v2h |
second parameter |
d2 |
the delta used in the numerical derivatives with respect to the parameter |
fd2 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v3 |
third parameter |
v3hat |
third parameter |
v3h |
third parameter |
d3 |
the delta used in the numerical derivatives with respect to the parameter |
fd3 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v4 |
fourth parameter |
v4hat |
fourth parameter |
v4h |
fourth parameter |
d4 |
the delta used in the numerical derivatives with respect to the parameter |
fd4 |
the fractional delta used in the numerical derivatives with respect to the parameter |
v5 |
fifth parameter |
v5hat |
fifth parameter |
v5h |
fifth parameter |
d5 |
the delta used in the numerical derivatives with respect to the parameter |
v6 |
sixth parameter |
v6hat |
sixth parameter |
v6h |
sixth parameter |
d6 |
the delta used in the numerical derivatives with respect to the parameter |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
ximin |
minimum value of shape parameter xi |
ximax |
maximum value of shape parameter xi |
fdalpha |
the fractional delta used in the numerical derivatives with respect to probability, for calculating the pdf as a function of quantiles |
kscale |
the known scale parameter |
kloc |
the known location parameter |
kshape |
the known shape parameter |
kdf |
the known degrees of freedom parameter |
kbeta |
the known beta parameter |
alpha |
a vector of values of alpha (one minus probability) |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
scale |
the scale parameter of the distribution |
shape |
the shape parameter of the distribution |
xi |
the shape parameter of the distribution |
xi1 |
first coefficient for the shape parameter of the distribution |
xi2 |
second coefficient for the shape parameter of the distribution |
lambda |
the lambda parameter of the distribution |
log |
logical for the density evaluation |
mm |
an index for which derivative to calculate |
nn |
an index for which derivative to calculate |
rr |
an index for which derivative to calculate |
lddi |
inverse observed information matrix |
lddi_k2 |
inverse observed information matrix, fixed shape parameter |
lddi_k3 |
inverse observed information matrix, fixed shape parameter |
lddi_k4 |
inverse observed information matrix, fixed shape parameter |
lddd |
third derivative of log-likelihood |
lddd_k2 |
third derivative of log-likelihood, fixed shape parameter |
lddd_k3 |
third derivative of log-likelihood, fixed shape parameter |
lddd_k4 |
third derivative of log-likelihood, fixed shape parameter |
lambdad |
derivative of the log prior |
lambdad_cp |
derivative of the log prior |
lambdad_rhp |
derivative of the log RHP prior |
lambdad_flat |
derivative of the log flat prior |
lambdad_rh_mle |
derivative of the log CRHP-MLE prior |
lambdad_rh_flat |
derivative of the log CRHP-FLAT prior |
lambdad_jp |
derivative of the log JP prior |
lambdad_custom |
custom value of the derivative of the log prior |
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
extramodels |
logical that indicates whether to add three additional prediction models |
pdf |
logical that indicates whether to return density functions evaluated at quantiles specified by input probabilities |
predictordata |
logical that indicates whether to calculate and return predictordata |
nonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
rnonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
customprior |
a custom value for the slope of the log prior at the maxlik estimate |
prior |
logical indicating which prior to use |
params |
model parameters for calculating logf |
yy |
vector of samples |
pp |
vector of probabilities |
dlogpi |
gradient of the log prior |
debug |
debug flag |
centering |
indicates whether the routine should center the data or not |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
No return value
Return message for ldd
manldd()manldd()
Square scalar matrix
Return message for lddd
manlddd()manlddd()
Cubic scalar array
Return message for lnn
manlnn()manlnn()
Scalar value
Return message for lnnn
manlnnn()manlnnn()
Scalar value
Return message for Logf
manlogf()manlogf()
Scalar value.
Return message for loglik
manloglik()manloglik()
Scalar
Return message for logscores
manlogscores()manlogscores()
Two scalars
Return message for means
manmeans()manmeans()
Two scalars
Return message for predictor.
manpredictor()manpredictor()
Two vectors
Return message for vector
manvector()manvector()
Vector
Return message for WAIC
manwaic()manwaic()
Two numeric values.
Move xi away from zero a bit
movexiawayfromzero(xi)movexiawayfromzero(xi)
xi |
xi |
Scalar
fitdistcp PackageApplies model selection using AIC, WAIC1, WAIC2 and leave-one-out logscore
to the input data ,
for 10 one tailed models in the fitdistcp package
(although for the GPD, the logscore is NA for mathematical reasons).
The code is straightforward, and the point is to illustrate what is
possible using the model selection outputs from the fitdistcp routines.
The input data may be automatically shifted so that the minimum value is positive.
For the Pareto, the data may be further shifted so that the minimum value is slightly greater than 1.
ms_flat_1tail( x, index = 1, nyears = 10, plottype = "empirical", plottingposition = "Weibull", quiet = FALSE )ms_flat_1tail( x, index = 1, nyears = 10, plottype = "empirical", plottingposition = "Weibull", quiet = FALSE )
x |
data vector |
index |
which data point to use for plotting positions |
nyears |
number of years for frequency calculations |
plottype |
What to plot? Possible values are 'both', 'empirical', 'cp' |
plottingposition |
Weibull or Hazen |
quiet |
logical for whether to print screen messages |
The 10 models are:
exp,
pareto_k2,
halfnorm,
lnorm,
frechet_k1,
weibull,
gamma,
invgamma,
invgauss and
gpd_k1.
Plots QQ plots to the screen, for each of the models, and returns a data frame containing
MLE parameter values
AIC scores (times -0.5), AIC weights
WAIC1 scores, WAIC1 weights
WAIC2 scores, WAIC2 weights
logscores, logscore weights
maximum likelihood and calibrating prior means
maximum likelihood and calibrating prior standard deviations
Stephen Jewson [email protected]
# because it's too slow for CRAN set.seed(1) nx=50 x=rlnorm(nx) print(ms_flat_1tail(x))# because it's too slow for CRAN set.seed(1) nx=50 x=rlnorm(nx) print(ms_flat_1tail(x))
fitdistcp PackageApplies model selection using AIC, WAIC1, WAIC2 and leave-one-out logscore
to the input data ,
for 7 two tailed models in the fitdistcp packages
The code is straightforward, and the point is to illustrate what is
possible using the model selection outputs from the fitdistcp routines.
ms_flat_2tail(x)ms_flat_2tail(x)
x |
data vector |
The 7 models are:
norm,
gnorm_k3,
gumbel,
logis,
lst_k3,
cauchy,
gev
Plots QQ plots to the screen, for each of the models, and returns a data frame containing
AIC scores (times -0.5), AIC weights
WAIC1 scores, WAIC1 weights
WAIC2 scores, WAIC2 weights
logscores, logscore weights
maximum likelihood and calibrating prior means
maximum likelihood and calibrating prior standard deviations
Stephen Jewson [email protected]
# because it's too slow for CRAN set.seed(1) nx=50 x=rnorm(nx) print(ms_flat_2tail(x))# because it's too slow for CRAN set.seed(1) nx=50 x=rnorm(nx) print(ms_flat_2tail(x))
fitdistcp PackageApplies model selection using AIC, WAIC1, WAIC2 and leave-one-out logscore
to the input data ,
for 5 one tailed models with predictors in the fitdistcp package.
The code is straightforward, and the point is to illustrate what is
possible using the model selection outputs from the fitdistcp routines.
The input data may be automatically shifted so that the minimum value is positive.
For the Pareto, the data is so that the minimum value is slightly greater than 1.
ms_predictors_1tail(x, t)ms_predictors_1tail(x, t)
x |
data vector |
t |
predictor vector |
The 5 models are:
exp_p1,
pareto_p1k2,
lnorm_p1,
frechet_p2k1,
weibull_p2.
Plots QQ plots to the screen, for each of the 5 models, and returns a data frame containing
AIC scores, AIC weights
WAIC1 scores, WAIC1 weights
WAIC2 scores, WAIC2 weights
logscores and logscore weights
Stephen Jewson [email protected]
# because it's too slow for CRAN set.seed(3) nx=100 predictor=c(1:nx)/nx x=rlnorm(nx,meanlog=predictor,sdlog=0.1) print(ms_predictors_1tail(x,predictor))# because it's too slow for CRAN set.seed(3) nx=100 predictor=c(1:nx)/nx x=rlnorm(nx,meanlog=predictor,sdlog=0.1) print(ms_predictors_1tail(x,predictor))
fitdistcp PackageApplies model selection using AIC, WAIC1, WAIC2 and leave-one-out logscore
to the input data ,
for 6 two tail models with predictors in the fitdistcp packages
(although for the GEV, the logscore is NA for mathematical reasons).
The code is straightforward, and the point is to illustrate what is
possible using the model selection outputs from the fitdistcp routines.
GEVD is temperamental in that it doesn't work if the shape parameter is extreme.
ms_predictors_2tail(x, t)ms_predictors_2tail(x, t)
x |
data vector |
t |
predictor vector |
The 11 models are:
norm_p1,
gumbel_p1,
logis_p1,
lst_k3_p1,
cauchy_p1 and
gev_p1.
Plots QQ plots to the screen, for each of the 6 models, and returns a data frame containing
AIC scores, AIC weights
WAIC1 scores, WAIC1 weights
WAIC2 scores, WAIC2 weights
logscores and logscore weights
Stephen Jewson [email protected]
# because it's too slow for CRAN set.seed(2) nx=100 predictor=c(1:nx)/nx x=rnorm(nx,mean=predictor,sd=1) print(ms_predictors_2tail(x,predictor))# because it's too slow for CRAN set.seed(2) nx=100 predictor=c(1:nx)/nx x=rnorm(nx,mean=predictor,sd=1) print(ms_predictors_2tail(x,predictor))
d*** and p*** routines
don't return DMGS pdfs and cdfsMessage to explain why GEV and GPD d*** and p*** routines
don't return DMGS pdfs and cdfs
nopdfcdfmsg(yy, pp)nopdfcdfmsg(yy, pp)
yy |
vector of samples |
pp |
vector of probabilities |
String
Bootstrap
norm_boot(x, n)norm_boot(x, n)
x |
a vector of training data values |
n |
number of random samples required |
A list containing a matrix of simulated parameter values
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qnorm_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, unbiasedv = FALSE, debug = FALSE ) rnorm_cp(n, x, method = "rust", rust = FALSE, mlcp = TRUE, debug = FALSE) dnorm_cp( x, y = x, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) pnorm_cp( x, y = x, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) tnorm_cp(method, n, x, debug = FALSE)qnorm_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, unbiasedv = FALSE, debug = FALSE ) rnorm_cp(n, x, method = "rust", rust = FALSE, mlcp = TRUE, debug = FALSE) dnorm_cp( x, y = x, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) pnorm_cp( x, y = x, rust = FALSE, nrust = 1000, boot = FALSE, nboot = 1000, debug = FALSE ) tnorm_cp(method, n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
unbiasedv |
logical for whether to include unbiased variance results in norm |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
method |
character string that indicates whether to use
rust |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
boot |
logical that indicates whether bootstrap-based posterior sampling calculations should be run or not (longer run time) |
nboot |
the number of posterior samples used in the bootstrap calculations |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The normal distribution has probability density function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d030norm_example_data_v1 p=c(1:9)/10 q=qnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_cp)", main="Normal: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d030norm_example_data_v1 p=c(1:9)/10 q=qnorm_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_cp)", main="Normal: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qnorm_dmgs_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, debug = FALSE ) rnorm_dmgs_cp(n, x, mlcp = TRUE, debug = FALSE) dnorm_dmgs_cp(x, y = x, debug = FALSE) pnorm_dmgs_cp(x, y = x, debug = FALSE)qnorm_dmgs_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, debug = FALSE ) rnorm_dmgs_cp(n, x, mlcp = TRUE, debug = FALSE) dnorm_dmgs_cp(x, y = x, debug = FALSE) pnorm_dmgs_cp(x, y = x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The normal distribution has probability density function
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d030norm_example_data_v1 p=c(1:9)/10 q=qnorm_dmgs_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_dmgs_cp)", main="Normal_DMGS: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)# # example 1 x=fitdistcp::d030norm_example_data_v1 p=c(1:9)/10 q=qnorm_dmgs_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_dmgs_cp)", main="Normal_DMGS: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)
log-likelihood function
norm_dmgs_loglik(vv, x)norm_dmgs_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
norm_dmgs_logscores(logscores, x)norm_dmgs_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
MLE and RHP predictive means
norm_dmgs_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)norm_dmgs_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Waic
norm_dmgs_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)norm_dmgs_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the density
norm_f1fa(x, v1, v2)norm_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density
norm_f2fa(x, v1, v2)norm_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_fd(x, v1, v2)norm_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_fdd(x, v1, v2)norm_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
norm_ldda(x, v1, v2)norm_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
norm_lddda(x, v1, v2)norm_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
norm_logf(params, x)norm_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_logfdd(x, v1, v2)norm_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_logfddd(x, v1, v2)norm_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Log scores for MLE and RHP predictions calculated using leave-one-out
norm_logscores(logscores, x)norm_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
Maximum likelihood estimator
norm_ml_params(x)norm_ml_params(x)
x |
a vector of training data values |
Scalar
Minus the first derivative of the cdf, at alpha
norm_mu1fa(alpha, v1, v2)norm_mu1fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
norm_mu2fa(alpha, v1, v2)norm_mu2fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qnorm_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rnorm_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tnorm_p1_cp(n, x, t, debug = FALSE)qnorm_p1_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, centering = TRUE, debug = FALSE ) rnorm_p1_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pnorm_p1_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tnorm_p1_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The normal distribution with a predictor has probability density function
where
is the random variable,
is the location parameter, modelled as a function
of parameters and predictor ,
and is the scale parameter.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d060norm_p1_example_data_v1_x tt=fitdistcp::d060norm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qnorm_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_p1_cp)", main="Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d060norm_p1_example_data_v1_x tt=fitdistcp::d060norm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qnorm_p1_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_p1_cp)", main="Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
The first derivative of the density
norm_p1_f1fa(x, t, v1, v2, v3) norm_p1_f1fa(x, t, v1, v2, v3)norm_p1_f1fa(x, t, v1, v2, v3) norm_p1_f1fa(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
norm_p1_f1fw(x, t, v1, v2, v3)norm_p1_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density for DMGS
The second derivative of the density
norm_p1_f2fa(x, t, v1, v2, v3) norm_p1_f2fa(x, t, v1, v2, v3)norm_p1_f2fa(x, t, v1, v2, v3) norm_p1_f2fa(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
norm_p1_f2fw(x, t, v1, v2, v3)norm_p1_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_fd(x, t, v1, v2, v3) norm_p1_fd(x, t, v1, v2, v3)norm_p1_fd(x, t, v1, v2, v3) norm_p1_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_fdd(x, t, v1, v2, v3) norm_p1_fdd(x, t, v1, v2, v3)norm_p1_fdd(x, t, v1, v2, v3) norm_p1_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
The second derivative of the normalized log-likelihood
norm_p1_ldda(x, t, v1, v2, v3) norm_p1_ldda(x, t, v1, v2, v3)norm_p1_ldda(x, t, v1, v2, v3) norm_p1_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
The third derivative of the normalized log-likelihood
norm_p1_lddda(x, t, v1, v2, v3) norm_p1_lddda(x, t, v1, v2, v3)norm_p1_lddda(x, t, v1, v2, v3) norm_p1_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
norm_p1_logf(params, x, t)norm_p1_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_logfdd(x, t, v1, v2, v3) norm_p1_logfdd(x, t, v1, v2, v3)norm_p1_logfdd(x, t, v1, v2, v3) norm_p1_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_logfddd(x, t, v1, v2, v3) norm_p1_logfddd(x, t, v1, v2, v3)norm_p1_logfddd(x, t, v1, v2, v3) norm_p1_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Normal-with-p1 observed log-likelihood function
norm_p1_loglik(vv, x, t)norm_p1_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
norm_p1_logscores(logscores, x, t)norm_p1_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
Maximum likelihood estimator
norm_p1_mlparams(x, t)norm_p1_mlparams(x, t)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Vector
Minus the first derivative of the cdf, at alpha
Minus the first derivative of the cdf, at alpha
norm_p1_mu1fa(alpha, t, v1, v2, v3) norm_p1_mu1fa(alpha, t, v1, v2, v3)norm_p1_mu1fa(alpha, t, v1, v2, v3) norm_p1_mu1fa(alpha, t, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
Minus the second derivative of the cdf, at alpha
norm_p1_mu2fa(alpha, t, v1, v2, v3) norm_p1_mu2fa(alpha, t, v1, v2, v3)norm_p1_mu2fa(alpha, t, v1, v2, v3) norm_p1_mu2fa(alpha, t, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The first derivative of the cdf
The first derivative of the cdf
norm_p1_p1fa(x, t, v1, v2, v3) norm_p1_p1fa(x, t, v1, v2, v3)norm_p1_p1fa(x, t, v1, v2, v3) norm_p1_p1fa(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the cdf
The second derivative of the cdf
norm_p1_p2fa(x, t, v1, v2, v3) norm_p1_p2fa(x, t, v1, v2, v3)norm_p1_p2fa(x, t, v1, v2, v3) norm_p1_p2fa(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_pd(x, t, v1, v2, v3) norm_p1_pd(x, t, v1, v2, v3)norm_p1_pd(x, t, v1, v2, v3) norm_p1_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p1_pdd(x, t, v1, v2, v3) norm_p1_pdd(x, t, v1, v2, v3)norm_p1_pdd(x, t, v1, v2, v3) norm_p1_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
norm_p1_predictordata(x, t, t0, params)norm_p1_predictordata(x, t, t0, params)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
norm_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat)norm_p1_waic(waicscores, x, t, v1hat, v2hat, v3hat)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
Two numeric values.
Bootstrap
norm_p12_boot(x, t1, t2, n)norm_p12_boot(x, t1, t2, n)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
n |
number of random samples required |
A list containing a matrix of simulated parameter values
Check MLE
norm_p12_checkmle(ml_params)norm_p12_checkmle(ml_params)
ml_params |
parameters |
No return value (just a message to the screen).
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, extramodels = FALSE, predictordata = TRUE, centering = TRUE, debug = FALSE ) rnorm_p12_cp( n, x, t1, t2, n01 = NA, n02 = NA, t01 = NA, t02 = NA, ics = c(0, 0, 0, 0), rust = FALSE, mlcp = TRUE, debug = FALSE ) dnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0), rust = FALSE, nrust = 1000, boot = FALSE, nboot = 10, centering = TRUE, rnonnegslopesonly = FALSE, debug = FALSE ) pnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0), rust = FALSE, nrust = 1000, boot = FALSE, nboot = 10, centering = TRUE, rnonnegslopesonly = FALSE, debug = FALSE ) tnorm_p12_cp( method, n, x, t1, t2, nonnegslopesonly = FALSE, ics = c(0, 0, 0, 0), debug = FALSE )qnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, p = seq(0.1, 0.9, 0.1), ics = c(0, 0, 0, 0), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, extramodels = FALSE, predictordata = TRUE, centering = TRUE, debug = FALSE ) rnorm_p12_cp( n, x, t1, t2, n01 = NA, n02 = NA, t01 = NA, t02 = NA, ics = c(0, 0, 0, 0), rust = FALSE, mlcp = TRUE, debug = FALSE ) dnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0), rust = FALSE, nrust = 1000, boot = FALSE, nboot = 10, centering = TRUE, rnonnegslopesonly = FALSE, debug = FALSE ) pnorm_p12_cp( x, t1, t2, t01 = NA, t02 = NA, n01 = NA, n02 = NA, y = x, ics = c(0, 0, 0, 0), rust = FALSE, nrust = 1000, boot = FALSE, nboot = 10, centering = TRUE, rnonnegslopesonly = FALSE, debug = FALSE ) tnorm_p12_cp( method, n, x, t1, t2, nonnegslopesonly = FALSE, ics = c(0, 0, 0, 0), debug = FALSE )
x |
a vector of training data values |
t1 |
a vector of predictors for the mean,
such that |
t2 |
a vector of predictors for the sd,
such that |
t01 |
a single value of the predictor
(specify either |
t02 |
a single value of the predictor
(specify either |
n01 |
an index for the predictor
(specify either |
n02 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
ics |
initial conditions for the maximum likelihood search |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
extramodels |
logical that indicates whether to run additional calculations and add three additional prediction models (longer runtime) |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
boot |
logical that indicates whether bootstrap-based posterior sampling calculations should be run or not (longer run time) |
nboot |
the number of posterior samples used in the bootstrap calculations |
rnonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
method |
character string that indicates whether to use
rust |
nonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The normal distribution with predictors on both parameters has probability density function
where
is the random variable,
is the location parameter, modelled as a function
of parameters and predictor ,
where is typically the ensemble mean,
and is the scale parameter,
modelled as a function of parameters and predictor ,
where is typically the ensemble spread.
The calibrating prior is given by the right Haar prior, which is
as given in the Jewson et al. (2025) reference given below.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which introduces this model.
Jewson S., Olivetti L., Messori G., Northop P., Sweeting T. (2025): An Objective Bayesian Method for Including Parameter Uncertainty in Ensemble Model Output Statistics; QJRMS (Quarterly Journal of the Royal Meteorological Society).
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d060norm_p1_example_data_v1_x tt=fitdistcp::d060norm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qnorm_p12_cp(x,t1=tt,t2=tt,n01=n0,n02=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_p12_cp)", main="Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d060norm_p1_example_data_v1_x tt=fitdistcp::d060norm_p1_example_data_v1_t p=c(1:9)/10 n0=10 q=qnorm_p12_cp(x,t1=tt,t2=tt,n01=n0,n02=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qnorm_p12_cp)", main="Normal w/ p1: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
Norm_p12 example data
norm_p12_exampledata(iseed)norm_p12_exampledata(iseed)
iseed |
The random seed |
A list containing data to run an example
The first derivative of the density for DMGS
norm_p12_f1fa(x, t01, t02, v1, v2, v3, v4)norm_p12_f1fa(x, t01, t02, v1, v2, v3, v4)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
The first derivative of the density for WAIC
norm_p12_f1fw(x, t1, t2, v1, v2, v3, v4)norm_p12_f1fw(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
The second derivative of the density for DMGS
norm_p12_f2fa(x, t01, t02, v1, v2, v3, v4)norm_p12_f2fa(x, t01, t02, v1, v2, v3, v4)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the density for WAIC
norm_p12_f2fw(x, t1, t2, v1, v2, v3, v4)norm_p12_f2fw(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_fd(x, t1, t2, v1, v2, v3, v4)norm_p12_fd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_fdd(x, t1, t2, v1, v2, v3, v4)norm_p12_fdd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The second derivative of the normalized log-likelihood
norm_p12_ldda(x, t1, t2, v1, v2, v3, v4)norm_p12_ldda(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The third derivative of the normalized log-likelihood
norm_p12_lddda(x, t1, t2, v1, v2, v3, v4)norm_p12_lddda(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
Logf for RUST
norm_p12_logf(params, x, t1, t2, nonnegslopesonly = FALSE)norm_p12_logf(params, x, t1, t2, nonnegslopesonly = FALSE)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
nonnegslopesonly |
logical that indicates whether to disallow non-negative slopes |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_logfdd(x, t1, t2, v1, v2, v3, v4)norm_p12_logfdd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_logfddd(x, t1, t2, v1, v2, v3, v4)norm_p12_logfddd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
3d array
observed log-likelihood function
norm_p12_loglik(vv, x, t1, t2)norm_p12_loglik(vv, x, t1, t2)
vv |
parameters |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
Scalar
Log scores for 5 predictions calculated using leave-one-out
norm_p12_logscores(logscores, x, t1, t2, ics)norm_p12_logscores(logscores, x, t1, t2, ics)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ics |
initial conditions for the maximum likelihood search |
Two scalars
Minus the first derivative of the cdf, at alpha
norm_p12_mu1fa(alpha, t01, t02, v1, v2, v3, v4)norm_p12_mu1fa(alpha, t01, t02, v1, v2, v3, v4)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Minus the second derivative of the cdf, at alpha
norm_p12_mu2fa(alpha, t01, t02, v1, v2, v3, v4)norm_p12_mu2fa(alpha, t01, t02, v1, v2, v3, v4)
alpha |
a vector of values of alpha (one minus probability) |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
The first derivative of the cdf
norm_p12_p1fa(x, t01, t02, v1, v2, v3, v4)norm_p12_p1fa(x, t01, t02, v1, v2, v3, v4)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
The second derivative of the cdf
norm_p12_p2fa(x, t01, t02, v1, v2, v3, v4)norm_p12_p2fa(x, t01, t02, v1, v2, v3, v4)
x |
a vector of training data values |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_pd(x, t1, t2, v1, v2, v3, v4)norm_p12_pd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_p12_pdd(x, t1, t2, v1, v2, v3, v4)norm_p12_pdd(x, t1, t2, v1, v2, v3, v4)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
v4 |
fourth parameter |
Matrix
Predicted Parameter and Generalized Residuals
norm_p12_predictordata(predictordata, x, t1, t2, t01, t02, params)norm_p12_predictordata(predictordata, x, t1, t2, t01, t02, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Set initial conditions
norm_p12_setics(x, t1, t2, ics)norm_p12_setics(x, t1, t2, ics)
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ics |
initial conditions for the maximum likelihood search |
Vector
Waic
norm_p12_waic( waicscores, x, t1, t2, v1hat, v2hat, v3hat, v4hat, lddi, lddd, lambdad )norm_p12_waic( waicscores, x, t1, t2, v1hat, v2hat, v3hat, v4hat, lddi, lddd, lambdad )
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
v4hat |
fourth parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The first derivative of the cdf
norm_p1fa(x, v1, v2)norm_p1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the cdf
norm_p2fa(x, v1, v2)norm_p2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_pd(x, v1, v2)norm_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
norm_pdd(x, v1, v2)norm_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Method of moments estimator
norm_unbiasedv_params(x)norm_unbiasedv_params(x)
x |
a vector of training data values |
Vector
Waic
norm_waic(waicscores, x, v1hat, v2hat)norm_waic(waicscores, x, v1hat, v2hat)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qpareto_k2_cp( x, p = seq(0.1, 0.9, 0.1), kscale = 1, means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rpareto_k2_cp(n, x, kscale = 1, rust = FALSE, mlcp = TRUE, debug = FALSE) dpareto_k2_cp(x, y = x, kscale = 1, rust = FALSE, nrust = 1000, debug = FALSE) ppareto_k2_cp(x, y = x, kscale = 1, rust = FALSE, nrust = 1000, debug = FALSE) tpareto_k2_cp(n, x, kscale = 1, debug = FALSE)qpareto_k2_cp( x, p = seq(0.1, 0.9, 0.1), kscale = 1, means = FALSE, waicscores = FALSE, logscores = FALSE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rpareto_k2_cp(n, x, kscale = 1, rust = FALSE, mlcp = TRUE, debug = FALSE) dpareto_k2_cp(x, y = x, kscale = 1, rust = FALSE, nrust = 1000, debug = FALSE) ppareto_k2_cp(x, y = x, kscale = 1, rust = FALSE, nrust = 1000, debug = FALSE) tpareto_k2_cp(n, x, kscale = 1, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
kscale |
the known scale parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Pareto distribution has various forms. The form we are using has exceedance distribution function
where
is the random variable
and
are the shape and scale parameters.
We consider the scale parameter to be known
(hence the k2 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025). Some others authors may refer to the shape and scale parameters as the scale and location parameters, respectively.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d011pareto_k2_example_data_v1 p=c(1:9)/10 q=qpareto_k2_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles) xmax=max(q$ml_quantiles,q$cp_quantiles) plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qpareto_k2_cp)", main="Pareto: quantile estimates") points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d011pareto_k2_example_data_v1 p=c(1:9)/10 q=qpareto_k2_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles) xmax=max(q$ml_quantiles,q$cp_quantiles) plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qpareto_k2_cp)", main="Pareto: quantile estimates") points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
The first derivative of the density
pareto_k2_f1fa(x, v1, kscale) pareto_k2_f1fa(x, v1, kscale)pareto_k2_f1fa(x, v1, kscale) pareto_k2_f1fa(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
Vector
Vector
The second derivative of the density
The second derivative of the density
pareto_k2_f2fa(x, v1, kscale) pareto_k2_f2fa(x, v1, kscale)pareto_k2_f2fa(x, v1, kscale) pareto_k2_f2fa(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
Matrix
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_fd(x, v1, v2) pareto_k2_fd(x, v1, v2)pareto_k2_fd(x, v1, v2) pareto_k2_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_fdd(x, v1, v2) pareto_k2_fdd(x, v1, v2)pareto_k2_fdd(x, v1, v2) pareto_k2_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Matrix
The second derivative of the normalized log-likelihood
The second derivative of the normalized log-likelihood
pareto_k2_ldda(x, v1, kscale) pareto_k2_ldda(x, v1, kscale)pareto_k2_ldda(x, v1, kscale) pareto_k2_ldda(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
Matrix
Matrix
The third derivative of the normalized log-likelihood
The third derivative of the normalized log-likelihood
pareto_k2_lddda(x, v1, kscale) pareto_k2_lddda(x, v1, kscale)pareto_k2_lddda(x, v1, kscale) pareto_k2_lddda(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
3d array
3d array
Logf for RUST
pareto_k2_logf(params, x, kscale)pareto_k2_logf(params, x, kscale)
params |
model parameters for calculating logf |
x |
a vector of training data values |
kscale |
the known scale parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_logfdd(x, v1, v2) pareto_k2_logfdd(x, v1, v2)pareto_k2_logfdd(x, v1, v2) pareto_k2_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_logfddd(x, v1, v2) pareto_k2_logfddd(x, v1, v2)pareto_k2_logfddd(x, v1, v2) pareto_k2_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
3d array
Log scores for MLE and RHP predictions calculated using leave-one-out
pareto_k2_logscores(logscores, x, kscale)pareto_k2_logscores(logscores, x, kscale)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
kscale |
the known scale parameter |
Two scalars
Maximum likelihood estimator
pareto_k2_ml_params(x, kscale)pareto_k2_ml_params(x, kscale)
x |
a vector of training data values |
kscale |
the known scale parameter |
Scalar
Minus the first derivative of the cdf, at alpha
Minus the first derivative of the cdf, at alpha
pareto_k2_mu1fa(alpha, v1, kscale) pareto_k2_mu1fa(alpha, v1, kscale)pareto_k2_mu1fa(alpha, v1, kscale) pareto_k2_mu1fa(alpha, v1, kscale)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
kscale |
the known scale parameter |
Vector
Vector
Minus the second derivative of the cdf, at alpha
Minus the second derivative of the cdf, at alpha
pareto_k2_mu2fa(alpha, v1, kscale) pareto_k2_mu2fa(alpha, v1, kscale)pareto_k2_mu2fa(alpha, v1, kscale) pareto_k2_mu2fa(alpha, v1, kscale)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
kscale |
the known scale parameter |
Matrix
Matrix
The first derivative of the cdf
The first derivative of the cdf
pareto_k2_p1fa(x, v1, kscale) pareto_k2_p1fa(x, v1, kscale)pareto_k2_p1fa(x, v1, kscale) pareto_k2_p1fa(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
Vector
Vector
The second derivative of the cdf
The second derivative of the cdf
pareto_k2_p2fa(x, v1, kscale) pareto_k2_p2fa(x, v1, kscale)pareto_k2_p2fa(x, v1, kscale) pareto_k2_p2fa(x, v1, kscale)
x |
a vector of training data values |
v1 |
first parameter |
kscale |
the known scale parameter |
Matrix
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_pd(x, v1, v2) pareto_k2_pd(x, v1, v2)pareto_k2_pd(x, v1, v2) pareto_k2_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_k2_pdd(x, v1, v2) pareto_k2_pdd(x, v1, v2)pareto_k2_pdd(x, v1, v2) pareto_k2_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Matrix
Waic
pareto_k2_waic(waicscores, x, v1hat, kscale)pareto_k2_waic(waicscores, x, v1hat, kscale)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
kscale |
the known scale parameter |
Two numeric values.
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qpareto_p1k2_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), kscale = 1, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rpareto_p1k2_cp( n, x, t, t0 = NA, n0 = NA, kscale = 1, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dpareto_p1k2_cp( x, t, t0 = NA, n0 = NA, y = x, kscale = 1, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) ppareto_p1k2_cp( x, t, t0 = NA, n0 = NA, y = x, kscale = 1, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tpareto_p1k2_cp(n, x, t, kscale = 1, debug = FALSE)qpareto_p1k2_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), kscale = 1, means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rpareto_p1k2_cp( n, x, t, t0 = NA, n0 = NA, kscale = 1, rust = FALSE, mlcp = TRUE, centering = TRUE, debug = FALSE ) dpareto_p1k2_cp( x, t, t0 = NA, n0 = NA, y = x, kscale = 1, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) ppareto_p1k2_cp( x, t, t0 = NA, n0 = NA, y = x, kscale = 1, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tpareto_p1k2_cp(n, x, t, kscale = 1, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
kscale |
the known scale parameter |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Pareto distribution with a predictor has various forms. The form we are using has exceedance distribution function
where
is the random variable,
is the shape parameter, modelled
as a function of parameters , and
is the scale parameter.
We consider the scale parameter to be known
(hence the k2 in the name).
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025). Note that others authors have referred to the shape and scale parameters as the scale and location parameters, respectively.
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2025): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with 1-3 linear predictors on the location (gev_p1n),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with predictor on the mean (norm_p1),
Normal with predictors on the mean and sd (norm_p12),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d056pareto_p1k2_example_data_v1_x tt=fitdistcp::d056pareto_p1k2_example_data_v1_t p=c(1:9)/10 n0=10 q=qpareto_p1k2_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qpareto_p1k2_cp)", main="Pareto w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d056pareto_p1k2_example_data_v1_x tt=fitdistcp::d056pareto_p1k2_example_data_v1_t p=c(1:9)/10 n0=10 q=qpareto_p1k2_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qpareto_p1k2_cp)", main="Pareto w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
pareto_p1k2_f1fa(x, t0, v1, v2, kscale)pareto_p1k2_f1fa(x, t0, v1, v2, kscale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Vector
The first derivative of the density for WAIC
pareto_p1k2_f1fw(x, t, v1, v2, kscale)pareto_p1k2_f1fw(x, t, v1, v2, kscale)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Vector
The second derivative of the density for DMGS
pareto_p1k2_f2fa(x, t0, v1, v2, kscale)pareto_p1k2_f2fa(x, t0, v1, v2, kscale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Matrix
The second derivative of the density for WAIC
pareto_p1k2_f2fw(x, t, v1, v2, kscale)pareto_p1k2_f2fw(x, t, v1, v2, kscale)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_fd(x, t, v1, v2, v3)pareto_p1k2_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_fdd(x, t, v1, v2, v3)pareto_p1k2_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
pareto_p1k2_ldda(x, t, v1, v2, kscale)pareto_p1k2_ldda(x, t, v1, v2, kscale)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Matrix
The third derivative of the normalized log-likelihood
pareto_p1k2_lddda(x, t, v1, v2, kscale)pareto_p1k2_lddda(x, t, v1, v2, kscale)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
3d array
Logf for RUST
pareto_p1k2_logf(params, x, t, kscale)pareto_p1k2_logf(params, x, t, kscale)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kscale |
the known scale parameter |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_logfdd(x, t, v1, v2, v3)pareto_p1k2_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_logfddd(x, t, v1, v2, v3)pareto_p1k2_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
observed log-likelihood function
pareto_p1k2_loglik(vv, x, t, kscale)pareto_p1k2_loglik(vv, x, t, kscale)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kscale |
the known scale parameter |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
pareto_p1k2_logscores(logscores, x, t, kscale, debug)pareto_p1k2_logscores(logscores, x, t, kscale, debug)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
kscale |
the known scale parameter |
debug |
debug flag |
Two scalars
pareto_k1 distribution: RHP mean
pareto_p1k2_means( means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kscale )pareto_p1k2_means( means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2, kscale )
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
kscale |
the known scale parameter |
Two scalars
Minus the first derivative of the cdf, at alpha
pareto_p1k2_mu1fa(alpha, t0, v1, v2, kscale)pareto_p1k2_mu1fa(alpha, t0, v1, v2, kscale)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Vector
Minus the second derivative of the cdf, at alpha
pareto_p1k2_mu2fa(alpha, t0, v1, v2, kscale)pareto_p1k2_mu2fa(alpha, t0, v1, v2, kscale)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Matrix
The first derivative of the cdf
pareto_p1k2_p1fa(x, t0, v1, v2, kscale)pareto_p1k2_p1fa(x, t0, v1, v2, kscale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Vector
The second derivative of the cdf
pareto_p1k2_p2fa(x, t0, v1, v2, kscale)pareto_p1k2_p2fa(x, t0, v1, v2, kscale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
kscale |
the known scale parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_pd(x, t, v1, v2, v3)pareto_p1k2_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
pareto_p1k2_pdd(x, t, v1, v2, v3)pareto_p1k2_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
pareto_p1k2_predictordata(predictordata, x, t, t0, params, kscale)pareto_p1k2_predictordata(predictordata, x, t, t0, params, kscale)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
kscale |
the known scale parameter |
Two vectors
Waic
pareto_p1k2_waic(waicscores, x, t, v1hat, v2hat, kscale, lddi, lddd, lambdad)pareto_p1k2_waic(waicscores, x, t, v1hat, v2hat, kscale, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
kscale |
the known scale parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
Cauchy-with-p1 distribution function
pcauchy_p1(x, t0, ymn, slope, scale)pcauchy_p1(x, t0, ymn, slope, scale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
Vector
Exponential-with-p1 distribution function
pexp_p1(x, t0, ymn, slope)pexp_p1(x, t0, ymn, slope)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
Vector
Frechet_k1-with-p2 distribution function
pfrechet_p2k1(x, t0, ymn, slope, lambda, kloc)pfrechet_p2k1(x, t0, ymn, slope, lambda, kloc)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
lambda |
the lambda parameter of the distribution |
kloc |
the known location parameter |
Vector
GEVD-with-p1: Distribution function
pgev_p1(y, t0, ymn, slope, sigma, xi)pgev_p1(y, t0, ymn, slope, sigma, xi)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
Vector
GEVD-with-p1: Distribution function
pgev_p12(y, t1, t2, ymn, slope, sigma1, sigma2, xi)pgev_p12(y, t1, t2, ymn, slope, sigma1, sigma2, xi)
y |
a vector of values at which to calculate the density and distribution functions |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
Vector
GEVD-with-p1: Distribution function
pgev_p123(y, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2)pgev_p123(y, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2)
y |
a vector of values at which to calculate the density and distribution functions |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi1 |
first coefficient for the shape parameter of the distribution |
xi2 |
second coefficient for the shape parameter of the distribution |
Vector
GEV-with-known-shape-with-p1 distribution function
pgev_p1k3(x, t0, ymn, slope, sigma, kshape)pgev_p1k3(x, t0, ymn, slope, sigma, kshape)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
kshape |
the known shape parameter |
Vector
GEVD-with-p1: Distribution function
pgev_p1n(y, t0, params)pgev_p1n(y, t0, params)
y |
a vector of values at which to calculate the density and distribution functions |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Vector
Gumbel-with-p1 distribution function
pgumbel_p1(x, t0, ymn, slope, sigma)pgumbel_p1(x, t0, ymn, slope, sigma)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Normal-with-p1 distribution function
plnorm_p1(x, t0, ymn, slope, sigma)plnorm_p1(x, t0, ymn, slope, sigma)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Logistic-with-p1 distribution function
plogis_p1(x, t0, ymn, slope, scale)plogis_p1(x, t0, ymn, slope, scale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
Vector
LST-with-p1 distribution function
plst_p1k3(x, t0, ymn, slope, sigma, kdf)plst_p1k3(x, t0, ymn, slope, sigma, kdf)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
kdf |
the known degrees of freedom parameter |
Vector
Normal-with-p1 distribution function
pnorm_p1(x, t0, ymn, slope, sigma)pnorm_p1(x, t0, ymn, slope, sigma)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Linear regression formula, densities
pnorm_p1_formula(y, tresid, tresid0, nx, muhat0, v3hat)pnorm_p1_formula(y, tresid, tresid0, nx, muhat0, v3hat)
y |
a vector of values at which to calculate the density and distribution functions |
tresid |
predictor residuals |
tresid0 |
predictor residual at the point being predicted |
nx |
length of training data |
muhat0 |
muhat at the point being predicted |
v3hat |
third parameter |
Vector
Normal-with-p12: Distribution function
pnorm_p12(y, t01, t02, ymn, slope, sigma1, sigma2)pnorm_p12(y, t01, t02, ymn, slope, sigma1, sigma2)
y |
a vector of values at which to calculate the density and distribution functions |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
Vector
pareto_k1-with-p2 distribution function
ppareto_p1k2(x, t0, ymn, slope, kscale)ppareto_p1k2(x, t0, ymn, slope, kscale)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
kscale |
the known scale parameter |
Vector
Predictive CDFs
punif_formula(x, y)punif_formula(x, y)
x |
a vector of training data values |
y |
a vector of values at which to calculate the density and distribution functions |
Two vectors
Weibull-with-p1 distribution function
pweibull_p2(x, t0, shape, ymn, slope)pweibull_p2(x, t0, shape, ymn, slope)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
shape |
the shape parameter of the distribution |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
Vector
Cauchy-with-p1 quantile function
qcauchy_p1(p, t0, ymn, slope, scale)qcauchy_p1(p, t0, ymn, slope, scale)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
Vector
-with-p1 quantile function
qexp_p1(p, t0, ymn, slope)qexp_p1(p, t0, ymn, slope)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
Vector
Frechet_k1-with-p2 quantile function
qfrechet_p2k1(p, t0, ymn, slope, lambda, kloc)qfrechet_p2k1(p, t0, ymn, slope, lambda, kloc)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
lambda |
the lambda parameter of the distribution |
kloc |
the known location parameter |
Vector
Temporary dummy for one of the cp models
qgamma_k1_ppm(x, p)qgamma_k1_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
Temporary dummy for one of the ppm models
qgamma_ppm(x, p)qgamma_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
Temporary dummy for one of the ppm models
qgev_k12_ppm(x, p)qgev_k12_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
Temporary dummy for one of the ppm models
qgev_mpd_ppm(x, p)qgev_mpd_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
GEVD-with-p1: Quantile function
qgev_p1(p, t0, ymn, slope, sigma, xi)qgev_p1(p, t0, ymn, slope, sigma, xi)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
Vector
Temporary dummy for one of the ppm models
qgev_p1_ppm(x, t, n0, p)qgev_p1_ppm(x, t, n0, p)
x |
a vector of training data values |
t |
a vector of predictors, such that |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
GEVD-with-p1: Quantile function
qgev_p12(p, t1, t2, ymn, slope, sigma1, sigma2, xi)qgev_p12(p, t1, t2, ymn, slope, sigma1, sigma2, xi)
p |
a vector of probabilities at which to generate predictive quantiles |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
Vector
GEVD-with-p1: Quantile function
qgev_p123(p, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2)qgev_p123(p, t1, t2, t3, ymn, slope, sigma1, sigma2, xi1, xi2)
p |
a vector of probabilities at which to generate predictive quantiles |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
xi1 |
first coefficient for the shape parameter of the distribution |
xi2 |
second coefficient for the shape parameter of the distribution |
Vector
GEV-with-known-shape-with-p1 quantile function
qgev_p1k3(p, t0, ymn, slope, sigma, kshape)qgev_p1k3(p, t0, ymn, slope, sigma, kshape)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
kshape |
the known shape parameter |
Vector
GEVD-with-p1: Quantile function
qgev_p1n(p, t0, params)qgev_p1n(p, t0, params)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Vector
Temporary dummy for one of the ppm models
qgev_ppm(x, p)qgev_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
Temporary dummy for one of the ppm models
qgpd_k1_ppm(x, p)qgpd_k1_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
Gumbel-with-p1 quantile function
qgumbel_p1(p, t0, ymn, slope, sigma)qgumbel_p1(p, t0, ymn, slope, sigma)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Normal-with-p1 quantile function
qlnorm_p1(p, t0, ymn, slope, sigma)qlnorm_p1(p, t0, ymn, slope, sigma)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Logistic-with-p1 quantile function
qlogis_p1(p, t0, ymn, slope, scale)qlogis_p1(p, t0, ymn, slope, scale)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
scale |
the scale parameter of the distribution |
Vector
LST-with-p1 quantile function
qlst_p1k3(p, t0, ymn, slope, sigma, kdf)qlst_p1k3(p, t0, ymn, slope, sigma, kdf)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
kdf |
the known degrees of freedom parameter |
Vector
Normal-with-p1 quantile function
qnorm_p1(p, t0, ymn, slope, sigma)qnorm_p1(p, t0, ymn, slope, sigma)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma |
the sigma parameter of the distribution |
Vector
Linear regression formula, quantiles
qnorm_p1_formula(alpha, tresid, tresid0, nx, muhat0, v3hat)qnorm_p1_formula(alpha, tresid, tresid0, nx, muhat0, v3hat)
alpha |
a vector of values of alpha (one minus probability) |
tresid |
predictor residuals |
tresid0 |
predictor residual at the point being predicted |
nx |
length of training data |
muhat0 |
muhat at the point being predicted |
v3hat |
third parameter |
Vector
Normal-with-p12: Quantile function
qnorm_p12(p, t01, t02, ymn, slope, sigma1, sigma2)qnorm_p12(p, t01, t02, ymn, slope, sigma1, sigma2)
p |
a vector of probabilities at which to generate predictive quantiles |
t01 |
a single value of the predictor (specify either |
t02 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
sigma1 |
first coefficient for the sigma parameter of the distribution |
sigma2 |
second coefficient for the sigma parameter of the distribution |
Vector
Temporary dummy for one of the ppm models
qntt_ppm(x, p)qntt_ppm(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
pareto_k1-with-p2 quantile function
qpareto_p1k2(p, t0, ymn, slope, kscale)qpareto_p1k2(p, t0, ymn, slope, kscale)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
kscale |
the known scale parameter |
Vector
Predictive Quantiles
qunif_formula(x, p)qunif_formula(x, p)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
Two vectors
Weibull-with-p1 quantile function
qweibull_p2(p, t0, shape, ymn, slope)qweibull_p2(p, t0, shape, ymn, slope)
p |
a vector of probabilities at which to generate predictive quantiles |
t0 |
a single value of the predictor (specify either |
shape |
the shape parameter of the distribution |
ymn |
the location parameter of the function of the predictor |
slope |
the slope of the function of the predictor |
Vector
fitdistcp PackageUses simulations to evaluate the reliability of
the predictive quantiles produced by the q****_cp routines in the fitdistcp package.
reltest( model = "exp", ntrials = 1000, nrepeats = 3, nx = 20, params = NA, alpha = seq(0.005, 0.995, 0.005), plotflag = TRUE, verbose = TRUE, dmgs = TRUE, debug = FALSE, aderivs = TRUE, unbiasedv = FALSE, pwm = FALSE, minxi = -10, maxxi = 10 )reltest( model = "exp", ntrials = 1000, nrepeats = 3, nx = 20, params = NA, alpha = seq(0.005, 0.995, 0.005), plotflag = TRUE, verbose = TRUE, dmgs = TRUE, debug = FALSE, aderivs = TRUE, unbiasedv = FALSE, pwm = FALSE, minxi = -10, maxxi = 10 )
model |
which distribution to test. Possibles values are
" |
ntrials |
the number of trials to run. 5000 typically gives good results. |
nrepeats |
the number of entire repeats of the test to run, to check for convergence. 3 is a good choice. |
nx |
the length of the training data to use. |
params |
values for the parameters for the specified distribution |
alpha |
the exceedance probability values at which to test |
plotflag |
logical to turn the plotting on and off |
verbose |
logical to turn loop counting on and off |
dmgs |
logical to turn DMGS calculations on and off (to optimize speed for maxlik only calculations) |
debug |
logical for turning debug messages on and off |
aderivs |
logical for whether to use analytic derivatives (instead of numerical) |
unbiasedv |
logical for whether to use the unbiased variance instead of maxlik (for the normal) |
pwm |
logical for whether to use PWM instead of maxlik (for the GEV) |
minxi |
minimum value for EVT shape parameter |
maxxi |
maximum value for EVT shape parameter |
The maximum likelihood quantiles (plotted in blue) do not give good reliability. They typically underestimate the tails (see panel (f)).
For
"exp",
"pareto_k1",
"unif",
"norm",
"lnorm",
"norm_p1" and
"lnorm_p1",
the calibrating prior quantiles are calculated using the right Haar prior
and an exact solution for the Bayesian prediction integral.
They will converge towards exact reliability with a large enough number of trials,
for any sample size.
For
"halfnorm",
"norm_dmgs",
"lnorm_dmgs",
"gnorm_k3",
"logis",
"lst_k3",
"cauchy",
"gumbel",
"frechet_k1",
"weibull",
"gev_k3",
"exp_p1",
"pareto_p1k3",
"gumbel_p1",
"logis_p1" and
"lst_p1k4"
"cauchy_p1",
"gumbel_p1",
"frechet_p2k1",
"weibull_p2",
"gev_p1k4",
"norm_p12",
"lst_p12k5"
the calibrating prior quantiles are calculated using the right Haar prior,
with the DMGS asymptotic solution for the Bayesian prediction integral.
They will converge towards good reliability with a large enough number of trials,
with the only deviation from exact reliability being due to the neglect of
higher order terms in the asymptotic expansion.
They will converge towards exact reliability with a large enough number of trials
and a large enough sample size.
For
"gamma",
"invgamma",
"invgauss",
"gev",
"gpd_k1" and
"gev_p1",
"gev_p12",
"gev_p123",
the calibrating prior quantiles are calculated using the "fitdistcp"
recommended calibrating priors,
with the DMGS asymptotic solution for the Bayesian prediction integral.
The chosen priors give reasonably good reliability with a
large enough number of trials,
and for large sample sizes, but may give poor reliability for small
sample sizes (e.g., n<20).
A plot showing 9 different reliability checks, and a list containing various outputs, including the probabilities shown in the plot.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2024): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with linear predictor on the mean (norm_p1),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
set.seed(1) # example 1 # -runs the default settings, which test reliability for the exponential distribution reltest()set.seed(1) # example 1 # -runs the default settings, which test reliability for the exponential distribution reltest()
Calculate EP from one model
reltest_makeep(model, pred1, tt0, tt10, tt20, tt30, params)reltest_makeep(model, pred1, tt0, tt10, tt20, tt30, params)
model |
which distribution to test. Possibles values are
" |
pred1 |
quantile predictions |
tt0 |
value of the predictor |
tt10 |
value of predictor 1 |
tt20 |
value of predictor 2 |
tt30 |
value of predictor 3 |
params |
the model parameters |
Vector
Calculate MaxEP from one model
reltest_makemaxep(model, ml_max, tt0, tt10, tt20, tt30, params)reltest_makemaxep(model, ml_max, tt0, tt10, tt20, tt30, params)
model |
which distribution to test. Possibles values are
" |
ml_max |
predicted max value |
tt0 |
value of the predictor |
tt10 |
value of predictor 1 |
tt20 |
value of predictor 2 |
tt30 |
value of predictor 3 |
params |
the model parameters |
Vector
Set default params for the chosen model
reltest_params(model = "exp", params)reltest_params(model = "exp", params)
model |
which distribution to test. Possibles values are
" |
params |
values for the parameters for the specified distribution |
Vector
Make prediction from one model
reltest_predict( model, xx, tt, tt1, tt2, tt3, n0, n10, n20, n30, pp, params, dmgs = TRUE, debug = FALSE, aderivs = TRUE, unbiasedv = FALSE, pwm = FALSE, minxi = -10, maxxi = 10 )reltest_predict( model, xx, tt, tt1, tt2, tt3, n0, n10, n20, n30, pp, params, dmgs = TRUE, debug = FALSE, aderivs = TRUE, unbiasedv = FALSE, pwm = FALSE, minxi = -10, maxxi = 10 )
model |
which distribution to test. Possibles values are
" |
xx |
training data |
tt |
predictor vector |
tt1 |
predictor vector 1 |
tt2 |
predictor vector 2 |
tt3 |
predictor vector 3 |
n0 |
index for predictor vector |
n10 |
index for predictor vector 1 |
n20 |
index for predictor vector 2 |
n30 |
index for predictor vector 2 |
pp |
probabilites at which to make quantile predictions |
params |
model parameters |
dmgs |
flag for whether to run dmgs calculations or not |
debug |
flag for turning debug messages on |
aderivs |
a logical for whether to use analytic derivatives (instead of numerical) |
unbiasedv |
a logical for whether to use the unbiased variance instead of maxlik (for the normal) |
pwm |
a logical for whether to use PWM instead of maxlik (for the GEV) |
minxi |
minimum value for EVT shape parameter |
maxxi |
maximum value for EVT shape parameter |
Two vectors
Random training data from one model
reltest_simulate( model = "exp", nx = 20, tt, tt1, tt2, tt3, params, minxi = -10, maxxi = -10 )reltest_simulate( model = "exp", nx = 20, tt, tt1, tt2, tt3, params, minxi = -10, maxxi = -10 )
model |
which distribution to test. Possibles values are
" |
nx |
the length of the training data to use. |
tt |
predictor vector |
tt1 |
predictor vector 1 |
tt2 |
predictor vector 2 |
tt3 |
predictor vector 2 |
params |
values for the parameters for the specified distribution |
minxi |
minimum value for EVT shape parameter |
maxxi |
maximum value for EVT shape parameter |
Vector
fitdistcp PackageThis routine is mainly for reproducing certain results in Jewson et al. (2025), and not of general interest.
It uses simulations to evaluate the reliability of
the predictive quantiles produced by the
qgev_cp, ggpd_cp and qgev_p1_cp
routines in the fitdistcp package.
For each model, results for 5 models are calculated.
This is to illustrate that the calibrating prior predictions dominate
the ml, flat, crhp_ml and jp predictions,
in terms of reliability.
reltest2( model = "gev", ntrials = 100, nrepeats = 3, nx = 50, params = c(0, 1, 0), alpha = seq(0.005, 0.995, 0.005), plotflag = TRUE, verbose = TRUE )reltest2( model = "gev", ntrials = 100, nrepeats = 3, nx = 50, params = c(0, 1, 0), alpha = seq(0.005, 0.995, 0.005), plotflag = TRUE, verbose = TRUE )
model |
which distribution to test. Possibles values are
" |
ntrials |
the number of trials to run. 5000 typically gives good results. |
nrepeats |
the number of entire repeats of the test to run, to check for convergence. 3 is a good choice. |
nx |
the length of the training data. |
params |
values for the parameters for the specified distribution |
alpha |
the alpha values at which to test |
plotflag |
logical to turn the plotting on and off |
verbose |
logical to turn loop counting on and off |
The maximum likelihood quantiles (plotted in blue) do not give good reliability. They typically underestimate the tails (see panel (f)).
The cp predictive quantiles generally give reasonably good reliability, especially for sample sizes of ~100.
The other predictions generally give poor reliability.
A plot showing 9 different reliability checks, and a list containing various outputs, including the probabilities shown in the plot.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2024): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with linear predictor on the mean (norm_p1),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
set.seed(1) # example 1 # -runs the default settings, which test reliability for the GEV distribution reltest2(nrepeats=1)set.seed(1) # example 1 # -runs the default settings, which test reliability for the GEV distribution reltest2(nrepeats=1)
Cases
reltest2_cases(model = "gev", nx = 50, params)reltest2_cases(model = "gev", nx = 50, params)
model |
which distribution to test. Possibles values are "gev", "gpd_k1", "gev_pred1". |
nx |
length of training data |
params |
model parameters |
Two integers
Cases
reltest2_makeep(model, pred1, tt0, params)reltest2_makeep(model, pred1, tt0, params)
model |
which distribution to test. Possibles values are "gev", "gpd_k1", "gev_pred1". |
pred1 |
quantile predictions |
tt0 |
value of predictor vector |
params |
model parameters |
Vector
Plots 9 diagnostics related to predictive probability matching.
reltest2_plot( model, ntrials, nrepeats, nx, params, nmethods, alpha, freqexceeded, case )reltest2_plot( model, ntrials, nrepeats, nx, params, nmethods, alpha, freqexceeded, case )
model |
which distribution to test. Possibles values are "gev", "gpd", "gev_p1". |
ntrials |
the number of trials o run. 5000 typically gives good results. |
nrepeats |
the number of entire repeats of the test to run, to check for convergence |
nx |
the length of the training data. |
params |
values for the parameters for the specified distribution |
nmethods |
the number of methods being tested |
alpha |
the values of alpha being tested |
freqexceeded |
the exceedance counts |
case |
there are 3 cases (must be set to case=1 except for my testing) |
Plots the results of reliability testing
Make prediction from one model
reltest2_predict(model = "gev", xx, tt, n0, pp, params, case, nmethods)reltest2_predict(model = "gev", xx, tt, n0, pp, params, case, nmethods)
model |
which distribution to test. Possibles values are
" |
xx |
training data |
tt |
predictor vector |
n0 |
index for predictor vector |
pp |
probabilities to predict |
params |
model parameters |
case |
the case number: different models have different lists of methods |
nmethods |
the number of methods: different models have different numbers of methods |
Vector
Random training data from one model
reltest2_simulate(model = "gev", nx = 50, tt, params)reltest2_simulate(model = "gev", nx = 50, tt, params)
model |
which distribution to test. Possibles values are "gev", "gpd_k1", "gev_pred1". |
nx |
the length of the training data. |
tt |
the predictor |
params |
values for the parameters for the specified distribution |
Vector
rgev but with maxlik xi guaranteed within bounds
rgev_minmax(nx, mu = 0, sigma = 1, xi = 0, minxi = -1, maxxi = 1)rgev_minmax(nx, mu = 0, sigma = 1, xi = 0, minxi = -1, maxxi = 1)
nx |
length of training data |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
Vector
rgev for gev_p1 but with maxlik xi within bounds
rgev_p1_minmax( nx, mu = 0, sigma = 1, xi = 0, tt, minxi = -0.45, maxxi = 0.45, centering = TRUE )rgev_p1_minmax( nx, mu = 0, sigma = 1, xi = 0, tt, minxi = -0.45, maxxi = 0.45, centering = TRUE )
nx |
length of training data |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
tt |
a vector of predictors |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
centering |
indicates whether the routine should center the data or not |
Vector
rgev for gev_p12 but with maxlik xi within bounds
rgev_p12_minmax( nx, mu = 0, sigma = 1, xi = 0, t1, t2, minxi = -0.45, maxxi = 0.45, centering = TRUE )rgev_p12_minmax( nx, mu = 0, sigma = 1, xi = 0, t1, t2, minxi = -0.45, maxxi = 0.45, centering = TRUE )
nx |
length of training data |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
centering |
indicates whether the routine should center the data or not |
Vector
rgev for gev_p123 but with maxlik xi within bounds
rgev_p123_minmax( nx, mu = 0, sigma = 1, xi = 0, t1, t2, t3, minxi = -0.45, maxxi = 0.45, centering = TRUE )rgev_p123_minmax( nx, mu = 0, sigma = 1, xi = 0, t1, t2, t3, minxi = -0.45, maxxi = 0.45, centering = TRUE )
nx |
length of training data |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
t1 |
a vector of predictors for the mean |
t2 |
a vector of predictors for the sd |
t3 |
a vector of predictors for the shape |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
centering |
indicates whether the routine should center the data or not |
Vector
rgev for gev_p1n but with maxlik xi within bounds
rgev_p1n_minmax( nx, mu = 0, sigma = 1, xi = 0, tt, minxi = -0.45, maxxi = 0.45, centering = TRUE )rgev_p1n_minmax( nx, mu = 0, sigma = 1, xi = 0, tt, minxi = -0.45, maxxi = 0.45, centering = TRUE )
nx |
length of training data |
mu |
the location parameter of the distribution |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
tt |
a vector of predictors |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
centering |
indicates whether the routine should center the data or not |
Vector
rgpd for gpd_k1 but with maxlik xi within bounds
rgpd_k1_minmax(nx, kloc, sigma, xi, minxi = -0.45, maxxi = 0.45)rgpd_k1_minmax(nx, kloc, sigma, xi, minxi = -0.45, maxxi = 0.45)
nx |
length of training data |
kloc |
the known location parameter |
sigma |
the sigma parameter of the distribution |
xi |
the shape parameter of the distribution |
minxi |
minimum value of shape parameter xi |
maxxi |
maximum value of shape parameter xi |
Vector
Generates a comment about the method
rhp_dmgs_cpmethod()rhp_dmgs_cpmethod()
String
Generates a comment about the method
rust_pumethod()rust_pumethod()
String
Plots 9 diagnostics related to predictive probability matching.
testppm_plot( model, ntrials, nrepeats, nx, params, nmethods, alpha, freqexceeded )testppm_plot( model, ntrials, nrepeats, nx, params, nmethods, alpha, freqexceeded )
model |
which distribution to test. Possibles values are |
ntrials |
the number of trials to run. 5000 typically gives good results. |
nrepeats |
the number of entire repeats of the test to run, to check for convergence |
nx |
the length of the training data. |
params |
values for the parameters for the specified distribution |
nmethods |
the number of methods being tested |
alpha |
the values of alpha being tested |
freqexceeded |
the exceedance counts |
Plots the results of reliability testing
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qunif_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, debug = FALSE, aderivs = TRUE ) runif_cp(n, x, mlcp = TRUE, debug = FALSE, aderivs = TRUE) dunif_cp(x, y = x, debug = FALSE, aderivs = TRUE) punif_cp(x, y = x, debug = FALSE, aderivs = TRUE)qunif_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, debug = FALSE, aderivs = TRUE ) runif_cp(n, x, mlcp = TRUE, debug = FALSE, aderivs = TRUE) dunif_cp(x, y = x, debug = FALSE, aderivs = TRUE) punif_cp(x, y = x, debug = FALSE, aderivs = TRUE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
debug |
logical for turning on debug messages |
aderivs |
(for code testing only) logical for whether to use analytic derivatives (instead of numerical). By default almost all models now use analytical derivatives. |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The uniform distribution has probability density function
and zero otherwise,
where
is the random variable
and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation is integrated analytically.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2024): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with linear predictor on the mean (norm_p1),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d025unif_example_data_v1 cat("length(x)=",length(x),"\n") p=c(1:9)/10 q=qunif_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qunif_cp)", main="unif: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)# # example 1 x=fitdistcp::d025unif_example_data_v1 cat("length(x)=",length(x),"\n") p=c(1:9)/10 q=qunif_cp(x,p) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qunif_cp)", main="unif: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2)
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qweibull_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rweibull_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dweibull_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pweibull_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tweibull_cp(n, x, debug = FALSE)qweibull_cp( x, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, debug = FALSE ) rweibull_cp(n, x, rust = FALSE, mlcp = TRUE, debug = FALSE) dweibull_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) pweibull_cp(x, y = x, rust = FALSE, nrust = 1000, debug = FALSE) tweibull_cp(n, x, debug = FALSE)
x |
a vector of training data values |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Weibull distribution has exceedance distribution function
where
is the random variable and
are the parameters.
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2024): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with linear predictor on the mean (norm_p1),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d052weibull_example_data_v1 p=c(1:9)/10 q=qweibull_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qweibull_cp)", main="Weibull: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d052weibull_example_data_v1 p=c(1:9)/10 q=qweibull_cp(x,p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qweibull_cp)", main="Weibull: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density
weibull_f1fa(x, v1, v2)weibull_f1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The second derivative of the density
weibull_f2fa(x, v1, v2)weibull_f2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_fd(x, v1, v2)weibull_fd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_fdd(x, v1, v2)weibull_fdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The second derivative of the normalized log-likelihood
weibull_ldda(x, v1, v2)weibull_ldda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The third derivative of the normalized log-likelihood
weibull_lddda(x, v1, v2)weibull_lddda(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
Logf for RUST
weibull_logf(params, x)weibull_logf(params, x)
params |
model parameters for calculating logf |
x |
a vector of training data values |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_logfdd(x, v1, v2)weibull_logfdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_logfddd(x, v1, v2)weibull_logfddd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
3d array
log-likelihood function
weibull_loglik(vv, x)weibull_loglik(vv, x)
vv |
parameters |
x |
a vector of training data values |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
weibull_logscores(logscores, x)weibull_logscores(logscores, x)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
Two scalars
MLE and RHP predictive means
weibull_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)weibull_means(means, ml_params, lddi, lddd, lambdad_rhp, nx, dim = 2)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
weibull_mu1fa(alpha, v1, v2)weibull_mu1fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Vector
Minus the second derivative of the cdf, at alpha
weibull_mu2fa(alpha, v1, v2)weibull_mu2fa(alpha, v1, v2)
alpha |
a vector of values of alpha (one minus probability) |
v1 |
first parameter |
v2 |
second parameter |
Matrix
The first derivative of the cdf
weibull_p1fa(x, v1, v2)weibull_p1fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
The fitdistcp package contains functions that generate predictive distributions
for various statistical models,
with and without parameter uncertainty.
Parameter uncertainty is included by using Bayesian prediction with a type of objective
prior known as a calibrating prior.
Calibrating priors are chosen to give predictions that give good reliability
(i.e., are well calibrated), for any
underlying true parameter values.
There are five functions for each model,
each of which uses training data x.
For model **** the five functions are as follows:
q****_cp returns predictive quantiles at the specified probabilities p,
and various other diagnostics.
r****_cp returns n random deviates from the predictive distribution.
d****_cp returns the predictive density function at the specified values y
p****_cp returns the predictive distribution function at the specified values y
t****_cp returns n random deviates from the posterior distribution
of the model parameters.
The q, r, d, p routines return two sets of results,
one based on maximum likelihood, and the other based on a calibrating prior.
The prior used depends on the model, and
is given under Details below.
Where possible, the Bayesian prediction integral is solved analytically. Otherwise, DMGS asymptotic expansions are used. Optionally, a third set of results is returned that integrates the prediction integral by sampling the parameter posterior distribution using the RUST rejection sampling algorithm.
qweibull_p2_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rweibull_p2_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dweibull_p2_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pweibull_p2_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tweibull_p2_cp(n, x, t, debug = FALSE)qweibull_p2_cp( x, t, t0 = NA, n0 = NA, p = seq(0.1, 0.9, 0.1), means = FALSE, waicscores = FALSE, logscores = FALSE, dmgs = TRUE, rust = FALSE, nrust = 1e+05, predictordata = TRUE, centering = TRUE, debug = FALSE ) rweibull_p2_cp( n, x, t, t0 = NA, n0 = NA, rust = FALSE, mlcp = TRUE, debug = FALSE ) dweibull_p2_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) pweibull_p2_cp( x, t, t0 = NA, n0 = NA, y = x, rust = FALSE, nrust = 1000, centering = TRUE, debug = FALSE ) tweibull_p2_cp(n, x, t, debug = FALSE)
x |
a vector of training data values |
t |
a vector of predictors, such that |
t0 |
a single value of the predictor
(specify either |
n0 |
an index for the predictor
(specify either |
p |
a vector of probabilities at which to generate predictive quantiles |
means |
logical that indicates whether to run additional calculations and return analytical estimates for the distribution means (longer runtime) |
waicscores |
logical that indicates whether to run additional calculations and return estimates for the WAIC1 and WAIC2 scores (longer runtime) |
logscores |
logical that indicates whether to run additional calculations and return leave-one-out estimates of the log-score (much longer runtime, non-EVT models only) |
dmgs |
logical that indicates whether DMGS calculations should be run or not (longer run time) |
rust |
logical that indicates whether RUST-based posterior sampling calculations should be run or not (longer run time) |
nrust |
the number of posterior samples used in the RUST calculations |
predictordata |
logical that indicates whether predictordata should be calculated |
centering |
logical that indicates whether the predictor should be centered |
debug |
logical for turning on debug messages |
n |
the number of random samples required |
mlcp |
logical that indicates whether maxlik and parameter uncertainty calculations should be performed (turn off to speed up RUST) |
y |
a vector of values at which to calculate the density and distribution functions |
q**** returns a list containing at least the following:
ml_params: maximum likelihood estimates for the parameters.
ml_value: the value of the log-likelihood at the maximum.
standard_errors: estimates of the standard errors on the parameters,
from the inverse observed information matrix.
ml_quantiles: quantiles calculated using maximum likelihood.
cp_quantiles: predictive quantiles calculated using a calibrating prior.
maic: the AIC score for the maximum likelihood model, times -1/2.
cp_method: a comment about the method used to generate the cp prediction.
For models with predictors, q**** additionally returns:
predictedparameter: the estimated value for parameter,
as a function of the predictor.
adjustedx: the detrended values of x
r**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_deviates: random deviates calculated using maximum likelihood.
cp_deviates: predictive random deviates calculated using a calibrating prior.
cp_method: a comment about the method used to generate the cp prediction.
d**** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_pdf: density function from maximum likelihood.
cp_pdf: predictive density function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
p*** returns a list containing the following:
ml_params: maximum likelihood estimates for the parameters.
ml_cdf: distribution function from maximum likelihood.
cp_cdf: predictive distribution function calculated using a calibrating prior
(not available in EVT routines, for mathematical reasons, unless using RUST).
cp_method: a comment about the method used to generate the cp prediction.
t*** returns a list containing the following:
theta_samples: random samples from the parameter posterior.
The Weibull distribution with predictor on the scale parameter has exceedance distribution function
where
is the random variable,
is the shape parameter and
is the scale parameter, modelled as a function of
parameters and predictor .
The calibrating prior is given by the right Haar prior, which is
as given in Jewson et al. (2025).
q**** optionally returns the following:
If rust=TRUE:
ru_quantiles: predictive quantiles calculated using a calibrating prior,
using posterior sampling with the RUST algorithm, based on inverting
an empirical CDF based on nrust samples.
If waicscores=TRUE:
waic1: the WAIC1 score for the calibrating prior model.
waic2: the WAIC2 score for the calibrating prior model.
If logscores=TRUE:
ml_oos_logscore: the leave-one-out logscore for the
maximum likelihood prediction
(not available in EVT routines, for mathematical reasons)
cp_oos_logscore: the leave-one-out logscore for the
parameter uncertainty model
available in EVT routines, for mathematical reasons)
If means=TRUE:
ml_mean: analytic estimate of the mean of the MLE predictive distribution,
where possible
cp_mean: analytic estimate of the mean of the calibrating prior
predictive distribution, where mathematically possible.
Can be compared with the mean estimated from random deviates.
r**** optionally returns the following:
If rust=TRUE:
ru_deviates: nrust predictive random deviatives calculated using a
calibrating prior,
using posterior sampling with RUST.
d**** optionally returns the following:
If rust=TRUE:
ru_pdf: predictive density calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust density functions.
p**** optionally returns the following:
If rust=TRUE:
ru_cdf: predictive probability calculated using a calibrating prior,
using posterior sampling with RUST,
averaging over nrust distribution functions.
Selecting these additional outputs increases runtime. They are optional so that runtime for the basic outputs is minimised. This facilitates repeated experiments that evaluate reliability over many thousands of repeats.
This model is a homogeneous model, and the cp results are based on the
right Haar prior.
For homogeneous models
(models with sharply transitive transformation groups),
a Bayesian prediction based on the right Haar prior
gives exact reliability,
as shown by Severini et al. (2002),
even when the true parameters are unknown.
This means that probabilities in the prediction will correspond to frequencies
of future outcomes in repeated trials (if the model is correct).
Maximum likelihood prediction does not give reliable predictions, even when the model is correct, because it does not account for parameter uncertainty. In particular, maximum likelihood predictions typically underestimate the tail in repeated trials.
The reliability of the maximum likelihood and the calibrating prior
predictive quantiles produced by
the q****_cp routines in fitdistcp can be quantified
using repeated simulations with the routine reltest.
For this model, the Bayesian prediction equation cannot be solved analytically,
and is approximated using the DMGS asymptotic
expansions given by Datta et al. (2000).
This approximation seems to work well for medium and large sample sizes,
but may not work well for small sample sizes (e.g., <20 data points).
For small sample sizes, it may be preferable to use posterior
sampling by setting rust=TRUE and looking at the ru outputs.
The performance for any sample size, in terms of reliability,
can be tested using reltest.
The Bayesian prediction equation can also be integrated using
ratio-of-uniforms-sampling-with-transformation (RUST), using the option
rust=TRUE.
fitdistcp then calls Paul Northrop's rust package (Northrop, 2023).
The RUST calculations are slower than the DMGS calculations.
For small sample sizes (e.g., n<20), and the very extreme tail, the DMGS approximation is somewhat poor (although always better than maximum likelihood) and it may be better to use RUST. For medium sample sizes (30+), DMGS is reasonably accurate, except for the very far tail.
It is advisable to check the RUST results for convergence versus the number of RUST samples.
It may be interesting to compare the DMGS and RUST results.
Stephen Jewson [email protected]
If you use this package, we would be grateful if you would cite the following reference, which gives the various calibrating priors, and tests them for reliability:
Jewson S., Sweeting T. and Jewson L. (2024): Reducing Reliability Bias in Assessments of Extreme Weather Risk using Calibrating Priors; ASCMO Advances in Statistical Climatology, Meteorology and Oceanography), https://ascmo.copernicus.org/articles/11/1/2025/.
An introduction to fitdistcp, with more examples,
is given on this webpage.
The fitdistcp package currently includes the following models (in alphabetical order):
Cauchy (cauchy),
Cauchy with linear predictor on the mean (cauchy_p1),
Exponential (exp),
Exponential with log-linear predictor on the scale (exp_p1),
Frechet with known location parameter (frechet_k1),
Frechet with log-linear predictor on the scale and known location parameter
(frechet_p2k1),
Gamma (gamma),
Generalized normal (gnorm),
GEV (gev),
GEV with linear predictor on the location (gev_p1),
GEV with linear predictor on the location and log-linear prediction on the scale
(gev_p12),
GEV with linear predictor on the location, log-linear prediction on the scale,
and linear predictor on the shape (gev_p123),
GEV with linear predictor on the location and known shape (gev_p1k3),
GEV with known shape (gev_k3),
GPD with known location (gpd_k1),
Gumbel (gumbel),
Gumbel with linear predictor on the mean(gumbel_p1),
Half-normal (halfnorm),
Inverse gamma (invgamma),
Inverse Gaussian (invgauss),
t distribution with unknown location and scale and known DoF (lst_k3),
t distribution with unknown location and scale, linear predictor on the location,
and known DoF (lst_p1k3),
Logistic (logis),
Logistic with linear predictor on the location (logis_p1),
Log-normal (lnorm),
Log-normal with linear predictor on the location (lnorm_p1),
Normal (norm),
Normal with linear predictor on the mean (norm_p1),
Pareto with known scale (pareto_k2),
Pareto with log-linear predictor on the shape and known scale (pareto_p1k2),
Uniform (unif),
Weibull (weibull),
Weibull with linear predictor on the scale (weibull_p2),
The level of predictive probability matching achieved
by the maximum likelihood and calibrating prior quantiles, for any model,
sample size and true parameter values, can be demonstrated using the
routine reltest.
Model selection among models can be demonstrated using the routines
ms_flat_1tail,
ms_flat_2tail,
ms_predictors_1tail,
and ms_predictors_2tail,
# # example 1 x=fitdistcp::d073weibull_p2_example_data_v1_x tt=fitdistcp::d073weibull_p2_example_data_v1_t p=c(1:9)/10 n0=10 q=qweibull_p2_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qweibull_p2_cp)", main="Weibull w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")# # example 1 x=fitdistcp::d073weibull_p2_example_data_v1_x tt=fitdistcp::d073weibull_p2_example_data_v1_t p=c(1:9)/10 n0=10 q=qweibull_p2_cp(x,tt,n0=n0,p=p,rust=TRUE,nrust=1000) xmin=min(q$ml_quantiles,q$cp_quantiles); xmax=max(q$ml_quantiles,q$cp_quantiles); plot(q$ml_quantiles,p,xlab="quantile estimates",xlim=c(xmin,xmax), sub="(from qweibull_p2_cp)", main="Weibull w/ p2: quantile estimates"); points(q$cp_quantiles,p,col="red",lwd=2) points(q$ru_quantiles,p,col="blue")
The first derivative of the density for DMGS
weibull_p2_f1fa(x, t0, v1, v2, v3)weibull_p2_f1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The first derivative of the density for WAIC
weibull_p2_f1fw(x, t, v1, v2, v3)weibull_p2_f1fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the density for DMGS
weibull_p2_f2fa(x, t0, v1, v2, v3)weibull_p2_f2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the density for WAIC
weibull_p2_f2fw(x, t, v1, v2, v3)weibull_p2_f2fw(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_fd(x, t, v1, v2, v3)weibull_p2_fd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_fdd(x, t, v1, v2, v3)weibull_p2_fdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The second derivative of the normalized log-likelihood
weibull_p2_ldda(x, t, v1, v2, v3)weibull_p2_ldda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The third derivative of the normalized log-likelihood
weibull_p2_lddda(x, t, v1, v2, v3)weibull_p2_lddda(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
Logf for RUST
weibull_p2_logf(params, x, t)weibull_p2_logf(params, x, t)
params |
model parameters for calculating logf |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar value.
Second derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_logfdd(x, t, v1, v2, v3)weibull_p2_logfdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Third derivative of the log density Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_logfddd(x, t, v1, v2, v3)weibull_p2_logfddd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
3d array
observed log-likelihood function
weibull_p2_loglik(vv, x, t)weibull_p2_loglik(vv, x, t)
vv |
parameters |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Scalar
Log scores for MLE and RHP predictions calculated using leave-one-out
weibull_p2_logscores(logscores, x, t)weibull_p2_logscores(logscores, x, t)
logscores |
logical that indicates whether to return leave-one-out estimates estimates of the log-score (much longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
Two scalars
weibull distribution: RHP mean
weibull_p2_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim)weibull_p2_means(means, t0, ml_params, lddi, lddd, lambdad_rhp, nx, dim)
means |
logical that indicates whether to return analytical estimates for the distribution means (longer runtime) |
t0 |
a single value of the predictor (specify either |
ml_params |
parameters |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad_rhp |
derivative of the log RHP prior |
nx |
length of training data |
dim |
number of parameters |
Two scalars
Minus the first derivative of the cdf, at alpha
weibull_p2_mu1fa(alpha, t0, v1, v2, v3)weibull_p2_mu1fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Minus the second derivative of the cdf, at alpha
weibull_p2_mu2fa(alpha, t0, v1, v2, v3)weibull_p2_mu2fa(alpha, t0, v1, v2, v3)
alpha |
a vector of values of alpha (one minus probability) |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
The first derivative of the cdf
weibull_p2_p1fa(x, t0, v1, v2, v3)weibull_p2_p1fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
The second derivative of the cdf
weibull_p2_p2fa(x, t0, v1, v2, v3)weibull_p2_p2fa(x, t0, v1, v2, v3)
x |
a vector of training data values |
t0 |
a single value of the predictor (specify either |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_pd(x, t, v1, v2, v3)weibull_p2_pd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_p2_pdd(x, t, v1, v2, v3)weibull_p2_pdd(x, t, v1, v2, v3)
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1 |
first parameter |
v2 |
second parameter |
v3 |
third parameter |
Matrix
Predicted Parameter and Generalized Residuals
weibull_p2_predictordata(predictordata, x, t, t0, params)weibull_p2_predictordata(predictordata, x, t, t0, params)
predictordata |
logical that indicates whether to calculate and return predictordata |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
t0 |
a single value of the predictor (specify either |
params |
model parameters for calculating logf |
Two vectors
Waic
weibull_p2_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)weibull_p2_waic(waicscores, x, t, v1hat, v2hat, v3hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
t |
a vector or matrix of predictors |
v1hat |
first parameter |
v2hat |
second parameter |
v3hat |
third parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.
The second derivative of the cdf
weibull_p2fa(x, v1, v2)weibull_p2fa(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
First derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_pd(x, v1, v2)weibull_pd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Vector
Second derivative of the cdf Created by Stephen Jewson using Deriv() by Andrew Clausen and Serguei Sokol
weibull_pdd(x, v1, v2)weibull_pdd(x, v1, v2)
x |
a vector of training data values |
v1 |
first parameter |
v2 |
second parameter |
Matrix
Waic for RUST
weibull_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)weibull_waic(waicscores, x, v1hat, v2hat, lddi, lddd, lambdad)
waicscores |
logical that indicates whether to return estimates for the waic1 and waic2 scores (longer runtime) |
x |
a vector of training data values |
v1hat |
first parameter |
v2hat |
second parameter |
lddi |
inverse observed information matrix |
lddd |
third derivative of log-likelihood |
lambdad |
derivative of the log prior |
Two numeric values.