GeoSimCopula: Simulation of Gaussian and non-Gaussian random fields using...

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

Simulation of Gaussian and non-Gaussian random fields using copula.

Description

Simulation of Gaussian and some non-Gaussian univariate spatial and spatio-temporal random fields using Gaussian, skew-Gaussian, Clayton-like or AMH constructions. Bivariate correlation models are not supported. The function returns a realization of a random field for a given covariance model and covariance parameters. Exact simulation is available through Cholesky or SVD decomposition; for supported purely spatial correlation models, turning-bands simulation is available through method="TB".

Usage

GeoSimCopula(coordx=NULL, coordy=NULL,coordz=NULL, coordt=NULL, 
coordx_dyn=NULL, corrmodel, distance="Eucl", grid=FALSE, 
 method="cholesky", model='Gaussian', n=1, param,
 anisopars=NULL,radius=1, sparse=FALSE,
 copula="Gaussian",X=NULL,spobj=NULL,nrep=1,progress=FALSE,check.duplicates=FALSE,
 L=10000,parallel=FALSE,ncores=6)

Arguments

coordx	Optional when coordx_dyn or spobj is supplied. A numeric (d \times 2)-matrix or (d \times 3)-matrix Coordinates on a sphere for a fixed radius radius are passed in lon/lat format expressed in decimal degrees.
coordy	A numeric vector giving 1-dimension of spatial coordinates; Optional argument, the default is NULL.
coordz	A numeric vector giving 1-dimension of spatial coordinates; Optional argument, the default is NULL.
coordt	A numeric vector giving the temporal coordinates at which the field is simulated. Optional argument; the default is NULL, in which case a spatial random field is expected. Temporal coordinates may be irregularly spaced; temporal lags are computed from the supplied coordinate values.
coordx_dyn	A list of m numeric (d_t \times 2)-matrices containing dynamical (in time) spatial coordinates. Optional argument, the default is NULL
corrmodel	String; the name of a correlation model, for the see GeoCovmatrix for the list of implemented correlation models.
distance	String; the name of the spatial distance. The default is Eucl, the Euclidean distance. See GeoFit for details.
grid	Logical; if FALSE (the default) the data are interpreted as spatial or spatio-temporal realisations on a set of non-equispaced spatial sites (irregular grid).
method	String; simulation engine for the latent fields. Use "cholesky" (default) or "svd" for exact simulation through GeoSim, and "TB" for turning-bands simulation through GeoSimapprox.
model	String; the type of RF and therefore the densities associated to the likelihood objects. Gaussian is the default, see the Section Details.
n	Numeric; the number of trials for binomial random fields. The number of successes in the negative Binomial random fields. Default is 1.
param	A list of parameter values required in the simulation procedure of random fields, see Examples.
anisopars	A list of two elements "angle" and "ratio" i.e. the anisotropy angle and the anisotropy ratio, respectively.
radius	Numeric; a value indicating the radius of the sphere when using the great circle distance. Default value is 1.
sparse	Logical; if TRUE then cholesky decomposition is performed using sparse matrices algorithms (spam packake). It should be used with compactly supported covariance models.FALSE is the default.
copula	String; one of "Gaussian", "SkewGaussian", "Clayton", or "AMH".
X	Numeric; Matrix of space-time covariates.
spobj	An object of class sp or spacetime. For space-time objects, the current sp2Geo() conversion uses sequential temporal indices and does not preserve irregular original time spacing; to retain irregular temporal distances, use the explicit-coordinate interface with numeric coordt.
nrep	Numeric; Numbers of indipendent replicates.
progress	Logic; If TRUE then a progress bar is shown.
check.duplicates	Logical. If TRUE, perform a fast exact scan for duplicated observation locations at this user entry point. The default is FALSE, so no duplicate-location scan is imposed. Internal bootstrap, cross-validation, and refitting calls do not repeat the scan.
L	Positive integer; number of turning-band lines used when method="TB". Ignored by exact methods.
parallel	Logical; default FALSE. For method="TB", set TRUE to allow GeoSimapprox to select a parallel turning-bands execution path.
ncores	Positive integer or NULL; default 6. With parallel=TRUE and method="TB", an explicit integer requests that many workers for the TB backend, subject to detected-core and job-count limits. Set ncores=NULL for automatic selection.

Details

Only univariate correlation models are accepted. Dynamic coordinates are supported and the returned data preserve the list structure and row order of coordx_dyn.

With method="TB", GeoSimCopula keeps the copula and marginal construction unchanged but generates each required latent field through GeoSimapprox(method="TB"). Consequently, TB is available only for purely spatial models supported by the turning-bands backend, requires distance="Eucl", and inherits the TB restrictions on correlation families and coordinate dimension. The sparse argument is ignored by the TB backend. Exact "cholesky" and "svd" simulations continue to use GeoSim.

