\Header{lines.saddle.distn}{Add a Saddlepoint Approximation to a Plot}
\keyword{aplot}{lines.saddle.distn}
\keyword{smooth}{lines.saddle.distn}
\keyword{nonparametric}{lines.saddle.distn}
\begin{Description}\relax
This function adds a line corresponding to a saddlepoint density or 
distribution function approximation to the current plot.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'saddle.distn':
lines(x, dens = TRUE, h = function(u) u, J = function(u) 1, 
     npts = 50, lty = 1, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object of class \code{"saddle.distn"}  (see
\code{\Link{saddle.distn.object}} representing a saddlepoint
approximation to a distribution.

\item[\code{dens}] A logical variable indicating whether the saddlepoint density
(\code{TRUE}; the default) or the saddlepoint distribution function
(\code{FALSE}) should be plotted.

\item[\code{h}] Any transformation of the variable that is required.  Its first argument
must be the value at which the approximation is being performed and the
function must be vectorized.

\item[\code{J}] When \code{dens=TRUE} this function specifies the Jacobian for any
transformation that may be necessary.  The first argument of \code{J}
must the value at which the approximation is being performed and the
function must be vectorized. If \code{h} is supplied \code{J} must
also be supplied and both must have the same argument list.

\item[\code{npts}] The number of points to be used for the plot.  These points will be evenly
spaced over the range of points used in finding the saddlepoint
approximation.

\item[\code{lty}] The line type to be used.

\item[\code{...}] Any additional arguments to \code{h} and \code{J}.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function uses \code{smooth.spline} to produce the saddlepoint
curve.  When \code{dens=TRUE} the spline is on the log scale and when
\code{dens=FALSE} it is on the probit scale.
\end{Details}
\begin{Value}
\code{sad.d} is returned invisibly.
\end{Value}
\begin{Section}{Side Effects}
A line is added to the current plot.
\end{Section}
\begin{References}\relax
Davison, A.C. and Hinkley, D.V. (1997) 
\emph{Bootstrap Methods and Their Application}. Cambridge University Press.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{saddle.distn}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# In this example we show how a plot such as that in Figure 9.9 of
# Davison and Hinkley (1997) may be produced.  Note the large number of
# bootstrap replicates required in this example.
expdata <- rexp(12)
vfun <- function(d, i) 
{    n <- length(d)
     (n-1)/n*var(d[i])
}
exp.boot <- boot(expdata,vfun, R = 9999)
exp.L <- (expdata-mean(expdata))^2 - exp.boot$t0
exp.tL <- linear.approx(exp.boot, L = exp.L)
hist(exp.tL, nclass = 50, prob = TRUE)
exp.t0 <- c(0,sqrt(var(exp.boot$t)))
exp.sp <- saddle.distn(A = exp.L/12,wdist = "m", t0 = exp.t0)

# The saddlepoint approximation in this case is to the density of
# t-t0 and so t0 must be added for the plot.
lines(exp.sp,h = function(u,t0) u+t0, J = function(u,t0) 1,
      t0 = exp.boot$t0)
\end{ExampleCode}
\end{Examples}

