\HeaderA{Variog.fit}{Fitting a parametric variogram model to an empirical variogram}{Variog.fit}
\keyword{file}{Variog.fit}
\begin{Description}\relax
This function estimates a parametric model fitted to an empirical 
variogram. The estimates are calculated using the weighted least squares 
method.
\end{Description}
\begin{Usage}
\begin{verbatim}
Variog.fit(emp.variog, variog.model="exponential", max.dist.fit=NULL, 
init.val=NULL, fix.nugget=FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{emp.variog}] an object of the class \kbd{emp.variog}, output of the function \code{Emp.variog} or of the function 
\code{avg.variog}.
\item[\code{variog.model}] character string giving the name of the parametric 
model to fit to the empirical variogram. Implemented models are 
\kbd{exponential}, \kbd{spherical}, \kbd{gauss}, \kbd{gencauchy}, and 
\kbd{matern}.
\item[\code{max.dist.fit}] number giving the maximum distance considered when fitting the variogram.
\item[\code{init.val}] numeric vector giving the initial values for the parameters. The number of initial values to be entered depends on the variogram model specified. 

If the variog.model specified is \kbd{exponential}, \kbd{spherical} or 
\kbd{gauss}, then the parameters required are, in order, the nugget 
effect, the variance and the range. 

If the variog.model specified is \kbd{gencauchy}, the parameters required 
are, in order, the nugget effect, the variance, the range, the smoothness 
parameter \kbd{a}, and the long-range parameter \kbd{b}.

If the variog.model specified is \kbd{matern} the parameters required are, 
in order, the nugget effect, the variance, the range, and the smoothness 
parameter \kbd{a}.

For more details on the valid range for the parameters and for the 
equation 
of the variogram models listed above, look below at the section "Details".
\item[\code{fix.nugget}] logical field indicating whether the nugget should be considered fixed or not. If \kbd{TRUE} the nugget effect will be assumed to be constant, and a value for the fixed nugget effect can be also provided. If the value provided is different from the one entered in the \kbd{init.val} field, then the value of the nugget effect is taken to be the one entered in the \kbd{init.val} field. 

If \kbd{FALSE} the nugget effect will be estimated along with the other parameters in the variogram model.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function estimates the parameters in the variogram model by minimizing the weighted least-square loss function

\deqn{LOSS(\theta) = \sum_k n_k [ \left( \frac{\hat{\gamma_k} - \gamma_k(\theta)}{\gamma_k(\theta)} \right)^2 ]}{}

where \eqn{n_k}{} is the number of pairs contributing to the variogram computation in the \eqn{k}{}th bin, \eqn{\hat{\gamma_k}}{} is the value of the empirical variogram in the \eqn{k}{}th bin and \eqn{\gamma_k(\theta)}{} is the value of the estimated parametric variogram model at the midpoint of the \eqn{k}{}th bin.

- Parametric variogram models -

The parametric model implemented for the variogram are: exponential (\kbd{exponential}), spherical(\kbd{spherical}), gaussian (\kbd{gauss}), generalized Cauchy (\kbd{gencauchy}) and Whittle-Matern (\kbd{matern}).

- \kbd{exponential}:

The equation of the exponential variogram with parameters the nugget 
effect, \eqn{\rho}{}, the variance, \eqn{\sigma^{2}}{}, and the range, 
\eqn{r}{}, is given by:

\deqn{\gamma(d) = \rho+\sigma^{2} \cdot (1-exp(- \frac{d}{r}))}{}

where \eqn{d}{} is the distance between the two locations and \eqn{\gamma(d)}{} is the value of the exponential variogram at distance \eqn{d}{}.

Notice that: the nugget effect, \eqn{\rho}{}, is a non-negative number, 
while the variance, \eqn{\sigma^2}{}, and the range, \eqn{r}{}, are positive 
numbers.


- \kbd{spherical}

The equation of the spherical variogram with parameters the nugget effect, 
\eqn{\rho}{}, the variance, \eqn{\sigma^{2}}{}, and the range, \eqn{r}{}, is 
given by:

\deqn{\gamma(d) = \rho+\sigma^{2} \cdot (\frac{3}{2} 
\cdot\frac{d}{r}-\frac{1}{2} \cdot \frac{d^3}{r^3})}{}

where \eqn{d}{} is the distance between the two locations and \eqn{\gamma(d)}{} is the value of the spherical variogram at distance \eqn{d}{}. 

Notice that: the nugget effect, \eqn{\rho}{}, is a non-negative number, 
while the variance, \eqn{\sigma^2}{}, and the range, \eqn{r}{}, are positive 
numbers.


- \kbd{gauss}

The equation of the gaussian variogram with parameters the nugget effect, 
\eqn{\rho}{}, the variance, \eqn{\sigma^{2}}{}, and the range, \eqn{r}{}, is 
given by:

\deqn{\gamma(d) = \rho+\sigma^{2} \cdot (1-exp(- \frac{d^2}{r^2} ))}{}

where \eqn{d}{} is the distance between the two locations and \eqn{\gamma(d)}{} is the value of the gaussian variogram at distance \eqn{d}{}.

Notice that: the nugget effect, \eqn{\rho}{}, is a non-negative number, 
while the variance, \eqn{\sigma^2}{}, and the range, \eqn{r}{}, are positive 
numbers.


- \kbd{gencauchy}

The equation of the generalized Cauchy variogram with parameters the 
nugget effect, \eqn{\rho}{}, the variance, \eqn{\sigma^{2}}{}, the range, 
\eqn{r}{}, the smoothness parameter, \eqn{a}{}, and the long-range parameter, \eqn{b}{}, is given by:

