R: Setting control arguments

RFoptions {RandomFields} | R Documentation

## Setting control arguments

### Description

`RFoptions` sets and returns control arguments for the analysis and the simulation of random fields. It expands the functionality of RFoptions.

### Usage

     RFoptions(...)

### Arguments

`...` | arguments in `tag = value` form, or a list of tagged values.

### Details

The subsections below comment on
1. `general`: General options
2. `br`: Options for Brown-Resnick Fields
3. `circulant`: Options for circulant embedding methods `RPcirculant`
4. `coords`: Options for coordinates and units, see coordinate systems
5. `direct`: Options for simulating by simple matrix decomposition
6. `distr`: Options for distributions, in particular `RRrectangular`
7. `empvario`: Options for calculating the empirical variogram
8. `fit`: Options for `RFfit`, `RFratiotest`, and `RFcrossvalidate`
9. `gauss`: Options for simulating Gaussian random fields
10. `graphics`: Options for graphical output
11. `gui`: Options for `RFgui`
12. `hyper`: Options for simulating hyperplane tessellations
13. `krige`: Options for Kriging
14. `maxstable`: Options for simulating max-stable random fields
15. `mpp`: Options for the random coins (shot noise) methods
16. `nugget`: Options for the nugget effect
17. `registers`: Register numbers
18. `sequ`: Options for the sequential method
19. `solve`: Options for solving linear systems
20. `special`: Options for some special methods
21. `spectral`: Options for the spectral (turning bands) method
22. `tbm`: Options for the turning bands method
23. `internal`: Internal

1. General options

`allowdistanceZero`

  boolean. Only used in `RFinterpolate` and in `RFfit`. If true, then multiple observations or identical locations are allowed within a single data set. In this case, the coordinates are slightly scattered, so that the points have some tiny distances.

  Default: `FALSE`.

`cPrintlevel`

  `cPrintlevel` is automatically set to `printlevel` when `printlevel` is changed. Standard users will never use a value higher than 3.

  0 : no messages
  1 : messages and warnings when the user's input looks odd
  2 : messages (and internal errors) documenting the choice of the simulation method
  3 : further user relevant informations
  4 : information on recursive function calls
  5 : function flow information of central functions
  6 : errors that are internally treated
  7 : details on building up the covariance structure
  8 : details on taking the square root of the covariance matrix
  9 : details on intermediate calculations
  10 : further details on intermediate calculations

  Note that `printlevel` works on the R level whereas `cPrintlevel` works on the C level.

  Default: 1

`detailed_output`

  logical. if `TRUE` some function, e.g. `RFcrossvalidate` will return additional information.

`every`

  integer. if greater than zero, then every `every`th iteration is printed if simulated by TBM or random coin method. The value zero means that nothing is printed.

  Default: `0`

`exactness`

  logical or NA. Currently only used when simulating Gaussian random fields.

  - `TRUE`: `RPcoins`, `RPhyperplane`, `RPsequential`, `RPspectral` and `RPtbm` and approximative circulant embedding are excluded. If the circulant embedding method is considered as badly behaved, then the matrix decomposition methods are preferred.

  - `FALSE`: all the methods are allowed. If the circulant embedding method is considered as badly behaved or the number of points to be simulated is large, the turning bands methods are rather preferred.

  - `NA`: Similar to `FALSE`, but some inexact algorithms get less preference.

  Default: `NA` .

`expected_number_simu`

  positive integer which is usally set internally as the value of the argument `n` in `RFsimulate`. The argument `expected_number_simu` should be set only by an advanced users and only if `RFsimulate` will be called with argument `n` alone.

`gridtolerance`

  used in `RFsimulate` to see if the coordinates build a grid for x, y, z, T-values. This argument is also used in case of conditional simulation where the data locations might ly on a grid.

  Default: `1e-6`

asList

  logical. Lists of arguments are treated slightly different from non-lists. If `asList=FALSE` they are treated the same way as non-lists. This options being set to `FALSE` after calling `RFoptions` it should be set as first element of a list.

  Default: `TRUE`

`modus_operandi`

  character. One of the values `"careless"`, `"sloppy"`, `"easygoing"`, `"normal"`, `"precise"`, `"pedantic"`, `"neurotic"` . This argument is in an experimental stage and its definition and effects will change very likely in near future. This argument sets a lot of argument at once related to estimation and simulation. `"careless"` prefers rather fast algorithms, but the results might be very rough approximations. By way of contrast, `"neurotic"` will try very hard to return exact result at the cost of hugh computing times.

  Default: `"normal"`

`na_rm_lines`

  logical. If `TRUE` then a line of the data that contains a `NA` value is deleted. Otherwise it is tried to deal with the `NA` value at higher costs of computing time.

  Default: `FALSE`.

`output`

  character. one of the values `"sp"` (if and only if `spConform=TRUE`), `"RandomFields"` (if and only if `spConform=FALSE`), `"geoR"`.

  The output mode `geoR` currently adds some attributes such as the call of the function.

  NOTE: `output` is in an experimental stage, whose effects might change in future. Currently, `output` changes the values of `reportcoord`, `returncall` and `spConform`.

`pch`

  character. `RFfit`: shown before evaluating any method; if `pch!=""` then one or two additional steps in the MLE methods are marked by “+” and “#”.

  Simulation:

  The character is printed after each performed simulation if more than one simulation is performed at once. If `pch='!'` then an absolute counter is shown instead of the character. If `pch='%'` then a counter of percentages is shown instead of the character. Note that also ‘^H’s are printed in the last two cases, which may have undesirable interactions with some few other R functions, e.g. `Sweave`.

  Default: `'*'`.

