\name{mob}
\encoding{latin1}

\alias{mob}
\alias{mob-class}
\alias{coef.mob}
\alias{deviance.mob}
\alias{fitted.mob}
\alias{logLik.mob}
\alias{predict.mob}
\alias{print.mob}
\alias{residuals.mob}
\alias{sctest.mob}
\alias{summary.mob}
\alias{weights.mob}

\title{Model-based Recursive Partitioning}

\description{
  MOB is an algorithm for model-based recursive partitioning yielding
  a tree with fitted models associated with each terminal node.
}

\usage{
mob(formula, weights, data = list(), na.action = na.omit, model = glinearModel,
  control = mob_control(), \dots)

\method{predict}{mob}(object, newdata = NULL, type = c("response", "node"), \dots)
\method{summary}{mob}(object, node = NULL, \dots)
\method{coef}{mob}(object, node = NULL, \dots)
\method{sctest}{mob}(x, node = NULL, \dots)
}

\arguments{
  \item{formula}{A symbolic description of the model to be fit. This
    should be of type \code{y ~ x1 + \dots + xk | z1 + \dots + zl} where
    the variables before the \code{|} are passed to the \code{model} and
    the variables after the \code{|} are used for partitioning.}
  \item{weights}{An optional vector of weights to be used in the fitting
    process. Only non-negative integer valued weights are allowed (default = 1).}
  \item{data}{A data frame containing the variables in the model.}
  \item{na.action}{A function which indicates what should happen when the data
    contain \code{NA}s, defaulting to \code{\link{na.omit}}.}
  \item{model}{A model of class \code{"\linkS4class{StatModel}"}. See details
    for requirements.}
  \item{control}{A list with control parameters as returned by
    \code{\link{mob_control}}.}
  \item{\dots}{Additional arguments passed to the \code{fit} call for
    the \code{model}.}
  \item{object, x}{A fitted \code{mob} object.}
  \item{newdata}{A data frame with new inputs, by default the learning data
    is used.}
  \item{type}{A character string specifying whether the response should be
    predicted (inherited from the \code{predict} method for the \code{model})
    or the ID of the associated terminal node.}
  \item{node}{A vector of node IDs for which the corresponding method should
    be applied.}
}

\details{
Model-based partitioning fits a model tree using the following algorithm:
  \enumerate{
    \item \code{fit} a \code{model} (default: a generalized linear model
          \code{"\linkS4class{StatModel}"} with formula \code{y ~ x1 + \dots + xk}
	  for the observations in the current node.
    \item Assess the stability of the model parameters with respect to each
          of the partitioning variables \code{z1}, \dots, \code{zl}. If
	  there is some overall instability, choose the variable \code{z}
	  associated with the smallest \eqn{p} value for partitioning, otherwise
	  stop. For performing the parameter instability fluctuation test,
	  a \code{\link[sandwich]{estfun}} method and a \code{\link{weights}} method is
	  needed.
    \item Search for the locally optimal split in \code{z} by minimizing the
          objective function of the \code{model}. Typically, this will be
	  something like \code{\link{deviance}} or the negative \code{\link{logLik}}
	  and can be specified in \code{\link{mob_control}}.
    \item Re-fit the \code{model} in both children, using \code{\link{reweight}}
          and repeat from step 2.
  }
  
More details on the conceptual design of the algorithm can be found in 
Zeileis, Hothorn, Hornik (2008) and some illustrations are provided in
\code{vignette("MOB")}.  
  
For the fitted MOB tree, several standard methods are inherited if they are
available for fitted \code{model}s, such as \code{print}, \code{predict},
\code{residuals}, \code{logLik}, \code{deviance}, \code{weights}, \code{coef} and
\code{summary}. By default, the latter four return the result (deviance, weights,
coefficients, summary) for all terminal nodes, but take a \code{node} argument
that can be set to any node ID. The \code{sctest} method extracts the results
of the parameter stability tests (aka structural change tests) for any given
node, by default for all nodes. Some examples are given below.
}

\value{
  An object of class \code{mob} inheriting from \code{\link{BinaryTree-class}}.
  Every node of the tree is additionally associated with a fitted model.
}

\references{ 

   Achim Zeileis, Torsten Hothorn, and Kurt Hornik (2008). Model-Based
   Recursive Partitioning. \emph{Journal of Computational and Graphical Statistics}, 
   \bold{17}(2), 492--514.

}

\seealso{\code{\link{plot.mob}}, \code{\link{mob_control}}}

\examples{

set.seed(290875)

if(require("mlbench")) {

## recursive partitioning of a linear regression model
## load data
data("BostonHousing", package = "mlbench")
## and transform variables appropriately (for a linear regression)
BostonHousing$lstat <- log(BostonHousing$lstat)
BostonHousing$rm <- BostonHousing$rm^2
## as well as partitioning variables (for fluctuation testing)
BostonHousing$chas <- factor(BostonHousing$chas, levels = 0:1, 
                             labels = c("no", "yes"))
BostonHousing$rad <- factor(BostonHousing$rad, ordered = TRUE)

## partition the linear regression model medv ~ lstat + rm
## with respect to all remaining variables:
fmBH <- mob(medv ~ lstat + rm | zn + indus + chas + nox + age + 
                                dis + rad + tax + crim + b + ptratio,
  control = mob_control(minsplit = 40), data = BostonHousing, 
  model = linearModel)

## print the resulting tree
fmBH
## or better visualize it
plot(fmBH)

## extract coefficients in all terminal nodes
coef(fmBH)
## look at full summary, e.g., for node 7
summary(fmBH, node = 7)
## results of parameter stability tests for that node
sctest(fmBH, node = 7)
## -> no further significant instabilities (at 5\% level)

## compute mean squared error (on training data)
mean((BostonHousing$medv - fitted(fmBH))^2)
mean(residuals(fmBH)^2)
deviance(fmBH)/sum(weights(fmBH))

## evaluate logLik and AIC
logLik(fmBH)
AIC(fmBH)
## (Note that this penalizes estimation of error variances, which
## were treated as nuisance parameters in the fitting process.)


## recursive partitioning of a logistic regression model
## load data
data("PimaIndiansDiabetes", package = "mlbench")
## partition logistic regression diabetes ~ glucose 
## wth respect to all remaining variables
fmPID <- mob(diabetes ~ glucose | pregnant + pressure + triceps + 
                                  insulin + mass + pedigree + age,
  data = PimaIndiansDiabetes, model = glinearModel, 
  family = binomial())

## fitted model
coef(fmPID)
plot(fmPID)
plot(fmPID, tp_args = list(cdplot = TRUE))
}
}
\keyword{tree}