% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bru.inference.R
\name{bru}
\alias{bru}
\alias{bru_rerun}
\alias{summary.bru}
\alias{print.summary_bru}
\alias{print.bru}
\title{Convenient model fitting using (iterated) INLA}
\usage{
bru(components = ~Intercept(1), ..., options = list(), .envir = parent.frame())

bru_rerun(result, options = list())

\method{summary}{bru}(object, verbose = FALSE, ...)

\method{print}{summary_bru}(x, ...)

\method{print}{bru}(x, ...)
}
\arguments{
\item{components}{Latent component definitions, either as a \code{\link[=bru_comp_list]{bru_comp_list()}}
object, or a \code{formula}-like specification.
Also used to define a default linear additive predictor.  See
\code{\link[=bru_comp]{bru_comp()}} for details.}

\item{\dots}{Observation models, each constructed by a calling \code{\link[=bru_obs]{bru_obs()}},
or \code{\link[=bru_obs_list]{bru_obs_list()}}.

Alternatively, for backwards compatibility, may be named parameters that
can be passed to a single \code{\link[=bru_obs]{bru_obs()}} call. These arguments will be
evaluated before calling \code{\link[=bru_obs]{bru_obs()}}, in order to detect if they already
are \code{bru_obs} objects. This means that special arguments that are only
available in the context of \code{data} or \code{response_data} (such as \code{Ntrials})
will only work properly in direct calls to \code{\link[=bru_obs]{bru_obs()}}.}

\item{options}{A \link{bru_options} options object or a list of options passed
on to \code{\link[=bru_options]{bru_options()}}}

\item{.envir}{Environment for component evaluation (for when a non-formula
specification is used)}

\item{result}{A previous estimation object of class \code{bru}}

\item{object}{An object obtained from a \code{\link[=bru]{bru()}} or \code{\link[=lgcp]{lgcp()}} call}

\item{verbose}{logical; If \code{TRUE}, include more details of the
component definitions. If \code{FALSE}, only show basic component
definition information. Default: \code{FALSE}}

\item{x}{An object to be printed}
}
\value{
bru returns an object of class "bru". A \code{bru} object inherits
from \code{INLA::inla} (see the inla documentation for its properties) and
adds additional information stored in the \code{bru_info} field.
}
\description{
This method is a wrapper for \code{INLA::inla} and provides
multiple enhancements.

\itemize{
\item
Easy usage of spatial covariates and automatic construction of inla
projection matrices for (spatial) SPDE models. This feature is
accessible via the \code{components} parameter. Practical examples on how to
use spatial data by means of the components parameter can also be found
by looking at the \code{\link[=lgcp]{lgcp()}} function's documentation.
\item
Constructing multiple observation models is straightforward. See
\code{\link[=bru_obs]{bru_obs()}} for more information on how to provide additional
models to \code{bru} using the \code{...} parameter list.
\item
Support for non-linear predictors. See example below.
\item
Log Gaussian Cox process (LGCP) inference is
available by using the \code{"cp"} family or (even easier) by using the
\code{\link[=lgcp]{lgcp()}} function.
}
}
\section{Methods (by generic)}{
\itemize{
\item \code{summary(bru)}: Takes a fitted \code{bru} object produced by \code{\link[=bru]{bru()}} or \code{\link[=lgcp]{lgcp()}}
and creates various summaries from it, including the summary output from
the corresponding \code{INLA::sumary()} method.
The \dots arguments are passed on to component summary functions, see
\code{\link[=summary.bru_comp]{summary.bru_comp()}}.

\item \code{print(bru)}: Print a summary of a \code{bru} object.

}}
\section{Functions}{
\itemize{
\item \code{bru_rerun()}: Continue the optimisation from a previously computed estimate. The estimation
\code{options} list can be given new values to override the original settings.

To rerun with a subset of the data (e.g. for cross validation or prior
sampling), use \code{\link[=bru_set_missing]{bru_set_missing()}} to set all or part of the response data
to \code{NA} before calling \code{bru_rerun()}.

}}
\examples{
\donttest{
if (bru_safe_inla()) {
  # Simulate some covariates x and observations y
  input.df <- data.frame(x = cos(1:10))
  input.df <- within(input.df, {
    y <- 5 + 2 * x + rnorm(10, mean = 0, sd = 0.1)
  })

  # Fit a Gaussian likelihood model
  fit <- bru(y ~ x + Intercept(1), family = "gaussian", data = input.df)

  # Obtain summary
  fit$summary.fixed
}


if (bru_safe_inla()) {
  # Alternatively, we can use the bru_obs() function to construct the
  # likelihood:

  lik <- bru_obs(
    family = "gaussian",
    formula = y ~ x + Intercept,
    data = input.df
  )
  fit <- bru(~ x + Intercept(1), lik)
  fit$summary.fixed
}

# An important addition to the INLA methodology is bru's ability to use
# non-linear predictors. Such a predictor can be formulated via bru_obs()'s
# \code{formula} parameter. The z(1) notation is needed to ensure that
# the z component should be interpreted as single latent variable and not
# a covariate:

if (bru_safe_inla()) {
  z <- 2
  input.df <- within(input.df, {
    y <- 5 + exp(z) * x + rnorm(10, mean = 0, sd = 0.1)
  })
  lik <- bru_obs(
    family = "gaussian", data = input.df,
    formula = y ~ exp(z) * x + Intercept
  )
  fit <- bru(~ z(1) + Intercept(1), lik)

  # Check the result (z posterior should be around 2)
  fit$summary.fixed
}
}

}
\author{
Fabian E. Bachl \email{bachlfab@gmail.com}
}
