\HeaderA{update.formula}{Model Updating}{update.formula}
\keyword{models}{update.formula}
\begin{Description}\relax
\code{update.formula} is used to update model formulae.
This typically involves adding or dropping terms,
but updates can be more general.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'formula':
update(old, new, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{old}] a model formula to be updated.
\item[\code{new}] a formula giving a template which specifies how to update.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Either or both of \code{old} and \code{new} can be objects such as
length-one character vectors which can be coerced to a formula via
\code{\LinkA{as.formula}{as.formula}}.

The function works by first identifying the \emph{left-hand side}
and \emph{right-hand side} of the \code{old} formula.
It then examines the \code{new} formula and substitutes
the \emph{lhs} of the \code{old} formula for any occurrence
of \sQuote{.} on the left of \code{new}, and substitutes
the \emph{rhs} of the \code{old} formula for any occurrence
of \sQuote{.} on the right of \code{new}.  The result is then
simplified \emph{via} \code{\LinkA{terms.formula}{terms.formula}(simplify = TRUE)}.
\end{Details}
\begin{Value}
The updated formula is returned.  The environment of the result will
that of \code{old}.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{terms}{terms}}, \code{\LinkA{model.matrix}{model.matrix}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
update(y ~ x,    ~ . + x2) #> y ~ x + x2
update(y ~ x, log(.) ~ . ) #> log(y) ~ x
\end{ExampleCode}
\end{Examples}

