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(...)

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

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

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

     The possible parameters are

     '_S_t_o_r_i_n_g' 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].

     '_P_r_i_n_t_L_e_v_e_l' 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

     '_P_r_a_c_t_i_c_a_l_R_a_n_g_e' 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').

             *  'TRUE' : 'PracticalRange' is applicable only if the
                value is known exactly.

             *  '2' : 'PracticalRange' is applicable if the value is
                known pretty well

             *  '3' : 'PracticalRange' is applicable if the value is
                roughly known

             *  '11' : if the practical range is not known exactly it
                is approximated numerically.

             *  '12' : if the practical range is not known pretty well
                it is approximated numerically.

             *  '13' : if the practical range is even not known
                approximately it is approximated numerically.

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

          Default: 'FALSE' [init].

     '_C_E._f_o_r_c_e' 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].

     '_C_E._m_m_i_n' 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].    

     '_C_E._t_o_l_R_e' Circulant embedding. Threshold above which eigenvalues
          are considered as non-negative.  Default: '-1E-5' [init].

     '_C_E._t_o_l_I_m' 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].

     '_C_E._t_r_i_a_l_s' 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].

     '_C_E._u_s_e_r_f_f_t' 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].

     '_C_E._s_t_r_a_t_e_g_y' 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].

     '_d_i_r_e_c_t._c_h_e_c_k_p_r_e_c_i_s_i_o_n' 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].

     '_d_i_r_e_c_t._m_a_x_v_a_r_i_a_b_l_e_s' 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]

     '_d_i_r_e_c_t._m_e_t_h_o_d' Decomposition of the covariance matrix. If
          'direct.method==1', Cholesky decomposition will not be
          attempted, but singular value decomposition used instead.
          Default: '0' [init].

     '_d_i_r_e_c_t._r_e_q_u_i_r_e_d_p_r_e_c_i_s_i_o_n' 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].

     '_s_p_e_c_t_r_a_l._l_i_n_e_s' Spectral turning bands. Number of lines used (in
          total for all additive components of the covariance
          function).  Default: '500' [do].

     '_s_p_e_c_t_r_a_l._g_r_i_d' 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].

     '_T_B_M_C_E._f_o_r_c_e' 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].

     '_T_B_M_C_E._m_m_i_n' Ordinary TBM methods.  This parameter corresponds to
          'CE.mmin'.  Default: '0' [init].

     '_T_B_M_C_E._t_o_l_R_e' Ordinary TBM methods.  This parameter corresponds to
          'CE.tolRe'. Default: '-1E-5' [init].

     '_T_B_M_C_E._t_o_l_I_m' Ordinary TBM methods.  This parameter corresponds to
          'CE.tolIm'.  Default: '1E-3' [init].

     '_T_B_M_C_E._t_r_i_a_l_s' Ordinary TBM methods.  This parameter corresponds
          to 'CE.trials'.  Default: '3' [init].

     '_T_B_M_C_E._u_s_e_r_f_f_t' Ordinary TBM methods.  This parameter corresponds
          to 'CE.userfft'.  Default: 'true' [init].

     '_T_B_M_C_E._s_t_r_a_t_e_g_y' Ordinary TBM methods.  This parameter corresponds
          to 'CE.strategy'.  Default: '0' [init].

     '_T_B_M_2._l_i_n_e_s' Ordinary 2-dimensional turning bands method.  Number
          of lines used.  Default: '60' [do].

     '_T_B_M_2._l_i_n_e_s_i_m_u_f_a_c_t_o_r' 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].

     '_T_B_M_2._l_i_n_e_s_i_m_u_s_t_e_p' If 'TBM2.linesimustep' is positive the grid on
          the line has lag 'TBM2.linesimustep'.  See also
          'TBM2.linesimufactor'.  Default: '0.0' [init].

     '_T_B_M_2._e_v_e_r_y' If 'TBM2.every>0' then every 'TBM2.every'th iteration
          is announced. Default: '0' [do].

     '_T_B_M_3_D_2._l_i_n_e_s' Ordinary 3-dimensional turning bands method,
          simulation of a _2-dimensional_ field.  Number of lines used.
           Default: '500' [do].

     '_T_B_M_3_D_2._l_i_n_e_s_i_m_u_f_a_c_t_o_r' 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].

     '_T_B_M_3_D_2._l_i_n_e_s_i_m_u_s_t_e_p' The grid on the line has lag
          'TBM3D2.linesimustep'.  See also 'TBM3D2.linesimufactor'. 
          Default: '0.0' [init].

     '_T_B_M_3_D_2._e_v_e_r_y' If 'TBM3D2.every>0' then every 'TBM3D2.every'th
          iteration is announced. Default: '0' [do].

     '_T_B_M_3_D_3._l_i_n_e_s' Ordinary 3-dimensional turning bands method,
          simulation of a _3-dimensional field_.  Number of lines used.
           Default: '500' [do].

     '_T_B_M_3_D_3._l_i_n_e_s_i_m_u_f_a_c_t_o_r' 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].

     '_T_B_M_3_D_3._l_i_n_e_s_i_m_u_s_t_e_p' The grid on the line has lag
          'TBM3D3.linesimustep'.  See also 'TBM3D3.linesimufactor'. 
          Default: '0.0' [init].

     '_T_B_M_3_D_3._e_v_e_r_y' If 'TBM3D3.every>0' then every 'TBM3D3.every'th
          iteration is announced. Default: '0' [do].

     '_M_P_P._a_p_p_r_o_x_z_e_r_o' 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].

     '_a_d_d._M_P_P._r_e_a_l_i_s_a_t_i_o_n_s' Random coins. Number of superposed
          realisations (to approximate the normal distribution; total
          number for all (additive) components with same anisotropy);
          Default: '100' [do].

     '_M_P_P._r_a_d_i_u_s' 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].

     '_m_a_x_s_t_a_b_l_e._m_a_x_G_a_u_s_s' 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].

     '_p_c_h' 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.

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

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

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

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

_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())

