\name{dsApplyPlot}
\alias{dsApplyPlot}
\title{Plots graphs from MCMC objects in database }
\description{
  Produces a plot for every parameter for every model in the current
  database. \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.
}
\usage{
dsApplyPlot(FUN, ..., chains, window, studentModelList = listStudentModels(), linkModelList = listLinkModels(), trimRegExp = NULL, maxparams = 99, prefix = "", ask = missing(prefix), silent = TRUE)
}
\arguments{
  \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{chains}{A vector of chains to extract data for.  By default it
    uses all chains which have positive length.}
  \item{window}{A vector containing the first and last cycle to use.  Last
  cycle defaults to length of smallest chain in database.  Burn-in
  defaults to 1001 for long series, 501 for short series and 1 for very
  short series.}
  \item{studentModelList}{List of names of student models to use.}
  \item{linkModelList}{List of names of link models to use..}
  \item{trimRegExp}{A regular expression for names of link or student
    models which will be trimmed from the list of models to be read.}
  \item{maxparams}{A interger given the maximum number of parameter to
    be read in a parameter set.  This saves reading really big parameter
    into memory and may avoid memory problems on some PCs.}
  \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.}
  \item{silent}{If false, the function will print messages about
    progress through the AMD file.}
}
\details{
 Applies a graphics function recursively to the models in a database.
 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}.

 The database used is the one referenced by the last call to
 \code{asp.dbConnect}.
  
 If the \code{prefix} argument is supplied, it generates a separate PDF
 file for each model to keep the plots organized.

 The arguments \code{studentModelList} and \code{linkModelsList}
 can be used to restrict calculations to a subset of models.  These
 arguments should be a list of model names.
}
\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.
}
\seealso{
  \code{\link[coda]{mcmc.list}},\code{\link{asp.dbConnect}},
  \code{\link{daCapoApplyPlot}},\code{\link{dsApplyPrint}},
  \code{\link[grDevices]{pdf}},
  \code{\link[graphics]{title}},\code{\link[graphics]{par}},
  \code{\link{grandPlots}}
}

\author{Russell Almond}
\note{
  This function is like doing \code{daCapo} and \code{daCapoApplyPlot}
  in one function call.  However, rather than create a large daCapo
  object in memory, it reads the data for one model at a time and then
  discards it.  Thus, it takes longer, but uses less memory.
}
\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")

  ## Save plots to PDF files
  dsApplyPlot(grandPlots,prefix="test_")

  \dontrun{
  ## Plot on screen, but only use first two link models
  X11()
  dsApplyPlot(dc,autocorr.plot,whichLinkModels=1:2)
  dev.off()
  }
}
}
\keyword{database}