variofit                package:geoR                R Documentation

_V_a_r_i_o_g_r_a_m _B_a_s_e_d _P_a_r_a_m_e_t_e_r _E_s_t_i_m_a_t_i_o_n

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

     Estimate covariance parameters by fitting a parametric model to a
     empirical variogram. Variograms models can be fitted by using
     weighted or ordinary least squares.

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

     variofit(vario, ini.cov.pars, cov.model = "matern",
              fix.nugget = FALSE, nugget = 0,
              fix.kappa = TRUE, kappa = 0.5,
              simul.number = NULL, max.dist = vario$max.dist,
              weights, minimisation.function,
              limits = pars.limits(), messages, ...)

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

   vario: an object of the class '"variogram"', typically an output of
          the function 'variog'. The object is a list with information
          about the empirical variogram.  

ini.cov.pars: initial values for the covariance parameters: sigma^2
          (partial sill) and phi (range parameter). See 'DETAILS'
          below.  

cov.model: a string with the name of the correlation function. For
          further details see documentation for 'cov.spatial'. For the
          linear model use 'cov.model = "linear"'. Defaults are
          equivalent to the _exponential_ model.  

fix.nugget: logical, indicating whether the parameter tau^2 (nugget
          variance) should be regarded as fixed ('fix.nugget = TRUE')
          or should be estimated ('fix.nugget = FALSE'). Defaults to
          'FALSE'.  

  nugget: value for the nugget parameter.  Regarded as a fixed values
          if 'fix.nugget = TRUE' or as a initial value for the
          minimization algorithm if 'fix.nugget = FALSE'.  Defaults to
          zero.  

fix.kappa: logical, indicating whether the parameter kappa should be
          regarded as fixed or  be estimated. Defaults to 'TRUE'.  

   kappa: value of the smoothness parameter.  Regarded as a fixed
          values if 'fix.kappa = TRUE' or as a initial value for the
          minimization algorithm if 'fix.kappa = FALSE'. Only required
          if one of the following correlation functions is used:
          '"matern"', '"powered.exponential"', '"cauchy"' and
          '"gneiting.matern"'. Defaults to 0.5.  

simul.number: number of simulation. To be used when the object passed
          to the argument 'vario' has empirical variograms for more
          than one data-set (or simulation). Indicates to which one the
          model will be fitted.  

max.dist: maximum distance considered when fitting the variogram.
          Defaults to 'vario$max.dist'.  

 weights: type weights used in the loss function. See 'DETAILS' below.  

  limits: values defining lower and upper limits for the model
          parameters used in the numerical minimisation. Only valid if
          'minimisation.function = "optim"'. The auxiliary function
          'pars.limits' is called to set the limits.  

minimisation.function: minimization function used to estimate the
          parameters. Options are '"optim"', '"nlm"'. If 'weights =
          "equal"' the option  '"nls"' is also valid and det as
          default. Otherwise defaults to '"optim"'.  

