GeoCovariogram: Computes the fitted variogram model.

In GeoModels: Procedures for Gaussian and Non Gaussian Geostatistical (Large) Data Analysis

Computes the fitted variogram model.

Description

The procedure computes and plots estimated covariance or semivariogram models of a Gaussian or a non-Gaussian spatial (temporal or bivariate spatial) random field. It allows to add the empirical estimates in order to compare them with the fitted model.

Usage

GeoCovariogram(fitted, distance="Eucl",answer.cov=FALSE,
 answer.vario=FALSE, answer.range=FALSE, fix.lags=NULL, 
 fix.lagt=NULL, show.cov=FALSE, show.vario=TRUE, 
 show.range=FALSE, add.cov=FALSE, add.vario=FALSE,
 pract.range=95, vario = NULL, invisible=FALSE, ...)

Arguments

fitted	A fitted object obtained from the GeoFit or GeoWLS procedures.
distance	String; the name of the spatial distance. When omitted, the distance stored in fitted is used when available. The empirical lag values are taken from vario; the fitted and empirical objects should therefore use the same spatial metric.
answer.cov	Logical; if TRUE the estimated covariance function is returned. For a bivariate Gaussian fit, the returned components are covariance11, covariance12, and covariance22.
answer.vario	Logical; if TRUE a vector with the estimated variogram is returned; if FALSE (the default) the variogram is not returned.
answer.range	Logical; if TRUE the estimated practical range is returned; if FALSE (the default) the practical range is not returned.
fix.lags	Integer; a positive index in the empirical spatial-lag grid (including its zero-lag entry) used for the temporal profile. The theoretical surface is matched to the corresponding lag value rather than reusing this index on a different grid. For dynamic spatial supports, if the zero-lag entry is selected but no collocated pairs exist across distinct times, the plot automatically uses the first positive-distance space-time bin containing finite empirical pairs; the fitted curve is evaluated at that bin's center and the panel title reports the bin interval.
fix.lagt	Integer; a positive index in the empirical temporal-lag grid (including its zero-lag entry) used for the spatial profile. The theoretical surface is matched to the corresponding time-lag value.
show.cov	Logical; if TRUE the estimated covariance function is plotted; if FALSE (the default) the covariance function is not plotted.
show.vario	Logical; if TRUE the estimated variogram is plotted; if FALSE (the default) the variogram is not plotted.
show.range	Logical; if TRUE the estimated practical range is added on the plot; if FALSE (the default) the practical range is not added.
add.cov	Logical; if TRUE the vector of the estimated covariance function is added on the current plot; if FALSE (the default) the covariance is not added.
add.vario	Logical; if TRUE the vector with the estimated variogram is added on the current plot; if FALSE (the default) the correlation is not added.
pract.range	Numeric scalar in [0,100]; the percentage of the marginal variance reached by the semivariogram when computing the practical range.
vario	A Variogram object obtained from the GeoVariogram procedure.
invisible	Logical; if TRUE, compute the sum of squared differences between the empirical and fitted semivariograms on the empirical lag grid. This diagnostic is computed independently of whether the variogram is plotted.
...	other optional parameters which are passed to plot functions.

Details

When a fitted univariate model has a nonconstant mean, the returned lag-only theoretical curve requires one representative marginal location. The function uses the average fitted linear predictor X\widehat\beta; for a site-specific fixed mean it uses the average of that vector. This does not alter the fitted mean used by likelihood, residual, simulation, or kriging calculations. For a univariate GeoFit object fitted with copula="Gaussian", copula="Clayton", or copula="SkewGaussian", the theoretical covariance and semivariogram are computed on the observed marginal scale with the same covariance engine used by GeoCovmatrix and GeoKrig. The supported continuous margins are "Gaussian", "StudentT", "LogGaussian", "Gamma", "Weibull", "Beta", "Beta2", "Kumaraswamy", "Kumaraswamy2", "Logistic", "SkewLaplace", "Tukeyh", "Tukeyh2", and "SinhAsinh". For the Gaussian copula, the monotone transformed-Gaussian Tukey and sinh–arcsinh margins use their exact model covariance. Clayton-like covariance uses cached deterministic copula quadrature and skew-Gaussian covariance uses the cached Hermite representation also used for linear prediction.

