\HeaderA{dX}{First derivatives from harmonic fits.}{dX}
\aliasA{dT}{dX}{dT}
\aliasA{dY}{dX}{dY}
\aliasA{test.dT}{dX}{test.dT}
\aliasA{test.dX}{dX}{test.dX}
\aliasA{test.dY}{dX}{test.dY}
\keyword{manip}{dX}
\begin{Description}\relax
\code{dX} calculates the x-derivatives for gridded data in
longitude-latitude coordinates. Is based on the equations by Stephenson (1961) p. 162
\deqn{\frac{dA}{dx} = \frac{1}{r \cos(\phi)} * \frac{d}
{d\theta}}{dA/dx = 1/(r cos(PHI)) * d/dTHETA}
where PHI is the latitude in radians and THETA the longitude.

\code{dY} calculates the y-derivatives for gridded data in longitude-latitude coordinates. 
\deqn{\frac{dA}{dy} = \frac{1}{r} \frac{d}{d\phi}}{dA/dy= 1/r d/dPHI}.

\code{dT} calculates the e.g. time derivatives of a time series.

All functions solve for the gradients by fitting coeffiecients to a Fourier
approximation \deqn{p(x) = a_0 + \sum_i[a_i \cos(w_i x) + b_i \sin(w_i
x)]}{p(x) = a0 + sum(a[i] cos(w[i]*x) + b[i]sin(w[i]*x))} 
and dp(x)/dx is \deqn{\frac{dp(x)}{dx} = \sum[w_i(-a_i \sin(w_i x) +
b_i \cos(w_i x))]}{dp(x)/dx = sum(w[i](-a[i] sin(w[i]*x) + b[i]cos(w[i]*x)))}

Also see \code{\LinkA{derivFFT}{derivFFT}}.

Version 1.1-6:

(i) Correction to the wave number in \code{dX} and \code{dY} -
previously wave number was scaled as 1/[number of points] and gave incorrect magnitudes for the derivatives, but now the wave number is 1/distance.

(ii) Included a simple confidence check (chk.conf) to set coefficients
to zero when +- 1 sd includes zero. This check can be disabled. Note, it
is recommended to use the minimum value for maxhar.

(iii) Included new test routines to test the magnitudes of the gradients.
\end{Description}
\begin{Usage}
\begin{verbatim}
dX(lon,lat,Z,r=6.378e06,maxhar=NULL,mask.bad=TRUE,plot=FALSE,chk.conf=1)
dY(lon,lat,Z,r=6.378e06,maxhar=NULL,mask.bad=TRUE,plot=FALSE,chk.conf=1)
dT(y,maxhar=NULL,plot=FALSE,chk.conf=1)
test.dX(field=NULL,maxhar=7)
test.dY(field=NULL,maxhar=5)
test.dT(y=NULL,maxhar=15)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{lon}] Longitudes
\item[\code{lat}] Latitude
\item[\code{Z}] Field values of which the gradients are sought
\item[\code{r}] mean radius of Earth
\item[\code{maxhar}] Number of harmonics to include. If NULL, \code{maxhar} is set to the length of the series.
\item[\code{mask.bad}] 
\item[\code{y}] a time series (vector).
\item[\code{plot}] plot data and fit
\item[\code{field}] Field to which the test is applied (default: DNMI.slp)
\item[\code{chk.conf}] If not NULL, test whether conf. int. (+- chk.conf * sd) includes zero - if
so, set coefficient to zero.
\end{ldescription}
\end{Arguments}
\begin{Value}
A list: list(Z=Z,a=a,b=b,c=c,dZ=dZ,Z.fit=Z.fit,lon=lon,lat=lat)
of class "map"
\end{Value}
\begin{Author}\relax
R.E. Benestad
\end{Author}
\begin{Examples}
\begin{ExampleCode}
# Construct a test series:
t <- seq(-3,3,by=0.1)
nt <- length(t)
y <- 2*rnorm(nt) + 10*sin(t/4) - 7*sin(t/3) + 4*cos(t) - sin(2*t) + 2*cos(3*t) + 0.5*sin(4*t)
plot(y)

dydt <- dT(y)
lines(dydt$y.fit,col="red")
dydt.2 <- dT(y,maxhar=3)
lines(dydt.2$y.fit,col="blue",lty=2)

# First derivative
plot(dydt$dy,type="l")
lines(dydt.2$dy,col="blue",lty=2)

# Second derivative
dy2dt2<-dT(dydt$dy)
dy2dt2.2<-dT(dydt.2$dy)
plot(dy2dt2$dy,type="l")
lines(dy2dt2.2$dy,col="blue",lty=2)
\end{ExampleCode}
\end{Examples}

