| vario.mod {EgoCor} | R Documentation |
Semi-variogram model fitting
Description
The function allows for user friendly exponential semi-variogram model fitting to data.
Based on the gstat function variogram, vgm and fit.variogram, the function fits one
or multiple exponential semi-variogram models given one or multiple maximal distances and number of bins.
All estimated model parameters are summarized in an information table.
Graphics of all models can be observed in a shiny application output
or in several plot windows, one for each empirical semi-variogram.
Additionally, a pdf file including all the figures can be
saved in a specified working directory.
Usage
vario.mod(
data,
max.dist = c(2000, 1500, 1000, 750, 500, 250),
nbins = 13,
fit.method = 7,
shinyresults = TRUE,
windowplots = FALSE,
pdf = FALSE,
pdf.directory = getwd(),
pdf.name = "Semivariograms"
)
Arguments
data |
A data frame or matrix containing the x-coordinates in the first column, the y-coordinates in the second column (by default in meters) and the data values in the third column. The dataset may contain more attributes in further columns. In this case, a warning is provided. All columns beyond the third one are ignored. |
max.dist |
An optional numeric argument; the default is the vector |
nbins |
An optional argument; the default is 13 bins for all empirical semi-variograms to be estimated.
Either a scalar or vector containing the number of bins can be inserted. If a vector is
provided, the |
fit.method |
An optional argument that specifies the fit method used by the gstat function fit.variogram to fit the semivariogram. The default value ist 7. Only values 1,2,6,7 are possible. Please see the package description of gstat for more information. |
shinyresults |
A logical argument; by default TRUE. If |
windowplots |
A logical argument; by default FALSE. If |
pdf |
A logical argument; by default FALSE. If |
pdf.directory |
A character argument to specify the folder in which the pdf file is saved.
If no file path is given, the pdf file is saved in the current working directory identified
by |
pdf.name |
A character argument to specify the name of the pdf file. If no name is provided, the file is saved as 'Semivariograms.pdf'. |
Details
Prespecification and Interpretation of max.dist and nbins arguments:
max.dist:
only data pairs with a separation smaller than the prespecified maximal distance are included in the semi-variogram
estimation. Data pairs that are separated by a higher distance are excluded.
nbins: the interval (0, max.dist] is separated into nbins equidistant
lag bins or intervals, respectively. Each pairwise distance is then assigned to one of the
bins. The point pair subsets N(h_k) := \{(\mathbf{s_i}, \mathbf{s_j}) \in D |\;\; ||\mathbf{s_i}-\mathbf{s_j}|| \in Bin_k\}
are defined
and a point estimate of the semi-variogram is estimated for each Bin_k for k =1,...nbins.
Empirical semi-variogram estimator:
Using the gstat function variogram an empirical semi-variogram according to
Matheron's semi-variogram estimator (Matheron 1962)
\hat{\gamma}(h) = \frac{1}{2\cdot|N(h)|} \sum_{(\mathbf{s_i},
\mathbf{s_j}) \in N(h)}\{Z(\mathbf{s_i})- Z(\mathbf{s_j})\}^2
with N(h) defined as above is obtained.
Exponential semi-variogram model:
Based on the empirical semi-variogram an exponential semi-variogram model of the form (Cressie et al. 1993)
\gamma_{exp}(h) = c_0 + \sigma_0^2 \Big\{1 - \exp\big(- \frac{h}{\phi}\big)\Big\}
for h > 0
is fitted using the vgm and fit.variogram function from package gstat via
weighted least squares estimation. The weights have the form
w_k = \vert N(h_k) \vert / h_k^2 specified by the fit.method = 7 argument
within the fit.variogram function.
For the numerical optimization, starting values for the model parameters have to be provided.
The initial value for the partial sill \sigma_0^2 equals the empirical variance of
the observations. The starting value for the nugget effect c_0 is set to zero.
The initial value for the shape parameter \phi is set as max.dist divided by 3.
Result statistics:
The results for all models are automatically printed when running the function and can be
found under function.output$infotable. Part of the table contains a repetition of the
specified max.dist and nbins parameters as well as the estimated model parameters.
The additional statistics within the infotable output are the following:
Practical range: In case of the exponential semi-variogram model, the
sill \sigma^2 = c_0 + \sigma_0^2 is only reached asymptotically. The distance H
at which \gamma(h^* = 0.95 \cdot \sigma^2) is called the practical range.
Formally, the practical range is
defined as
prac.range = \phi ln\Big( \frac{\sigma_0^2}{0.05(c_0 + \sigma_0^2)} \Big).
Relative Structural Variability (RSV): The relative structural variability is a measure of the proportion of the total variance with a spatial structure and defined as
RSV = \frac{\sigma_0^2}{c_0 + \sigma_0^2}.
Relative Bias: The relative bias describes the proportion of the total variance according to the semi-variogram model to the true total variance. It is estimated as
rel. bias = \frac{c_0 + \sigma_0^2}{\widehat{Var(Z)}},
where \widehat{Var(Z)} is the sample variance or empirical variance of the attribute of
interest of the dataset at hand.
A relative bias of 1 indicates equality of
sample variance and variance according to the semi-variogram model.
For more details, see Schabenberger and Gotway (2017).
Value
A list containing the following arguments:
infotable |
A table containing the statistics of all estimated exponential semi-variogram models.
Each row corresponds to one model.
Shown are the prespecified |
variog.list |
A list: each list entry contains the |
vmod.list |
A list: each list entry contains the |
input.arguments |
A list containing the evaluated input arguments, namely the |
call |
Contains the call of the function. |
The models are visualized in an automatically opened shiny application if shinyresults = T. Beware
that in this case the output of the vario.mod function is not saved in the environment, even with a variable name assigned.
In order to save the output, set shinyresults = F.
If the argument windowplots = T, one or multiple graphics of the estimated
empirical semi-variograms and semi-variogram models are plotted in the R environment.
If the argument pdf = T, a pdf file containing the same figures is saved in the manually
specified or current working directory.
References
Cressie N, Ribeiro PJ, Diggle PJ (1993).
Statistics for spatial data, Rev. ed. edition.
Wiley, New York.
ISBN 9781119115151.
Matheron G (1962).
Traité de géostatistique appliquée. 1 (1962), volume 1.
Editions Technip.
Schabenberger O, Gotway CA (2017).
Statistical methods for spatial data analysis.
CRC press.
See Also
variogram in the gstat package for further information on
the estimation of the empirical semi-variogram;
fit.variogram and vgm in the gstat package for further information on the default settings
when fitting an exponential semi-variogram model to an empirical semi-variogram.
Examples
if(interactive()){
## Example 1
# Default options:
vario.mod(data = birth)
# This is equal to
vario.mod(data = birth, max.dist = c(2000,1500,1000,750,500,250), nbins = 13,
shinyresults = TRUE, windowplots = FALSE,
pdf = FALSE, pdf.directory = getwd(), pdf.name = "Semivariograms")
## Example 2
# Open graphics in regular windows and not in shiny application:
vario.mod(data = birth, max.dist = c(2000,1500,1000,750,500,250), nbins = 15:10,
shinyresults = FALSE, windowplots = TRUE)
## Example 3
# Generate a pdf with the following command:
vario.mod(data = birth, shinyresults = FALSE, windowplots = FALSE,
pdf = TRUE, pdf.directory = getwd())
# You find a pdf file in your current working directory.
}