RFparameters          package:RandomFields          R Documentation

_C_o_n_t_r_o_l _P_a_r_a_m_e_t_e_r_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

       RFparameters(...)

       RFparameters.default(Storing=storing, PrintLevel=printlevel,
                            PracticalRange=practicalrange, CE.force=ce.force,
                            CE.mmin=ce.mmin, CE.tolRe=ce.tolRe,
                            CE.tolIm=ce.tolIm, CE.trials=ce.trials,
                            direct.checkprecision=directcheckprecision,
                            direct.maxvariables=directmaxvariables,
                            direct.method=directmethod,
                            direct.requiredprecision=directrequiredprecision,
                            spectral.lines=spectrallines,
                            spectral.grid=spectralgrid,
                            TBMCE.force=tbmceforce, TBMCE.mmin=tbmcemmin,
                            TBMCE.tolRe=tbmcetolre, TBMCE.tolIm=tbmcetolim,
                            TBMCE.trials=tbmcetrials, TBM2.lines=tbm2lines,
                            TBM2.linesimufactor=tbm2linesimufactor,
                            TBM2.linesimustep=tbm2linesimustep,
                            TBM3D2.lines=tbm3D2lines,
                            TBM3D2.linesimufactor=tbm3D2linesimufactor,
                            TBM3D2.linesimustep=tbm3D2linesimustep,
                            TBM3D3.lines=tbm3D3lines,
                            TBM3D3.linesimufactor=tbm3D3linesimufactor,
                            TBM3D3.linesimustep=tbm3D3linesimustep,
                            MPP.approxzero=mppapproxzero,
                            add.MPP.realisations=addmpprealisations,
                            MPP.radius=mppradius,
                            maxstable.maxGauss=maxstablemaxGauss, pch=pchx)

_A_r_g_u_m_e_n_t_s:

     ...: arguments as given in `RFparameters.default' and listed in
          the following.

 Storing: logical.  If `TRUE' then intermediate results are kept after
          each simulation; if several simulation are made with the same
          parameters (e.g., by `n'>1 in GaussRF or several calls of
          GaussRF) then `Storing=TRUE' accelerates the simulations, but
          needs additional memory.  Default: `TRUE' [init, do].

PrintLevel: If `PrintLevel'<=0 there is not any output on the screen. 
          The higher the number the more tracing information.  Default:
          1 [init, do].
          1 : messages about errors occurred
          2 : messages about partial failures of the algorithm 

PracticalRange: The range of the covariance functions can be adjusted
          so that cov(1) is about 0.05 (for `scale==1'). 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: Circulant embedding usually uses the smallest matrix
          possible; by `CE.mmin' the minimum number of rows and columns
          of the matrix are given.  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]. 

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: `1000'
          [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.  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].

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 smaller than the smallest
          distance.  See also `TBM2.lines'.  Default: `2.0' [init].

TBM2.linesimustep: The grid on the line has lag `TBM2.linesimustep'. 
          See also `TBM2.linesimufactor'.  Default: `0.0' [init].

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.lines'.  Default: `2.0' [init].

TBM3D2.linesimustep: The grid on the line has lag
          `TBM3D2.linesimustep'.  See also `TBM3D2.linesimufactor'. 
          Default: `0.0' [init].

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.lines'. Default: `2.0' [init].

TBM3D3.linesimustep: The grid on the line has lag
          `TBM3D3.linesimustep'.  See also `TBM3D3.linesimufactor'. 
          Default: `0.0' [init].

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). 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. 
          Default: `"#"' [do].  

_D_e_t_a_i_l_s:

     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' will not have any effect.  These parameters have
     the flag "[init]".

     Parameters like `TBM2.lines' (which determines the number of
     i.i.d. proceses to be simulated on the line) are only relevant
     when generating random numbers.  These parameters are read by
     `DoSimulateRF', 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 relevant even if 
     `GaussRF' is used, but 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 parameters, and takes over the stored
     intermediate results (that have been calculated with the
     `RFparameters()' at that time).  To prevent this put
     `RFparameters(Storing==FALSE)' or use `DeleteRegister()'.

     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.

_V_a_l_u_e:

     returns `NULL' if any parameter has been given, and the list of
     all parameter values otherwise.

_A_u_t_h_o_r(_s):

     Martin Schlather, Martin.Schlather@uni-bayreuth.de <URL:
     http://www.geo.uni-bayreuth.de/~martin>

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     `GaussRF', `GetPracticalRange',  `MaxStableRF', `RandomFields',
     and `RFMethods'.

_E_x_a_m_p_l_e_s:

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

