RFparameters {RandomFields}R Documentation

Control Parameters

Description

RFparameters sets and returns control parameters for the simulation of random fields

Usage

   RFparameters(...)

Arguments

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

Details

The possible parameters are

Storing
Logical. If TRUE then intermediate results are kept after each simulation; if several simulation are performed with the same model parameters then Storing=TRUE accelerates the simulations, but needs additional memory.
Note that in subsequent calls of GaussRF intermediate changes of RFparameters with flag "[init]" do not have any influence on the algorithm. Hence, for studying the effects for divers values of technical parameters like CE.force, CE.mmin, etc. the parameter Storing must be FALSE. See also last paragraphs in the Details. Default: TRUE [init, do].
PrintLevel
If PrintLevel<=0 there is not any output on the screen. The higher the number the more tracing information is given. Default: 1 [init, do].
1 : error messages
2 : messages about partial failures of the algorithm
PracticalRange
logical or 2, 3, 11, 12, 13. If not FALSE the range of the covariance functions is adjusted so that cov(1) is about 0.05 (for scale==1).

Note that values beyond FALSE, TRUE, and 11, are only used for specialists' purposes.

Default: FALSE [init].

CE.force
Logical. Circulant embedding does not work if a certain matrix has negative eigenvalues. Sometimes it is convenient to replace all the negative eigenvalues by zero (CE.force==TRUE) after CE.trials number of trials. Default: FALSE [init].
CE.mmin
Scalar or vector. Circulant embedding usually uses the smallest matrix possible; by CE.mmin the minimum number of rows and columns of the matrix are given. If CE.mmin>=0 then the minimum absolute size is given.
If CE.mmin<0 then the follow holds. If CE.userfft==FALSE then the matrix has -CE.mmin times the size of the size of the smallest matrix. If CE.userfft==TRUE then the matrix has max(-CE.mmin/2,1) times the size of the size of the smallest matrix. Default: 0 [init].
CE.tolRe
Circulant embedding. Threshold above which eigenvalues are considered as non-negative. Default: -1E-5 [init].
CE.tolIm
Circulant embedding. If the modulus of the imaginary part is less than CE.tolIm then the eigenvalue is considered as real. Default: 1E-3 [init].
CE.trials
Circulant embedding. A larger embedding matrix is likely to make more eigenvalues non-negative. If at least one of the thresholds CE.tolRe and CE.tolIm are missed then the matrix size is doubled, and the matrix is checked again. This procedure is repeated up to CE.trials-1 times. If there are still negative eigenvalues, the simulation method fails if CE.force==FALSE. Default: 3 [init].
CE.userfft
Logical. If FALSE the columns of the circulant matrix have length 2^k for some k. Otherwise the algorithm tries to find a nicely factorizable number close to the size of the given matrix. Default: FALSE [init].
CE.strategy
0 : if matrix has negative eigenvalues then the size in each direction is doubled;
1 : the size is enhanced only in one direction, namely that where the covariance function has the largest value at the end point of the grid - note that the default value of CE.trials is probably too small in that case.
Default: 0 [init].
direct.checkprecision
Gaussian random vectors can be generated by means of the square root of the covariance matrix. By default Cholesky decomposition is used. If direct.checkprecision==TRUE then the precision is checked. Default: FALSE [init].
direct.maxvariables
Decomposition of the covariance matrix. If the number of variables to generate is greater than direct.maxvariables, then any matrix decomposition method is rejected. It is important that this option is set conveniently if method==NULL in GaussRF. Default: 1800 [init]
direct.method
Decomposition of the covariance matrix. If direct.method==1, Cholesky decomposition will not be attempted, but singular value decomposition used instead. Default: 0 [init].
direct.requiredprecision
Decomposition of the covariance matrix. If direct.checkprecision==TRUE and the direct.requiredprecision is not reached then Cholesky decomposition fails, and singular value decomposition is used. Default: 1e-11 [init].
spectral.lines
Spectral turning bands. Number of lines used (in total for all additive components of the covariance function). Default: 500 [do].
spectral.grid
Logical. Spectral turning bands is implemented for 2 dimensions only. The angle of the lines is random if spectral.grid==FALSE, and k*pi/spectral.lines for k in 1:spectral.lines, otherwise. Default: TRUE [do].
TBMCE.force
Ordinary TBM methods. At the moment only the circulant embedding method on the line is implemented; this parameter corresponds to CE.force. Default: FALSE [init].
TBMCE.mmin
Ordinary TBM methods. This parameter corresponds to CE.mmin. Default: 0 [init].
TBMCE.tolRe
Ordinary TBM methods. This parameter corresponds to CE.tolRe. Default: -1E-5 [init].
TBMCE.tolIm
Ordinary TBM methods. This parameter corresponds to CE.tolIm. Default: 1E-3 [init].
TBMCE.trials
Ordinary TBM methods. This parameter corresponds to CE.trials. Default: 3 [init].
TBMCE.userfft
Ordinary TBM methods. This parameter corresponds to CE.userfft. Default: true [init].
TBMCE.strategy
Ordinary TBM methods. This parameter corresponds to CE.strategy. Default: 0 [init].
TBM2.lines
Ordinary 2-dimensional turning bands method. Number of lines used. Default: 60 [do].
TBM2.linesimufactor
Either TBM2.linesimufactor or TBM2.linesimustep must be greater than zero. The parameter that is zero is ignored. The grid on the line is TBM2.linesimufactor-times finer than the smallest distance. See also TBM2.linesimustep. Default: 2.0 [init].
TBM2.linesimustep
If TBM2.linesimustep is positive the grid on the line has lag TBM2.linesimustep. See also TBM2.linesimufactor. Default: 0.0 [init].
TBM2.every
If TBM2.every>0 then every TBM2.everyth iteration is announced. Default: 0 [do].
TBM3D2.lines
Ordinary 3-dimensional turning bands method, simulation of a 2-dimensional field. Number of lines used. Default: 500 [do].
TBM3D2.linesimufactor
Either TBM3D2.linesimufactor or TBM2.linesimustep must be greater than zero. The parameter that is zero is ignored. The grid on the line is TBM3D2.linesimufactor-times smaller than the smallest distance. See also TBM3D2.linesimustep. Default: 2.0 [init].
TBM3D2.linesimustep
The grid on the line has lag TBM3D2.linesimustep. See also TBM3D2.linesimufactor. Default: 0.0 [init].
TBM3D2.every
If TBM3D2.every>0 then every TBM3D2.everyth iteration is announced. Default: 0 [do].
TBM3D3.lines
Ordinary 3-dimensional turning bands method, simulation of a 3-dimensional field. Number of lines used. Default: 500 [do].
TBM3D3.linesimufactor
Either TBM3D3.linesimufactor or TBM2.linesimustep must be greater than zero. The parameter that is zero is ignored. The grid on the line is TBM3D3.linesimufactor-times smaller than the smallest distance. See also TBM3D3.linesimustep. Default: 2.0 [init].
TBM3D3.linesimustep
The grid on the line has lag TBM3D3.linesimustep. See also TBM3D3.linesimufactor. Default: 0.0 [init].
TBM3D3.every
If TBM3D3.every>0 then every TBM3D3.everyth iteration is announced. Default: 0 [do].
MPP.approxzero
Marked point processes. Functions that do not have compact support are set to zero outside the ball outside which the function has absolute values less than MPP.approxzero. Default: 0.001 [init].
add.MPP.realisations
Random coins. Number of superposed realisations (to approximate the normal distribution; total number for all (additive) components with same anisotropy); Default: 100 [do].
MPP.radius
Marked point processes. In order avoid edge effects, the simulation area is enlarged by a constant r so that all marks have their (supposed) support in the ball with radius r centred at the origin; see also MPP.approxzero. If MPP.radius>0 the true radius r is replaced by MPP.radius. Default: 0.0 [init].
maxstable.maxGauss
Max-stable random fields. 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 extremal Gaussian random fields, see MaxStableRF, the upper endpoint is approximated by maxstable.maxGauss. Default: 3.0 [init].
pch
Character. The character is printed after each performed simulation if more than one simulation is performed at once. If pch='!' then a counter is shown instead of the character. Note that also '^H's are printed if the counter (pch='!') is shown, which may have undesirable interactions with some few other R functions, e.g. Sweave. Default: '*' [do].

