\HeaderA{corSpher}{Spherical Correlation Structure}{corSpher}
\keyword{models}{corSpher}
\begin{Description}\relax
This function is a constructor for the \code{corSpher} class,
representing a spherical spatial correlation structure. Letting
\eqn{d}{} denote the range and \eqn{n}{} denote the nugget
effect, the correlation between two observations a distance
\eqn{r < d}{} apart is \eqn{1-1.5(r/d)+0.5(r/d)^3}{} when no
nugget effect is present and \eqn{(1-n)
(1-1.5(r/d)+0.5(r/d)^3)}{(1-n)*(1-1.5(r/d)+0.5(r/d)^3)}  
when a nugget effect is assumed. If \eqn{r \geq d}{r >= d} the
correlation is zero. Objects created using this constructor must later
be initialized using the appropriate \code{Initialize} method.
\end{Description}
\begin{Usage}
\begin{verbatim}
corSpher(value, form, nugget, metric, fixed)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{value}] an optional vector with the parameter values in
constrained form. If \code{nugget} is \code{FALSE}, \code{value} can
have only one element, corresponding to the "range" of the
spherical correlation structure, which must be greater than
zero. If \code{nugget} is \code{TRUE}, meaning that a nugget effect
is present, \code{value} can contain one or two elements, the first
being the "range" and the second the "nugget effect" (one minus the
correlation between two observations taken arbitrarily close
together); the first must be greater than zero and the second must be
between zero and one. Defaults to \code{numeric(0)}, which results in
a range of 90\% of the minimum distance and a nugget effect of 0.1
being assigned to the parameters when \code{object} is initialized.
\item[\code{form}] a one sided formula of the form \code{\textasciitilde{} S1+...+Sp}, or
\code{\textasciitilde{} S1+...+Sp | g}, specifying spatial covariates \code{S1}
through \code{Sp} and,  optionally, a grouping factor \code{g}. 
When a grouping factor is present in \code{form}, the correlation
structure is assumed to apply only to observations within the same
grouping level; observations with different grouping levels are
assumed to be uncorrelated. Defaults to \code{\textasciitilde{} 1}, which corresponds
to using the order of the observations in the data as a covariate,
and no groups.
\item[\code{nugget}] an optional logical value indicating whether a nugget
effect is present. Defaults to \code{FALSE}.
\item[\code{metric}] an optional character string specifying the distance
metric to be used. The currently available options are
\code{"euclidean"} for the root sum-of-squares of distances;
\code{"maximum"} for the maximum difference; and \code{"manhattan"}
for the sum of the absolute differences. Partial matching of
arguments is used, so only the first three characters need to be
provided. Defaults to \code{"euclidean"}.
\item[\code{fixed}] an optional logical value indicating whether the
coefficients should be allowed to vary in the optimization, or kept
fixed at their initial value. Defaults to \code{FALSE}, in which case
the coefficients are allowed to vary.
\end{ldescription}
\end{Arguments}
\begin{Value}
an object of class \code{corSpher}, also inheriting from class
\code{corSpatial}, representing a spherical spatial correlation
structure.
\end{Value}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{References}\relax
Cressie, N.A.C. (1993), "Statistics for Spatial Data", J. Wiley \& Sons.

Venables, W.N. and Ripley, B.D. (1997) "Modern Applied Statistics with
S-plus", 2nd Edition, Springer-Verlag.

Littel, Milliken, Stroup, and Wolfinger (1996) "SAS Systems for Mixed
Models", SAS Institute.

Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models
in S and S-PLUS", Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{Initialize.corStruct}{Initialize.corStruct}},
\code{\LinkA{summary.corStruct}{summary.corStruct}},
\code{\LinkA{dist}{dist}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
sp1 <- corSpher(form = ~ x + y)

# example lme(..., corSpher ...)
# Pinheiro and Bates, pp. 222-249
fm1BW.lme <- lme(weight ~ Time * Diet, BodyWeight,
                   random = ~ Time)
# p. 223
fm2BW.lme <- update(fm1BW.lme, weights = varPower())
# p 246 
fm3BW.lme <- update(fm2BW.lme,
           correlation = corExp(form = ~ Time))
# p. 249
fm6BW.lme <- update(fm3BW.lme,
          correlation = corSpher(form = ~ Time))

# example gls(..., corSpher ...)
# Pinheiro and Bates, pp. 261, 263
fm1Wheat2 <- gls(yield ~ variety - 1, Wheat2)
# p. 262 
fm2Wheat2 <- update(fm1Wheat2, corr =
   corSpher(c(28, 0.2),
     form = ~ latitude + longitude, nugget = TRUE))

\end{ExampleCode}
\end{Examples}

