\HeaderA{Emp.variog}{Empirical variogram of forecast errors averaged over time}{Emp.variog}
\keyword{file}{Emp.variog}
\begin{Description}\relax
Calculates the empirical variogram of forecast errors, averaged over time.
\end{Description}
\begin{Usage}
\begin{verbatim}
Emp.variog(day, obs, forecast, id, coord1, coord2, cut.points=NULL, max.dist=NULL, nbins=300)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{day}] numeric vector containing the day of observation.
\item[\code{obs}] numeric vector containing the observed weather quantity.
\item[\code{forecast}] numeric vector containing the forecasted weather quantity.
\item[\code{id}] vector with the id of the metereological stations.
\item[\code{coord1}] vector containing the longitudes of the metereological stations.
\item[\code{coord2}] vector containing the latitudes of the metereological stations.
\item[\code{cut.points}] numeric vector containing the cutpoints used for variogram binning.
\item[\code{max.dist}] a numerical value giving the upper bound for the distance considered in the variogram computation.
\item[\code{nbins}] a numerical value giving the number of bins for variogram 
binning. If both \code{cut.points} and \code{nbins} are entered, the entry 
for \code{nbins} will be ignored and the vector with the cutpoints will 
instead be used for variogram binning.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function includes bias-correction; it regresses the forecasts on the 
observed weather quantity and computes the residuals. The empirical variogram of the residuals is then calculated by determining, for each day, the distance among all pairs of stations that have been observed in the same day and by calculating for each day the sum of all the squared differences in the residuals within each bin. These sums are then averaged over time, with weights for each bin given by the sum over time of the number of pairs of stations within the bin. 

The formula used is:
\deqn{ \gamma(h) = \sum_d \frac{1}{2N_{(h,d)}} (\sum_i (Y(x_{i}+h,d)-Y(x_{i},d))^2)}{}

where \eqn{\gamma(h)}{} is the empirical variogram at distance \eqn{h}{}, \eqn{N_{(h,d)}}{} is the number of pairs of stations that have been recorded at day \eqn{d}{} and whose 
distance is equal to \eqn{h}{}, and \eqn{Y(x_{i}+h,d)}{} and \eqn{Y(x_{i},d)}{} are, respectively, the values of the residuals on day \eqn{d}{} at stations located at \eqn{x_{i}+h}{} 
and \eqn{x_{i}}{}. Variogram binning is ignored in this formula.

\bold{- Defaults}

If the vector with the cutpoints is not specified, the cutpoints are determined so that there are \code{nbins} bins with approximately the same number of pairs per bin. 

If both the vector with the cutpoints and the number of bins, \code{nbins}, are unspecified, the function by default determines the cutpoints so that there are 300 bins with approximately the same number of pairs per bin. If both the vector with the cutpoints and the number of bins are provided, the entry for the number of bins is ignored and the vector with the cutpoints is used for variogram binning.

The default value for the maximum distance considered in the variogram computation is the \eqn{90}{}-th percentile of the distances between the stations.
\end{Details}
\begin{Value}
The function returns a list with components given by:
\begin{ldescription}
\item[\code{mar.var}] Marginal variance of the forecast errors.
\item[\code{bin.midpoints}] Numeric vector with midpoints of the bins used in the empirical variogram computation.
\item[\code{number.pairs}] Numeric vector with the number of pairs per bin.
\item[\code{empir.variog}] Numeric vector with the empirical variogram values.
\end{ldescription}
\end{Value}
\begin{Note}\relax
Depending on the data, the function might require substantial computing time. As a consequence, if the interest is in producing 
probabilistic weather forecasts and generating ensemble members, it is advised to save the output in a file and then use the 
\code{\LinkA{Variog.fit}{Variog.fit}} and \code{\LinkA{Field.sim}{Field.sim}} functions.
\end{Note}
\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.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{EmpDir.variog}{EmpDir.variog}} for directional empirical variogram of forecast errors averaged over time, \code{\LinkA{avg.variog}{avg.variog}} and 
\code{\LinkA{avg.variog.dir}{avg.variog.dir}} for, respectively, empirical and directional empirical variogram of a random variable averaged over time, and 
\code{\LinkA{Variog.fit}{Variog.fit}} for estimation of parameters in a parametric variogram model.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Loading data
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 variogram
## No specified cutpoints, no specified maximum distance
## Default number of bins
variogram <- Emp.variog(day=day,obs=obs,forecast=forecast,id=id,
coord1=coord1,coord2=coord2,cut.points=NULL,max.dist=NULL,nbins=NULL)
## Plotting variogram
plot(variogram$bin.midpoints,variogram$empir.variog,xlab="Distance",
ylab="Semi-variance",main="Empirical variogram")

## Computing variogram
## Specified cutpoints, specified maximum distance
## Unspecified number of bins
variogram <- 
Emp.variog(day=day,obs=obs,forecast=forecast,id=id,coord1=coord1,
coord2=coord2,cut.points=seq(0,1000,by=5),max.dist=800,nbins=NULL)
## Plotting variogram
plot(variogram$bin.midpoints,variogram$empir.variog,xlab="Distance",
ylab="Semi-variance",main="Empirical variogram")


\end{ExampleCode}
\end{Examples}