`practicalrange`

  logical or integer. If not `FALSE` the range of primitive covariance functions is adjusted so that cov(1) is zero for models with finite range. (Operators are too complex to be adjusted; for anisotropic covariance the practical range is not well defined.)

  The value of cov(1) is about 0.05 (for `scale=1`) for models without range. See `RMmodel` or type
  `RFgetModelNames(type="positive definite", domain="single variable", isotropy="isotropic", operator=FALSE, vdim=1)`
  for the list of primitive models.

  - `FALSE` : the practical range ajustment is not used.

  - `TRUE` : `practicalrange` is applicable only if the value is known exactly, or, at least, can be approximated by a closed formula.

  - `2` : if the practical range is not known exactly it is approximated numerically.

  Default: `FALSE` .

`printlevel`

  If `printlevel`<=0 there is not any output on the screen. The higher the number the more tracing information is given. Standard users will never use a value higher than 3.

  0 : no messages
  1 : important (error) messages and warnings
  2 : less important messages
  3 : details, but still for the user
  4 : recursive call tracing (only used within `RFfit`)
  5 : function flow information of large functions
  6 : errors that are internally treated
  7 : details on intermediate calculations
  8 : further details on intermediate calculations

  Default: 1

reportcoord

  character. Current values are `"always"`, `"important"`, `"warn"`, `"never"`,

  Both `"warn"` and `"important"` have any effect only if the coordinate system is changed internally. In this case `"warn"` yields a displayed warning message whereas `"important"` adds an attribute to the result as in the case `"always"`.

  If `"always"` or `"important"` the reports are added as attribute to the results. Note that in this case the class of the result may change (e.g. from `"numeric"` to `"atomic"`).

  Default: `"warn"`

returncall

  logical. If `TRUE` then the call is returned as an attribute

  Default: `TRUE`

seed

  integer. If `NULL` or `NA` `set.seed` is not called. Otherwise, `set.seed(seed)` is set before simulations are performed, e.g. by `RFsimulate` or `RFdistr`.

  If the argument is set locally, i.e., within a function, it has the usual local effect. If it is set globally, i.e. by `RFoptions` the `seed` is fixed for all subsequent calls.

  If the number of simulations `n` is greater than one and if `RFoptions(seed=seed)` is set, the ith simulation is started with the seed ‘`seed`+i-1’.

  Note also that `RFratiotest` has its own argument `seed` with a slightly different meaning.

`set`

  integer. Certain models (e.g. `RMfixcov` and `RMcovariate`) allow for lists as arguments. `set` selects a certain list element. If necessary the list is recycled.

`spConform`

  logical. `spConform=TRUE` might be used by a standard user as this allows the comfortable use of `plot`, for instance, while `spConform=FALSE` is much faster and and consumes much less memory, hence might be used by programmers or advanced users.

  Details: if `spConform=TRUE` then `RFsimulate` and many other functions return an `sp`-object (which is an S4 object). Otherwise, matrices or lists are returned as defined in RandomFields 2.0, see the manuals for the specific functions. Frequently, the latter have now a class attribute to make the output nicer.

  Note: for large data sets (to be generated), `spConform=TRUE` should not be used.

  See also `output`.

  Default: `TRUE`

`skipchecks`

  logical. If `TRUE`, several checks whether the given parameter values and the dimension are within the allowed range is skipped. Do not change the value of this variable except you really know what you do.

  Default: `FALSE` $

`storing`

  Logical. If `FALSE` then the intermediate results are destroyed after the simulation of the random field(s) or if an error had occured. If `storing=TRUE`, then additional simulations can be performed by calling `RFsimulate` with at most the argument `n`. This call can then be much faster, but the a rather large amount of memory could be kept.

  When `storing` turned from `TRUE` to `FALSE` by global call then all registers are deleted. Advanced: With `RFoptions(storing=list(FALSE, register, model_register))` single registers can be deleted.

  Default: `FALSE`

`Ttriple`

  Logical or `NA`. If `TRUE`, then triple for the time argument `T` is expected, containing start, step (by), length. If `FALSE` a sequence on a grid is expected. If `NA` then the decision is automatic, but will lead to an error if ambiguous.

`vdim_close_together`

  logical. Used especially in functions that create covariance matrices. If the model is multivariate, then two ways of ordering the matrix exist. To consider first all variables at a certain location (`vdim_close_together=TRUE`) or to consider first all locations keeping the variable fixed (`vdim_close_together=FALSE`). Note that several simulation methods rely on the value `FALSE`, so that these methods will not work anymore if `vdim_close_together=TRUE`.

  Default: `FALSE`.

2. Options for Brown-Resnick Fields

`corr_factorr`

  to do

`deltaAM`

  to do

`maxtrendmem`

  integer; the maximal number of trends for shifted locations that may be stored at the same time when simulating BR processes via `RPbrshifted`; if `maxtrendmem` is large, multiple trend evaluation may be avoided.

  Default: `1e8` .

`meshsize`

  positive; width of the grid on which the shape functions in the M3 representation of BR processes are simulated; only used for simulation of BR processes via `RPbrmixed`.

  Default: `0.1` .

`optim_mixed`

  `0, 1, 2`; only used for simulation of BR processes via `RPbrmixed`.
  If `optim_mixed=0`, the arguments `lambda` and `areamat` of `RPbrshifted` are used for the simulation.
  If `optim_mixed=1`, `lambda` is estimated for `areamat=1`.
  If `optim_mixed=2`, `areamat` is optimized and `lambda` is estimated.

  Default: `1` .

`optim_mixed_maxpoints`

  positive integer; only used for simulation of BR processes via `RPbrmixed` with `optim_mixed>0`. Maximal number of Poisson points used for the optimization of `areamat` and the estimation of `lambda`.

  Default: `10000` .

`optim_mixed_tol`

  value in [0,1]; only used for simulation of BR processes via `RPbrmixed` with `optim_mixed=2`. In this case, `areamat` is optimized under the constraint that the probability of drawing the shape function incorrectly is bounded by `optim_mixed_tol` (cf. Oesting et al., 2012).

  Default: `0.01` .

`variobound`

  positive; the shape functions in the mixed moving maxima representation are cut off where the variogram belonging to `phi` exceeds `variobound`.

  Default: `8.0` .