messages: logical. Indicates whether or not status messages are printed
          on the screen (or other output device) while the function is
          running.  

     ...: further parameters to be passed to the minimization function.
          Typically arguments of the type 'control()' which controls
          the behavior of the minimization algorithm. See documentation
          for the  selected minimization function for further details.  

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

     *Numerical minimization*

     The parameter values are found by numerical optimization using one
     of the functions: 'optim', 'nlm' and 'nls'. In given circunstances
     the algorithm may not converge to correct parameter values when
     called with default options and the user may need to pass extra
     options for the optimizers. For instance the function 'optim'
     takes a 'control' argument. The user should try different initial
     values and if the parameters have different orders of magnitude
     may need to use options to scale the parameters. Some possible
     workarounds in case of problems include:

        *  rescale you data values (dividing by a constant, say)

        *  rescale your coordinates (subtracting values and/or dividing
           by constants)

        *  Use the  mechanism to pass 'control()' options for the
           optimiser internally

     *Initial values*

     The algorithms for minimization functions require initial values
     of the parameters.

     A unique initial value is used if a vector is provided in the
     argument 'ini.cov.pars'. The elements are initial values for
     sigma^2 and phi, respectively. This vector is concatenated with
     the value of the argument 'nugget' if 'fix.nugget = FALSE' and
     'kappa' if 'fix.kappa = TRUE'.

     Specification of multiple initial values is also possible. If this
     is the case, the function searches for the one which minimizes the
     loss function and uses this as the initial value for the
     minimization algorithm. Multiple initial values are specified  by
     providing a matrix in the argument 'ini.cov.pars' and/or, vectors
     in the arguments  'nugget' and 'kappa' (if included in the
     estimation). If 'ini.cov.pars' is a matrix, the first column has
     values of sigma^2 and the second has values of  phi. 

     Alternatively the argument 'ini.cov.pars' can take an object of
     the class 'eyefit' or 'variomodel'. This allows the usage  of an
     output of the functions 'eyefit', 'variofit' or 'likfit' be used
     as initial value.

     If 'minimisation.function = "nls"' only the values of phi and
     kappa (if this is included in the estimation) are used. Values for
     the remaning are not need by the algorithm.

     If 'cov.model = "linear"' only the value of sigma^2 is used.
     Values for the remaning are not need by this algorithm.

     If 'cov.model = "pure.nugget"' no initial values are needed since
     no minimisation function is used.

     *Weights*

     The different options for the argument 'weights' are used to
     define the loss function to be minimised. The available options
     are as follows.

     '"_n_p_a_i_r_s"' indicates that the weights are given by the number of
          pairs in each bin. This is the default option unless
          'variog$output.type == "cloud"'. The loss function is:

        LOSS(theta) = sum_k n_k (hat(gamma) - gamma(theta))^2


     '"_c_r_e_s_s_i_e"' weights as suggested by Cressie (1985).

 LOSS(theta) = sum_k n_k [(hat(gamma_k) - gamma_k(theta))/{gamma_k(theta)}]^2


     '"_e_q_u_a_l"' equal values for the weights. For this case the
          estimation corresponds to the ordinary least squares
          variogram fitting. This is the default option if
          'variog$output.type == "cloud"'.

          LOSS(theta) = sum_k (hat(gamma) - gamma(theta))^2


          Where theta is the vector with the variogram parameters and
          for each kth-bin n_k is the number of pairs, hat(gamma_k) is
          the value of the empirical variogram and gamma_k(theta) is
          the value of the theoretical variogram.

          See also Cressie (1993) and Barry, Crowder and Diggle (1997)
          for further discussions on  methods to estimate the variogram
          parameters.

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

     An object of the 'class' '"variomodel"' and '"variofit"' which is
     list with the following components: 

  nugget: value of the nugget parameter. An estimated value if
          'fix.nugget = FALSE' or a fixed value if 'fix.nugget = TRUE'.            

cov.pars: a two elements vector with estimated values of the covariance
          parameters sigma^2 and phi,  respectively.  

cov.model: a string with the name of the correlation function.  

   kappa: fixed value of the smoothness parameter.  

   value: minimized value of the loss function.  

max.dist: maximum distance considered in the variogram fitting. 

minimisation.function: minimization function used.  

 weights: a string indicating the type of weights used for the
          variogram fitting.  

  method: a string indicating the type of variogram fitting method (OLS
          or WLS).  

fix.kappa: logical indicating whether the parameter kappa was fixed.  

fix.nugget: logical indicating whether the nugget parameter was fixed.  

  lambda: transformation parameters inherith from the object provided
          in the argument 'vario'.  

 message: status messages returned by the function.  

    call: the function call.  

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

     Paulo Justiniano Ribeiro Jr. paulojus@leg.ufpr.br, 
      Peter J. Diggle p.diggle@lancaster.ac.uk.

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

     Barry, J.T., Crowder, M.J. and Diggle, P.J. (1997) Parametric
     estimation of the variogram. _Tech. Report, Dept Maths & Stats,
     Lancaster University_.

     Cressie, N.A.C (1985) _Mathematical Geology_. *17*, 563-586. 

     Cressie, N.A.C (1993) _Statistics for Spatial Data_. New York:
     Wiley.

     Further information on the package 'geoR' can be found at:
      <URL: http://www.leg.ufpr.br/geoR>.

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

     'cov.spatial' for a detailed description of the available
     correlation (variogram) functions, 'likfit' for maximum and
     restricted maximum likelihood estimation, 'lines.variomodel' for
     graphical output of the fitted model. For details on the
     minimization functions see 'optim', 'nlm' and 'nls'.

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

     vario100 <- variog(s100, max.dist=1)
     ini.vals <- expand.grid(seq(0,1,l=5), seq(0,1,l=5))
     ols <- variofit(vario100, ini=ini.vals, fix.nug=TRUE, wei="equal")
     summary(ols)
     wls <- variofit(vario100, ini=ini.vals, fix.nug=TRUE)
     summary(wls)
     plot(vario100)
     lines(wls)
     lines(ols, lty=2)

