\HeaderA{sensitivityZelig}{Perturbations-based Sensitivity Analysis of Zelig Models}{sensitivityZelig}
\aliasA{pzelig}{sensitivityZelig}{pzelig}
\keyword{misc}{sensitivityZelig}
\keyword{optimize}{sensitivityZelig}
\begin{Description}\relax
This is a wrapper to perturb analyses launches through Zelig, with
extension functions to summarize results.
\end{Description}
\begin{Usage}
\begin{verbatim}
sensitivityZelig(z, ptb.R=50, ptb.ran.gen=NULL, ptb.s=NULL, explanatoryOnly=FALSE, summarize=FALSE, simulate=FALSE, simArgs=NULL, ptb.rangen.ismatrix=FALSE)
        pzelig(...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{z}] an analysis output by \code{zelig} 
\item[\code{ptb.R}] number of replications for perturbation analysis 
\item[\code{ptb.ran.gen}] a single function, or a vector of functions to be
used to perturb each vector see \code{\LinkA{PTBi}{PTBi}} 
\item[\code{ptb.s}] a size, or vector of sizes, to be used in the vector perturbation functions
\item[\code{explanatoryOnly}] a flag indicating whether explanatory variables should be perturbed by default
\item[\code{summarize}] if true, return a sensitivity summary, as would \code{summary(sensitivityZelig())}. 
\item[\code{simulate}] if true, return a sensitivity summary, and a zelig simulation,
as would \code{psim(sensitivityZelig())}. This decreases system memory use,
and can significantly speed up analysis for large datasets.
\item[\code{simArgs}] a list of arguments to pass to psim, if simulate is true
\item[\code{...}] args as in sensitivityZelig
\item[\code{ptb.rangen.ismatrix}] If true, expects ptb.ran.gen to be a matrix function, for use
with correlated noise structure. See below
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Uses \code{sensitivity} to perform sensitivity analysis on a \code{zelig} model.
\end{Details}
\begin{Value}
Returns a list which contains the result  of each model run. Along
with attributes about the settings used in the perturbations.
Use \code{summary} to summarize the results or extract a matrix of
of the model parameters across the entire set of runs.
\end{Value}
\begin{Note}\relax
This was originally called "pzelig".
If ptb.ran.gen is not specified,  then \code{PTBdefault} will be used, with q=ptb.s, for each
explanatory variable in the input data. By default, response variables will also 
be perturbed, unless \code{explanatoryOnly} is true.
\end{Note}
\begin{Author}\relax
Micah Altman
\email{Micah\_Altman@harvard.edu}
\url{http://www.hmdc.harvard.edu/micah_altman/}
\end{Author}
\begin{References}\relax
Altman, M., J. Gill and M. P. McDonald.  2003.  \emph{Numerical Issues in Statistical
Computing for the Social Scientist}.  John Wiley \& Sons.
\url{http://www.hmdc.harvard.edu/numerical_issues/}
\end{References}
\begin{SeeAlso}\relax
See Also as \code{\LinkA{perturb}{perturb}},  \code{\LinkA{PTBdefault}{PTBdefault}},  \code{\LinkA{zelig}{zelig}},
\code{\LinkA{psim}{psim}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

# Sensitivity analysis of the classic longley data, as run through zelig.
#
# Note: Compare to the example documented under the main perturb page.

# example requires Zelig.

if(!is.R()){
  # splus version of require ignores quietly!
  ow<-options(warn=-1)
} else {
   data(longley)
   # accuracy supplies longley for SPLUS automagically, for examples only
}

# workaround for Zelig < 3.4 & R 2.8 & possible broken build environment
goodZelig <- require(Zelig,quietly=TRUE) && (!inherits(try(zelig(Employed~GNP,"ls",longley,cite=FALSE),silent=TRUE),"try-error"))
if (!is.R()) {
      options(ow)
}
if (goodZelig) { 
   
   # not used due to zelig bug: zelig.out=zelig(Employed~.,"ls",longley) 
   # run longley regression
   
   zelig.out=try(zelig(Employed~GNP.deflator+GNP+Unemployed+Armed.Forces+Population+Year,"ls",longley),silent=TRUE)

   # default settings
   perturb.zelig.out = sensitivityZelig(zelig.out)                 

   # Note: without zelig, the preceding would be:  perturb.out = perturb(longley,lm,Employed~.) 

   # plots the perturbed lm replications individually
   plot(perturb.zelig.out)        
   # summarizes the overall sensitivity of coefficient estimates
   summary(perturb.zelig.out)             
   plot(summary(perturb.zelig.out))
   
   # since the "ls" model relies on "lm" which supports anova, can summarize
   # using anova
   anova(perturb.zelig.out)
   plot(anova(perturb.zelig.out))
   
   # Up to this point, we could have done this without Zelig... here's the fun part.
  
   # set values of explanatory variables
   setx.out=setx(perturb.zelig.out, Year=1955)       

   # Note: could also have used setx.out=setx(z,Year=1955)  instead of the line above,
   #       or  simply called psim() below without setx.out, which would default to using setx(perturb.zelig.out)

   # use simulation to predict value of explanatory variable based on
   # 
   sim.perturb.zelig.out = psim(perturb.zelig.out,setx.out)

   # this plots the profile of the predicted distribution of the explanatory variable, Employed
   # around the point wher Year=1955, and other explanatory variables are at their midpoints

   plot(sim.perturb.zelig.out)

   # this provides a summary of the predicted distribution of the explanatory variable

   print(summary(sim.perturb.zelig.out))
   
 }
 if (!is.R()) {
   options(ow)
 }
\end{ExampleCode}
\end{Examples}

