.\" -*- nroff -*- generated from .Rd format
.BG
.FN likfit
.TL
Likelihood Estimation for Gaussian Random Fields
.DN
This function estimates the parameters of a (transformed) Gaussian
random field using either maximum likelihood (ML) or restricted maximum
likelihood (REML).
Includes option for the estimation the Box-Cox transformation parameter.
.CS

likfit(geodata, coords=geodata$coords, data=geodata$data, trend = "cte",
       ini, fix.nugget = FALSE, nugget = 0, 
       cov.model = c("matern", "exponential", "gaussian", "spherical",
         "circular", "cubic", "wave", "powered.exponential",
         "cauchy", "gneiting", "gneiting.matern", "pure.nugget"),
       kappa = 0.5, fix.lambda = TRUE, lambda = 1, method = "ML", 
       predicted = FALSE, residuals = FALSE, 
       automatic.refit = FALSE, range.limits, messages.screen = TRUE, ...) 

.RA
.AG geodata
a list containing elements `coords' and
`$data' described below. If not provided the arguments
`coords' and `data' must be provided instead.
.AG coords
an n x 2 matrix containing in each row Euclidean
coordinates of the n data locations. By default it takes the
element `$coords' of the argument `geodata'.
.AG data
a vector with data values. By default it takes the
element `$data' of the argument `geodata'.
.AG trend
specifies the mean part of the model. The options are:
`"cte"' (constant mean - default option), `"1st"' (a first degree polynomial
on the coordinates), `"2nd"' (a second degree polynomial
on the coordinates), or a formula of the type `~X' where `X'
is a matrix with the covariates (external trend). 
.AG ini
initial values of the covariance parameters. These values
are used to initiate the numerical minimizer. If the model to be
fitted has 3 parameters: nugget (tau^2), sill (sigma^2)
and range (phi), `ini' is a vector with initial values for
these tree parameters. If the model to be fitted does not have has
nugget `ini' is a vector with 2 components, the initial values for
sigma^2 and phi. If `ini' is a matrix with several
initial values on the rows a search for the better initial value is
performed. The values of the likelihood function is computed for each of
them and the row with maximum value is used to initiate the numerical maximization.
.AG fix.nugget
A flag indication whether or not the nugget parameter
must be included in the estimation. If `fix.nugget = T' the
argument `ini' must be a vector of length 2 or a matrix with 2 columns
.AG nugget
Value of the nugget parameter when `fix.nugget = TRUE'. Defaults to zero.
.AG cov.model
model for the correlation function. See options in the
function call and/or documentation for the function `cov.spatial'. 
.AG kappa
extra parameter needed for some of the correlation
functions: (`"matern", "powered.exponential", "gneiting"' and
`"gneiting.matern"'). For more details see documentation for the
function `cov.spatial'. This parameter is always regarded
as fixed during the ML/REML parameter estimation.
.AG fix.lambda
If `TRUE' (default option) the transformation parameter is regarded as fixed (known) during the estimation process otherwise the ML/REML for this parameter is also computed.
.AG lambda
Box-Cox transformation parameter. Two particular cases are lambda = 1 which corresponds to no
transformation and lambda = 0 corresponding to the log-transformation.    The value of the transformation parameter lambda is regarded as a fixed value for the parameter if `fix.lambda = TRUE' or is used as a initial value in the search if  `fix.lambda = FALSE'.
.AG method
`ML' for maximum likelihood or `REML' for restricted maximum likelihood.
.AG predicted
a matrix with the several compnents of the predicted values, at the data locations.
.AG residuals
a matrix with several components of the residuals
(random parsto of the model), at the data locations.
.AG automatic.refit
Defaults to `FALSE'. If set to `TRUE' the model is automatically
changed and fitted again as follows:

.in +


.ti -\w@*\ @u
* In the case of a model with nugget, if the relative nugget
is less than 0.01 the model without nugget is fitted.

.ti -\w@*\ @u
* If the range parameters is less than 1e-12 or a value
provided in the argument `range.limits' a model without
spatial correlation is fitted.

.in -


.AG range.limits
minimum and maximum values allowed for the
correlation function parameter (range). Defaults to  `c(0, +Inf)'.
.AG messages.screen
a flag `TRUE' or `FALSE' indicating
whether or not messages are printed on the screen (or output device)
while the function is running.
.AG \&...
additional parameters to be passed to `nlminb'. 
Typically `control' type arguments which controls the
behavior of the minimization algorithm. See documentation of
`nlminb' for further details.
.RT
A list with the following components:
.AG cov.model
a string with the name of the correlation
function. See function call for the options.
.AG nugget
value of the nugget parameter tau^2. This
is the estimated value if `fix.nugget = FALSE' or the fixed
(known) value if `fix.nugget = TRUE'.
.AG cov.pars
a 2 elements vector with the estimated sill and range
parameters, respectively.
.AG kappa
(fixed) value of the smoothness parameter required by
some of the correlation functions.
.AG beta
estimated mean parameters. Can be either a scalar or
vector depending on the trend model (covariates) used.
.AG beta.var
variance (or covariance matrix) of the mean parameter. 
.AG lambda
Box-Cox transformation parameter. A fixed (know) value if
`fix.lambda = TRUE' or the estimated value if `fix.lambda = FALSE'.
.AG loglik
the value of the maximized likelihood.
.AG npars
number of estimated parameters.
.AG AIC
Value of the Akaike information criteria.
.AG BIC
Value of the Bayesian information criteria.
.AG trend.ols
Trend (mean parameters) estimated by ordinary least
squares (i.e. ignoring the spatial correlation).
.AG info.lambda
information about the Box-Cox transformation
parameter to be used by other functions which uses the output of `likfit()'.
.AG method
Estimation method used, `"ML"' (maximum likelihood)
or `"REML"' (restricted maximum likelihood).
.AG s2
estimated residual variance. Only returned if
`predicted = TRUE' or 
.br
 `residuals = TRUE'.
.AG predicted
predicted values at data locations. Only returned if
`predicted = TRUE'.
.AG residuals
estimated residuals at data locations. Only returned if
`residuals = TRUE'.
.AG info
results returned by the `nlminb'.
.AG max.dist
maximum distance found between 2 data points. This
information is used by other functions which uses results from `likfit()'.
.AG trend.matrix
trend matrix (covariates).
.AG call
the function call.
Note
`proflik.phi', `proflik.ftau', `proflik.nug' are
auxiliary functions which computed the value of the likelihood for
models without nugget, with a fixed nugget and including nugget,
respectively.
These functions are internally called by `nlminb' when
estimating the model parameters..SH REFERENCES
Further information about `geoR/geoS' can be found at:
.br
<URL: http://www.maths.lancs.ac.uk/~ribeiro/geoR.html>
.SA
`summary.variomodel', `olsfit',
`wlsfit', 
`plot.variogram', `lines.variogram',
`lines.variomodel', `proflik',
`optim', `nlm'.
.EX
data(s100)
ml <- likfit(s100, ini=c(\&.5, .5), fix.nug=T)
summary(ml)
reml <- likfit(s100, ini=c(\&.5, .5), fix.nug=T, met="REML")
summary(reml)
plot(variog(s100))
lines(ml)
lines(reml, lty=2)

.KW spatial
.WR
