roiGls: Perform frequency analysis of a target site using Region of...
In martindurocher/floodRFA: A R-package for regional frequency of floods

Description Usage Arguments Details References Examples

Returns the fitting of the regression models at a target site with the best calibration settings.

roiGls(form, ...)

## S3 method for class 'formula'
roiGls(form, x, x0, nk, S = NULL, distance = NULL,
  criteria = "vp0", lambda = 1, sigTol = 0, verbose = FALSE)

## S3 method for class 'list'
roiGls(form, x, x0, ...)

`form`	Formula or list of formulas to try.
`x`	Data frame containing all variables in the formulas.
`x0`	Data.frame or list containing the input variables of the target
`nk`	Scalar or vector providing a series of neighborhood sizes to try.
`S`	Sampling covariance matrix for the output variable.
`distance`	Vector of distance between the donors and target
`criteria`	Criteria to select the best calibration. One of 'gcv','vp0','avp', 'avpo'.
`lambda`	Scalar that modified the penalty in the GCV criteria
`sigTol`	Lower limit for the model variance during the clalibration
`verbose`	If true a progress bar is printed.

The GLS model was proposed by Stedinger and Takser (1985):

y= X β + η + ε

where η and ε are two independent terms of errors. The total error is ε = η + δ and includes respectively the error due to sampling, with known covariance matrix S, and a iid term of error η with variance σ^2. Therefore, the covariance matrix of the total error is then given by

Λ = σ^2 I + S = σ^2 G.

For a given model error σ^2, the cholesky decomposition provide the matrix decomposition G^{-1} = UU'. Solving the initial GLS model with known model variance is then equivant to solving the ordinary least-squares problem

U'y = UX + ε^\ast.

A new estimation of the model error can be obtained by

\hatσ^2 = (n-p)^{-1} ∑_{i =1 }^n ε_i^\ast

where n is the number of sites and p the number of parameters. Subsequent iterations are then performed to improved the global fitting of the GLS model until σ^2 has converged.

Stedinger, J. R., & Tasker, G. D. (1985). Regional Hydrologic Analysis: 1. Ordinary, Weighted, and Generalized Least Squares Compared. Water Resources Research, 21(9), 1421–1432. https://doi.org/10.1029/WR021i009p01421

Reis, D. S., Stedinger, J. R., & Martins, E. S. (2005). Bayesian generalized least squares regression with application to log Pearson type 3 regional skew estimation. Water Resources Research, 41(10), W10419. https://doi.org/10.1029/2004WR003445

Kjeldsen, T. R., & Jones, D. A. (2009). An exploratory analysis of error components in hydrological regression modeling. Water Resources Research, 45(2), W02407. https://doi.org/10.1029/2007WR006283

xd <- ungaugedDemoData()

lform <- list(y ~ x,
              y ~ x + I(x^2))

fit <- roiGls( lform, xd$data[-1,], xd$data[1,],
              S = xd$S[-1,-1],
              distance = xd$distance[1,-1],
              nk = seq(20,200,10))

# Show best calibration settings
print(fit)

# Summary of the model
summary(fit)
plot(fit)