`vertnumber`

  positive integer; for an efficient simulation of the shape functions in the M3 representation of BR processes, the component E from of the domain [x_0, Inf] x E of the underlying Poisson point process is sub-dividedinto cubes (cf. Oesting et al., 2012); `vertical` is the number of vertical breaks of E; only used for simulation of BR processes via `RPbrmixed` with `optim_mixed=2`.

  Default: `7` .

3. `circulant`: Options for circulant embedding methods, cf. `RPcirculant`
These options influence the standard circulant embedding method, cutoff circulant embedding intrinsic circulant embedding. It can also influence `RPtbm` if the line is simulated with any circulant embedding method.

`approx_maxgrid`

  See `RPcirculant`

`approx_step`

  See `RPcirculant`

`dependent`

  See `RPcirculant`

`force`

  See `RPcirculant`

`maxGB`

  See `RPcirculant`

`maxmem`

  See `RPcirculant`

`mmin`

  See `RPcirculant`

`strategy`

  See `RPcirculant`

`tolIm`

  See `RPcirculant`

`tolRe`

  See `RPcirculant`

`trials`

  See `RPcirculant`

`useprimes`

  See `RPcirculant`

4. `coords`: Options for coordinates and units

`coord_system`

  character. See coordinate systems

`coordunits`

  See coordinate systems

`coordnames`

  See coordinate systems

`new_coord_system`

  See coordinate systems

`new_coordunits`

  See coordinate systems

`polar_coord`

  See coordinate systems

`varnames`

  See coordinate systems

`varunits`

  See coordinate systems

`xyz_notation`

  See coordinate systems

`zenit`

  See coordinate systems

5. `direct`: Options for simulating by simple matrix decomposition

`max_variab`

  See `RPdirect`

6. `distr`: Options for distributions, in particular `RRrectangular`

`innermin`

  Default value to simulate from the `RRrectangular` distribution. The minimal length of the interval where the Taylor expansion shall be valid.

  Default: `1e-20` .

`maxit`

  Default value to simulate from the `RRrectangular` distribution.

  The number of iterative steps where the the constant of the Taylor development is increased, to find an upper bound for the given function.

  Default: `20` .

`maxsteps`

  Default value to simulate from the `RRrectangular` distribution.

  `maxsteps` is usually the number of steps in the middle part of the approximation. From this value and the length between the determined endpoints for the approximation at the origin and in the tail, the step length is calculated. If the step length is less than `minsteplen` the number of steps is reduced.

  Default: `1000` .

`mcmc_n`

  In case of the use of MCMC it leaves out n-1 member of the Markov chain bevor the n member is returned. See also maxsteps.

  Default: `15` .

`minsteplen`

  Default value to simulate from the `RRrectangular` distribution. The minimal step length for the middle part of approximation, which is a step function,

  Default: `0` (i.e. not used as a criterion.)

`outermax`

  Default value to simulate from the `RRrectangular` distribution. The largest possible endpoint for the middle part that approximates the function by a step function. See also `innermax`.

  Default: 20.

`parts`

  Default value to simulate from the `RRrectangular` distribution.

  `parts` determines the number of tests that are performed to check whether a proposed power function is an upper bound for the given function, at the origin and the tail.

  Default: `8` .

`repetitions`

  Minimal number of realisations to determine a quantity of the distribution by MCMC. E.g. to determine the integral value c in the paper of Oesting, Schlather, Zhou.

  Default: 1000.

`safety`

  Default value to simulate from the `RRrectangular` distribution.

  First, at the origin, the first power function of the Taylor expansion is taken as potential upper function. The constant of the power function are increased by factor 1 + `safety` and the exponent of the function similarly decreased. A number of test evaluations is performed to check whether this modified function is indeed a upper bound. If not, the considered interval at the origin is reduced iteratively, the constants of the power function further increased and the exponent decreased. If `maxit` iteration have been performed without success, the search for an upper bound fails. The search at the origin also fails if the interval around the origin has become less than `innermin`.

  Similar procedure is performed for the tail.

  Default: `0.08` .

7. `empvario`: Options for calculating the empirical variogram

`fft`

  Logical. Determines whether FFT should be used for data on a grid Default: `TRUE`.

`phi0`

  numeric. In case of anisotropic fields directional cones are considered. The argument `phi0` determines the starting angle.

  Default: `0`.

`pseudovariogram`

  logical. Only in the multivariate case. Whether the pseudovariogram or the crossvariogram should be calculated.

  Default: `FALSE`.

`theta0`

  numeric. In case of anisotropic fields directional cones are considered. The argument `theta0` determines one of the boundaries, hence all boundaries for a given fixed number of cones. The argument `theta0` determines the starting value of the second anglue in polar coordinate representation in 3 dimensions.

  Default: `0`.

`tol0`

  numeric. Estimated values of the empirical variogram below `tol0` times the grid step in the third dimension are considered to be zero. Hence the respective values are set to zero.

  Default: `1e-13`.

8. `fit`: Options for `RFfit`, `RFratiotest`, and `RFcrossvalidate`

`algorithm`

  See RFfitOptimiser.

  Default: `NULL`

`approximate_functioncalls`

  In case the parameter vector is too close to the given bounds, the ML target function is evaluated on a grid to get a new initial value for the ML estimation. The number of points of the grid is approximately `approximate_functioncalls`.

  Default: `50`

`boxcox_lb`

  lower bound for the Box-Cox transformation

  Default: `-10`.

`boxcox_ub`

  upper bound for the Box-Cox transformation

  Default: `10`.

`bin_dist_factor`

  numeric. The empirical variogram is calculated up the distance `bin_dist_factor` times (maximum distance among any pair of locations)

  Default: `0.5`.

`bins`

  vector of explicit boundaries for the bins or the number of bins for the empirical variogram (used in the LSQ target function, which is described at the beginning of the Details). Note that for anisotropic models, the value of `bins` might be enlarged.

  Default: `20`.

