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
0. basic: See RFoptions
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 everyth 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. (Only used for kriging – estimation can fully deal with NAs.)

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.

seed_incr, seed_sub_incr

(does not work yet) This argument is important iff RFsimulate is used within a function from package parallel. The value of seed_incr should be set only locally, i.e. not by RFoptions().

If seed_incr != 0 (or the number of simulations n is greater than 1) and !is.na(seed) then the seed for each simulation is calculated as

seed + (k-1) * seed_sub_incr + seed_incr * n

where k runs from 1 to n.

Default: 0

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=FALSE.

Default: FALSE.

2. Options for Brown-Resnick Fields

deltaAM

integer; only used for simulation of BR processes via RPbrmixed with optim_mixed=2. In this case, deltaAM is the number of additionally simulated Gaussian processes used for an update of areamat in the optimization pricedure.

Default: 300

maxtrendmem

integer; the maximal number of real valued variables used for intermediate storage:

• RPbrshifted: trends for shifted locations that may be stored at the same time when simulating BR processes.

• RPbrnormed: Let n be the number of locations. Then a n\times n (covariance) matrix has to be evaluated at random columns.

if maxtrendmem is large (and n small, n≤ 10^4), multiple evaluations can be avoided.

Default: 1e7 .

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 RPbrmixed 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_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

Maximal size of the covariance matrix.

Default: 12000

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

OBSOLETE. 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.

• note the use_naturalscaling only affects simple models, no operators. Also functions that define a parameter of the model are not changed.

Default: FALSE.

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.

filecharacter; 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.

grDefault

logical. If FALSE the graphic style up to Version 3.2 is used. Otherwise, the changes of th graphical style are reduced to a minimum.

Default: FALSE

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 cRFgui

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 when the constant c in the paper of Oesting, Schlather, Zhou (2018) has to be estimated. E.g. if eps_zhou=0.01 then the first 2 digits should be correct.

Default: 0.01

flathull

NA, FALSE, TRUE. Only used in M3 modelling in the algorithm by Oesting, Schlather, Zhou (2018). The argument is considered only if the simulation is performed on a grid. If flat=TRUE , then the density is considered to be flat in the convex hull of the grid, i.e. the simulation method of Schlather (2002) is used. If flat=NA the choice is done automatically.

Default: FALSE .

max_gauss

The simulation of the max-stable process by the old-fashioned method of Schlather (2002) and by older methods for Brown-Resnick processes 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 (2018) 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. So, it is advantageous to simulate all fields at once by RFsimulate(..., n = ).

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. This option allows the simulation to interrupt after maxpoints shape function have been placed.

Default: 2e9 (never).

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

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

min_shape_gumbel

To increase speed, the minimum field value is assumed to be min_shape_gumbel for calculation of threshold values for simulation short cuts. During a simulation, its value becomes void as soon as the real (current) minimum of the field being simulated exceeds min_shape_gumbel

Default: -1e15.

scatter_method

logical. If

Default: NA;

xi

Extreme value index. Default: 2e9 . While ξ can be set globally, the shift μ and the scale s can be given only locally within the process definitions, e.g., RPsmith.

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_method

scatter_size, scatter_max

Real valued and integer valued, respectively, or NA.

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

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

det_as_log

See RFoptions

eigen2zero

See RFoptions

max_chol

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

Default: 8192

max_svd

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

Default: 6555

pivot

Type of pivoting for the Cholesky decomposition. Possible values are

PIVOT_NONE

No pivoting.

PIVOT_AUTO

If the matrix has a size greater than 3x3 and Choleskey fails without pivoting, privoting is done. For matrices of size less than 4x4, no pivoting and no checks are performed.

PIVOT_DO

Do alwaoys pivoting. NOTE: privoted Cholesky decomposition yields only very approximately an upper triangular matrix L, but still L^t L = M holds true.

PIVOT_IDX

uses the same pivoting as in the previous pivoted decomposition. This option becomes relevant only when simulations with different parameters or different models shall be performed with the same seed so that also the pivoting must be coupled.

Default: PIVOT_auto

pivot_actual_size

See RFoptions

pivot_check

logical. Only used in pivoted Cholesky decomposition. If TRUE and a numerically zero diagonal element is detected, it is checked whether the offdiagonal elements are numerically zero as well. (See also pivot_max_deviation and pivot_max_reldeviation.) if NA then, in RPdirect, the value is equivent to

FALSE

if the model is positive (semi-)definite.

TRUE

if the model is genuinely negative definite.

Default: NA

pivot_idx

See RFoptions

pivot_relerror

See RFoptions

pivot_max_deviation

See RFoptions

pivot_max_reldeviation

See RFoptions

solve_method

See RFoptions

spam_factor

See RFoptions

spam_min_n

See RFoptions

spam_min_p

See RFoptions

spam_pivot

See RFoptions

spam_sample_n

See RFoptions

spam_tol

See RFoptions

svdtol

See RFoptions

use_spam

See RFoptions

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.

allow_duplicated_locations

logical. If FALSE duplicated locations are not allowed. If TRUE then the (standard) nugget effect becomes a non-stationary model in an abstract space that cannot be extended outside the given locations. See also RMnugget for the distinction between measurement error and spatial nugget.

Default: FALSE.

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, https://www.wim.uni-mannheim.de/schlather/

References

Basic

• 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, RFoptions, and RFgetMethodNames.

Examples