supdist: The Support of a Distribution based on the Parameters

In wasquith/lmomco: L-Moments, Censored L-Moments, Trimmed L-Moments, L-Comoments, and Many Distributions

The Support of a Distribution based on the Parameters

Description

This function takes a parameter object, such as that returned by lmom2par, and computes the support (the lower and upper bounds, \{L, U\}) of the distribution given by the parameters. The computation is based on two calls to par2qua for the parameters in argument para (\Theta) and nonexceedance probabilities F \in \{0, 1\}:

lower <- par2qua(0, para)
upper <- par2qua(1, para)

The quality of \{L, U\} is dependent of the handling of F \in \{0,1\} internal to each quantile function. Across the suite of distributions supported by lmomco, potential applications, and parameter combinations, it difficult to ensure numerical results for the respective \{L, U\} are either very small, are large, or are (or should be) infinite. The distinction is sometimes difficult depending how fast the tail(s) of a distribution is (are) either approaching a limit as F respectively approaches 0^{+} or 1^{-}.

The intent of this function is to provide a unified portal for \{L, U\} estimation. Most of the time R (and lmomco) do the right thing anyway and the further overhead within the parameter estimation suite of functions in lmomco is not implemented.

The support returned by this function might be useful in extended application development involving probability density functions pdfCCC (f(x,\Theta), see dlmomco) and cumulative distribution functions cdfCCC (F(x,\Theta), see plmomco) functions—both of these functions use as their primary argument a value x that exists along the real number line.

Usage

supdist(para, trapNaN=FALSE, delexp=0.5, paracheck=TRUE, ...)

Arguments

para	The parameters of the distribution.
trapNaN	A logical influencing how NaN are handled (see Note).
delexp	The magnitude of the decrementing of the exponent to search down and up from. A very long-tailed but highly peaked distribution might require this to be smaller than default.
paracheck	A logical controlling whether the parameters are checked for validity.
...	Additional arguments to pass.

Value

An R list is returned.

type	Three character (minimum) distribution type (for example, type="gev");
support	The support (or range) of the fitted distribution;
nonexceeds	The nonexceedance probabilities at the computed support.
fexpons	A vector indicating how the respective lower and upper boundaries were arrived at (see Note); and
finite	A logical on each entry of the support with a preemptive call by the is.finite function in R.
source	An attribute identifying the computational source of the distribution support: “supdist”.

Note

Concerning fexpons, for the returned vectors of length 2, index 1 is for \{L\} and index 2 is for \{U\}. If an entry in fexpons is NA, then F = 0 or F = 1 for the respective bound was possible. And even if trapNaN is TRUE, no further refinement on the bounds was attempted.

On the otherhand, if trapNaN is TRUE and if the bounds \{L\} and (or) \{U\} is not NA, then an attempt was made to move away from F \in \{0,1\} in incremental integer exponent from 0^{+} or 1^{-} until a NaN was not encountered. The integer exponents are i \in [-(\phi), -(\phi - 1), \ldots, -4], where \phi = .Machine$sizeof.longdouble and -4 is a hardwired limit (1 part in 10,000). In the last example in the Examples section, the \{U\} for F=1 quantile is NaN but 1 - 10^i for which i = -16, which also is the .Machine$sizeof.longdouble on the author's development platform.

At first release, it seems there was justification in triggering this to TRUE if a quantile function returns a NA when asked for F = 0 or F = 1—some quantile functions partially trapped NaNs themselves. So even if trapNaN == FALSE, it is triggered to TRUE if a NA is discovered as described. Users are encouraged to discuss adaptions or changes to the implementation of supdist with the author.

Thus it should be considered a feature of supdist that should a quantile function already trap errors at either F = 0 or F = 1 and return NA, then trapNaN is internally set to TRUE regardless of being originally FALSE and the preliminary limit is reset to NaN. The Rice distribution quarice is one such example that internally already traps an F = 1 by returning x(F{=}1) = NA.

Author(s)

W.H. Asquith

See Also

lmom2par

Examples

lmr <- lmoms(c(33, 37, 41, 54, 78, 91, 100, 120, 124))
supdist(lmom2par(lmr, type="gov" )) # Lower = 27.41782, Upper = 133.01470
supdist(lmom2par(lmr, type="gev" )) # Lower = -Inf,     Upper = 264.4127

supdist(lmom2par(lmr, type="wak" ))               # Lower = 16.43722, Upper = NaN
supdist(lmom2par(lmr, type="wak" ), trapNaN=TRUE) # Lower = 16.43722, Upper = 152.75126
#$support  16.43722  152.75126
#$fexpons        NA  -16
#$finite       TRUE  TRUE
## Not run: 
para <- vec2par(c(0.69, 0.625), type="kmu") # very flat tails and narrow peak!
supdist(para, delexp=1   )$support # [1] 0        NaN
supdist(para, delexp=0.5 )$support # [1] 0.000000 3.030334
supdist(para, delexp=0.05)$support # [1] 0.000000 3.155655
# This distribution appears to have a limit at PI and the delexp=0.5

## End(Not run)

wasquith/lmomco documentation built on April 10, 2024, 4:20 a.m.