\name{daCapo}
\alias{daCapo}
\title{
  Creates a daCapo object with the contents of a StatShop database.
}
\description{
  Reads a StatShop database and creates a \code{daCapo} object which
  consists of a collection of \code{mcmc.list} objects organized by model
  and variable.   Other functions can then produce summaries of these
  results.
}
\usage{
daCapo(chains, window, studentModelList = listStudentModels(),
         linkModelList = listLinkModels(),trimRegExp=NULL,maxparams=99)
}
\arguments{
  \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}{A list of names of student models whose data
    will be read.}
  \item{linkModelList}{A list of names of link models whose data will be
    read.}
  \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.
    }
}
\value{
  An object of class \code{daCapo}.  The two primary components
  \code{studentModels} and \code{linkModels} each contains a list
  indexed by model name, and each list contains a list of
  \code{mcmc.list} objects indexed by the name of a variable in the
  model.  Thus the essential structure is a list of lists of
  \code{mcmc.list} objects. 

  \item{studentModels}{All student models in the database (after filtering).}
  \item{linkModels}{All link models in the database (after filtering).}
  \item{chains}{The list of chains used for this extract.}
  \item{window}{The time series window used for this extract.}
}
\details{
  This function automates most of the work of extracting coda objects
  from the StatShop database.  It tries to read the meta-data from the
  database and perform a sensible extraction.

  The resulting data structure is pretty complex and generally should be
  stored to a variable rather than printed.  Two utility functions
  \code{daCapoApplyPrint} and \code{daCapoApplyPlot} recursively apply
  \code{coda} functions to each of the arguments.
}
\note{
  The result of the \code{daCapo} function is typically a quite large
  object, and can exceed memory limits (especially under Windows).  The
  fucntions \code{dsApplyPlot} and \code{dsApplyPrint} do much the same
  as \code{daCapo} plus \code{daCapoApplyPlot} or \code{daCapoApplyPlot}
  without generating the large \code{daCapo} object.

  If multiple analyses are to be made on the same database, then
  \code{daCapo} is more efficient, but uses much more memory.
}

\seealso{
  \code{\link[coda]{mcmc.list}},\code{\link{daCapoApplyPlot}},
  \code{\link{daCapoApplyPrint}},\code{\link{asp.dbConnect}},
  \code{\link{buildRMatrix}}
}
\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()
  daCapoApplyPrint(dc,summary)
  asp.dbDisconnect()
}
}
\keyword{database}