For "Beta2" and "Kumaraswamy2" with covariates, and more generally whenever the marginal location varies over the observation sites, a single lag-only covariance curve is not uniquely defined by distance alone. The displayed curve therefore uses the representative marginal predictor described above (the average fitted linear predictor). It is a representative theoretical semivariogram for diagnostic comparison with the empirical one.

For non-Gaussian univariate models, the practical range is computed directly from the fitted observed-scale covariance and semivariogram. This avoids using a Gaussian-correlation range as a surrogate for a transformed marginal model. If the requested percentage is not reached on the evaluated lag grid, the returned practical range is NA. For a Gaussian model, the correlation root calculation is retained. A bivariate practical range is not defined by this function and is returned as NA.

For space-time profile plots, fix.lags and fix.lagt select an empirical lag value; the closest point on the fitted 150-point surface grid is then used. This keeps empirical and theoretical profiles aligned even though their grids have different resolutions. For dynamic spatial supports, finite empirical space-time bins are displayed as points rather than vertical stems. The empirical temporal margin \gamma(0,u) is used when actual collocated locations are available at distinct times. If fix.lags=1 requests that zero-lag profile but no collocated dynamic pairs exist, the plot instead uses the first positive-distance space-time bin with finite empirical values. Thus the panel represents a near-zero spatial band (for example 0<h<h_1) rather than displaying an empty empirical profile; the fitted curve is evaluated at the center of the selected spatial bin. The title reports the actual bin interval. No zero-valued empirical temporal observations are imputed, and the underlying GeoVariogram temporal margin remains the true collocated \gamma(0,u) margin.

For a non-copula LogGaussian model, covariance and semivariogram are reported on the observed scale, including the representative factor \exp(2\eta) in the marginal variance, consistently with GeoCovmatrix.

For a non-copula SinhAsinh model, the nugget attenuation is applied to the latent Gaussian correlation before the nonlinear sinh–arcsinh correlation map is evaluated. This is the same ordering used by GeoCovmatrix, GeoCorrFct, and GeoKrig.

Objects returned by GeoResiduals() with residual_type = "Pearson" are intentionally rejected. The empirical variogram of Pearson residuals is useful by itself, but it is not on the same scale as the response covariance model stored in the original discrete GeoFit object.

The function computes the fitted variogram model

Value

By default the function produces the requested plot invisibly. When answer.cov=TRUE and/or answer.vario=TRUE, it invisibly returns a list containing the lag grid and the fitted covariance and/or semivariogram. When answer.range=TRUE, the practical range is included as range. With invisible=TRUE and no requested answer, the sum-of-squares diagnostic used by the function is returned invisibly. For a bivariate Gaussian fit with answer.cov=TRUE, the list contains covariance11, covariance12, and covariance22.

Author(s)

Moreno Bevilacqua, [e-mail],https://sites.google.com/view/moreno-bevilacqua/home, Víctor Morales Oñate, [e-mail], https://sites.google.com/site/moralesonatevictor/, Christian Caamaño-Carrillo, [e-mail],https://www.researchgate.net/profile/Christian-Caamano

References

Cressie, N. A. C. (1993) Statistics for Spatial Data. New York: Wiley.

Gaetan, C. and Guyon, X. (2010) Spatial Statistics and Modelling. Springer-Verlag, New York.

See Also

GeoFit.

Examples

library(GeoModels)

