mleRF              package:RandomFields              R Documentation

_M_a_x_i_m_u_m _L_i_k_e_l_i_h_o_o_d _E_s_t_i_m_a_t_i_o_n _o_f _R_a_n_d_o_m _F_i_e_l_d _P_a_r_a_m_e_t_e_r_s

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

     This function estimates arbitrary parts of the parameter vector of
     a random field specification by maximising the likelihood.

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

     mleRF(coord, data, model, param, lower.kappa=NULL, upper.kappa=NULL,
           sill=NA, ...) 

     mleRF.default(coord, data, model, param, lower.kappa=NULL,
                   upper.kappa=NULL, sill=NA,
                   use.naturalscaling=TRUE, PrintLevel=0, trace.optim=0,
                   bins=20, distance.factor=0.5, upperbound.scale.factor=10,
                   lowerbound.scale.factor=20, lowerbound.scale.LS.factor=5,
                   upperbound.var.factor=10, lowerbound.var.factor=100,
                   lowerbound.sill=1e-10, scale.max.relative.factor=1000,
                   minbounddistance=0.001, minboundreldist=0.02,
                   approximate.functioncalls=50, pch="*")

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

   coord: (n x 2)-matrix of coordinates.

    data: vector of values measured at `coord'.

   model: string; covariance model, see `CovarianceFct', or type
          `PrintModelList()' to get all options.

   param: vector of parameters for a random field specification:
          `param=c(mean, variance, nugget, scale,...)'; the parameters
          must be given in this order. Further parameters are to be
          added in case of a parametrised class of covariance
          functions, see `CovarianceFct'. Any components set to `NA'
          are estimated; the others are kept fix. 

lower.kappa: lower bounds for additional parameters of a parametrised
          class.

upper.kappa: upper bounds for additional parameters of a parametrised
          class.

    sill: If not `NA' the sill is kept fix.  See Details.

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

use.naturalscaling: logical.  If `TRUE' then internally, rescaled
          covariance functions will be used for which cov(1)~=0.05. 
          See Details.

PrintLevel: level to which messages are shown.  See Details.

