% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spautor.R
\name{spautor}
\alias{spautor}
\title{Fit spatial autoregressive models}
\usage{
spautor(
  formula,
  data,
  spcov_type,
  spcov_initial,
  estmethod = "reml",
  random,
  randcov_initial,
  partition_factor,
  W,
  row_st = TRUE,
  M,
  ...
)
}
\arguments{
\item{formula}{A two-sided linear formula describing the fixed effect structure
of the model, with the response to the left of the \code{~} operator and
the terms, separated by \code{+} operators, on the right.}

\item{data}{A data frame or \code{sf} object that contains
the variables in \code{fixed}, \code{random}, and \code{partition_factor},
as well as potentially geographical information.}

\item{spcov_type}{The spatial covariance type. Available options include
\code{"car"} and \code{"sar"}. Parameterizations of each spatial covariance type are
available in Details. When \code{spcov_type} is specified, relevant spatial
covariance parameters are assumed unknown, requiring estimation.
\code{spcov_type} is not required (and is
ignored) if \code{spcov_initial} is provided.  Multiple values can be
provided in a character vector. Then \code{splm()} is called iteratively
for each element and a list is returned for each model fit.
The default for \code{spcov_type} is \code{"car"}.}

\item{spcov_initial}{An object from \code{\link[=spcov_initial]{spcov_initial()}} specifying initial and/or
known values for the spatial covariance parameters.
Not required if \code{spcov_type} is provided. Multiple \code{\link[=spcov_initial]{spcov_initial()}}
objects can be provided in a list. Then \code{splm()} is called iteratively
for each element and a list is returned for each model fit.}

\item{estmethod}{The estimation method. Available options include
\code{"reml"} for restricted maximum likelihood and \code{"ml"} for maximum
likelihood The default is
\code{"reml"}.}

\item{random}{A one-sided linear formula describing the random effect structure
of the model. Terms are specified to the right of the \code{~ operator}.
Each term has the structure \code{x1 + ... + xn | g1/.../gm}, where \code{x1 + ... + xn}
specifies the model for the random effects and \code{g1/.../gm} is the grouping
structure. Separate terms are separated by \code{+} and must generally
be wrapped in parentheses. Random intercepts are added to each model
implicitly when at least  one other variable is defined.
If a random intercept is not desired, this must be explicitly
defined (e.g., \code{x1 + ... + xn - 1 | g1/.../gm}). If only a random intercept
is desired for a grouping structure, the random intercept must be specified
as \code{1 | g1/.../gm}. Note that \code{g1/.../gm} is shorthand for \code{(1 | g1/.../gm)}.
If only random intercepts are desired and the shorthand notation is used,
parentheses can be omitted.}

\item{randcov_initial}{An optional object specifying initial and/or
known values for the random effect variances.}

\item{partition_factor}{A one-sided linear formula with a single term
specifying the partition factor.  The partition factor assumes observations
from different levels of the partition factor are uncorrelated.}

\item{W}{Weight matrix specifying the neighboring structure used.
Not required if \code{data} is an \code{sf} polygon object,
as \code{W} is calculated internally. If calculated internally,
\code{W} is computed using \code{sf::st_intersects()}.}

\item{row_st}{A logical indicating whether row standardization be performed on
\code{W}. The default is \code{TRUE}.}

\item{M}{M matrix satisfying the car symmetry condition. The car
symmetry condition states that \eqn{(I - range * W)^{-1}M} is symmetric, where
\eqn{I} is an identity matrix, \eqn{range} is a constant that controls the
spatial dependence, \code{W} is the weights matrix,
and \eqn{^{-1}} represents the inverse operator.
\code{M} is required for car models
when \code{W} is provided and \code{row_st} is \code{FALSE}.  When \code{M},
is required, the default is the identity matrix.}

\item{...}{Other arguments to \code{stats::optim()}.}
}
\value{
A list with many elements that store information about
the fitted model object. If \code{spcov_type} or \code{spcov_initial} are
length one, the list has class \code{spautor}. Many generic functions that
summarize model fit are available for \code{spautor} objects, including
\code{AIC}, \code{AICc}, \code{anova}, \code{augment}, \code{coef},
\code{cooks.distance}, \code{deviance}, \code{fitted}, \code{formula},
\code{glance}, \code{glances}, \code{hatvalues}, \code{influence},
\code{labels}, \code{logLik}, \code{loocv}, \code{model.frame}, \code{model.matrix},
\code{plot}, \code{predict}, \code{print}, \code{pseudoR2}, \code{summary},
\code{terms}, \code{tidy}, \code{update}, and \code{vcov}. If
\code{spcov_type} or \code{spcov_initial} are length greater than one, the
list has class \code{spautor_list} and each element in the list has class
\code{spautor}. \code{glances} can be used to summarize \code{spautor_list}
objects, and the aforementioned \code{spautor} generics can be used on each
individual list element (model fit).
}
\description{
Fit spatial linear models for areal data (i.e., spatial autoregressive models)
using a variety of estimation methods, allowing for random effects,
partition factors, and row standardization.
}
\details{
The spatial linear model for areal data (i.e., spatial autoregressive model)
can be written as
\eqn{y = X \beta + \tau + \epsilon}, where X is the fixed effects design
matrix, \eqn{\beta} are the fixed effects, \eqn{\tau} is random error that is
spatially dependent, and \eqn{\epsilon} is random error that is spatially
independent. Together, \eqn{\tau} and \eqn{\epsilon} are modeled using
a spatial covariance function, expressed as
\eqn{de * R + ie * I}, where \eqn{de} is the dependent error variance, \eqn{R}
is a matrix that controls the spatial dependence structure among observations,
\eqn{ie} is the independent error variance, and \eqn{I} is
an identity matrix. Note that \eqn{de} and \eqn{ie} must be non-negative while \eqn{range}
must be between the reciprocal of the maximum
eigenvalue of \code{W} and the reciprocal of the minimum eigenvalue of
\code{W}.

\code{spcov_type} Details: Parametric forms for \eqn{R} are given below:
\itemize{
\item{car: }{\eqn{(I - range * W)^{-1}M}, weights matrix \eqn{W},
symmetry condition matrix \eqn{M}}
\item{sar: }{\eqn{[(I - range * W)(I - range * W)^T]^{-1}},
weights matrix \eqn{W}, \eqn{^T} indicates matrix transpose}
}
If there are observations with no neighbors, they are given a unique variance
parameter called \code{extra}, which must be non-negative.

\code{estmethod} Details: The various estimation methods are
\itemize{
\item{\code{reml}: }{Maximize the restricted log-likelihood.}
\item{\code{ml}: }{Maximize the log-likelihood.}
}

By default, all spatial covariance parameters except \code{ie}
as well as all random effect variance parameters
are assumed unknown, requiring estimation. \code{ie} is assumed zero and known by default
(in contrast to models fit using \code{\link[=splm]{splm()}}, where \code{ie} is assumed
unknown by default). To change this default behavior, specify \code{spcov_initial}
(an \code{NA} value for \code{ie} in \code{spcov_initial} to assume
\code{ie} is unknown, requiring estimation).

\code{random} Details: If random effects are used (the estimation method must be \code{"reml"} or
\code{"ml"}), the model
can be written as \eqn{y = X \beta + Z1u1 + ... Zjuj + \tau + \epsilon},
where each Z is a random effects design matrix and each u is a random effect.

\code{partition_factor} Details:  The partition factor can be represented in matrix form as \eqn{P}, where
elements of \eqn{P} equal one for observations in the same level of the partition
factor and zero otherwise. The covariance matrix involving only the
spatial and random effects components is then multiplied element-wise
(Hadmard product) by \eqn{P}, yielding the final covariance matrix.

Observations with \code{NA} response values are removed for model
fitting, but their values can be predicted afterwards by running
\code{predict(object)}. This is the only way to perform prediction for
\code{spautor()} models (i.e., the prediction locations must be known prior
to estimation).
}
\note{
This function does not perform any internal scaling. If optimization is not
stable due to large extremely large variances, scale relevant variables
so they have variance 1 before optimization.
}
\examples{
spmod <- spautor(log_trend ~ 1, data = seal, spcov_type = "car")
summary(spmod)
}
