\name{daCapoApplyPlot}
\alias{daCapoApplyPlot}
\title{
 Applies a graphics function recursively to the parts of the daCapo
 object.
}
\description{
  Produces a plot for every parameter for every model in a daCapo
  object.  \code{FUN} is assumed to be a plotting function, which is
  applied to each parameter set.  If \code{prefix} is supplied, a
  separate PDF file is generated for each model's worth of plots.
}
\synopsis{
daCapoApplyPlot(daCapo.obj, FUN,...,
         whichStudentModels=1:length(daCapo.obj$studentModels),
         whichLinkModels=1:length(daCapo.obj$linkModels),
         prefix="",ask=missing(prefix))
}
\usage{
daCapoApplyPlot(daCapo.obj, FUN, ...,prefix=)
daCapoApplyPlot(daCapo.obj, FUN, ...,ask=TRUE)
daCapoApplyPlot(daCapo.obj, FUN, ..., whichStudentModels=,whichLinkModels=)
}

\arguments{
  \item{daCapo.obj}{A \code{daCapo} object holding data from a StatShop
    database.}
  \item{FUN}{A function which is assumed to be a graphics function,
    e.g., \code{plot}.}
  \item{\dots}{Additional arguments to the graphics function.}
  \item{whichStudentModels}{A vector which is used to select which
    student models are plotted.}
  \item{whichLinkModels}{A vector which is used to select which link
    models are plotted.}
  \item{prefix}{If supplied, then assume that output will be sent to a
    collection of PDF files.  The names of the files will be the model
    names with the prefix prepended.}
  \item{ask}{If true, the \code{ask} graphics parameter will be set to
    true.  Almost certainly useful for on-screen graphics.}
}
\details{
 Applies a graphics function recursively to the parts of the daCapo
 object.  The assumption is that each function generates a plot.
 In particular, a \code{sub} argument is added to each plot giving the
 name of the model and parameter, and the \code{ask} argument is passed
 along as well.  Note that the main objects passed to \code{FUN} are
 \code{mcmc.list} objects, so generic functions should have an
 appropriate method for \code{mcmc.list}.
 
 If the \code{prefix} argument is supplied, it generates a separate PDF
 file for each model to keep the plots organized.

 The arguments \code{whichStudentModels} and \code{whichLinkModels}
 can be used to print out only a subset of the models.  This is probably
 important for large plots.  These are used to subset the
 \code{studentModels} and \code{linkModels} components of 
 \code{daCapo.obj}, so any legal syntax for \code{"["} should work.
}
\section{Side Effects}{
  If prefix is given, it creates a number of PDF files.  Otherwise,
  graphics are created on screen.

  Note:  Wraps calls to \code{FUN} in try, so that errors in one model
  will be printed to console and the function will move on to the next
  model.
}
\note{
  This function \code{dsApplyPlot} is available for doing \code{daCapo}
  and \code{daCapoApplyPlot} in one function call.  Producing the
  \code{daCapo} object is more efficient if multiple diagnostics are to
  be run on the same object, but it can be very large in memory.
}
\seealso{
  \code{\link[coda]{mcmc.list}},\code{\link{daCapo}},
  \code{\link{daCapoApplyPrint}},\code{\link[grDevices]{pdf}},
  \code{\link[graphics]{title}},\code{\link[graphics]{par}},
  \code{\link{grandPlots}},\code{\link{dsApplyPlot}}
  
}
\examples{
### This example will only run if you have the StatShop test databases
### installed on your machine.
StatShop <- Sys.getenv("STATSHOP")
if (StatShop == "") {
  warn("StatShop not installed, skipping test.")
} else {
  asp.dbConnect("mcmc_statistics_test","junit")
  dc <- daCapo()
  ## Save plots to PDF files
  daCapoApplyPlot(dc,grandPlots,prefix="test_")
  ## Plot on screen, but only use first two link models
  \dontrun{
  X11()
  daCapoApplyPlot(dc,autocorr.plot,whichLinkModels=1:2)
  dev.off()
  }
  asp.dbDisconnect()
}
}
\keyword{database}