ShowModels           package:RandomFields           R Documentation

_I_n_t_e_r_a_c_t_i_v_e _C_h_o_i_c_e _o_f _M_o_d_e_l_s _a_n_d _P_a_r_a_m_e_t_e_r_s

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

     'ShowModels' is an interactive plot for the selection of  models
     and their one- or two-dimensional simulations; it also allows for
     the fitting of variogram models by eye.

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

     ShowModels(x, y=NULL,
                covx=ifelse(is.null(empirical), diff(range(x))/5,
                            max(empirical$c)), 
                fixed.rs=FALSE, method=NULL, empirical=NULL,
                model=NULL, param=NULL, all.param=NULL, PracticalRange=FALSE,   
                legends = TRUE, register=0, Mean=NULL, erase=TRUE,
                x.fraction=0.60, cex.names=1, covx.default = 100,
                link.fct=NULL, Zlim=NULL, maxstable.maxGauss=2,
                Col.rect="red", Col.bg="blue", Col.sep="grey",
                Col.line="red", Col.txt="black", Col.flash="red",
                Col.vario="blue", Col.main="black",
                Col.model=c("red", "black"),  vario.lty=c(1,2), 
                cex.leg =0.7,  update=TRUE, screen.new=TRUE, debug=FALSE, ...)

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

       x: if 'NULL' simulations are not performed; otherwise it gives
          the x coordinates of a grid. 

       y: if 'NULL' at most one-dimensional simulations are performed
          (depending on the value of 'x'); otherwise 'y' gives the y
          coordinates of a two-dimensional grid.

    covx: if a single value is given, it is the largest distance for
          which the covariance functions or the variograms are plotted;
          otherwise the models are plotted for the given values, and
          the origin.

fixed.rs: if 'TRUE' then the same random seed is used for all
          simulations.

  method: simulation method, see RFMethods; if 'NULL' then a suitable
          simulation method is chosen automatically.

empirical: empirical variogram; a list as returned by
          'EmpiricalVariogram'. Also empirical variograms with a pair
          number of anisotropy directions may be passed. Then the first
          and the middle one are taken. 

   model: covariance model, see 'CovarianceFct', or type
          'PrintModelList()' to get all options. If given, this model
          is shown at the beginning. Additive or multiplicative models
          are not allowed.

          However, model can also be given by a simple list definition,
          see 'CovarianceFct'. Then 'param' must not be given. In this
          case also anisotropic models can be defined. 

   param: parameter vector: 'param=c(mean, variance, nugget,
          scale,...)'; the parameters must be given in this order; see
          'CovarianceFct' for more details. Only considered if 'model'
          is given. If given, 'model' is initialised by 'param'.

all.param: 'all.param=c(mean, variance, nugget, scale)'; the parameters
          must be given in this order; If 'all.param' is given then the
          parameters of all covariance functions are set to the given
          values.  The values are overwritten for a specific model if
          'model' and 'param' are given. Note that it is not possible
          to set the values of additional (form) parameters of a
          parametrised class by means of 'all.param'.

          In case of an anisotropic model the anisotropy matrix is by
          default diagonal with both entries equal to 1/'all.param[4]'. 

PracticalRange: logical.  If 'TRUE' the range of the covariance
          functions C(h) is adjusted so that the covariance function is
          about 0.05 for 'scale==1' and distance h=1.

 legends: if 'TRUE' then a legend is added to the two-dimensional plot.

register: register where intermediate results of the simulations are
          stored, see also 'GaussRF'.

    Mean: mean of the random field

   erase: parameter of 'split.screen', which is called at the very
          beginning

x.fraction: the current screen is split into 2 x 2 screens.   The
          parameter 'x.fraction' gives the size of the left screens in
          the x directions as part of 1. See also the Details.

cex.names: font size for model names

covx.default: if 'length(cov.x)==1' then [0, 'cov.x'] is covered by
          'covx.default' points of equal distance

link.fct: 'NULL' or 'function(values)' or "MaxStable".   Transformation
          of the  Gaussian random field. 

           If 'link.fct="MaxStable"' then max-stable random fields are
          simulated for the given covariance function and the extremal
          coefficient function is given (up the constant -1) instead of
          the variogram or the covariance function 

    Zlim: Vector of two elements or list of two vectors of two
          elements. Graphical limits for the Gaussian random process
          (and the transformed field).

