% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bru_input.R
\name{bru_input}
\alias{bru_input}
\alias{new_bru_input}
\alias{bru_input.bru_input}
\alias{bru_input.bru_comp}
\alias{bru_input.bru_comp_list}
\alias{bru_input.bru_model}
\alias{bru_input.bru_obs}
\alias{bru_input.bru_obs_list}
\alias{bru_input.bru_mapper}
\alias{bru_input.bm_pipe}
\alias{bru_input.bm_multi}
\alias{bru_input.bm_collect}
\alias{bru_input.bm_repeat}
\alias{bru_input.bm_sum}
\title{Store and evaluate component inputs}
\usage{
new_bru_input(input, label = NULL, layer = NULL, selector = NULL, ...)

bru_input(...)

\method{bru_input}{bru_input}(
  x,
  data = NULL,
  mask = NULL,
  null.on.fail = FALSE,
  .envir = parent.frame(),
  ...
)

\method{bru_input}{bru_comp}(x, ..., label = x$label)

\method{bru_input}{bru_comp_list}(x, ...)

\method{bru_input}{bru_model}(x, lhoods, ...)

\method{bru_input}{bru_obs}(x, components, ...)

\method{bru_input}{bru_obs_list}(x, components, ...)

\method{bru_input}{bru_mapper}(x, ..., label = "<unknown>")

\method{bru_input}{bm_pipe}(x, ..., label = "<unknown>")

\method{bru_input}{bm_multi}(x, ..., label = "<unknown>")

\method{bru_input}{bm_collect}(x, ..., label = "<unknown>")

\method{bru_input}{bm_repeat}(x, ..., label = "<unknown>")

\method{bru_input}{bm_sum}(x, ..., label = "<unknown>")
}
\arguments{
\item{input}{An expression to be evaluated.}

\item{label}{character; optional label used to identify the object in
informational messages.}

\item{layer}{Optional expression that evaluates layer names or indices for
use with \code{\link[=eval_spatial]{eval_spatial()}}}

\item{selector}{character or integer; optional selector for use with
use with \code{\link[=eval_spatial]{eval_spatial()}}}

\item{\dots}{Passed on to sub-methods.}

\item{x}{A \code{bru_input} object, or other object for recursive evaluation.}

\item{data}{A \code{data.frame}, \code{tibble}, \code{sf}, \code{list}, or \verb{Spatial*} object of
covariates and/or point locations.}

\item{mask}{A \code{bru_data_mask} object, constructed internally.}

\item{null.on.fail}{logical; if \code{TRUE}, return \code{NULL} if the input evaluation
fails. If \code{FALSE} (default), return a vector of 1s and issue a warning
(only for deprecated use of \code{coordinates} without having loaded the \code{sp}
package), or stop with an error.}

\item{.envir}{environment in which to evaluate the input expression. Default
is \code{parent.frame()}}

\item{lhoods}{A \code{bru_obs_list} object containing all observations models.}

\item{components}{A \code{bru_comp_list} object containing all components
defined in the model.}
}
\value{
\itemize{
\item \code{bru_input(bru_comp)}: A list of mapper input values, formatted
for the full component mapper (of type \link{bm_pipe})
}

\itemize{
\item \code{bru_input(bru_comp_list)}: A list of mapper input values,
with one entry for each component.
}

\itemize{
\item \code{bru_input(bru_model)}: A list of mapper input values,
with one entry for each observation model, each containing a list
of inputs for the components used by the corresponding observation model.
}

\itemize{
\item \code{bru_input(bru_obs_list)}: A list of mapper input values,
with one entry for each observation model, each containing a list
of inputs for the components used by the corresponding observation model.
}

\itemize{
\item \code{bru_input(bru_obs_list)}: A list of mapper input values,
with one entry for each observation model, each containing a list
of inputs for the components used by the corresponding observation model.
}
}
\description{
Store and evaluate component inputs, including support for
non-standard-evaluation with \code{rlang}, automatic transfer to
function calls, \code{\link[=eval_spatial]{eval_spatial()}}, and \code{\link[MatrixModels:model.Matrix]{MatrixModels::model.Matrix()}}.

These functions are normally only called internally, but users may find
it useful to call them directly to experiment, and to make advanced
model definitions using \link{ibm_input_set}/\code{\link[=ibm_input_new]{ibm_input_new()}}.
}
\section{Methods (by class)}{
\itemize{
\item \code{bru_input(bru_input)}: Attempts to evaluate a component input (e.g. \code{main},
\code{group}, \code{replicate}, or \code{weight}), and process the results:
\enumerate{
\item If \code{rlang::eval_tidy()} failed, return NULL or map everything to 1
(see the \code{null.on.fail} argument). This should normally not
happen, unless the component use logic is incorrect,
(via \code{used})
leading to missing columns for a certain likelihood in a
multi-\code{bru_obs()} model.
\item If we obtain a function, apply the function to the data object
\item If we obtain an object supported by \code{\link[=eval_spatial]{eval_spatial()}}, extract the values
of that data frame at the point locations
\item If we obtain a formula, call \code{ModelMatrix::model.Matrix()}
\item Else we obtain a vector and return as-is. This happens when input
references a column of the data points, or some other complete expression
}

\item \code{bru_input(bru_model)}: Computes the component inputs for included components
for each observation model.

\item \code{bru_input(bru_mapper)}: Evaluate the input associated with a \code{bru_mapper}.

\item \code{bru_input(bm_pipe)}: Evaluate the inputs for each sub-mapper in a \code{bm_pipe}
object.

\item \code{bru_input(bm_multi)}: Evaluate the inputs for each sub-mapper in a \code{bm_multi}
object.

\item \code{bru_input(bm_collect)}: Evaluate the inputs for each sub-mapper in a
\code{bm_collect} object.

\item \code{bru_input(bm_repeat)}: Evaluate the inputs for the sub-mapper in a \code{bm_repeat}
object.

\item \code{bru_input(bm_sum)}: Evaluate the inputs for each sub-mapper in a \code{bm_sum}
object.

}}
\section{Functions}{
\itemize{
\item \code{new_bru_input()}: Create a \code{bru_input} object.

\item \code{bru_input()}: Evaluate inputs

}}
\section{Simple covariates and the input parameters}{


It is not unusual for a random effect act on a transformation of a covariate.
In other frameworks this would mean that the transformed covariate would have
to be calculated in advance and added to the data frame that is usually
provided via the \code{data} parameter. inlabru provides the option to do this
transformation automatically. For instance, one might be interested in the
effect of a covariate \eqn{x^2}. In inla and other frameworks this would
require to add a column \code{xsquared} to the input data frame and use the
formula

\itemize{\item{\code{formula = y ~ f(xsquared, model = "linear")},}}

In inlabru this can be achieved in several ways of using the \code{main} parameter
(\code{map} in version 2.1.13 and earlier), which does not need to be named.

\itemize{
\item{\code{components = y ~ psi(x^2, model = "linear")}}
\item{\code{components = y ~ psi(main = x^2, model = "linear")}}
\item{\code{components = y ~ psi(mySquareFun(x), model = "linear")},}
\item{\code{components = y ~ psi(myOtherSquareFun, model = "linear")},}
}

In the first example inlabru will interpret the map parameter as an
expression to be evaluated within the data provided. Since \eqn{x} is a known
covariate it will know how to calculate it. The second example is an
expression as well but it uses a function called \code{mySquareFun}. This function
is defined by user but has to be accessible within the work space when
setting up the components. The third example provides the function
\code{myOtherSquareFun}. In this case, inlabru will call the function as
\code{myOtherSquareFun(.data.)}, where \code{.data.} is the data provided via the
\code{\link[=bru_obs]{bru_obs()}} \code{data} parameter. The function needs to know what parts of the
data to use to construct the needed output. For example,

\if{html}{\out{<div class="sourceCode">}}\preformatted{myOtherSquareFun <- function(data) \{
  data[ ,"x"]^2
\}
}\if{html}{\out{</div>}}

Interactions can be handled by a formula input and \code{model = "fixed"}:
\code{components = y ~ 0 + name(~ 1 + x:z, model = "fixed")}
}