`critical`

  logical or signed integer.

  If `critical=FALSE` and if the result of any maximum likelihood method is on a borderline, then the optimisation is redone in a modified way (which takes about double extra time)

  If `critical=TRUE` and if the result of any maximum likelihood method is on a borderline, then a kind of profile likelihood optimization is done (which takes about 10 times extra time)

  If `critical>=2` then a kind of profile likelihood optimization is always done (which takes about `n_crit` times extra time) for an automatically chosen selection of the model parameters.

  If `critical>=3` then a kind of profile likelihood optimization is always done (which takes about `n_crit` times extra time) for all the parameters.

  If `critical<0` then none of the refined methods are performed.

  Default: `TRUE`.

`cross_refit`

  logical. For each of the subset of the cross-validation method the parameters have to be fitted to the given model. If `cross_refit` is `TRUE`, this is done, but takes a huge amount of time. If `FALSE`, the model is fitted only once to the data and the value at each point is predicted with the same model given the values of the other points.

  Default: `FALSE`.

estimate_variance

  see `RFlikelihood`.

factr, factr_recall

  See the argument `control` in optim. `factr_recall` is used for intermediate calculations.

likelihood

  character – not programmed yet. types of likelihood are `"auto"`, `"full"`, `"composite"`, `"tesselation"`;

  Default: `"auto"`

`lowerbound_scale_factor`

  The lower bound for the scale is determined as

  (minimum distance between different pairs of points) /
  `lowerbound_scale_factor`.

  Default: `3`.

`lowerbound_scale_ls_factor`

  For the LSQ target function a different lower bound for the scale is used. It is determined as

  (minimum distance between different pairs of points) /
  `lowerbound_scale_ls_factor`.

  Default: `5`.

`lowerbound_var_factor`

  The lower bound for the nugget and the variance is determined as var(`data`) / `lowerbound_var_factor`. If a standard model definition is given and either the nugget or the variance is fixed, the parameter to be estimated must also be greater than `lowerbound_sill`.

  Default: `10000`.

`maxmixedvar`

  upper bound for variance in a mixed model; so, the covariance model for mixed model part might be calibrated appropriately

`max_neighbours`

  integer. Maximum number of locations (with depending values) that are allowed.

  Default: `5000`.

`minbounddistance`

  If any value of the parameter vector returned from the ML estimation is closer than `minbounddistance` to any of the bounds or if any value has a relative distance smaller than `minboundreldist`, then it is assumed that the MLE algorithm has dropped into a local minimum, and it will be continued with evaluating the ML target function on a grid, cf. the beginning paragraphs of the Details.

  Default: `0.001`.

`minboundreldist`

  relative distance to the bounds below which a part of the algorithm is considered as having failed. See `minbounddistance`.

  Default: `0.02`.

`min_diag`

  Minimal value of any estimated diagonal matrix element.

  Default: `1e-7`.

`n_crit`

  integer. The approximate profiles that are considered.

  Default: `10`.

`nphi`

  scalar or vector of 2 components. If it is a vector then the first component gives the first angle of the xy plane and the second one gives the number of directions on the half circle. If scalar then the first angle is assumed to be zero. Note that a good estimation of the variogramm by LSQ with a anisotropic model a large value for `ntheta` might be needed (about 20).

  Default: `1`.

`ntheta`

  scalar or vector of 2 components. If it is a vector then the first component gives the first angle in the third direction and the second one gives the number of directions on the half circle. If scalar then the first angle is assumed to be zero.

  Note that a good estimation of the variogramm by LSQ with a anisotropic model a large value for `ntheta` might be needed (about 20).

  Default: `1`.

`ntime`

  scalar or vector of 2 components. if `ntimes` is a vector, then the first component are the maximum time distance (in units of the grid length `T[3]`) and the second component gives the step size (in units of the grid length `T[3]`). If scalar then the step size is assumed to 1 (in units of the grid length `T[3]`).

  Default: `20`.

`only_users`

  boolean. If true then only `users_guess` is used as a starting point for the fitting algorithms

  Default: `FALSE`.

`optimiser`

  See RFfitOptimiser.

  Default: `"optim"`.

pgtol, pgtol_recall

  See the argument `control` in optim. `pgtol_recall` is used for intermediate calculations.

`refine_onborder`

  logical. If `TRUE` and an estimated parameter of the model is close to the boundary, a second search for the optimum is started.

  Default: `TRUE`

`minmixedvar`

  lower bound for variance in a mixed model; so, the covariance model for mixed model part might be calibrated appropriately

  Default: 1/1000

`ratiotest_approx`

  logical. if `TRUE` the approximative formula that twice the difference of the likelihoods follow about a χ^2 distribution is used. The parameter of freedom equals the number of parameters to be estimated for the covariance function, including those for the covariates.

  Default: `TRUE`

`reoptimise`

  logical. If `TRUE && !only_users` then at a very last step, the optimisation is redone with currently best parameters and likelihood as scale parameter for `optim`.

  Default: `TRUE`.

`scale_max_relative_factor`

  If the initial scale value for the ML estimation obtained by the LSQ target function is less than (minimum distance between different pairs of points) / `scale_max_relative_factor`

  a warning is given that probably a nugget effect is present. Note: if `scale_max_relative_factor` is greater than `lowerbound_scale_ls_factor` then no warning is given as the scale has the lower bound (minimum distance between different pairs of points) / `lowerbound_scale_ls_factor`.

  Default: `1000`

`scale_ratio`

  `RFfit` uses `parscale` and `fnscale` in the calls of `optim`. As these arguments should have the magnitude of the estimated values, `RFfit` checks this by calculating the absolute log ratios. If they are larger than `scale_ratio`, `parscale` and `fnscale` are reset and the optimisation is redone.

  Default: `0.1`.

`shortnamelength`

  The names of the variables in the returned table are abbreviated by taking the first `shortnamelength` letters.

  Default: `4`.

`smalldataset`

  If the number of locations is considered as small, then some more data are kept in the storage to accelerate the estimation algorithm.

  Default: `2000`.

`split`

  integer. If the number of parameters to be numerically optimised is larger than or equal to `split` then `RFfit` checks whether a space-time covariance model or a multivariate covariance model can be split into components, so that certain parameters can be estimated separately.

  Default: `4`.