################################################################
###
### Example 1. Plot of fitted covariance and fitted 
### and empirical semivariogram from a Gaussian RF 
### with Matern correlation. 
###
###############################################################
set.seed(21)
# Set the coordinates of the points:
x = runif(300, 0, 1)
y = runif(300, 0, 1)
coords=cbind(x,y)

# Set the model's parameters:
corrmodel = "Matern"
model = "Gaussian"
mean = 0
sill = 1
nugget = 0
scale = 0.2/3
smooth=0.5

param=list(mean=mean,sill=sill, nugget=nugget, scale=scale, smooth=smooth)
# Simulation of the Gaussian random field:
data = GeoSim(coordx=coords, corrmodel=corrmodel, model=model,param=param)$data
I=Inf
start=list(mean=0,scale=scale,sill=sill)
lower=list(mean=-I,scale=0,sill=0)
upper=list(mean= I,scale=I,sill=I)
fixed=list(nugget=nugget,smooth=smooth)
# Maximum composite-likelihood fitting of the Gaussian random field:
fit = GeoFit(data=data,coordx=coords, corrmodel=corrmodel,model=model,
 likelihood="Marginal",type='Pairwise',start=start,
 lower=lower,upper=upper,
 optimizer="nlminb", fixed=fixed,neighb=3)

# Empirical estimation of the variogram:
vario = GeoVariogram(data=data,coordx=coords,maxdist=0.5)

# Plot of covariance and variogram functions:
GeoCovariogram(fit,show.vario=TRUE, vario=vario,pch=20)

################################################################
###
### Example 2. Plot of fitted covariance and fitted 
### and empirical semivariogram from a Bernoulli 
### RF with Genwend correlation. 
###
###############################################################
set.seed(2111)

model="Binomial";n=1
# Set the coordinates of the points:
x = runif(500, 0, 1)
y = runif(500, 0, 1)
coords=cbind(x,y)

# Set the model's parameters:
corrmodel = "GenWend"
mean = 0
nugget = 0
scale = 0.2
smooth=0
power=4
param=list(mean=mean, nugget=nugget, scale=scale,smooth=0,power2=4)
# Simulation of the Gaussian RF:
data = GeoSim(coordx=coords, corrmodel=corrmodel, model=model,param=param,n=n)$data

start=list(mean=0,scale=scale)
fixed=list(nugget=nugget,power2=4,smooth=0)
# Maximum composite-likelihood fitting of the Binomial random field:
fit = GeoFit(data,coordx=coords, corrmodel=corrmodel,model=model,
 likelihood="Marginal",type='Pairwise',start=start,n=n,
 optimizer="BFGS", fixed=fixed,neighb=4)

# Empirical estimation of the variogram:
vario = GeoVariogram(data,coordx=coords,maxdist=0.5)

# Plot of covariance and variogram functions:
GeoCovariogram(fit, show.vario=TRUE, vario=vario,pch=20,ylim=c(0,0.3))


################################################################
###
### Example 3. Plot of fitted covariance and fitted 
### and empirical semivariogram from a Weibull RF
### with Wend0 correlation. 
###
###############################################################
set.seed(111)

model="Weibull";shape=4
# Set the coordinates of the points:
x = runif(700, 0, 1)
y = runif(700, 0, 1)
coords=cbind(x,y)

# Set the model's parameters:
corrmodel = "Wend0"
mean = 0
nugget = 0
scale = 0.4
power2=4


param=list(mean=mean, nugget=nugget, scale=scale,shape=shape,power2=power2)
# Simulation of the Gaussian RF:
data = GeoSim(coordx=coords, corrmodel=corrmodel, model=model,param=param)$data

start=list(mean=0,scale=scale,shape=shape)
I=Inf
lower=list(mean=-I,scale=0,shape=0)
upper=list(mean= I,scale=I,shape=I)
fixed=list(nugget=nugget,power2=power2)

