Simulate a spatial normal (Gaussian) random variable

Simulate a spatial normal (Gaussian) random variable with a specific mean and covariance structure.

Usage

sprnorm(
  spcov_params,
  mean = 0,
  samples = 1,
  data,
  randcov_params,
  partition_factor,
  ...
)

# S3 method for class 'exponential'
sprnorm(
  spcov_params,
  mean = 0,
  samples = 1,
  data,
  randcov_params,
  partition_factor,
  xcoord,
  ycoord,
  ...
)

# S3 method for class 'none'
sprnorm(
  spcov_params,
  mean = 0,
  samples = 1,
  data,
  randcov_params,
  partition_factor,
  ...
)

# S3 method for class 'car'
sprnorm(
  spcov_params,
  mean = 0,
  samples = 1,
  data,
  randcov_params,
  partition_factor,
  W,
  row_st = TRUE,
  M,
  ...
)

Arguments

spcov_params: An spcov_params() object.
mean: A numeric vector representing the mean. mean must have length 1 (in which case it is recycled) or length equal to the number of rows in data. The default is 0.
samples: The number of independent samples to generate. The default is 1.
data: A data frame or sf object containing spatial information.
randcov_params: A randcov_params() object.
partition_factor: A formula indicating the partition factor.
...: Other arguments. Not used (needed for generic consistency).
xcoord: Name of the column in data representing the x-coordinate. Can be quoted or unquoted. Not required if data are an sf object.
ycoord: Name of the column in data representing the y-coordinate. Can be quoted or unquoted. Not required if data are an sf object.
W: Weight matrix specifying the neighboring structure used for car and sar models. Not required if data are an sf polygon object and W should be calculated internally (using queen contiguity).
row_st: A logical indicating whether row standardization be performed on W. The default is TRUE.
M: M matrix satisfying the car symmetry condition. The car symmetry condition states that \((I - range * W)^{-1}M\) is symmetric, where \(I\) is an identity matrix, \(range\) is a constant that controls the spatial dependence, W is the weights matrix, and \(^{-1}\) represents the inverse operator. M is required for car models when W is provided and row_st is FALSE. When M, is required, the default is the identity matrix.

Value

If samples is 1, a vector of random variables for each row of data is returned. If samples is greater than one, a matrix of random variables is returned, where the rows correspond to each row of data and the columns correspond to independent samples.

Details

Random variables are simulated via the product of the covariance matrix's square (Cholesky) root and independent standard normal random variables with mean 0 and variance 1. Computing the square root is a significant computational burden and likely unfeasible for sample sizes much past 10,000. Because this square root only needs to be computed once, however, it is nearly the sample computational cost to call sprnorm() for any value of samples.

Only methods for the exponential, none, and car covariance functions are documented here, but methods exist for all other spatial covariance functions defined in spcov_initial(). Syntax for the exponential method is the same as syntax for spherical, gaussian, triangular, circular, cubic, pentaspherical, cosine, wave, jbessel, gravity, rquad, magnetic, matern, cauchy, and pexponential methods. Syntax for the car method is the same as syntax for the sar method. The extra parameter for car and sar models is ignored when all observations have neighbors.

Examples

spcov_params_val <- spcov_params("exponential", de = 1, ie = 1, range = 1)
sprnorm(spcov_params_val, data = caribou, xcoord = x, ycoord = y)
#>  [1] -0.06980081 -0.68020627 -0.56886464 -0.26815128 -1.01535060  2.33551655
#>  [7] -0.44967057 -1.92889316 -1.63504814 -2.32871896  1.93289443  1.85437674
#> [13] -1.55763216 -1.20003818 -2.16023906 -0.28367420  1.60990348  0.30700052
#> [19] -1.05285940 -3.05679064 -0.19894495  4.34957221  0.15534697 -0.78244287
#> [25] -2.39471474  2.95632391  0.94821654  0.43928418 -1.57004380  0.89329132
sprnorm(spcov_params_val, mean = 1:30, samples = 5, data = caribou, xcoord = x, ycoord = y)
#>            [,1]       [,2]      [,3]      [,4]       [,5]
#>  [1,]  2.078090  1.3147187  1.441157  2.124264  0.5462837
#>  [2,]  2.840552  0.2225271  1.685848  2.586706  4.0892017
#>  [3,]  6.115456  4.5206299  5.159078  4.402004  1.1861009
#>  [4,]  2.783873  3.1979665  5.672752  3.679482  2.3481716
#>  [5,]  5.190463  3.6040938  6.630187  5.375776  4.4039315
#>  [6,]  8.025303  6.6460794  4.857592  5.557943  5.1827048
#>  [7,]  4.890117  7.3494126  6.591105  9.463003  7.6571161
#>  [8,]  9.603237  6.6343564  6.693872  9.185765  8.4138987
#>  [9,]  9.388534  7.8719517  8.660903  8.534503  7.9407269
#> [10,] 10.928985  7.4975513 11.436805  9.949048 10.3371819
#> [11,] 12.374689  8.9616718 12.231921 10.300568 10.2829292
#> [12,] 12.195869 11.5621364 12.928044 14.589577 13.3807373
#> [13,] 15.608122 12.8850120 13.926398 15.352861 12.4245765
#> [14,] 14.198620 13.0868805 14.133952 12.762481 11.3430095
#> [15,] 14.799059 15.0785857 13.979685 14.438695 13.1587026
#> [16,] 16.307745 17.8768995 12.218104 13.984914 13.8725352
#> [17,] 14.574256 15.6592328 18.465883 17.309888 18.2788915
#> [18,] 16.288000 17.9217261 18.870794 16.868634 17.5694213
#> [19,] 17.119627 19.3590533 17.479299 19.474120 19.7600068
#> [20,] 18.946611 20.4888340 20.398798 21.530128 18.7400504
#> [21,] 21.124212 20.0470900 20.281633 18.049198 20.0074259
#> [22,] 21.046118 22.6511808 21.296460 20.258446 22.6361451
#> [23,] 21.080317 23.1293510 23.742695 24.728682 25.4201797
#> [24,] 21.584540 24.3182510 22.871521 23.912125 26.0899007
#> [25,] 24.717717 24.4614129 25.786639 23.123184 24.4012597
#> [26,] 26.026392 27.1471721 26.111566 23.031574 27.7883921
#> [27,] 27.592915 31.8283411 26.266823 26.528206 26.4244062
#> [28,] 30.205454 30.5862874 27.328975 28.569603 27.8954187
#> [29,] 30.003495 29.5748153 30.263001 30.023616 29.4048819
#> [30,] 28.712228 29.4849548 31.163288 30.137724 32.0432562