\section{Spatial Covariates}{


When fitting spatial models it is common to work with covariates that depend
on space, e.g. sea surface temperature or elevation. Although it is
straightforward to add this data to the input data frame or write a covariate
function like in the previous section there is an even more convenient way in
inlabru. Spatial covariates are often stored as \code{SpatialPixelsDataFrame},
\code{SpatialPixelsDataFrame} or \code{RasterLayer} objects. These can be provided
directly via the input expressions if they are supported by \code{\link[=eval_spatial]{eval_spatial()}},
and the \code{\link[=bru_obs]{bru_obs()}} data is an \code{sf} or \code{SpatialPointsDataFrame} object.
\code{inlabru} will then automatically evaluate and/or interpolate the covariate
at your data locations when using code like

\if{html}{\out{<div class="sourceCode">}}\preformatted{components = y ~ psi(mySpatialPixels, model = "linear")
}\if{html}{\out{</div>}}

For more precise control, use the the \code{layer} and \code{selector} arguments (see
\code{\link[=bru_comp]{bru_comp()}}), or call \code{\link[=eval_spatial]{eval_spatial()}} directly, e.g.:

\if{html}{\out{<div class="sourceCode">}}\preformatted{components = y ~ psi(eval_spatial(mySpatialPixels, where = .data.),
                     model = "linear")
}\if{html}{\out{</div>}}
}

\section{Coordinates}{


A common spatial modelling component when using inla are SPDE models. An
important feature of inlabru is that it will automatically calculate the so
called A-matrix (a component model matrix) which maps SPDE values at the mesh
vertices to values at the data locations. For this purpose, the input can be
set to \code{coordinates}, which is the \code{sp} package function that extracts point
coordinates from the \code{SpatialPointsDataFrame} that was provided as input to
\code{\link[=bru_obs]{bru_obs()}}. The code for this would look as follows:

\if{html}{\out{<div class="sourceCode">}}\preformatted{components = y ~ field(coordinates, model = inla.spde2.matern(...))
}\if{html}{\out{</div>}}

Since \code{coordinates} is a function from the \code{sp} package, this results in
evaluation of \code{sp::coordinates(.data.)}, which loses any CRS information
from the data object.

For \code{sf} data with a geometry column (by default named \code{geometry}), use

\if{html}{\out{<div class="sourceCode">}}\preformatted{components = y ~ field(geometry, model = inla.spde2.matern(...))
}\if{html}{\out{</div>}}

Since the CRS information is part of the geometry column of the \code{sf} object,
this retains CRS information, so this is more robust, and allows the model
to be built on a different CRS than the observation data.
}

\examples{
(inp <- new_bru_input(x, "LABEL"))
bru_input(inp, data.frame(x = 1:3))

}
\seealso{
\code{\link[=bru_input_text]{bru_input_text()}}

\code{\link[=summary.bru_input]{summary.bru_input()}}, \code{\link[=bru_comp]{bru_comp()}}

\link{ibm_input}
}
\author{
Fabian E. Bachl \email{bachlfab@gmail.com}, Finn Lindgren
\email{finn.lindgren@gmail.com}
}
