\HeaderA{parse.formula}{Parsing user-input formulas into multiple syntax}{parse.formula}
\keyword{utilities}{parse.formula}
\begin{Description}\relax
Parse the input formula (or list of formulas) into the 
standard format described below.  Since labels for this format will vary 
by model, \code{parse.formula} will evaluate a function \code{describe.model},
where \code{model} is given as an input to \code{parse.formula}.

If the \code{describe.model} function has more than one parameter for
which \code{ExpVar = TRUE} and \code{DepVar = TRUE}, then the
user-specified equations must have labels to match those parameters,
else \code{parse.formula} should return an error. In addition, if the
formula entries are not unambiguous, then \code{parse.formula} returns an error.
\end{Description}
\begin{Usage}
\begin{verbatim}
parse.formula(formula, model, data = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] either a single formula or a list of \code{formula} objects
\item[\code{model}] a character string specifying the name of the model
\item[\code{data}] an optional data frame for models that require a factor response variable
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Acceptable user inputs are as follows:

\Tabular{lll}{
& User Input   & Output from \code{parse.formula}\\
& & \\
Same covariates, & cbind(y1, y2) ~ x1 + x2 * x3  & list(mu1 = y1 ~ x1 + x2 * x3,\\
separate effects &                               &      mu2 = y2 ~ x1 + x2 * x3,\\
&                               &      rho = ~ 1)\\
& & \\
With \code{rho} as a & list(cbind(y1, y2) ~ x1 + x2, & list(mu1 = y1 ~ x1 + x2,\\
systematic equation  & rho = ~ x4 + x5)              &      mu2 = y2 ~ x1 + x2,\\
&                               &      rho = ~ x4 + x5)\\
& & \\
With constraints & list(mu1 = y1 ~ x1 + tag(x2, "x2"), & list(mu1 = y1 ~ x1 + tag(x2, "x2"),\\
(same variable)  &      mu2 = y2 ~ x3 + tag(x2, "x2")) &      mu2 = y2 ~ x3 + tag(x2, "x2"),\\
&                                     &      rho = ~ 1)\\
& & \\
With constraints &  list(mu1 = y1 ~ x1 + tag(x2, "z1"), & list(mu1 = y1 ~ x1 + tag(x2, "z1"),\\
(different variables) &     mu2 = y2 ~ x3 + tag(x4, "z1")) &     mu2 = y2 ~ x3 + tag(x4, "z1"),\\
&                                  &         rho = ~ 1)\\
}
\end{Details}
\begin{Value}
The output is a list of formula objects with class 
\code{c("multiple", "list")}.  Let's say that the name of the model is 
\code{"bivariate.probit"}, and the corresponding describe function is 
\code{describe.bivariate.probit}, which identifies \code{mu1} and 
\code{mu2} as systematic components, and an ancillary parameter \code{rho}, which
may be parameterized, but is estimated as a scalar by default.
\end{Value}
\begin{Author}\relax
Kosuke Imai <\email{kimai@princeton.edu}>; Gary King
<\email{king@harvard.edu}>; Olivia Lau <\email{olau@fas.harvard.edu}>; Ferdinand Alimadhi 
<\email{falimadhi@iq.harvard.edu}>
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{parse.par}{parse.par}}, \code{\LinkA{model.frame.multiple}{model.frame.multiple}}, 
\code{\LinkA{model.matrix.multiple}{model.matrix.multiple}}, and the full Zelig manual at
\url{http://gking.harvard.edu/zelig}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
data(sanction)
formulae <- list(cbind(import, export) ~ coop + cost + target)
fml <- parse.formula(formulae, model = "bivariate.probit")
D <- model.frame(fml, data = sanction)
## End(Not run)\end{ExampleCode}
\end{Examples}