`cliquesize`

  integer. `RFfit` tries to split the data set into parts of size splitn_neighbours[2] or less, but never more than `splitn_neighbours[3]` and never less than splitn_neighbours[1].

  Default: `c(200, 1000, 3000)`.

`splitfactor_neighbours`

  The total number of neighbouring boxes in each direction 1 + 2\code{splitfactor}, including the current box itself.

  Default: `2`.

`split_refined`

  logical. If `TRUE` then also submodels are fitted if splitted. This takes more time, but `anova` and `RFratiotest`, for instance, will give additional information.

  Default: `TRUE`.

`upperbound_scale_factor`

  The upper bound for the scale is determined as

  `upperbound_scale_factor` * (maximum distance between all pairs of points).

  Default: `3`.

`upperbound_var_factor`

  The upper bound for the variance and the nugget is determined as `upperbound_var_factor` * var(`data`)

  Default: `10`.

`use_naturalscaling`

  logical. Only used if model is given in standard (simple) way. If `TRUE` then internally, rescaled covariance functions will be used for which cov(1)~=0.05. `use_naturalscaling` has the advantage that `scale` and the form parameters of the model get ‘orthogonal’, but `use_naturalscaling` does not work for all models.

  Note that this argument does not influence the output of `RFfit`: the parameter vector returned by `RFfit` refers always to the standard covariance model as given in `RMmodel`. (In contrast to `practicalrange` in `RFoptions`.)
  Advantages if `use_naturalscaling=TRUE`:

  - `scale` and the shape parameter of a parameterised covariance model can be estimated better if they are estimated simultaneously.

  - The estimated bounds calculated by means of `upperbound_scale_factor` and `lowerbound_scale_factor`, etc. might be more realistic.

  - in case of anisotropic models, the inverse of the elements of the anisotropy matrix should be in the above bounds.

  Disadvantages if `use_naturalscaling=TRUE`:

  - For some covariance models with additional parameters, the rescaling factor has to be determined numerically. Then, more time is needed to perform `RFfit`.

  Default: `TRUE`.

9. `gauss`: Options for simulating Gaussian random fields

`approx_zero`

  Value below which a correlation is considered to be essentially zero. This argument is used to determine the practical range of covariance function with non-compact support.

  Default: `0.05`

`boxcox`

  real vector of one or two components. If the first component is `Inf` then no transformation is performed. Otherwise the BoxCox transformation is performed. Note that Box Cox only works in a Gaussian framework. Note further that either `boxcox` or `loggauss` may be given.

  Default `c(Inf, 0)`

`direct_bestvar`

  integer. When searching for an appropriate simuation method the matrix decomposition method (`method="direct"`) is preferred if the number of variables is less than or equal to `direct_bestvariables`.

  Default is `1200`.

`loggauss`

  logical. Whether a log-Gauss random fields should be returned. See also `boxcox` for a generalisation.

`paired`

  (“Antithetic pairs”.) Logical. If `TRUE` then the second half of the simulations is logical. If `TRUE` then the second half of the simulations is obtained by only changing the signs of all the standard Gaussian random variables, on which the first half of the simulations is based. Default is `FALSE`.

`stationary_only`

  See `RPgauss`

10. `graphics`: Options for graphical output

`always_close_device`

  logical. If `FALSE` the current device is kept as it is; otherwise the current device is closed before the next device is opened. If `NA` it closes the preceding device if the opened device is pdf or jpeg.

  Default: `NA`.

`always_open_device`

  logical. If `TRUE` a new graphical window is opened for every `plot` if a standard graphical output is used, trying to respect the aspect ratios for the plots. The devices pdf and jpeg are always opened.

  If `NA` then the value is set to `interactive()`.

  Default: `TRUE`.

`close_screen`

  logical; only relevant if `split_screen = TRUE` and `always_close_screen = FALSE`. If `FALSE` the windows opened by `split.screen` are left open.

  Default: `TRUE`.

`file`character; only relevant if `split_screen = TRUE`. argument `file` in `pdf` If `""` then no internal naming is performed.

Default: `""`.

`filenumber`

  integer; only relevant if `split_screen = TRUE`. Starting number of the file if `onefile=FALSE`. It is set to 0 whenever `file` is changed and `onefile=FALSE`.

  Default 0.

`grPrintlevel`

  integer values 0, 1, 2; only relevant when simulations are plotted. The higher the more text is shown in the plot.

  Default: `1`.

`height`

  real number; only relevant if a new device is opened, see `alwyas_open_screen`.

  - `height=NA` or `height` is not positive: no device is opened.

  - `width = NA` If `height` is greater than zero then it gives the height of a single figure in a plot created by RandomFields; See also `close_screen`.

    If plots with multiple figures are shown, the height and width of the plot will be increased by a factor up the ones given by `increase_upto`.

    The width is calculated so that the aspect ratio is correct.

  - `width` not `NA` `height` and `width` give the size of the whole window.

  Default: `6`.

`increase_upto`

  See `height`.

  Default: `c(3,4)`.

`split_screen`

  logical. If `TRUE` `split.screen` is used to split the screen. Otherwise `par(mfcol)`. When using `split_screen` then the figures tend to be fancier.

  Default: `TRUE`.

`onefile`

  logical; only relevant if `split_screen = TRUE`. About the behaviour of argument `onefile` in `pdf`

  Default: `FALSE`.

`width`

  real number or NA; only relevant if `always_open_screen=TRUE`. See `height` for details.

  Default: `NA`.

11. `gui`: Options for c`RFgui`

`alwaysSimulate`

  logical. If `TRUE` then a new random field is simulated whenever a parameter is changed. Otherwise only the covariance function or the variogram is re-plotted; simulations are performed only when the correponding button is pressed.

  Default: `TRUE`.

