\name{addvar}
\alias{addvar}
\title{
  Added Variable Plot for Point Process Model
}
\description{
  Computes the coordinates for an Added Variable Plot
  for a fitted point process model.
}
\usage{
addvar(model, covariate, ...,
                   subregion=NULL,
                   bw="nrd0", adjust=1,
                   from=NULL, to=NULL, n=512,
                   bw.input = c("points", "quad"),
                   bw.restrict = FALSE,
                   covname, crosscheck=FALSE)
}
\arguments{
  \item{model}{
    Fitted point process model (object of class \code{"ppm"}).
  }
  \item{covariate}{
    The covariate to be added to the model. Either a
    pixel image, a \code{function(x,y)}, or a character string
    giving the name of a covariate that was supplied when
    the model was fitted.
  }
  \item{subregion}{
    Optional.  A window (object of class \code{"owin"})
    specifying a subset of the spatial domain of the data.
    The calculation will be confined to the data in this subregion.
  }
  \item{bw}{
    Smoothing bandwidth or bandwidth rule
    (passed to \code{\link[stats]{density.default}}).
  }
  \item{adjust}{
    Smoothing bandwidth adjustment factor
    (passed to \code{\link[stats]{density.default}}).
  }
  \item{n, from, to}{
    Arguments passed to \code{\link[stats]{density.default}} to
    control the number and range of values at which the function
    will be estimated.
  }
  \item{\dots}{
    Additional arguments passed to \code{\link[stats]{density.default}}.
  }
  \item{bw.input}{
    Character string specifying the input data used for automatic
    bandwidth selection. 
  }
  \item{bw.restrict}{
    Logical value, specifying whether bandwidth selection is performed using
    data from the entire spatial domain or from the \code{subregion}.
  }
  \item{covname}{
    Optional. Character string to use as the name of the covariate.
  }
  \item{crosscheck}{
    For developers only.
    Logical value indicating whether to perform
    cross-checks on the validity of the calculation.
  }
}
\details{
  This command generates the plot coordinates for an Added Variable Plot
  for a spatial point process model.
  
  Added Variable Plots (Cox, 1958, sec 4.5; Wang, 1985)
  are commonly used in linear models and generalized linear
  models, to decide whether a model with response \eqn{y} and predictors \eqn{x}
  would be improved by including another predictor \eqn{z}.
  
  In a (generalised) linear model 
  with response \eqn{y} and predictors \eqn{x},
  the Added Variable Plot for a new covariate \eqn{z} 
  is a plot of the smoothed Pearson residuals from the original model
  against the scaled residuals from a weighted linear
  regression of \eqn{z} on \eqn{x}.
  If this plot has nonzero slope, then the new covariate \eqn{z} is
  needed. For general advice see Cook and Weisberg(1999); Harrell (2001).
  
  Essentially the same technique can be used for a spatial point process
  model (Baddeley et al, 2012).

  The argument \code{model} should be a fitted spatial point process
  model (object of class \code{"ppm"}). 

  The argument \code{covariate}
  identifies the covariate that is to be considered for addition to
  the model. It should be either a pixel image (object of class
  \code{"im"}) or a \code{function(x,y)} giving the values of the
  covariate at any spatial location. Alternatively \code{covariate}
  may be a character string, giving the name of a covariate that was
  supplied (in the \code{covariates} argument to \code{\link{ppm}})
  when the model was fitted, but was not used in the model.

  The result of \code{addvar(model, covariate)} is an object belonging
  to the classes \code{"addvar"} and \code{"fv"}. Plot this object to
  generate the added variable plot. 
  
  Note that the plot method shows the pointwise significance bands
  for a test of the \emph{null} model, i.e. the null hypothesis
  that the new covariate has no effect.

  The smoothing bandwidth is controlled by the arguments
  \code{bw}, \code{adjust}, \code{bw.input} and \code{bw.restrict}.
  If \code{bw} is a numeric value, then
  the bandwidth is taken to be \code{adjust * bw}.
  If \code{bw} is a string representing a bandwidth selection rule
  (recognised by \code{\link[stats]{density.default}})
  then the bandwidth is selected by this rule.

  The data used for automatic bandwidth selection are
  specified by \code{bw.input} and \code{bw.restrict}.
  If \code{bw.input="points"}  (the default) then bandwidth selection is
  based on the covariate values at the points of the original point
  pattern dataset to which the model was fitted.
  If \code{bw.input="quad"} then bandwidth selection is
  based on the covariate values at every quadrature point used to
  fit the model.
  If \code{bw.restrict=TRUE} then the bandwidth selection is performed
  using only data from inside the \code{subregion}.
}
\value{
  An object of class \code{"addvar"} containing the coordinates
  for the added variable plot. There is a \code{plot} method.
}
\section{Internal data}{
  The return value has an attribute \code{"spatial"} which contains
  the internal data: the computed values of the residuals,
  and of all relevant covariates,
  at each quadrature point of the model. It is an object of class
  \code{"ppp"} with a data frame of marks.
}
\references{
  Baddeley, A. and Chang, Y.-M. and Song, Y. and Turner, R. (2012)
  \emph{Residual diagnostics for covariate effects
    in spatial point process models}.
  Submitted for publication.
  
  Cook, R.D. and Weisberg, S. (1999)
  \emph{Applied regression, including computing and graphics}.
  New York: Wiley.
  
  Cox, D.R. (1958) \emph{Planning of Experiments}. New York: Wiley.

  Harrell, F. (2001) \emph{Regression Modeling Strategies}. New York: Springer.

  Wang, P. (1985) Adding a variable in generalized linear models.
  \emph{Technometrics} \bold{27}, 273--276.
}
\author{
  Adrian Baddeley
  \email{Adrian.Baddeley@csiro.au}
  \url{http://www.maths.uwa.edu.au/~adrian/},
  Rolf Turner
  \email{r.turner@auckland.ac.nz},
  Ya-Mei Chang and Yong Song.
}
\seealso{
  \code{\link{parres}},
  \code{\link{rhohat}},
  \code{\link{rho2hat}}.
}
\examples{
  X <-  rpoispp(function(x,y){exp(3+3*x)})
  model <- ppm(X, ~y)
  adv <- addvar(model, "x")
  plot(adv)
  adv <- addvar(model, "x", subregion=square(0.5))
}
\keyword{spatial}
\keyword{models}