# control.georob: Tuning Parameters for georob In georob: Robust Geostatistical Analysis of Spatial Data

## Description

This page documents parameters used to control georob. It describes the arguments of the functions control.georob, param.transf, fwd.transf, dfwd.transf, bwd.transf, control.rq, control.nleqslv, control.nlminb and control.optim, which all serve to control the behaviour of georob.

## Usage

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 control.georob(ml.method = c("REML", "ML"), reparam = TRUE, maximizer = c("nlminb", "optim"), initial.param = TRUE, initial.fixef = c("lmrob", "rq", "lm"), bhat = NULL, min.rweight = 0.25, param.tf = param.transf(), fwd.tf = fwd.transf(), deriv.fwd.tf = dfwd.transf(), bwd.tf = bwd.transf(), psi.func = c("logistic", "t.dist", "huber"), irwls.maxiter = 50, irwls.ftol = 1.e-5, force.gradient = FALSE, min.condnum = 1.e-12, zero.dist = sqrt(.Machine[["double.eps"]]), error.family.estimation = c("gaussian", "long.tailed"), error.family.cov.effects = c("gaussian", "long.tailed"), error.family.cov.residuals = c("gaussian", "long.tailed"), cov.bhat = TRUE, full.cov.bhat = FALSE, cov.betahat = TRUE, cov.delta.bhat = TRUE, full.cov.delta.bhat = TRUE, cov.delta.bhat.betahat = TRUE, cov.ehat = TRUE, full.cov.ehat = FALSE, cov.ehat.p.bhat = FALSE, full.cov.ehat.p.bhat = FALSE, hessian = TRUE, rq = control.rq(), lmrob = lmrob.control(), nleqslv = control.nleqslv(), optim = control.optim(), nlminb = control.nlminb(), pcmp = control.pcmp(), ...) param.transf(variance = "log", snugget = "log", nugget = "log", scale = "log", alpha = c( RMaskey = "log", RMdewijsian = "logit2", RMfbm = "logit2", RMgencauchy = "logit2", RMgenfbm = "logit2", RMlgd = "identity", RMqexp = "logit1", RMstable = "logit2" ), beta = c(RMdagum = "logit1", RMgencauchy = "log", RMlgd = "log"), delta = "logit1", gamma = c(RMcauchy = "log", RMdagum = "logit1"), kappa = "logit3", lambda = "log", mu = "log", nu = "log", f1 = "log", f2 ="log", omega = "identity", phi = "identity", zeta = "identity") fwd.transf(...) dfwd.transf(...) bwd.transf(...) control.rq(tau = 0.5, rq.method = c("br", "fnb", "pfn"), rq.alpha = 0.1, ci = FALSE, iid = TRUE, interp = TRUE, tcrit = TRUE, rq.beta = 0.99995, eps = 1e-06, Mm.factor = 0.8, max.bad.fixup = 3, ...) control.nleqslv(method = c("Broyden", "Newton"), global = c("dbldog", "pwldog", "qline", "gline", "none"), xscalm = c("fixed", "auto"), control = list(ftol = 1e-04), ...) control.optim(method = c("BFGS", "Nelder-Mead", "CG", "L-BFGS-B", "SANN", "Brent"), lower = -Inf, upper = Inf, control = list(reltol = 1e-05), ...) control.nlminb(control = list(rel.tol = 1.e-5), lower = -Inf, upper = Inf, ...) 