maxstable.maxGauss: 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'. The shown Gaussian random field is
          multiplied with the largest point of the Poisson point
          process. 

Col.rect: colour for interactive plot; see 'eval.parameters'.

  Col.bg: colour for interactive plot; see 'eval.parameters'.

 Col.sep: colour for interactive plot; see 'eval.parameters'.

Col.line: colour for interactive plot; see 'eval.parameters'.

 Col.txt: colour for interactive plot; see 'eval.parameters'.

Col.flash: colour for the previously chosen model

Col.vario: colour for the empirical variogram plot

Col.main: colour for the title of the random field

Col.model: vector of two colours for plotting the variogram of the
          Gaussian random field and the transformed field

vario.lty: vector of two line types for primary and secondary axis of
          the variogram

 cex.leg: font size used in the legends

  update: logical.  If 'TRUE' the plots are updated after each
          interactive change of the values.  Otherwise, the bottom
          'simulate' is added in the menu.

screen.new: logical.  If 'FALSE' the screen is erased before a
          simulation and completely rebuild;  otherwise the screen is
          updated.  If 'FALSE' flickering appears during the update of
          the current screen, otherwise it may happen during the
          reorganisation of any window (and may take quite a lot of
          time). 

   debug: logical. If 'TRUE' then internally the
          'RFparameter()$PrintLevel' is set to 5. 

     ...: additional graphics options for the plot of the one- or
          two-dimensional simulations, see 'plot' and 'image'.

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

     The interactive plot consists of 3 parts:

        *  top left: graph of the covariance function or the variogram.
           In case 'empirical' is given the empirical variogram is also
           plotted. If 'link.fct' is given, then also the covariance
           function or the variogram is plotted. If the correlation
           model is for a non-stationary random field, the variogram
           for the transformed random field is not estimated in a
           primitive way - this is indicated with a star in the legend

        *  bottom left: one- or two-dimensional simulation

        *  right: \itemize {

        *  list of implemented models; a specific model is chosen by
           the left mouse button, or:

        *  menu for the parameters of the chosen model. The list
           includes the variance, a nugget effect, the mean and the
           scale or the anisotropy parameters. Further, some global
           parameters can be changed. They are the 'PracticalRange' 
           (see 'RFparameters' for details) and the angle of the main
           variogram direction (or NA, then it follows the angle of the
           anisotropy). Finally, the user can choose between the plot
           of the covariance and the corresponding variogram. }

     The interactive plot is left by clicking any mouse button
     different from the left when the top right part is active.

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

     list of the last model and its parameters.

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

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

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

     'CovarianceFct', 'eval.parameters', 'GaussRF', 'RFMethods',
     'RandomFields'.

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

     # first example: one-dimensional simulations

     # system("xset b off") ## for unix systems

     RFparameters(Print=1)
     x <-  seq(1,10,0.1);
     ShowModels(x=x)

     # second example: two-dimensional simulations and
     #                 empirical variogram
     dx <- runif(300,0,8)
     dy <- runif(300,0,8)
     dz <- GaussRF(x=dx, y=dy, grid=FALSE, model="gaus",
           param=c(1,2,1,2))
     ev <- EmpiricalVariogram(x=dx, y=dy, data=dz, grid=FALSE,
           bin=(-1:20)/4)
     x <-  seq(1,5,0.1);
     ShowModels(x=x, y=x, empirical=ev)

     # third example: two-dimensional anistropic simulations and
     #                link function
     x <- seq(1,10,0.1)

     ShowModels(x=x, y=x, link=function(x) x^2,
               model=list(list(model="exp", var=1, aniso=c(1,0,0,5))))

     x <-  seq(1,10,0.1)
     ShowModels(x=x, link=function(x) x^2,
                model=list(list(model="exp",var=1, scale=1)))

     x <-  seq(1,10,0.1)
     RFparameters(CE.force=TRUE, CE.trials=1, CE.mmin=-4, CE.userfft=FALSE)
     ShowModels(x=x, link="MaxStable", fixed.rs=TRUE,
                model=list(list(model="gauss",var=1, scale=1)), type="l")