trace.optim: tracing of the function `optim'

    bins: number of bins of the empirical variogram.  See Details.

distance.factor: relative right bound for the bins.  See Details.

upperbound.scale.factor: relative upper bound for scale.  See Details.

lowerbound.scale.factor: relative lower bound for scale.  See Details.

lowerbound.scale.LS.factor: relative lower bound for scale in an
          auxiliary function call.  See Details.

upperbound.var.factor: relative upper bound for variance and nugget. 
          See Details.

lowerbound.var.factor: relative lower bound for variance and nugget. 
          See Details.

lowerbound.sill: absolute lower bound for variance and nugget.  See
          Details.

scale.max.relative.factor: relative lower bound for scale below which
          an additional nugget effect is detected.  See Details.

minbounddistance: absolute distance to the bounds below which a part of
          the algorithm is considered as having failed.  See Details.

minboundreldist: relative distance to the bounds below which a part of
          the algorithm is considered as having failed.  See Details.

approximate.functioncalls: approximate evaluations of the ML target
          function on a grid.  See Details.

     pch: character shown before each step of calculation; depending on
          the specification there are two to five steps. Default: "*".

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

     The maximisation is performed using `optim'.  Since `optim' needs
     as input parameter an initial vector of parameters, `mleRF'
     estimates this initial parameter first using an auxiliary target
     function, namely weighted least squares for the empirical
     variogram.

     If the best parameter vector of the MLE found so far is too close
     to some given bounds, see the specific parameters below, it is
     assumed that `optim' ran into a local minimum because of a bad
     starting value by the auxiliary target function. In this case the
     MLE target function is calculated on a grid, the best parameter
     vector is taken, and the optimisation is restarted with this
     parameter vector.

     Comments on specific parameters:

        *  `lower.kappa'
           If a covariance function possesses additional parameters,
           see `stable' in `CovarianceFct' for example, one may supply
           (vectors of) lower and upper limits by `lower.kappa' and
           `upper.kappa'.  Note that the values of these two parameters
           are not recycled if the number of parameters of a covariance
           function is a multiple of the length of `lower.kappa' or
           `upper.kappa'.  In case a covariance model has more than one
           parameter, and if the second parameter is to be estimated,
           say, then limits for the first and the second parameters
           should be supplied.  (The function assigns the given limits
           to the parameters by always starting with the first
           parameter, whether it is estimated or not.)  It is advised
           to limit seriously the domain of the additional parameters
           of the covariance model and/or the total number of
           parameters to be estimated, if additional parameters of the
           covariance model are also estimated.

        *  `upper.kappa'
           See `lower.kappa'.

        *  `sill'
           Additionally to estimating `nugget' and `variance'
           separately, they may also be estimated together under the
           condition that `nugget' + `variance' = `sill'. For the
           latter a finite value for `sill' has to be supplied, and 
           `nugget' and  `variance' are set to `NA'.

        *  `use.naturalscaling'
           logical. If `TRUE' then internally, rescaled covariance
           functions will be used for which cov(1)~=0.05. However this
           parameter does not influence the output of `mleRF': the
           parameter vector returned by `mleRF' refers always to the
           standard covariance model as given in `CovarianceFct'. (In
           contrast to `PracticalRange' in `RFparameters'.)
           Advantages if `use.naturalscaling==TRUE':

           *  `scale' and the shape parameter of a parameterised
              covariance model can be estimated better if they are
              estimated simultaneously.

           *  The estimated bounds calculated  by means of
              `upperbound.scale.factor', `lowerbound.scale.factor',
              etc. might be more realistic.

        Disadvantages if `use.naturalscaling==TRUE':

           *  For some covariance models with additional parameters,
              the rescaling factor has to be determined numerically.
              Then, more time is needed to perform `mleRF'.

        Default: `TRUE'.

        *  `PrintLevel'
           0 : no message
           1 : error messages
           2 : warnings
           3 : minimum debugging information
           5 : extended debugging information, including graphics
           Default: `0'.

        *  `trace.optim'
           see control parameter `trace' of `optim'.  Default: `0'.

        *  `bins'
           number of bins for the empirical variogram (used in the
           auxiliary target function, which is described at the
           beginning of the Details).  Default: `20'.

        *  `distance.factor'
           right boundary of the last bin is calculated as
           `distance.factor' * (maximum distance between all pairs of
           points).  Default: `0.5'.

        *  `upperbound.scale.factor'
           The upper bound for the scale is determined as
           `upperbound.scale.factor' * (maximum distance between all
           pairs of points).  Default: `10'.

        *  `lowerbound.scale.factor'
           The lower bound for the scale is determined as (minimum
           distance between different pairs of points) /
           `lowerbound.scale.factor'.  Default: `20'.

        *  `lowerbound.scale.LS.factor'
           For the auxiliary target function a different lower bound
           for the scale is used. It is determined as (minimum distance
           between different pairs of points) /
           `lowerbound.scale.LS.factor'.  Default: `5'.

        *  `upperbound.var.factor'
           The upper bound for the variance and the nugget is
           determined as `upperbound.var.factor' * var(data).  Default:
           `10'.

        *  `lowerbound.var.factor'
           The lower bound for the variance and the nugget is
           determined as var(data) / `lowerbound.var.factor'.  If
           either the nugget or the variance is fixed, the parameter to
           be estimated must also be greater than `lowerbound.sill'. 
           Default: `100'.

        *  `lowerbound.sill'
           See `lowerbound.var.factor'.  Default: `1E-10'.

        *  `scale.max.relative.factor'
           If the initial scale value for the ML estimation obtained by
           the auxiliary target function is less than (minimum distance
           between different pairs of points) /
           `scale.max.relative.factor' it is assumed that a nugget
           effect is present.  In case the user set `nugget=0', the ML
           estimation is automatically performed for `nugget=NA'
           instead of `nugget=0'.  Note: if `scale.max.relative.factor'
           is greater than `lowerbound.scale.LS.factor' then `nugget'
           is never set to `NA' as the scale has the lower bound
           (minimum distance between different pairs of points) /
           `lowerbound.scale.LS.factor'.  Default: `1000'.

        *  `minbounddistance'
           If any value of the parameter vector returned from the ML
           estimation is closer than `minbounddistance' to any of the
           bounds or if any value has a relative distance smaller than
           `minboundreldist', then it is assumed that the MLE algorithm
           has dropped into a local minimum, and it will be continued
           with evaluating the ML target function on a grid, cf. the
           beginning paragraphs of the Details. Default: `0.001'.

        *  `minboundreldist'
           See `minbounddistance'.  Default: `0.02'.

        *  `approximate.functioncalls'
           In case the parameter vector is too close to the given
           bounds, the ML target function is evaluated on a grid to get
           a new initial value for the ML estimation.  The number of
           points of the grid is approximately
           `approximate.functioncalls'.  Default: `50'.

     Another maximum likelihood estimator for random fields exists as
     part of the package `geoR' whose homepage is at <URL:
     http://www.maths.lancs.ac.uk/~ribeiro/geoR.html>.  However, the
     philosophies of `mleRF' and `likfit' of the package `geoR' differ.
      The function `likfit' offers more possibilities and higher
     flexibility concerning co-variates and value transformations, for
     example.  By way of contrast, `mleRF' is still restricted to
     estimating parts of the parameter vector of a random field (as a
     consistent part of the package `RandomFields').  However, `mleRF'
     allows for estimating any combination of the components of this
     parameter vector.  In case both functions can be used, the
     parameters estimated by `likfit' and `mleRF' agree in about 95
     percent of the cases.  Concerning the remaining cases, `likfit'
     beats `mleRF' more frequently than vice versa; however `mleRF'
     does not need initial values for the optimisation, and the code of
     `mleRF' is in general faster.

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

     A vector of the form `c(mean,variance,nugget,sill,...)' is
     returned, i.e. the parameter vector of the ML estimation including
     the fixed components.  Here, the dots `...' stand for additional
     parameters of the covariance model, see `CovarianceFct'.

