\name{GeoWLS}
\alias{GeoWLS}
\alias{print.GeoWLS}
\encoding{UTF-8}
\title{WLS of Gaussian random fields}
\description{
 the function returns the parameter estimates of a Gaussian random field obtained by
 the weighted least squares estimator.
}
\usage{
GeoWLS(data, coordx, coordy=NULL,coordz=NULL, coordt=NULL, coordx_dyn=NULL, corrmodel, 
 distance="Eucl", fixed=NULL, grid=FALSE, maxdist=NULL,neighb=NULL,
 maxtime=NULL, optimizer='Nelder-Mead',
 numbins=NULL, radius=1, start=NULL, weighted=FALSE,optimization=TRUE,
 numbins_t=NULL)
}
\arguments{
 \item{data}{A \eqn{d}{d}-dimensional vector (a single spatial realisation) or a (\eqn{d \times d}{d x d})-matrix (a single spatial realisation on regular grid) or a
 (\eqn{t \times d}{t x d})-matrix (a single spatio-temporal realisation) or an (\eqn{d \times d \times t \times n }{d x d x t})-array
 (a single spatio-temporal realisation on regular grid). See \code{\link{GeoFit}} for details.}
 \item{coordx}{A numeric (\eqn{d \times 2}{d x 2})-matrix or (\eqn{d \times 3}{d x 3})-matrix 
 Coordinates on a sphere for a fixed radius \code{radius} 
 are passed in lon/lat format expressed in decimal degrees.}
 \item{coordy}{A numeric vector giving 1-dimension of
 spatial coordinates; Optional argument, the default is \code{NULL}.}
 \item{coordz}{A numeric vector giving 1-dimension of
 spatial coordinates; Optional argument, the default is \code{NULL}.}
 \item{coordt}{A numeric vector giving one dimension of temporal coordinates. Optional argument; the default is \code{NULL}, in which case a spatial random field is expected. Temporal coordinates may be irregularly spaced; temporal lags are computed from the supplied coordinate values.}
 \item{coordx_dyn}{A list of \eqn{m} numeric (\eqn{d_t \times 2}{d x 2})-matrices
 containing dynamical (in time) spatial coordinates. Optional argument, the default is \code{NULL}
 } 
 \item{corrmodel}{String; the name of a correlation model, for the
 description (see \code{\link{GeoFit}}).}
 \item{distance}{String; the name of the spatial distance. The default is \code{Eucl},
 the Euclidean distance. See \code{\link{GeoFit}} for details.
		 of \code{\link{GeoFit}}.}
 \item{fixed}{A named list giving the values of the parameters that
 will be considered as known values. The listed parameters for a
 given correlation function will be not estimated, i.e. if
 \code{list(nugget=0)} the nugget effect is ignored.}
 \item{grid}{Logical; if \code{FALSE} (the default) the data
 are interpreted as a vector or a (\eqn{n \times d}{n x d})-matrix,
 instead if \code{TRUE} then (\eqn{d \times d
 \times n}{d x d x n})-matrix is considered.}
 \item{maxdist}{A numeric value denoting the maximum distance, see
 \code{\link{GeoFit}} for details.}
 \item{neighb}{Numeric; an optional positive integer indicating the 
 order of neighborhood. See \code{\link{GeoFit}} for details}
 \item{maxtime}{Numeric; an optional positive maximum temporal lag, expressed in the same units as \code{coordt}. See \code{\link{GeoFit}} for details.}
 \item{optimizer}{String; the optimization algorithm
 (see \code{\link{optim}} for details). 'Nelder-Mead' is the
 default.}
 \item{numbins}{Historical GeoModels argument giving the number of spatial bin boundaries; \code{numbins - 1} empirical spatial classes are used. See Details.}
 \item{numbins_t}{Optional positive integer giving the number of temporal classes for irregularly spaced \code{coordt}. If \code{NULL}, \code{numbins - 1} is used. Regularly spaced times use their directly attainable temporal lags.}
 \item{radius}{Numeric; a value indicating the radius of the sphere when using the great circle distance. Default value is 1.} 
 \item{start}{A named list with the initial values of the
 parameters that are used by the numerical routines in maximization
 procedure. \code{NULL} is the default (see \code{\link{GeoFit}}).}
 \item{weighted}{Logical; if \code{TRUE} then the weighted least square
 estimator is considered. If \code{FALSE} (the
 default) then the classic least square is used.}
 \item{optimization}{Logical; if \code{TRUE} then the weighted least square
 minimization is performed. Otherwise the weighted least square function is evaluated at the starting value.} 
}