\deqn{\gamma(d) = \rho+\sigma^{2} \cdot 
(1-(1+\frac{d^a}{r^a})^{- \frac{b}{a}})}{}

where \eqn{d}{} is the distance between the two locations and \eqn{\gamma(d)}{} is the value of the generalized Cauchy variogram at distance \eqn{d}{}.

Notice that: the nugget effect, \eqn{\rho}{}, is a non-negative number, the 
variance, \eqn{\sigma^2}{}, and the range, \eqn{r}{}, are positive numbers, 
the smoothness parameter, \eqn{a}{}, is a number in \eqn{(0,2]}{}, and the long-range parameter, \eqn{b}{}, is a positive number.


- \kbd{matern}

The equation of the Whittle-Matern variogram with parameters the nugget 
effect, \eqn{\rho}{}, the variance, \eqn{\sigma^{2}}{}, the range, \eqn{r}{}, 
and the smoothness parameter, \eqn{a}{}, is given by:

\deqn{\gamma(d) = \rho+\sigma^{2} \cdot (1-(\frac{2^{1-a}}{\Gamma(a)}\cdot 
\frac{d^a}{r^a} \cdot K_{a}(\frac{d}{r}))}{}

where \eqn{d}{} is the distance between the two locations, \eqn{\gamma(d)}{} is the value of the Whittle-Matern variogram at distance \eqn{d}{}, \eqn{\Gamma}{} is the gamma function and \eqn{K_a}{} is the Bessel function of the third kind with parameter \eqn{a}{}.

Notice that: the nugget effect, \eqn{\rho}{}, is a non-negative number, the 
variance, \eqn{\sigma^2}{}, the range, \eqn{r}{}, and the smoothness 
parameter, \eqn{a}{}, are positive numbers.


- Defaults -

The default value for the maximum distance is \eqn{\frac{1}{2 \cdot \sqrt{2}}}{} times the maximum distance considered in the empirical variogram. 

Default for the initial values of the parameters is \kbd{NULL}, in which case the initial values for the parameters are determined internally and depend on the empirical variogram values.

By default, the nugget effect is not considered constant. Thus, the 
default value for the \code{fix.nugget} field is \kbd{FALSE}.
\end{Details}
\begin{Value}
The function returns a list with components given by: 
\begin{ldescription}
\item[\code{model}] name of the parametric model fitted to the empirical variogram.
\item[\code{nugget}] Estimate of the nugget effect.
\item[\code{variance}] Estimate of the variance.
\item[\code{range}] Estimate of the range.
\item[\code{additional.par}] Numeric vector with the estimates of the 
additional parameters required by the parametric variogram model. This is 
returned only if the parametric model fitted are \kbd{gencauchy} or 
\kbd{matern}
\end{ldescription}
\end{Value}
\begin{Author}\relax
Gel, Y., Raftery, A. E., Gneiting, T., Berrocal, V. J. \email{veronica@stat.washington.edu}.
\end{Author}
\begin{References}\relax
Gel, Y., Raftery, A. E., Gneiting, T. (2004). Calibrated 
probabilistic mesoscale weather field forecasting: the Geostatistical 
Output Perturbation (GOP) method (with discussion). \emph{Journal of the 
American Statistical Association}, \bold{Vol. 99 (467)}, 575--583.

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

Gneiting, T., Schlather, M. (2004). Stochastic models that separate 
fractal dimension and the Hurst effect. \emph{SIAM Review} \bold{46}, 
269--282.

Stein, M. L. (1999). \emph{Interpolation of Spatial Data - Some Theory for Kriging}. Springer-Verlag: New York.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{Emp.variog}{Emp.variog}} for computation of the empirical 
variogram of forecast errors, and \code{\LinkA{avg.variog}{avg.variog}} for computation 
of the empirical variogram of a random variable.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Loading data
library(fields)
library(RandomFields)
data(slp)
day <- slp$date.obs
id <- slp$id.stat
coord1 <- slp$lon.stat
coord2 <- slp$lat.stat
obs <- slp$obs
forecast <- slp$forecast

## Computing the empirical variogram
variogram <- 
Emp.variog(day=day,obs=obs,forecast=forecast,id=id,coord1=coord1,coord2=coord2,
cut.points=NULL,max.dist=NULL,nbins=NULL)
## Estimating parameters
## Without specifying initial values for the parameters
param.variog <- 
Variog.fit(emp.variog=variogram,variog.model="exponential",max.dist.fit=NULL,
init.val=NULL,fix.nugget=FALSE)
## Plotting the empirical variogram with the estimated parametric variogram superimposed
plot(variogram$bin.midpoints,variogram$empir.variog,xlab="Distance",ylab="Semi-variance")
lines(variogram$bin.midpoints,linesmodel(distance=variogram$bin.midpoints,
variog.model="exponential",param=c(param.variog$nugget,
param.variog$variance,param.variog$range)))

## Specifying the initial values for the parameters and keeping the nugget effect fixed
param.variog <- 
Variog.fit(emp.variog=variogram,variog.model="exponential",max.dist.fit=NULL,
init.val=c(0,2,100),fix.nugget=TRUE)
## Plotting the empirical variogram with superimposed the estimated parametric variogram
plot(variogram$bin.midpoints,variogram$empir.variog,xlab="Distance",ylab="Semi-variance")
lines(variogram$bin.midpoints,linesmodel(distance=variogram$bin.midpoints,
variog.model="exponential",param=c(param.variog$nugget,
param.variog$variance,param.variog$range)))


\end{ExampleCode}
\end{Examples}

