% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/effect.R
\name{bru_comp}
\alias{bru_comp}
\alias{component}
\alias{bru_component}
\alias{bru_comp.character}
\title{Latent model component construction}
\usage{
bru_comp(...)

bru_component(...)

\method{bru_comp}{character}(
  object,
  main = NULL,
  weights = NULL,
  ...,
  model = NULL,
  mapper = NULL,
  main_layer = NULL,
  main_selector = NULL,
  n = NULL,
  values = NULL,
  season.length = NULL,
  nrow = NULL,
  ncol = NULL,
  copy = NULL,
  weights_layer = NULL,
  weights_selector = NULL,
  group = 1L,
  group_mapper = NULL,
  group_layer = NULL,
  group_selector = NULL,
  ngroup = NULL,
  control.group = NULL,
  replicate = 1L,
  replicate_mapper = NULL,
  replicate_layer = NULL,
  replicate_selector = NULL,
  nrep = NULL,
  marginal = NULL,
  A.msk = deprecated(),
  .envir = parent.frame(),
  envir_extra = NULL
)
}
\arguments{
\item{\dots}{Parameters passed on to other methods}

\item{object}{A character label for the component}

\item{main}{\code{main} takes an R expression that evaluates to where the latent variables
should be evaluated (coordinates, indices, continuous scalar (for rw2 etc)).
Arguments starting with weights, group, replicate behave similarly to main,
but for the corresponding features of \code{INLA::f()}. \code{main} supports \code{tidy}
evaluation expressions, with \code{.data} and \code{.env} pronouns.}

\item{weights, weights_layer, weights_selector}{Optional specification of effect scaling weights.
Same syntax as for \code{main}.}

\item{model}{Either one of "const" (same as "offset"), "factor_full",
"factor_contrast", "linear",
"fixed", or a model name or
object accepted by INLA's \code{f} function. If set to NULL, then "linear" is used
for vector inputs, and "fixed" for matrix input (converted internally to
an iid model with fixed precision)}

\item{mapper}{Information about how to do the mapping from the values evaluated in \code{main},
and to the latent variables. Auto-detects spde model objects in model and
extracts the mesh object to use as the mapper, and auto-generates mappers
for indexed models. (Default: NULL, for auto-determination)}

\item{main_layer, main_selector}{The \verb{_layer} input should evaluate to a numeric index or character name or
vector of which
layer/variable to extract from a covariate data object given in \code{main}.
(Default: NULL if \verb{_selector} is given. Otherwise the effect component name,
if it exists in the covariate object, and otherwise the first column of
the covariate data frame)

The \verb{_selector} value should be a character name of a variable
whose contents determines which layer to extract from a covariate for each
data point. (Default: NULL)}

\item{n}{The number of latent variables in the model. Should be auto-detected
for most or all models. Default: NULL, for auto-detection. Models with
matrix input for \code{Cmatrix} or \code{graph} will use the matrix size.
An error is given if it realises it can't figure it out by itself.}

\item{values}{Specifies for what covariate/index values INLA should build
the latent model. Normally generated internally based on the mapping details.
(Default: NULL, for auto-determination)}

\item{season.length}{Passed on to \code{INLA::f()} for model \code{"seasonal"}
(TODO: check if this parameter is still fully handled)}

\item{nrow, ncol}{Number of rows and columns for \code{model} types
"rw2d", "rw2diid", and "matern2d". Default is \code{NULL}.}

\item{copy}{character; label of other component that this component should
be a copy of. If the \code{fixed = FALSE}, a scaling constant is estimated, via a
hyperparameter. If \code{fixed = TRUE}, the component scaling is fixed, by
default to 1; for fixed scaling, it's more efficient to express the scaling
in the predictor expression instead of making a copy component.}

\item{group, group_mapper, group_layer, group_selector, ngroup}{Optional specification of kronecker/group model indexing.}

\item{control.group}{\code{list} of kronecker/group model parameters, currently
passed directly on to \code{INLA::f}}

\item{replicate, replicate_mapper, replicate_layer, replicate_selector, nrep}{Optional specification of indices for an independent
replication model. Same syntax as for \code{main}}

\item{marginal}{May specify a \code{bm_marginal()} mapper,
that is applied before scaling by \code{weights}.}

\item{A.msk}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} and has no effect.}

\item{.envir}{Evaluation environment. Can later be accessed via
\code{\link[=bru_comp_env]{bru_comp_env()}}. Default: \code{parent.frame()}}

