EgoCor (version 1.3.4)

par.uncertainty: Semi-variogram model parameter uncertainty

Description

Standard error estimates for the nugget effect \(c_0\), partial sill \(\sigma_0^2\) and shape parameter \(\phi\) of a fitted exponential semi-variogram model.

Usage

par.uncertainty(
  vario.mod.output,
  mod.nr,
  par.est = NULL,
  data = NULL,
  max.dist = NULL,
  nbins = NULL,
  B = 1000,
  threshold.factor = 3,
  fit.method = 7,
  mc.cores = 1
)

Value

The function returns parameter estimates and corresponding standard error estimates together and provides a list with the following objects:

se

A vector of length 3 containing the estimated standard errors of the nugget effect, the partial sill and the shape parameter.

unc.table

A matrix containing the parameter estimates and the corresponding standard errors.

re_estimates

A matrix with B rows containing the set of bootstrap re-estimates for each parameter.

re_estimate.mean

A vector containing the mean parameter estimates based on the set of bootstrap re-estimates for each parameter.

call

The function call.

Arguments

vario.mod.output

An output of the vario.mod function containing the information of the estimated exponential semi-variogram model of interest.

mod.nr

The index number specifiying one of the exponential semi-variogram models listed in the vario.mod.ouput.

par.est

A vector of length three containing the estimated parameters: the nugget effect, the partial sill and the shape parameter of the estimated exponential semi-variogram model. It is automatically extracted from the vario.mod.output, if provided.

data

The data frame or matrix used to estimate the exponential semi-variogram of interest containing the x-coordinates in meters in the first column, the y-coordinates in meters in the second column and the data values in the third column. It is automatically extracted from the vario.mod.output, if provided.

max.dist

The maximal distance used for the estimation of the exponential semi-variogram model of interest. It is automatically extracted from the vario.mod.output, if provided.

nbins

The number of bins used for the estimation of the exponential semi-variogram model of interest. It is automatically extracted from the vario.mod.output, if provided.

B

The number of bootstrap repetitions to generate a set of re-estimates of each parameter.

threshold.factor

The threshold factor specifies the filter within the filtered bootstrap method (see details). If not specified, a default value of 3 is used.

fit.method

The fit method used in the semivariogram estimation with the gstat package.

mc.cores

The number of cores used for bootstrapping, utilizing the parallel R-package. More than one core is not supported on windows systems.

Details

Two alternative approaches for the input of the arguments:

1. Provide the arguments vario.mod.output (output object from vario.mod function) and mod.nr (number of the model in the infotable).

2. Provide the necessary information manually, namely par.est (vector with estimated nugget, partial sill and shape parameters), data (used to estimate the semi-variogram model parameters), max.dist (semi-variogram parameter, numeric of length 1) and nbins (semi-variogram parameter, numeric of length 1).

Filtered bootstrap method:

For the semi-variogram model parameter estimation, the weighted least squares method is used in order to make the numerical calculation possible for large sample sizes. A filter is set up within the bootstrapping process to remove all bootstrap estimates for which the estimation algorithm for the semi-variogram model parameters did not converge.

The parameter standard errors are estimated using the generalized bootstrap method with check-based filtering. The semi-variogram structure from the given model is used to remove the spatial correlation structure within the original dataset. Then, classical bootstrap sampling with replacement is used to generate B bootstrap samples from the uncorrelated data. Each bootstrap sample inherits the correlation structure back and is used to estimate the nugget effect, partial sill and shape parameter for an exponential model. Within the bootstrap repetitions, a test is performed to check whether the estimated parameters lie within a probable range. If the total variance of the bootstrap model exceeds the empirical variance of the data times the treshold factor \(\tau\), ie. $$c_{0 b}^* + \sigma_{0 b}^{2*} > \tau \widehat{Var(\mathbf{z})}$$ for the bth bootstrap estimate, it is discarded. Otherwise, it is saved. This procedure is performed until B bootstrap estimates have aggregated. The empirical standard deviation calculated from the bootstrap estimates provides the uncertainty estimate for each parameter.

Details about the algorithm used to obtain standard errors for the parameters of the exponential semi-variogram model are provided in dyck_sv_ses;textualEgoCor.

Reproducibility:

In order to generate reproducible bootstrap results, set a random seed with the command set.seed() before using the par.uncertainty function.

References

Examples

## Example 1
# Estimate semi-variogram models:
mods = vario.mod(data = birth, max.dist = c(1000,600), nbins = 13,
                 shinyresults = FALSE, windowplots = FALSE)
print(mods$infotable)

# Estimate the parameter standard errors:
if (FALSE) {
se.mod1 = par.uncertainty(vario.mod.output = mods, mod.nr = 1, B = 1000)
se.mod2 = par.uncertainty(vario.mod.output = mods, mod.nr = 2, B = 1000)
}

## Example 2
# Type in the specifications of the estimated exponential semi-variogram manually:
if (FALSE) {
se.mod1.man = par.uncertainty(par.est = c(1021.812, 225440.3, 0),
              data = birth, max.dist = 1000, nbins = 13, B = 1000)

se.mod2.man = par.uncertainty(par.est = c(121895.486, 107232.6, 63.68720),
              data = birth, max.dist = 600, nbins = 13, B = 1000)
}