`simu_method`

  `"RPcirculant"`, `"RPcutoff"`, `"RPintrinsic"`, `"RPtbm"`, `"RPspectral"`, `"RPdirect"`, `"RPsequential"`, `"RPaverage"`, `"RPnugget"`, `"RPcoins"`, `"RPhyperplane"`, `"RPspecific"`, `"any method"`.

  Default: `"RPcirculant"`.

`size`

  vector of 2 components. Grid size of the simulated stochastic processes. The two components of the vector correspond to one-dimensional and two-dimensional processes, respectively.

  Default: `c(1024, 64)`.

12. `hyper`: Options for simulating hyperplane tessellations

`mar_distr`

  integer. This argument should not be changed yet.

  It codes the marginal distribution used in the simulation:

  0 : uniform distribution
  1 : Frechet distribution with form argument `mar.param`
  2 : Bernoulli distribution (Binomial with n=1) with argument `mar.param`

  Default: `0` .

`mar_param`

  Argument used for the marginal distribution. The argument should not be changed yet.

  Default: `NA` .

`maxlines`

  integer. Maximum number of allowed lines.

  Default: `1000` .

`superpos`

  integer. number of superposed hyperplane tessellations.

  Default: `300` .

13. `krige`: Options for Kriging

`cholesky_R`

  obsolete

`fillall`

  logical value for imputing. If true all the components are estimated whether they are `NA` or not.

  Default: `TRUE`.

`locmaxn`

  Kriging is conditions on maximal `locmaxn` points. If the data contain more points, neighbourhood kriging is performed.

  Default: `8000`.

`locsplitfactor`

  In case of neighbourhood kriging, the area is split into small boxes. The complete neighbourhood contains (2 * `locsplitfactor` +1) boxes in each direction.

  Default: `2`.

`locsplitn`

  vector of 3 components. A box should contain no more than `locsplitn[3]` points, but never less than `locsplitn[1]`. If a box had originally less than `locsplitn[1]` points, then the box is increased until at least `locsplitn[2]` points are in the box.

  Default: `c(200, 1000, 5000)`.

`method`

  obsolete

`return.variance`

  logical. If `FALSE` the kriged field is returned. If `TRUE` a list of two elements, `estim` and `var`, i.e. the kriged field and the kriging variances, is returned.

  Default: `FALSE`.

14. `maxstable`: Options for simulating max-stable random fields

`check_every`

  integer. In order to get a precise simulation result, by definition, the maximum must be taken, for each shape function, over alle locations of interest. Clearly, small values will not play a role. To this end, the global minimum has to be determined. The calculation of the global minimum is expensive and therefor should not be done too frequently. On the other hand, rare updates increases the computing times for taking the maximum over a single shape functions. Here, after every `check_every` considered shape function, the global minimum is calculated. It is expected that a good choice for `check_every` is in in the interval [10, 100].

  (For ease and for concerns of efficiency, the more adequate, local minimum is not considered.)

  Default: 30 .

`density_ratio`

  value in [0,1]. This argument is considered only if `flat=-1` and the simulation is performed on a grid. Then, the ratio between the highest and the lowest value is calculated within the convex hull of the grid. If the value is less than `density_ratio` then the grid points are considered separately. Else the density is considered to be constant in the convex hull of the grid.

  Default: 0.0.

`eps_zhou`

  positive real number, which gives the aimed relative precision. E.g. if `eps_zhou=0.01` then the first 2 digits should be correct.

  Default: 0.01

`flat`

  `-1, FALSE, TRUE`. The argument is considered only if the simulation is performed on a grid. If `flat` is logical, then the density is considered to `flat` in the convex hull of the grid. If `flat=-1` the choice is done automatically.

  Default: -1 .

`max_gauss`

  The simulation of the max-stable process based on random fields uses a stopping rule that necessarily needs a finite upper endpoint of the marginal distribution of the random field. In the case of `Brown-Resnick processes`, `extremal Gaussian fields`, and `extremal t fields`, the upper endpoint is approximated by `standardmax`.

  Default: `3.0` .

`max_n_zhou`

  positive integer. The overall constant c in the paper of Oesting, Schlather, Zhou (2014) has to be determined by MCMC, if the shape functions are random.

  The two arguments, `min_n_zhou` and `max_n_zhou`, give the minimal and the maximal number of simulations that are performed. To economize computer time the values of c is partially estimated when the shape functions are simulated. If the number of shape functions is larger than the number of simulations given by `eps_zhou` then no further simulation is performed to determine c.

  Default: 1000 and 10000000, respectively.

`maxpoints`

  positive integer; the maximal number of Poisson points to be simulated for one realization of the max-stable random field. This option will not be considered for most of the users.

  Default: `2e9` .

`mcmc_zhou`

  positive integer. In case of random shape functions, an MCMC step is required. `mcmc_zhou`-1 equals the number of members of the MCMC chain that are left out before the next value of the chain is returned.

  Default: 20

`min_n_zhou`

  see `max_n_zhou`

`xi`

  Extreme value index. Default: `2e9` .

`mcmc_zhou`

  positive integer. In case of random shape functions, an MCMC step is required. `mcmc_zhou`-1 equals the number of members of the MCMC chain that are left out before the next value of the chain is returned.

  Default: 20

`min_n_zhou`

  see `max_n_zhou`

`xi`

  Extreme value index.

  Default: `1.0` .

15. `mpp`: Options for the random coins (shot noise) methods

`about_zero`

  In certain cases (Coins,RMtruncsupport), functions are assumed to zero if the value is less than `about_zero`.

  Default: `0.001` .

`n_estim_E`

  integer. Number of draws from the distribution of the scale to estimate the mean of the distribution. This is used only if the mean of the scale distribution is not explicitely given. Default: `50000` .

