Package 'lmomPi'

Validate L-moment Constraints

Description

This function checks whether a given set of L-moments satisfies theoretical and practical constraints commonly used in statistical modeling. These constraints ensure the validity of L-moment ratios and help detect potential issues in the data or its transformation (e.g., log-transformed data with non-positive values).

Usage

are.lmoms.valid(
  lmom,
  clean = TRUE,
  return_numeric = FALSE,
  condt3t4 = TRUE,
  condtt3 = FALSE
)

Arguments

lmom	vector of L-moments
clean	logical if it is TRUE (default) clean lmom's names
return_numeric	logical if it is TRUE L-moments corrected are returned instead of a boolean value.
condt3t4	logical if TRUE condition on t_3 and t_4 is applied.
condtt3	logical if TRUE condition on t and t_3 is applied (only for a distribution that takes positive values, p.24 ref).

Value

logical value indicating if all of these conditions are verified:

• $\lambda_2 > 0$ (L-scale must be positive)

• $|\tau_3| < 1$ (L-skewness must lie within $(-1, 1)$)

• $|\tau_i| < 1$ (i-th L-moment ratio must lie within $(-1, 1)$ for i>3)

• $\lambda_1$ and $\lambda_2$ must be finite

• $\frac{5\tau_3^2 - 1 }{4} \leq \tau_4 < 1$ is verified for theoretical consistency

• $2\tau-1 \leq \tau_3 < 1$ is verified for theoretical consistency (only for a distribution that takes positive values, p.24 ref)

References

Hosking, J.R.M. and Wallis, J.R. (1997). Regional Frequency Analysis: An Approach Based on L-Moments. Cambridge University Press. doi:10.1017/CBO9780511529443

Examples

library(lmomPi)

data(airquality)
lmom <- samlmu(airquality$Ozone, 6)
are.lmoms.valid(lmom = lmom)

are.lmoms.valid(lmom = lmom,return_numeric=TRUE)

lmoml <- samlmu(airquality$Ozone, 6,ratio=FALSE)

are.lmoms.valid(lmom = lmoml)
are.lmoms.valid(lmom = lmoml,condtt3=TRUE)
are.lmoms.valid(lmom = lmoml,return_numeric=TRUE)
are.lmoms.valid(lmom = lmoml,return_numeric=TRUE,condtt3=TRUE)

---

Generic function for cdf...: probability distribution fitting with L-Moments.

Description

These functions compute value(s) of cumulated probability or SPI-like (normal standardize) index from a sample or time series of x.

Usage

cdf(
  para,
  x,
  probability_distribution_attrname = "probability_distrib",
  indices = NULL,
  return.as.spi = FALSE,
  spi.scale = NA,
  distrib = NA,
  ...
)

spi.cdf(x, para, ...)

cdf.spi(x, para, ...)

Arguments

