CovarianceFct          package:RandomFields          R Documentation

_C_o_v_a_r_i_a_n_c_e _A_n_d _V_a_r_i_o_g_r_a_m _M_o_d_e_l_s

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

     'CovarianceFct' returns the values of a covariance function

     'Variogram' returns the values of a variogram model

     'PrintModelList' prints the list of currently implemented models
     including the corresponding simulation methods

     'GetModelList' returns a matrix of currently implemented models
     and their simulation methods

     'GetModelNames' returns a list of currently implemented models

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

     CovarianceFct(x, model, param, dim=ifelse(is.matrix(x),ncol(x),1),
                   fctcall="Covariance")

     Variogram(x, model, param, dim=ifelse(is.matrix(x),ncol(x),1))

     PrintModelList()

     GetModelList(abbr=TRUE)

     GetModelNames()

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

       x: vector or (n x 'dim')-matrix.  In particular, if the model is
          isotropic or 'dim=1' then 'x' is a vector.

   model: character or list; if character then name of the covariance
          function or variogram model - see below, or type
          'PrintModelList()' for all options; see Details for the
          definition of the model by a list.  

   param: vector or matrix of parameters or missing, see Details and
          Examples;  The simplest form is that 'param' is vector of the
          form 'param=c(NA,variance,nugget,scale,...)', in this order;
           The dots '...' stand for additional parameters of the model.            

     dim: dimension of the space in which the model is applied

 fctcall: this parameter should not be changed by the user

    abbr: logical or numerical. If 'TRUE' the names for the methods are
          abbreviated. If numerical, 'abbr' gives the number of
          letters.

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

     The implemented models are in standard notation for a covariance
     function (variance 1, nugget 0, scale 1) and for positive real
     arguments x (and t): 

        *  'bessel'

                  C(x)= 2^a Gamma(a+1)x^(-a) J_a(x)

           The parameter a is greater than or equal to (d-2)/2, where d
           is the dimension of the random field.

        *  Brownian motion
            see '2dfractalB' and '3dfractalB'

        *  cardinal sine
            see 'wave'

        *  'cauchy'

                          C(x)=(1+x^2)^(-a)

           The parameter a is positive.  The model possesses two
           generalisations, the 'gencauchy' model and the 'hyperbolic'
           model.

        *  'cauchytbm'

                 C(x)= (1+(1-b/c)x^a)(1+x^a)^(-b/a-1)

           The parameter a is in (0,2],  b is positive, and c is an
           integer.  The model is valid for dimensions d<=c. 
            It allows for simulating random fields where  fractal
           dimension and Hurst coefficient can be chosen independently.
            It has negative correlations for b>c and large x.

        *  'circular'

    C(x)=1-2/pi*(x sqrt(1-x^2)+asin(x))   if 0<=x<=1, 0 otherwise

           This isotropic covariance function is valid only for
           dimensions less than or equal to 2.

        *  'cone'
            This model is used only for methods based on marked point
           processes (see 'RFMethods'); it is defined only in two
           dimensions. The corresponding (boolean) function is a
           truncated cone with socle. The base has radius 1/2. The
           model has three parameters, a, b, and c:
            a gives the radius of the top circle of the cone, given as
           part of the socle radius; a in [0,1).
            b gives the height of the socle.
            c gives the height of the truncated cone.

        *  'cubic'

 C(x)= 1- 7 x^2 + 8.75 x^3 - 3.5 x^5 + 0.75 x^7  if 0<=x<=1, 0 otherwise

           This model is valid only for dimensions less than or equal
           to 3.  It is a 2 times differentiable covariance functions
           with compact support. 

        *  'dampedcosine'

                        C(x)= exp(-a x) cos(x)

           This model is valid for dimension 1 iff a>=0, for dimension
           2 iff a>=1, and for dimension 3 iff a >= sqrt(3).

        *  'exponential'

                             C(x)=exp(-x)

           This model is a special case of the 'whittlematern' model
           (for a=1/2 there) and the 'stable' class (for a=1).

        *  fractal Brownian motion
            see '2dfractalB' and '3dfractalB'

        *  'FD'

       C(k) = (-1)^k G(1-a)^2/(G(1-a+k)G(1-a-k)) for integer k

           and linearly interpolated otherwise. Here, G is the Gamma
           function. The fractionally differenced process is a time
           series model where the grid locations are multiples of the
           scale parameter.  The parameter a is in [-1/2, 1/2). 

        *  'fractgauss'

               C(x) = 0.5 (|x+1|^a - 2|x|^a + |x-1|^a)

           This model is the covariance function for the fractional
           Gaussian noise with Hurst parameter H =a/2, a in (0,2]

        *  'gauss'

                            C(x)=exp(-x^2)

           This model is a special case of the 'stable' class (for a=2
           there). Note that the corresponding function for the random
           coins method (cf. the methods based on marked point
           processes in 'RFMethods') is

                             exp(-2 x^2).

           See 'gneiting' for an alternative model that does not have
           the disadvantages of the Gaussian model.

        *  'gencauchy' (generalised 'cauchy')

                         C(x)= (1+x^a)^(-b/a)

           The parameter a is in (0,2], and b is positive. 
            This model allows for simulating random fields where
           fractal dimension and Hurst coefficient can be chosen
           independently.

        *  'gengneiting' (generalised 'gneiting')
            if a=1 then

      C(x)=[1 + (b+1) * x] * (1-x)^(b+1) if 0<=x<=1, 0 otherwise

           if a=2 then

 C(x)= [1 + (b+2) * x + ((b+2)^2-1) * x^2 / 3] * (1-x)^(b+2) if 0<=x<=1, 0 otherwise

           if a=3 then

 C(x)=[1 + (b+3) * x +  (2 * (b+3)^2 - 3) * x^2 / 5 + ((b+3)^2 - 4) * (b+3) * x^3 / 15] * (1-x)^(b+3) if 0<=x<=1, 0 otherwise

           The parameter a is a positive integer; here only the cases
           a=1, 2, 3 are implemented. The parameter b is greater than
           or equal to (d + 2a +1)/2 where d is the dimension of the
           random field.

        *  'gneiting'

 C(x)= (1 + 8 s x + 25 s^2 x^2 + 32 s^3 x^3)*(1-s x)^8   if 0<=s x<=1, 0 otherwise

           where s=0.301187465825. This isotropic covariance function
           is valid only for dimensions less than or equal to 3.  It is
           a 6 times differentiable covariance functions with compact
           support.
            It is an alternative to the 'gaussian' model since its
           graph is visually hardly distinguishable from the graph of
           the Gaussian model, but possesses neither the mathematical
           and nor the numerical disadvantages of the Gaussian model.
            This model is a special case of 'gengneiting' (for a=3 and
           b=5 there). Note that, in the original work by Gneiting
           (1999),  s = 10 sqrt(2) / 47 ~= .3008965, a numerical value
           slightly deviating from the optimal one.

        *  gneitingdiff is obsolete, see example below

 C(x)=(1 + 8 x/b + 25 (x/b)^2 + 32 (x/b)^3)*(1-x/b)^8 * 2^{1-a} Gamma(a)^{-1} x^a K_a(x)   if 0<=x<=b, 0 otherwise

           This isotropic covariance function is valid only for
           dimensions less than or equal to 3.  The parameters a and b
           are positive.
            This class of models with compact support allows for smooth
           parametrisation of the differentiability up to order 6.     

        *  'hyperbolic'

 C(x)= c^(-b) (K_b(a*c))^(-1) * (c^2 +x^2)^(0.5 b) * K_b(a sqrt(c^2 + x^2))

           The parameters are such that
            c>=0,  a>0   and  b>0,    or
            c>0 ,  a>0   and  b=0,    or
            c>0 ,  a>=0, and  b<0.
            Note that this class is over-parametrised; always one of
           the three parameters  a, c, and scale can be eliminated in
           the formula. Therefore, one of these parameters should be
           kept fixed in any simulation study. 
            The model contains as special cases the 'whittlematern'
           model and the 'cauchy' model, for  c=0 and a=0,
           respectively.

        *  J-Bessel
            see 'bessel'

        *  K-Bessel
            see 'whittlematern'

        *  linear with sill
            See 'power' ('a=1' there).

        *  lgd1 (local-global distinguisher)

 C(x)= 1- b(a+b)^{-1}|x|^a for |x|<= 1   and   a(a+b)^{-1}|x|^-b for |x|> 1

           Here b>0 and a is in (0, 1.5-d/2] for dimension d=1,2. The
           random field has fractal dimension d + 1 - a/2 and Hurst
           coefficient 1 - b/2 for b in (0,1]

        *  matern
            See 'whittlematern'.

        *  'nsst' (Non-Separable Space-Time model)

                 C(x,t)= psi(t)^{-f} phi(x / psi(t))

           This model is used for space-time modelling where the
           spatial component is isotropic.  Here
            phi is the 'stable' model if b=1
            phi is the 'whittlematern' model if b=2
            phi is the 'cauchy' model if b=3
            and a is the respective parameter for the model. The
           function psi satisfies
            psi^2(t) = (t^c+1)^d if e=1
            psi^2(t) = (d^{-1} t^c+1)/(t^c+1) if e=2
            psi^2(t)=-log(t^c+1/d)/log d if e=3
            The parameter f must be greater than or equal to the
           spatial dimension of the field. Furthermore, c in (0,2]  and
           d in (0,1). The spatial dimension must be '>=1'.

        *  'nsst2'

                 C(x,t)= psi(t)^{-g} phi(x / psi(t))

           This model is used for space-time modelling where the
           spatial component is isotropic.  Here
            phi is the 'gencauchy' model if c=1
            The parameters a and b are the respective parameters for
           the model. The function psi satisfies
            psi^2(t) = (t^d+1)^e if f=1
            psi^2(t) = (e^{-1} t^d+1)/(t^d+1) if f=2
            psi^2(t)=-log(t^d+1/e)/log e if f=3
            The parameter g must be greater than or equal to the
           spatial dimension of the field. Furthermore, d in (0,2]  and
           e in (0,1]. Necessarily, 'dim>=2'. The spatial dimension
           must be '>=1'.

        *  'nugget'

                               1(x==0)

           Here, either 'param[2]', the 'variance', or 'param[3]', the
           'nugget', must be zero.

        *  'penta'

 C(x)= 1 - 22/3 x^2 +33 x^4 - 77/2 x^5 + 33/2 x^7 - 11/2 x^9 + 5/6 x^11  if 0<=x<=1,   0 otherwise

           valid only for dimensions less than or equal to 3.  This is
           a 4 times differentiable covariance functions with compact
           support.

        *  'power'

               C(x)= (1-x)^a   if 0<=x<=1, 0 otherwise

           This covariance function is valid for dimension d if a >=
           (d+1)/2.  For a=1 we get the well-known triangle (or tent)
           model, which is valid on the real line, only.

        *  powered exponential
            See 'stable'.

        *  'qexponential'

                 C(x) = (2 exp(-x)-a exp(-2x))/(2-a)

           The parameter a takes values in [0,1].   

        *  'spherical'

          C(x)= 1 - 1.5 x + 0.5 x^3  if 0<=x<=1, 0 otherwise

           This isotropic covariance function is valid only for
           dimensions less than or equal to 3.

        *  'stable'

                            C(x)=exp(-x^a)

           The parameter a is in [0,2]. See 'exponential' and
           'gaussian' for special cases.

        *  symmetric stable
            See 'stable'.

        *  tent model
            See 'power'.

        *  triangle
            See 'power'.

        *  'wave'

                         C(x)=sin(x)/x if x>0

           This isotropic covariance function is valid only for
           dimensions less than or equal to 3. It is a special case of
           the 'bessel' model (for a=3).

        *  'whittlematern'

                C(x)=2^{1-a} Gamma(a)^{-1} x^a K_a(x),

           The parameter a is positive. 
            This is the model of choice if the smoothness of a random
           field is to be parametrised. It is a special case of the
           'hyperbolic' model (for c=0 there).

        *  '2dfractalB'

                            gamma(x) = x^a

           The parameter a is in [0,2].

        *  '3dfractalB'

                            gamma(x) = x^a

           The parameter a is in [0,2]. The same as '2dfractalB' except
           that this implementation allows for simulating random fields
           in 3 dimensions.

     Let cov be a model given in standard notation.  Then the
     covariance model applied with arbitrary variance and scale equals

                     variance * cov( (.)/scale).


     For a given covariance function cov the variogram gamma equals 

                     gamma(x) = cov(0) - cov(x).


     Note that the value of the covariance function or variogram
     depends also on 'RFparameters()$PracticalRange'.  If the latter is
     'TRUE' and the covariance model is isotropic then the covariance
     function is internally rescaled such that cov(1)~=0.05 for
     standard parameters ('scale==1').

     The model and the parameters can be specified by three different
     forms; the first 'standard' form allows for the specification of
     the covariance model as given above for an isotropic random field.
      The second form defines isotropic nested models using matrices. 
     The third form allows for defining anisotropic and/or space-time
     models using lists; here any basic models can arbitrarily be
     combined by multiplication and summation.

        *  'model' is a string; 'param' is a vector of the form
           'param=c(mean,variance,nugget,scale,...)'. (These components
           might be given separately or bound to a simple list passed
           to 'model'.)

           The first component of _param_ is reserved for the 'mean' of
           a random field and thus ignored in the evaluation of the
           covariance function or variogram.  The parameters mean,
           variance, nugget, and scale must be given in this order;
           additional parameters have to be supplied in case of a
           parametrised class of models (e.g. 'hyperbolic', see below),
           in the order a, b, c.

           Let cov be a model given in standard notation.  Then the
           covariance model applied with arbitrary variance, nugget,
           and scale equals

                 nugget + variance * cov( (.)/scale).


           Some models allow certain parameter combinations only for
           certain dimensions.  As any model valid in d dimensions is
           also valid in 1 dimension, the default in 'CovarianceFct'
           and 'Variogram' is 'dim=1'.

        *  'model' is a string; 'param' is a matrix with columns of the
           form 'c(variance, scale, ...)'.

           Except that the entries for the 'mean' and the 'nugget' are
           missing all explanations given above also apply here.  Each
           column defines a summand of the nested model. A nugget
           effect is indicated by 'scale=0'; possibly additional
           parameters are ignored.

        *  'model' is a list as specified below; 'param' is missing.

           'model = list(l.1, OP.1, l.2, OP.2, ..., l.n)' where n is at
           most 10. The lists 'l.i' are all either of the  form 'l.i =
           list(model=,var=,kappas=,scale=,method=)'  or of the form 
           'l.i = list(model=,var=,kappas=,aniso=,method=)'. 'model' is
           a string; 'var' gives the variance; 'scale' is a scalar
           whereas 'aniso' is a d x d matrix, which is multiplied from
           the right to the n x d matrix of points; at the transformed
           points the values of the (isotropic) random field (with
           scale 1) are calculated. The dimension d of matrix must
           match the number of columns of 'x'. The models given by
           'l.i' can be combined by 'OP.i="+"' or 'OP.i="*"'.  'method'
           is ignored here; it can be set in 'GaussRF'.

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

     'CovarianceFct' returns a vector of values of the covariance
     function.

     'Variogram' returns a vector of values of the variogram model.

     'PrintModelList' prints a table of the currently implemented
     covariance functions and the matching methods. 'PrintModelList'
     returns 'NULL'.

     'GetModelNames' returns a list of implemented models