`scatter_size`, `scatter_max`

  Used in function `RMscatter` that calculates ∑_{i=1}^n f(x + h_i) for some function f and for some distances h_i.

  Real valued and integer valued, respectively, or `NA`. Let \varepsilon=`about_zero`, s=`scatter_size` and m=`scatter_max`. We distinguish 4 cases:

  - `scatter_size > 0` and `scatter_max >= 0`
    Here, n equals (2m)^d. and h_i \in M = \{ (k s, …, k s),…, (m s, …, m s)\} with k=-m.

  - `scatter_size > 0` and `scatter_max < 0`
    same as the previous case, but m is chosen such that f(k_i e_i s_i) \approx \varepsilon, -k_i\in N, i=1,…,d and f(m_i e_i s_i) \approx \varepsilon, m \in N.

  - `scatter_size <= 0` and `scatter_max >= 0`
    This option is possible only for grids. Here h_i runs on the given grid i=1,…,d, but at most `scatter_max` steps.

  - `scatter_size <= 0` and `scatter_max < 0`
    this option is possible only for grids. Here, h_i runs over the whole grid.

`shape_power`

  Shape functions are powered by `shape_power` before used as intensity function for the point process.

  Default: `2.0`.

16. `nugget`: Options for the nugget effect
Simulating a nugget effect is per se trivial. However, it gets complicated and best methods (including `direct` and `circulant embedding`!) fail if zonal anisotropies are considered, where sets of points have to be identified that belong to the same subspace of eigenvalue 0 of the anisotropy matrix.

`tol`

  The nugget tolerance influences two different kind of models

  - `RPnugget`

  - `R.is`

  See there for more information.

17. `registers`: Register numbers
Model for different purposes are or can be stored at different places. They are called registers and have non-negative numbers up to 21 (currently). The user can use the registers 0..9.

`register`

  number in 0:9; place where intermediate calculation for random field simulation are stored; the number refers to 10 internal registers 0..9.

  Changing the register number only makes sense, when two different random fields, say, are to be simulated alternatingly, several times in a row. Then the simlulation speed can be increased if several registers are used, `storing=TRUE` and `RFsimulate` is used with the only argument `n`.

  Default: `0`

18. `sequ`: Options for the sequential method

`back_steps`

  See `RPsequential`

`initial`

  See `RPsequential`

`max_variables`

  See `RPsequential`

19. `solve`: Options for solving linear systems

`max_chol`

  integer. Maximum number of rows of a matrix in a Cholesky decomposition

  Default: 8192

`max_svn`

  integer. Maximum number of rows of a matrix in a svd decomposition

  Default: 6555

`matrix_methods`

  vector of at most 3 integers that gives the sequence of methods in order to inverse a matrix or to calculate its square root:

  0 : Choleskey decomposition
  1 : SVD
  2 : spam (sparse matrix algorithm)
  3 : OR
  4 : LU
  5 : <none>

  Note that if `use_spam` is not `false` the algorithm checks whether a sparse matrix algorithm should be used and which is then tried first.

  Values larger than 4 are used internally:
  5 : no further method available
  6 : not initialised
  7 : diagonal matrix found

  Default: `5`.

`spam_factor`

  integer. See argument `spam_sample_n`.

  Default: 4294967

`spam_min_n`

  integer. Has the matrix

  Default: 400

`spam_min_p`

  number in (0,1) giving the proportion of zero about which an sparse matrix algorithm is used.

  Default: `0.8`

`spam_pivot`

  integer. Pivoting algorithm for sparse matrices: 0:none; 1:MMD, 2:RCM

  See package `spam` for details.

  Default: 1

`spam_sample_n`

  Whether a matrix is sparse or not is tested by a ‘random’ sample of size `spam_sample_n`; The selection of the sample is iteratively obtained by multiplying the index by `spam_factor` modulo the size of the matrix.

  Default: 500.

`spam_tol`

  largest absolute value being considered as zero. Default: `DBL_EPSILON`

`svdtol`

  When the svd decomposition is used for calculating the square root of a matrix then the absolute componentwise difference between this matrix and the square of the square root must be less than `svdtol`. No check is performed if `svdtol` is negative.

  When the svd decomposition is used for calculating the inverse of a matrix then a diagonal value is set to zero if it is less than `svdtol`.

  Default: `1e-8`

`use_spam`

  Should the package `spam` (sparse matrices) be used for matrix calculations? If `TRUE` spam is always used. If `FALSE`, it is never used. If `NA` its use is determined by the size and the sparsity of the matrix.

  Default: `NA`.

20. `special`: Options for specific methods

`multicopies`

  Only used by `RMmult`. The covariance functions are multiplied if the corresponding independent random fields are multiplied. To get an approximative Gaussian random fields with a multiplicative covariance functions the average over `multicopies` products of random fields is calculated.

21. `spectral`: Options for the spectral (turning bands) method

`ergodic`

  In case of an additive model and `ergodic=FALSE`, the additive component are chosen proportional to their variance. In total `lines` are simulated. If `ergodic=TRUE`, the components are simulated separately and then added.

  Default: `FALSE`.

`prop_factor`

  see `RPspectral`

`sigma`

  see `RPspectral`

`sp_grid`

  see `RPspectral`

`sp_lines`

  see `RPspectral`

22. `tbm`: Options for the turning bands method

`center`

  Scalar or vector. If not `NA`, the `center` is used as the center of the turning bands for `TBM2` and `TBM3`. Otherwise the center is determined automatically such that the line length is minimal. See also `points` and the examples below.

  Default: `NA` .

`fulldim`

  positiv integer. The dimension of the space into which the simulated field is embedded. So, the value `fulldim` must be at least the dimension of the field.

  Default: 3.

`grid`

  Logical. The angle of the lines is random if `grid=FALSE`, and k*pi/`lines` for k in `1:lines`, otherwise.

  This option is used by both `RPspectral` and `RPtbm`, the latter only when the dimension is 2.

  Default: `TRUE` .

`layers`

  Logical or integer. If `TRUE` then the turning layers are used whenever a time component is given. If `NA` the turning layers are used only when the traditional TBM is not applicable. If `FALSE` then turning layers may never be used.

  Default: `TRUE` .

`lines`

  Number of lines used.

  Default: `60` .

`linesimustep`

  If `linesimustep` is positive the grid on the line has lag `linesimustep`. See also `linesimufactor`.

  Default: `0.0` .