\item{envir_extra}{Environment for storing \code{INLA::f()} argument values.
If NULL, an new environment is created. Can be accessed via
\code{\link[=bru_comp_env_extra]{bru_comp_env_extra()}}}
}
\description{
Similar to \code{glm()}, \code{gam()} and \code{inla()}, \code{\link[=bru]{bru()}} models can be constructed
via a formula-like syntax, where each latent effect is specified. However, in
addition to the parts of the syntax compatible with \code{INLA::inla}, \code{bru}
components offer additional functionality which facilitates modelling, and
the predictor expression can be specified separately, allowing more complex
and non-linear predictors to be defined. The formula syntax is just a way to
allow all model components to be defined in a single line of code, but the
definitions can optionally be split up into separate component definitions.
See Details for more information.

The \code{bru_comp} methods all rely on the \code{\link[=bru_comp.character]{bru_comp.character()}}
method, that defines a model component with a given label/name. The user
usually doesn't need to call these methods directly, but can instead supply a
formula expression that can be interpreted by the
\code{\link[=bru_comp_list.formula]{bru_comp_list.formula()}} method, called inside \code{\link[=bru]{bru()}}.
}
\details{
As shorthand, \code{\link[=bru]{bru()}} will understand basic additive formulae describing
fixed effect models. For instance, the components specification \code{y ~ x} will
define the linear combination of an effect named \code{x} and an intercept to the
response \code{y} with respect to the likelihood family stated when calling
\code{\link[=bru]{bru()}}. Mathematically, the linear predictor \eqn{\eta}{eta} would be
written as

\deqn{\eta = \beta x + c,}{eta = beta * x + c,}

where:

\describe{
\item{\eqn{c}{c}}{is the \emph{intercept}}
\item{\eqn{x}{x}}{is a \emph{covariate}}
\item{\eqn{\beta}{beta}}{is a \emph{latent variable} associated with \eqn{x}{x}
and} \item{\eqn{\psi = \beta x}{psi = beta * x}}{ is called the \emph{effect} of
\eqn{x}{x}}
}

A problem that arises when using this kind of R formula is that it does not
clearly reflect the mathematical
formula. For instance, when providing the formula to inla, the resulting
object will refer to the random
effect \eqn{\psi = \beta * x } as \code{x}.
Hence, it is not clear when \code{x} refers to the covariate
or the effect of the covariate.

The \code{bru_comp.character} method is inlabru's equivalent to
\code{INLA}'s \code{f()} function but adds functionality that is unique to inlabru.

The \code{main}, \code{weights}, \code{group}, \code{replicate}, and \verb{*_layer} arguments
support \code{tidy} evaluation expressions, with \code{.data} and \code{.env} pronouns.
}
\section{Functions}{
\itemize{
\item \code{bru_component()}: Backwards compatibility alias for \code{bru_comp()}

}}
\section{Naming random effects}{


In INLA, the \code{f()} notation is used to define more complex models, but
a simple linear effect model can also be expressed as

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

where \code{f()} is the inla specific function to set up random effects of all
kinds. The underlying predictor would again be \eqn{\eta = \beta * x + c} but
the result of fitting the model would state \code{x} as the random effect's name.
bru allows rewriting this formula in order to explicitly state the name of
the random effect and the name of the associated covariate. This is achieved
by replacing \code{f} with an arbitrary name that we wish to assign to the effect,
e.g.

\itemize{\item{\code{components = y ~ psi(x, model = "linear")}.}}

Being able to discriminate between \eqn{x} and \eqn{\psi} is relevant because
of two functionalities bru offers. The formula parameters of both \code{\link[=bru]{bru()}} and
the prediction method \link{predict.bru} are interpreted in the mathematical
sense. For instance, \code{predict} may be used to analyze the analytical
combination of the covariate \eqn{x} and the intercept using

\itemize{\item{\verb{predict(fit, data.frame(x=2)), ~ exp(psi + Intercept)}.}}

which corresponds to the mathematical expression \ifelse{html}{\out{e
<sup>&#946; + c</sup>}}{\eqn{e^{x \beta + c}}}.

On the other hand, predict may be used to only look at a transformation of
the latent variable \eqn{\beta_\psi}

\itemize{\item{\code{predict(fit, NULL, ~ exp(psi_latent))}.}}

which corresponds to the mathematical expression \ifelse{html}{\out{e
<sup>&#946;</sup>}}{\eqn{e^{\beta}}}.
}

\examples{
# As an example, let us create a linear component. Here, the component is
# called "myLinearEffectOfX" while the covariate the component acts on is
# called "x". Note that a list of components is returned because the
# formula may define multiple components

cmp <- bru_comp_list(~ myLinearEffectOfX(main = x, model = "linear"))
summary(cmp)
# Equivalent shortcuts:
cmp <- bru_comp_list(~ myLinearEffectOfX(x, model = "linear"))
cmp <- bru_comp_list(~ myLinearEffectOfX(x))
# Individual component
cmp <- bru_comp("myLinearEffectOfX", main = x, model = "linear")
summary(cmp)
\donttest{
if (bru_safe_inla()) {
  # As an example, let us create a linear component. Here, the component is
  # called "myEffectOfX" while the covariate the component acts on is called
  # "x":

  cmp <- bru_comp("myEffectOfX", main = x, model = "linear")
  summary(cmp)

  # A more complicated component:
  cmp <- bru_comp("myEffectOfX",
    main = x,
    model = INLA::inla.spde2.matern(fmesher::fm_mesh_1d(1:10))
  )

  # Compound fixed effect component, where x and z are in the input data.
  # The formula will be passed on to MatrixModels::model.Matrix:
  cmp <- bru_comp("eff", ~ -1 + x:z, model = "fixed")
  summary(cmp)
}
}

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

Other component constructors: 
\code{\link{bru_comp_list}()}
}
\author{
Fabian E. Bachl \email{bachlfab@gmail.com} and
Finn Lindgren \email{Finn.Lindgren@gmail.com}
}
\concept{component constructors}