_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:

     Overviews:

        *  Chiles, J.-P. and Delfiner, P. (1999) _Geostatistics.
           Modeling Spatial Uncertainty._ New York: Wiley.

        *  Gneiting, T. and Schlather, M. (2004) Statistical modeling
           with covariance functions. _In preparation._

        *  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. (2002) Models for stationary max-stable random
           fields. _Extremes_ *5*, 33-44.

        *  Yaglom, A.M. (1987) _Correlation Theory of Stationary and
           Related Random Functions I, Basic Results._ New York:
           Springer.

        *  Wackernagel, H. (1998) _Multivariate Geostatistics._ Berlin:
           Springer, 2nd edition.

     Cauchy models, generalisations and extensions

        *  Gneiting, T. and Schlather, M. (2004) Stochastic models
           which separate fractal dimension and Hurst effect. _SIAM
           review_ To appear.

     Gneiting's models

        *  Gneiting, T. (1999) Correlation functions for atmospheric
           data analysis. _Q. J. Roy. Meteor. Soc., Part A_ *125*,
           2449-2464. 

     Holeeffect model

        *  Zastavnyi, V.P. (1993) Positive definite functions depending
           on a norm. _Russian Acad. Sci. Dokl. Math._ *46*, 112-114. 

     Hyperbolic model

        *  Shkarofsky, I.P. (1968) Generalized turbulence
           space-correlation and wave-number spectrum-function pairs.
           _Can. J. Phys._ *46*, 2133-2153.

     lgd

        *  Gneiting, T. and Schlather, M. (2004) Stochastic models
           which separate fractal dimension and Hurst effect. _SIAM
           review_ 

     nsst

        *  Gneiting, T. (2001) Nonseparable, stationary covariance
           functions for space-time data, _JASA_ *97*, 590-600.

        *  Gneiting, T. and  Schlather, M. (2001) Space-time covariance
           models. In El-Shaarawi, A.H. and Piegorsch, W.W.: _The
           Encyclopedia of Environmetrics._ Chichester: Wiley.

     Power model

        *  Golubov, B.I. (1981) On Abel-Poisson type and Riesz means,
           _Analysis Mathematica_ *7*, 161-184.

        *  Zastavnyi, V.P. (2000) On positive definiteness of some
           functions, _J. Multiv. Analys._ *73*, 55-81.

     2d/3dfractalB

        *  Stein, M.L. (2002) Fast and exact simulation of fractional
           Brownian surfaces. {\emph J. Comput. Graph. Statist.} *11*,
           587-599.

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

     'EmpiricalVariogram', 'GetPracticalRange', 'parameter.range',
     'RandomFields', 'RFparameters', 'ShowModels'.

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

      PrintModelList()
      x <- 0:100

      # the following five model definitions are the same!
      ## (1) very traditional form
      (cv <- CovarianceFct(x, model="bessel", c(NA,2,1,5,0.5)))

      ## (2) traditional form in list notation
      model <- list(model="bessel", param=c(NA,2,1,5,0.5))
      cv - CovarianceFct(x, model=model)

      ## (3) nested model definition
      cv - CovarianceFct(x, model="bessel",
                         param=cbind(c(2, 5, 0.5), c(1, 0, 0)))

      #### most general notation in form of lists
      ## (4) isotropic notation 
      model <- list(list(model="bessel", var=2, kappa=0.5, scale=5),
                    "+",
                    list(model="nugget", var=1))
      cv - CovarianceFct(x, model=model)
                   
      ## (5) anisotropic notation
      model <- list(list(model="bessel", var=2, kappa=0.5, aniso=0.2), 
                    "+",
                    list(model="nugget", var=1, aniso=1))
      cv - CovarianceFct(as.matrix(x), model=model)

      # The model gneitingdiff was defined in RandomFields v1.0.
      # This isotropic covariance function is valid for dimensions less
      # than or equal to 3 and has two positive parameters.
      # It is a class of models with compact support that allows for
      # smooth parametrisation of the differentiability up to order 6.     
      # The former model `gneitingdiff' must now be coded as
      gneitingdiff <-  function(p){
        list(list(m="gneiting", v=p[2], s=p[6]*p[4]*10*sqrt(2)/47),
            "*",
            list(m="whittle", k=p[5], v=1.0, s=p[4]),
            "+",
            list(m="nugget", v=p[3]))
      }
      # and then 
      param <- c(NA, runif(5,max=10)) ## as usual, here an example
      CovarianceFct(x,gneitingdiff(param))
      ## instead of formerly CovarianceFct(x,"gneitingdiff",param)