## Arguments

 ml.method character keyword defining whether non-robust maximum likelihood (ML) or restricted maximum likelihood (REML default) estimates will be computed (ignored if tuning.psi <= tuning.psi.nr). reparam logical. If TRUE (default) the re-parametrized variance parameters σ_B^2, η and ξ are estimated by Gaussian (RE)ML, otherwise the original parameters τ^2, σ_n^2 and σ^2 (cf. subsection Estimating variance parameters by Gaussian (RE)ML, section Details of georob). maximizer character keyword defining the Gaussian (restricted) log-likelihood is maximized by nlminb (default) or optim. initial.param logical, controlling whether initial values of variogram parameters are computed for solving the estimating equations of the variogram and anisotropy parameters. If initial.param = TRUE (default) robust initial values of parameters are computed by discarding outlying observations based on the “robustness weights” of the initial fit of the regression model by lmrob and fitting the spatial linear model by Gaussian REML to the pruned data set. For initial.param = FALSE no initial parameter values are computed and the estimating equations are solved with the initial values passed by param and aniso to georob (see Details of georob. initial.fixef character keyword defining whether the function lmrob or rq is used to compute robust initial estimates of the regression parameters β (default "lmrob"). If the fixed effects model matrix has not full columns rank, then lm is used to compute initial values of the regression coefficients. bhat initial values for the spatial random effects hatB, with hatB=0 if bhat is equal to NULL (default). min.rweight positive numeric. “Robustness weight” of the initial lmrob fit that observations must exceed to be used for computing robust initial estimates of variogram parameters by setting initial.param = TRUE (see georob; default 0.25). param.tf a function such as param.transf, which returns a named vector of character strings that define the transformations to be applied to the variogram parameters for model fitting, see Details. fwd.tf a function such as fwd.transf, which returns a named list of invertible functions to be used to transform variogram parameters, see Details. deriv.fwd.tf a function such as dfwd.transf, which returns a named list of functions corresponding to the first derivatives of fwd.tf, see Details. bwd.tf a function such as bwd.transf, which returns the named list of inverse functions corresponding to fwd.tf, see Details. psi.func character keyword defining what ψ_c-function should be used for robust model fitting. Possible values are "logistic" (a scaled and shifted logistic CDF, default), "t.dist" (re-descending ψ_c-function associated with Student t-distribution with c degrees of freedom) and "huber" (Huber's ψ_c-function). irwls.maxiter positive integer equal to the maximum number of IRWLS iterations to solve the estimating equations of B and β (default 50). irwls.ftol numeric convergence criterion for IRWLS. Convergence is assumed if the objective function changes in one IRWLS iteration does not exceed ftol. force.gradient logical controlling whether the estimating equations or the gradient of the Gaussian restricted log-likelihood are evaluated even if all variogram parameters are fixed (default FALSE). min.condnum positive numeric. Minimum acceptable ratio of smallest to largest singular value of the model matrix X (default 1.e-12). zero.dist positive numeric equal to the maximum distance, separating two sampling locations that are still considered as being coincident. error.family.estimation character keyword, defining the probability distribution for ε (default: "gaussian") that is used to approximate the covariance of hatB when solving the estimating equations, see Details. error.family.cov.effects character keyword, defining the probability distribution for ε (default: "gaussian") that is used to approximate the covariances of hatβ, hatB and B-hatB, see Details. error.family.cov.residuals character keyword, defining the probability distribution for ε (default: "long.tailed") that is used to approximate the covariances of hatε=Y-X hatβ - hatB and hatε+ hatB=Y-X hatβ, see Details. cov.bhat logical controlling whether the covariances of hatB are returned by georob (default FALSE). full.cov.bhat logical controlling whether the full covariance matrix (TRUE) or only the variance vector of hatB is returned (default FALSE). cov.betahat logical controlling whether the covariance matrix of hatβ is returned (default TRUE). cov.delta.bhat logical controlling whether the covariances of B-hatB are returned (default TRUE). full.cov.delta.bhat logical controlling whether the full covariance matrix (TRUE) or only the variance vector of B-hatB is returned (default TRUE). cov.delta.bhat.betahat logical controlling whether the covariance matrix of B-hatB and hatβ is returned (default TRUE). cov.ehat logical controlling whether the covariances of hatε=Y-X hatβ - hatB are returned (default TRUE). full.cov.ehat logical controlling whether the full covariance matrix (TRUE) or only the variance vector of hatε=Y-X hatβ - hatB is returned (default FALSE). cov.ehat.p.bhat logical controlling whether the covariances of hatε+ hatB=Y-X hatβ are returned (default FALSE). full.cov.ehat.p.bhat logical controlling whether the full covariance matrix (TRUE) or only the variance vector of hatε+ hatB=Y-X hatβ is returned (default FALSE). hessian logical scalar controlling whether for Gaussian (RE)ML the Hessian should be computed at the MLEs. rq a list of arguments passed to rq or a function such as control.rq that generates such a list (see rq for allowed arguments). lmrob a list of arguments passed to the control argument of lmrob or a function such as lmrob.control that generates such a list (see lmrob.control for allowed arguments). nleqslv a list of arguments passed to nleqslv or a function such as control.nleqslv that generates such a list (see nleqslv for allowed arguments). nlminb a list of arguments passed to nlminb or a function such as control.nlminb that generates such a list (see nlminb for allowed arguments). optim a list of arguments passed to optim or a function such as control.optim that generates such a list (see optim for allowed arguments). pcmp a list of arguments, passed e.g. to pmm or a function such as control.pcmp that generates such a list (see control.pcmp for allowed arguments). ... for fwd.transf, dfwd.transf and bwd.transf a named vectors of functions, extending the definition of transformations for variogram parameters (see Details). variance, snugget, nugget, scale, alpha, beta, delta, gamma, kappa, lambda, mu, nu character strings with names of transformation functions of the variogram parameters. f1, f2, omega, phi, zeta character strings with names of transformation functions of the variogram parameters. tau, rq.method, rq.alpha, ci, iid, interp, tcrit arguments passed as ... to rq. Note that only "br", "fnb" and "pfn" methods of rq() are currently supported. rq.beta, eps, Mm.factor, max.bad.fixup arguments passed as ... to rq. method, global, xscalm, control, lower, upper, reltol, rel.tol arguments passed to related arguments of nleqslv, nlminb and optim, respectively.

## Details

#### Parameter transformations

The arguments param.tf, fwd.tf, deriv.fwd.tf, bwd.tf define the transformations of the variogram parameters for RE(ML) estimation. Implemented are currently "log", "logit1", "logit2", "logit3" (various variants of logit-transformation, see code of function fwd.transf) and "identity" (= no) transformations. These are the possible values that the many arguments of the function param.transf accept (as quoted character strings) and these are the names of the list components returned by fwd.transf, dfwd.transf and bwd.transf. Additional transformations can be implemented by:

1. Extending the function definitions by arguments like

fwd.tf = fwd.transf(my.fun = function(x) your transformation),
deriv.fwd.tf = dfwd.transf(my.fun = function(x) your derivative),
bwd.tf = bwd.transf(my.fun = function(x) your back-transformation),

2. Assigning to a given argument of param.transf the name of the new function, e.g.
variance = "my.fun".

Note the values given for the arguments of param.transf must match the names of the functions returned by fwd.transf, dfwd.transf and bwd.transf.

#### Approximation of covariances of fixed and random effects and residuals

The robustified estimating equations of robust REML depend on the covariances of hatB. These covariances (and the covariances of B-hatB, hatβ, hatε, hatε+ hatB) are approximated by expressions that in turn depend on the variances of ε, ψ(ε/τ) and the expectation of ψ'(ε/τ) (= \partial / \partial ε ψ(ε/τ)). The arguments error.family.estimation, error.family.cov.effects and error.family.cov.residuals control what parametric distribution for ε is used to compute the variance of ε, ψ(ε/τ) and the expectation of ψ'(ε/τ) when

• solving the estimating equations (error.family.estimation),

• computing the covariances of hatβ, hatB and B-hatB (error.family.cov.effects) and

• computing the covariances of hatε=Y-X hatβ - hatB and hatε+ hatB=Y-X hatβ (error.family.cov.residuals).

Possible options are: "gaussian" or "long.tailed". In the latter case the PDF of ε is assumed to be proportional to 1/τ \exp(-ρ(ε/τ)), where ψ(x)=ρ'(x).

## Value

control.georob, control.rq, control.nleqslv, control.optim and control.nlminb all create lists with control parameters passed to georob, rq, nleqslv, optim, nlminb, respectively. Note that the list returned by code.georob contains some components (irwls.initial, tuning.psi.nr, cov.bhat.betahat, aux.cov.pred.target) that cannot be changed by the user.

param.transf generates a list with character strings that define what transformations are used for estimating the variogram parameters, and fwd.transf, bwd.transf and dfwd.transf return lists of functions with forward and backward transformations and the first derivatives of the forward transformations.

## Author(s)

Andreas Papritz [email protected]

georobIntro for a description of the model and a brief summary of the algorithms; georob for (robust) fitting of spatial linear models; georobObject for a description of the class georob; plot.georob for display of RE(ML) variogram estimates; predict.georob for computing robust Kriging predictions; and finally georobMethods for further methods for the class georob.
  1 2 3 4 5 6 7 8 9 10 11 12 13 ## Not run: data(meuse) r.logzn.rob <- georob(log(zinc) ~ sqrt(dist), data = meuse, locations = ~ x + y, variogram.model = "RMexp", param = c(variance = 0.15, nugget = 0.05, scale = 200), tuning.psi = 1, control = control.georob(cov.bhat = TRUE, cov.ehat.p.bhat = TRUE, initial.fixef = "rq"), verbose = 2) qqnorm(rstandard(r.logzn.rob, level = 0)); abline(0, 1) qqnorm(ranef(r.logzn.rob, standard = TRUE)); abline(0, 1) ## End(Not run)