`linesimufactor`

  `linesimufactor` or `linesimustep` must be non-negative; if `linesimustep` is positive then `linesimufactor` is ignored. If both arguments are naught then `points` is used (and must be positive). The grid on the line is `linesimufactor`-times finer than the smallest distance. See also `linesimustep`.

  Default: `2.0` .

`points`

  integer. If greater than 0, `points` gives the number of points simulated on the TBM line, hence must be greater than the minimal number of points given by the size of the simulated field and the two paramters `TBMx.linesimufactor` and `TBMx.linesimustep`. If `points` is not positive the number of points is determined automatically. The use of `center` and `points` is highlighted in an example below.

  Default: `0`.

`reduceddim`

  if positiv integer, then the value itself. If negativ, then the value is substracted from fulldim.

  Default: `-2`.

23. `internal`: Internal options mostly for warnings and messages

All these options should not be changed by the user unless he/she really known what he/she is doing.

Most of the options below change their value in a session without the user's notice.

`do_tests`

  Internal variable. Do not use it. Default: `FALSE`.

`examples_reduced`

  non-negative integer. If positve, then the design of any simulation in RandomFields is internally reduced in size (roughly downto the given value in each direction). Warnings report this behaviour. This option is necessary to run the examples of RandomFields under the time constraint of CRAN.

`stored.init`

  internally used logical argument. This option is closely related to `storing` which controls whether intermediate calculations should be stored to have faster repeated simulations.

  This user option is internally overwritten if the user calls several simulations at once. This current value is stored in `stored.init`.

  Default: `FALSE`.

`warn_ambiguous`

  internally used logical argument. Usually, the argument `grid` in `RFsimulate`, for instance, can or should be given. If not given, the system takes a default definition. Additionally a message is displayed in this case if `ambiguous=TRUE`.

  Default: `FALSE`.

`warn_aspect_ratio`

  internally used logical argument. if `TRUE` then a warning is given not a standard graphical device is used and the package plots try to keep a certain aspect ratio.

  Default: `TRUE`

`warn_colour_palette`

  internally used logical argument. If none of the packages RColorBrewer and colorspace are available and graphics are displayed, a message is displayed.

  Default: `TRUE`.

`warn_constant`

  The definition of `RMconstant` has changed. A warning is displayed if the command is used. `warn_constant` will become obsolete in future versions.

  Default: `TRUE`.

`warn_coordinates`

  internally used logical argument. If `TRUE` then a transformation from earth coordinates to cartesian coordinates is reported.

  Default: `TRUE`.

`warn_missing_zenit`

  Only for Earth systems: a missing zenit is frequently a cause for errors that are difficult to understand. Therefore, in such cases an additional warning message is displayed.

  Default: `TRUE`

`warn_newAniso`

  obsolete.
  internally used logical argument. If `newAniso=TRUE` and the argument `Aniso` is used in the model definition, then a message is displayed that the matrix `Aniso` is multiplied from the right by x, where up to Version 2.0 the argument `aniso` was available which was multiplied from the left by x.

  Default: `TRUE`.

`warn_newstyle`

  internally used logical argument. If `TRUE` a message is displayed the by the argument `spConform=FALSE` oldstyle return values are obtained instead of S4 objects.

  Default: `TRUE`.

`warn_normal_mode`

  internally used logical argument. if `TRUE` then the function `RFfit` displays the message that other values for the option `modus_operandi` are available.

  Default: `TRUE`.

`warn_oldstyle`

  internally used logical argument. If `TRUE` a warning is given if an obsolete function from Version 2 is used.

  Default: `TRUE`.

`warn_on_grid`

  internally used logical argument. If a (one-dimensional) grid is given, but the argument `grid=FALSE`, e.g. in `RFsimulate`, this contraction is reported if `warn_on_grid=TRUE`

  Default: `TRUE`.

`warn_scale`

  internally used logical argument. If `warn_scale=TRUE` then a scale less than 10 [km] is reported if earth coordinates are transformed to cartesian coordinates.

  Default: `TRUE`.

`warn_var`

  In some cases, RandomFields cannot detect whether the variance is non-negative. If `TRUE` then a warning is displayed in such a case. Default: `TRUE`.

### Value

`NULL` if any argument is given, and the full list of arguments, otherwise.

### Author(s)

Martin Schlather, schlather@math.uni-mannheim.de http://ms.math.uni-mannheim.de/de/publications/software

### References

- General

  - Schlather, M. (1999) An introduction to positive definite functions and to unconditional simulation of random fields. Technical report ST 99-10, Dept. of Maths and Statistics, Lancaster University.

  - Schlather, M. (2011) Construction of covariance functions and unconditional simulation of random fields. In Porcu, E., Montero, J.M. and Schlather, M., Space-Time Processes and Challenges Related to Environmental Problems. New York: Springer.

- rectangular distribution; `eps_zhou`

  - Oesting, M., Schlather, M. and Zhou, C. (2013) On the Normalized Spectral Representation of Max-Stable Processes on a compact set. arXiv, 1310.1813

- `shape_power`

  - Ballani, F. and Schlather, M. (2015) In preparation.

### See Also

`RFsimulate`, RFoptionsAdvanced, `RandomFields`, and `RFgetMethodNames`.

### Examples

    RFoptions(seed=0) ## *ANY* simulation will have the random seed 0; set
    ##                   RFoptions(seed=NA) to make them all random again

    RFoptions()

    ############################################################
    ##                                                        ##
    ## use of exactness                                       ##
    ##                                                        ##
    ############################################################
    x <- seq(0, 1, 1/30)
    model <- RMgauss()

    for (exactness in c(NA, FALSE, TRUE)) {
      readline(paste("\n\nexactness: `", exactness, "'; press return"))
      z <- RFsimulate(model, x, x, exactness=exactness,
                      stationary_only=NA, storing=TRUE)
      print(RFgetModelInfo(which="internal")$internal$name)
    }

[Package RandomFields version 3.1.50 Index]