For the constructive Clayton-like simulator, param$nu must be a positive integer and is never rounded silently. For copula="SkewGaussian", param$nu is the bounded reflection-asymmetry parameter \eta\in(-1,1) and is internally mapped to \gamma_\eta=\eta/\sqrt{1-\eta^2}. The continuous margins audited for copula simulation and pairwise copula fitting with the Gaussian, Clayton-like and skew–Gaussian copulas are Gaussian, StudentT, LogGaussian, Gamma, Weibull, Beta, Beta2, Kumaraswamy, Kumaraswamy2, Logistic, and SkewLaplace. The Gaussian copula additionally has audited simulation and pairwise fitting for Poisson, Binomial, and BinomialNeg. Exact conditional simulation for these discrete copula margins is not currently implemented. For model="StudentT", param$df is the reciprocal degrees-of-freedom parameter: the Student-t degrees of freedom are exactly 1/param$df, without integer rounding. The same no-rounding convention is used for the Student-t degrees of freedom of a "SkewStudentT" marginal. Because copula margins are obtained through inverse CDFs, the integer latent-field restrictions used by direct GeoSim / GeoSimapprox Gamma, Beta, and Student-t constructions do not apply here. Gamma margins require a finite positive shape and use shape shape/2 and scale 2/shape, hence the multiplicative factor has unit mean. With dynamic coordinates, X may be a row-stacked matrix or a list of matrices aligned with coordx_dyn. For SkewStudentT, skew is the native \delta\in(-1,1) parameter and is converted to the skew-t shape \alpha=\delta/\sqrt{1-\delta^2}. The Tukey-g-and-h implementation uses its continuous limit when the skew parameter is zero. Kumaraswamy margins use the inverse of the CDF employed by GeoPit.

Aliases accepted by the main modelling API, including Gauss, SkewGauss, LogGauss, and TwoPieceGauss, are canonicalized before the marginal transform. nrep must be a positive integer. For the AMH construction, nu is checked to be a finite scalar; no additional theoretical parameter range is imposed by this simulator. The returned param component is the parameter list supplied by the user.

Binary and Bernoulli are aliases of Binomial with n=1; Geom and Geometric are aliases of BinomialNeg with n=1.

For univariate simulation, the marginal location is \mu=X\beta, with coefficients named mean, mean1, and so on in the order of the columns of X. If X=NULL, the model is intercept-only. A vector param$mean supplies a known location value at each observation and cannot be combined with X.

Value

Returns an object of class GeoSimCopula. An object of class GeoSimCopula is a list containing at most the following components:

bivariate	Always FALSE; bivariate correlation models are rejected.
coordx	A d-dimensional vector of spatial coordinates;
coordy	A d-dimensional vector of spatial coordinates;
coordt	A t-dimensional vector of temporal coordinates;
coordx_dyn	A list of dynamical (in time) spatial coordinates;
corrmodel	The correlation model; see GeoCovmatrix.
data	The simulated data. Dynamic space-time output is a list with one vector per time, aligned with coordx_dyn; fixed-location space-time output preserves the matrix layout of GeoSim.
distance	The type of spatial distance;
method	The method of simulation
model	The type of RF, see GeoFit.
n	The number of trial for Binomial random fields;the number of successes in a negative Binomial random fields;
numcoord	The number of spatial coordinates;
numtime	The number the temporal realisations of the RF;
param	A list of the parameters
radius	The radius of the sphere if coordinates are passed in lon/lat format;
randseed	The seed used for the random simulation;
spacetime	TRUE if spatio-temporal and FALSE if spatial RF;
copula	The type of copula

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

Bevilacqua M., Alvarado E., Caamano C. (2024) A flexible Clayton-like spatial copula with application to bounded support data. Journal of Multivariate Analysis 201

Examples

library(GeoModels)

################################################################
###
### Example: Simulation of a reparametrized Beta RF
### for beta regression
### with Gaussian and Clayton Copula 
### with underlying Wendland correlation.
###
###############################################################
set.seed(261)
NN=1400
x <- runif(NN);y <- runif(NN)
coords=cbind(x,y)

corrmodel="GenWend"
X=cbind(rep(1,NN),runif(NN))

NuisParam("Beta2",num_betas=2,copula="Gaussian")
CorrParam("GenWend")
#### Gaussian copula
param=list(smooth=0,power2=4, min=0,max=1,
 mean=0.1,mean1=0.1,scale=0.3,nugget=0,shape=5)

data <- GeoSimCopula(coordx=coords, corrmodel=corrmodel, model="Beta2",param=param,
 copula="Gaussian",sparse=TRUE,X=X)$data

if (requireNamespace("fields", quietly = TRUE)) fields::quilt.plot(coords,data)


#### Clayton copula
NuisParam("Beta2",num_betas=2,copula="Clayton")
CorrParam("GenWend")
param=list(smooth=0,power2=4, min=0,max=1,
 mean=0.2,mean1=0.1,scale=0.3,nugget=0,shape=6,nu=4)
data1 <- GeoSimCopula(coordx=coords, corrmodel=corrmodel, model="Beta2",param=param,
 copula="Clayton",sparse=TRUE,X=X)$data

hist(data1,freq=FALSE)
if (requireNamespace("fields", quietly = TRUE)) fields::quilt.plot(coords,data1)

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