fit = GeoFit(data,coordx=coords, corrmodel=corrmodel,model=model,
 likelihood="Marginal",type='Pairwise',start=start,
 lower=lower,upper=upper,
 optimizer="nlminb", fixed=fixed,neighb=3)

# Empirical estimation of the variogram:
vario = GeoVariogram(data,coordx=coords,maxdist=0.5)

# Plot of covariance and variogram functions:
GeoCovariogram(fit, show.vario=TRUE, vario=vario,pch=20)

################################################################
###
### Example 4. Plot of fitted and empirical semivariogram
### from a space time Gaussian random fields 
### with double Matern correlation. 
###
###############################################################
set.seed(92)
# Define the spatial-coordinates of the points:
x = runif(50, 0, 1)
y = runif(50, 0, 1)
coords=cbind(x,y)
# Define the temporal sequence:
time = seq(0, 10, 1)


param=list(mean=mean,nugget=nugget,
 smooth_s=0.5,smooth_t=0.5,scale_s=0.5/3,scale_t=2/2,sill=sill)
# Simulation of the spatio-temporal Gaussian random field:
data = GeoSim(coordx=coords, coordt=time, corrmodel="Matern_Matern",param=param)$data

fixed=list(nugget=0, mean=0, smooth_s=0.5,smooth_t=0.5)
start=list(scale_s=0.2, scale_t=0.5, sill=1)
# Maximum composite-likelihood fitting of the space-time Gaussian random field:
fit = GeoFit(data, coordx=coords, coordt=time, corrmodel="Matern_Matern", maxtime=1,
 neighb=3, likelihood="Marginal", type="Pairwise",fixed=fixed, start=start)

# Empirical estimation of spatio-temporal covariance:
vario = GeoVariogram(data,coordx=coords, coordt=time, maxtime=5,maxdist=0.5)

# Plot of the fitted space-time variogram
GeoCovariogram(fit,vario=vario,show.vario=TRUE)

# Plot of covariance, variogram and spatio and temporal profiles:
GeoCovariogram(fit,vario=vario,fix.lagt=1,fix.lags=1,show.vario=TRUE,pch=20)


################################################################
###
### Example 5. Plot of fitted and empirical semivariogram
### from a bivariate Gaussian random fields 
### with Matern correlation. 
###
###############################################################
set.seed(92)
# Define the spatial-coordinates of the points:
x <- runif(600, 0, 2)
y <- runif(600, 0, 2)
coords <- cbind(x,y)

# Simulation of a bivariate spatial Gaussian RF:
# with a Bivariate Matern
set.seed(12)
param=list(mean_1=4,mean_2=2,smooth_1=0.5,smooth_2=0.5,smooth_12=0.5,
 scale_1=0.12,scale_2=0.1,scale_12=0.15,
 sill_1=1,sill_2=1,nugget_1=0,nugget_2=0,pcol=-0.5)
data <- GeoSim(coordx=coords,corrmodel="Bi_matern",
 param=param)$data



# selecting fixed and estimated parameters
fixed=list(mean_1=4,mean_2=2,nugget_1=0,nugget_2=0,
 smooth_1=0.5,smooth_2=0.5,smooth_12=0.5)
start=list(sill_1=var(data[1,]),sill_2=var(data[2,]),
 scale_1=0.1,scale_2=0.1,scale_12=0.1,
 pcol=cor(data[1,],data[2,]))


# Maximum marginal pairwise likelihood
fitcl<- GeoFit(data=data, coordx=coords, corrmodel="Bi_Matern",
 likelihood="Marginal",type="Pairwise",
 optimizer="BFGS" , start=start,fixed=fixed,
 neighb=4)
print(fitcl)

# Empirical estimation of spatio-temporal covariance:
vario = GeoVariogram(data,coordx=coords,maxdist=0.4,bivariate=TRUE)
GeoCovariogram(fitcl,vario=vario,show.vario=TRUE,pch=20)

GeoModels documentation built on Sept. 23, 2026, 5:07 p.m.