The following refers to the simulation of Gaussian random fields (InitGaussRF, GaussRF), but most parts also apply for the simulation of max-stable random fields (InitMaxStableRF, MaxStableRF).

Some of the global parameters determine the basic settings of a simulation, e.g. direct.method (which chooses a square root of a positive definite matrix). The values of such parameters are read by InitGaussRF and stored in an internal register. Changing such a parameter between calling InitGaussRF and calling DoSimulateRF or between subsequent calls of GaussRF will not have any effect. These parameters have the flag "[init]".

Parameters like TBM2.lines (which determines the number of i.i.d. processes to be simulated on the line) are only relevant when generating random numbers. These parameters are read by DoSimulateRF (or by the second part of GaussRF), and are marked by "[do]".

Storing has an influence on both, InitGaussRF and DoSimulateRF. InitGaussRF may reserve more memory if Storing==TRUE. DoSimulateRF will free the register if Storing==FALSE, whatever the value of Storing was when InitGaussRF was called.

The distinction between [init] and [do] is also relevant if GaussRF is used and called a second time with the same parameters for the random field and if RFparameters()$Storing==TRUE. Then GaussRF realises that the second call has the same random field parameters, and takes over the stored intermediate results (that have been calculated with the RFparameters() at that time). To prevent the use of stored intermediate results or to take into account intermediate changes of RFparameters set RFparameters(Storing==FALSE) or use DeleteRegister() between calls of GaussRF.

A programme that checks whether the parameters are well adapted to a specific simulation problem is given as an example of EmpiricalVariogram().

For further details on the implemented methods, see RFMethods.

Value

If any parameter has been given RFparameters returns an invisible list of the given parameters in full name.
Otherwise the complete list of parameters is returned. Further the values of the following internal readonly variables are returned

covmaxchar max. name length for variogram/covariance models
methodmaxchar max. name length for methods
distrmaxchar max. name length for a distribution
covnr number of currently implemented variogram/covariance models
methodnr number of currently implemented variogram/covariance models
distrnr number of currently implemented distributions
maxdim maximum number of dimensions for a random field
maxmodels maximum number of models, i.e. the possible register numbers in GaussRF for example, are 1,...,maxmodels.

Author(s)

Martin Schlather, martin.schlather@cu.lu http://www.cu.lu/~schlathe

References

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.

See Also

GaussRF, GetPracticalRange, MaxStableRF, RandomFields, and RFMethods.

Examples

 RFparameters(Storing=TRUE)
 str(RFparameters())

[Package Contents]