\details{
 \code{GeoWLS} is defined for Gaussian random fields and therefore does
 not expose a \code{model} argument. Its native least-squares kernels compare
 the empirical variogram with the Gaussian variogram parameterized by nugget,
 sill, and the selected correlation model.

 The historical \code{numbins} parameter gives the number of spatial bin
 boundaries, so \code{numbins - 1} spatial classes are used. For
 spatio-temporal data, regular temporal coordinates are handled from their
 common spacing without constructing all pairwise temporal differences;
 irregular temporal coordinates use \code{numbins_t} temporal classes.

 Empty empirical cells are retained in the rectangular spatial-temporal lag
 grid and are skipped by the least-squares objective through their zero pair
 count. This preserves the correspondence between empirical cells and their
 spatial/temporal lags.

 The \code{maxdist} parameter indicates the positive finite maximum distance
 below which pairs are considered in the (weighted) least squares.
}

\value{
 Returns an object of class \code{WLS}.
 An object of class \code{WLS} is a list containing
 at most the following components:

 \item{bins}{Adjacent intervals of grouped distances;}
 \item{bint}{Adjacent intervals of grouped temporal separations}
 \item{centers}{The centers of the bins;}
 \item{coordx}{The vector or matrix of spatial coordinates;}
 \item{coordy}{The vector of spatial coordinates;}
 \item{coordt}{The vector of temporal coordinates;}
 \item{convergence}{A string that denotes if convergence is reached;}
 \item{corrmodel}{The correlation model;}
 \item{data}{The vector or matrix of data;}
 \item{distance}{The type of spatial distance;}
 \item{fixed}{The vector of fixed parameters;}
 \item{iterations}{The number of iteration used by the numerical routine;}
 \item{maxdist}{The maximum spatial distance used for the calculation of the variogram used in least square estimation.
 If no spatial distance is specified then it is NULL;}
 \item{maxtime}{The maximum temporal distance used for the calculation of the variogram used in least square estimation.
 If no temporal distance is specified then it is NULL;}
 \item{numbins_t}{The requested number of temporal classes for irregular time coordinates, or \code{NULL};}
 \item{message}{Extra message passed from the numerical routines;}
 \item{numcoord}{The number of spatial coordinates;}
 \item{numtime}{The number the temporal realisations of the random field;}
 \item{param}{The vector of parameters' estimates;}
 \item{variograms}{The empirical spatial variogram;}
 \item{variogramt}{The empirical temporal variogram;}
 \item{variogramst}{The empirical spatio-temporal variogram;}
 \item{weighted}{A logical value indicating if its the weighted
 method;}
 \item{wls}{The value of the least squares at the minimum.}

}

\references{

 Cressie, N. A. C. (1993) \emph{Statistics for Spatial Data}. New York:
 Wiley.

 Gaetan, C. and Guyon, X. (2010) \emph{Spatial Statistics and Modelling}.
 Springer-Verlag, New York.

}

\seealso{\code{\link{GeoFit}}, \code{\link{optim}}}



\author{Moreno Bevilacqua, \email{moreno.bevilacqua89@gmail.com},\url{https://sites.google.com/view/moreno-bevilacqua/home},
Víctor Morales Oñate, \email{victor.morales@uv.cl}, \url{https://sites.google.com/site/moralesonatevictor/},
Christian Caamaño-Carrillo, \email{chcaaman@ubiobio.cl},\url{https://www.researchgate.net/profile/Christian-Caamano}
}

 
\examples{
library(GeoModels)


# Set the coordinates of the sites:

set.seed(211)
x <- runif(200, 0, 1)
set.seed(98)
y <- runif(200, 0, 1)
coords <- cbind(x,y)

################################################################
###
### Example 1. Least square fitting of a Gaussian random field
### with exponential correlation.
###
###############################################################

# Set the model's parameters:
corrmodel <- "Exponential"
mean <- 0
sill <- 1
nugget <- 0
scale <- 0.15/3
param <- list(mean=0,sill=sill, nugget=nugget, scale=scale)
# Simulation of the Gaussian random field:
set.seed(2)
data <- GeoSim(coordx=coords, corrmodel=corrmodel, param=param)$data

fixed=list(nugget=0,mean=mean)
start=list(scale=scale,sill=sill)
# Least square fitting of the random field:
fit <- GeoWLS(data=data,coordx=coords, corrmodel=corrmodel,
 fixed=fixed,start=start,maxdist=0.5)

# Results:
print(fit)

}

\keyword{LeastSquare}