_A_c_k_n_o_w_l_e_d_g_e_m_e_n_t:

     Thanks to Paulo Ribeiro for hints and comparing `mleRF' to
     `likfit' of the package `geoR' whose homepage is at  <URL:
     http://www.maths.lancs.ac.uk/~ribeiro/geoR.html>.

_N_o_t_e:

     This function does not depend on the value of
     `RFparameters()$PracticalRange'.  The function `mleRF' always uses
     the standard specification of the covariance model as given in
     `CovarianceFct'.

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

     Ribeiro, P. and Diggle, P. (2001) Software for geostatistical
     analysis using R and S-PLUS: geoR and geoS, version 0.6.15. <URL:
     http://www.maths.lancs.ac.uk/~ribeiro/geoR.html>.

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

     `CovarianceFct', `GetPracticalRange', `RandomFields'.

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

      model <-"expon"
      param <- c(0,1,0,1)
      estparam <- c(NA,NA,0,NA) ## NA means here: "to be estimated"
      ## sequence in `estparam' is
      ## mean, variance, nugget, scale, (+ further model parameters)
      ## So, mean, variance, and scale will be estimated here.
      ## Nugget is fixed and equals zero.
      points <- 100
      x <- runif(points,0,3)
      y <- runif(points,0,3) ## 100 random points in square [0, 3]^2
      f <- GaussRF(x=x, y=y, grid=FALSE, model=model, param=param)
      mleRF(coord=cbind(x,y), data=f, model=model, param=estparam)