x, para, ...	L-moments and further parameters for cdf... and cdf
probability_distribution_attrname	attribute name for probability distribution
indices	vector of string working as factors or indices, e g. the month names or similar. It must be of the same length of x or the length equal to 1 other NULL, if not used. If used, it computes cdf for each factor.
return.as.spi	logical parameter. Default is FALSE. If it is TRUE probability value is transformed to a normalized random variable through standard qnorm, as for Standard Precipitation Index (SPI) (https://climatedataguide.ucar.edu/climate-data/standardized-precipitation-index-spi).
spi.scale	integer value or NA. If it greater than 1 x is filtered with the sum of a generic element of x and the previous spi.scale-1 ones (e.g. SPI-3,SPI-6, etc. ). Default is NA (no filtering) which is equivalent to spi.scale=1.
distrib	character string indicating the probability distribution, it can be used in case para has no attributes. Default is NA and distribution info are all passed through para.

Value

A vector of cumulated probability value(s) or SPI-like Gaussianized values. It is a list of vectors in case of several probability parametric distribution functions (i.e. para is a list and length(para)>1).

See Also

pel,cdfexp,cdfgam,cdfgev,cdfglo,

cdfgpa,cdfgno,cdfgum,cdfkap,cdfln3,cdfnor,cdfpe3,cdfwak,cdfwei

Examples

# Sample L-moments of Ozone from the airquality data
data(airquality)
lmom <- samlmu(airquality$Ozone,nmom=6)

distrib <- c("exp","gam","gev","glo","gpa","gno","gum","kap",
"ln3","nor","pe3","wak","wei")

para_list <- pel(distrib=distrib,lmom=lmom)
cdf_list <- cdf(para=para_list,x=airquality$Ozone)

cdf_gam <- cdf(para=para_list$gam,x=airquality$Ozone)
cdf_gam2 <- cdf(para=para_list$gam,x=airquality$Ozone,distrib="gam")

if (any(cdf_gam!=cdf_gam2,na.rm=TRUE)) stop("Any possible errors after  0.6.3 package updates!") 



## Comparison with the SPI/SPEI algorithms:  'SPEI::spi' ('SPEI' package)


if (requireNamespace("SPEI",quietly = TRUE)) {
 library(SPEI)
 data(wichita)

 distrib_wichita <- 'pe3'
 spi.scale <- 1

 month_wichita <- sprintf("M%02d",wichita$MONTH)
 para_whichita  <- pel(x=wichita$PRCP,indices=month_wichita,distrib=distrib_wichita,
						spi.scale=spi.scale,check_lmom_validity=TRUE)
 spi_wichita   <- spi.cdf(x=wichita$PRCP,indices=month_wichita,para=para_whichita,
						spi.scale=spi.scale)
 spi_wichita_speipkg   <- spi(data=wichita$PRCP,distrib='PearsonIII',scale=spi.scale)
 difference <- spi_wichita-spi_wichita_speipkg$fitted
}

---

Generic function for pel...

Description

Generic function for pel...: probability distribution fitting with L-Moments

Usage

pel(
  distrib = c("exp", "gam", "gev", "glo", "gpa", "gno", "gum", "kap", "ln3", "nor",
    "pe3", "wak", "wei"),
  lmom = NULL,
  probability_distribution_attrname = "probability_distrib",
  x = NULL,
  nmom = 5,
  sort.data = TRUE,
  ratios = sort.data,
  trim = 0,
  indices = NULL,
  spi.scale = NA,
  correction = NULL,
  check_lmom_validity = FALSE,
  condt3t4 = TRUE,
  ...
)

pel_x(x, ...)

pel_lmom(lmom, ...)

Arguments

distrib	character string indicating the probability distribution to fit
lmom, ...	L-moments and further parameters for pel...
probability_distribution_attrname	attribute name for probability distribution
x	vector containg sample. It is utiled to calculete L-moments in case lmom is set equal to NULL.
nmom, sort.data, ratios, trim	arguments for samlmu (nmom=5 by default). Thay are utilized if argument lmom is NULL.
indices	optional index or tag character vector of the same length of x used as INDEX for tapply. It is used to fit different probability distribution in one sample time series (e. g. months in an year).
spi.scale	integer value or NA. If it is greater than 1, x is filtered with the sum of a generic element of x and the previous spi.scale-1 ones (e.g. SPI-3,SPI-6, etc. ). Default is NA (no filtering) which is equivalent to spi.scale=1.
correction	numeric value correction for the 3rd (and higher) L-moment estimation. Default is NULL , generally it is not used. It is used and suggested to be 10^(-10) in case of a massive function use with lmom=NULL (e.g. raster cell or zonal statistics).
check_lmom_validity	logical. Default is FALSE. If it is TRUE, L-moments are checked through are.lmoms.valid
condt3t4	argument for are.lmoms.valid in case are.lmoms.valid==TRUE

Details

pel_x and pel_lmom are wrapper functions of pel whose first argument is x or lmom respectively.

Value

A numeric vector containing the parameters of the selected probability distribution. It is a list in case of selection of several probability distributions (i.e. length(distrib)>1).

See Also

pel...,pelexp,pelgam,pelgev,pelglo,pelgpa,

pelgno,pelgum,pelkap,pelln3,pelnor,

pelpe3,pelwak,pelwei,

cdf,qua

Examples

# Sample L-moments of Ozone from the airquality data
 data(airquality)
 lmom <- samlmu(airquality$Ozone,nmom=6)
 distrib <- "gev"    
 # Fit a GEV distribution
 out_gev <- pel(distrib=distrib,lmom=lmom)

 distrib <- c("exp","gam","gev","glo","gpa","gno","gum","kap","ln3",
 "nor","pe3","wak","wei")

 out_list <- pel(distrib=distrib,lmom=lmom)

---

Generic function for qua...: probabilily distribution fitting with L-Moments

Description

Generic function for qua...: probabilily distribution fitting with L-Moments

Usage

qua(
  para,
  f,
  probability_distribution_attrname = "probability_distrib",
  distrib = NA,
  ...
)

Arguments

f, para, ...	L-moments and further parameters for qua...
probability_distribution_attrname	attribute name for probability distribution
distrib	character string indicating the probability distribution, it can be used in case para has no attributes. Default is NA and distribution info are all passed through para.

Value

A vector of quantiles. It is a list of vectors of quantiles in case of several probability parametric distribution functions (i.e. para is a list and length(para)>1).

See Also

pel,quaexp,quagam,quagev,quaglo,quagpa,quagno,quagum,

quakap,qualn3,quanor,quape3, quawak,quawei

Examples

# Sample L-moments of Ozone from the airquality data
data(airquality)
lmom <- samlmu(airquality$Ozone,nmom=6)

distrib <- c("exp","gam","gev","glo","gpa","gno","gum","kap","ln3","nor",
	"pe3","wak","wei")

para_list <- pel(distrib=distrib,lmom=lmom)
f <- (1:10)/10
qua_list <- qua(para=para_list,f=f)

qua_gam <- qua(para=para_list$gam,f=f)
qua_gam2 <- qua(para=as.vector(para_list$gam),f=f,distrib="gam")

if (any(qua_gam!=qua_gam2,na.rm=TRUE)) stop("Any possible errors after  0.6.3 package updates!")

---