Merge branch 'release/2.2.8' into stable

DESCRIPTION

@@ -1,18 +1,23 @@
 Package: inlabru
 Type: Package
 Title: Spatial Inference using Integrated Nested Laplace Approximation
-Version: 2.2.7
+Version: 2.2.8
 Authors@R: c(
-  person("Finn", "Lindgren", email = "finn.lindgren@gmail.com", role = c("aut", "cre"),
+  person("Finn", "Lindgren", email = "finn.lindgren@gmail.com",
+         role = c("aut", "cre", "cph"),
          comment = c(ORCID = "0000-0002-5833-2011",
                      "Finn Lindgren continued development of the main code")),
-  person("Fabian E.", "Bachl", email = "bachlfab@gmail.com", role = c("aut"),
+  person("Fabian E.", "Bachl", email = "bachlfab@gmail.com",
+         role = c("aut", "cph"),
          comment = "Fabian Bachl wrote the main code"),
-  person("David L.", "Borchers", email = "dlb@st-andrews.ac.uk", role = c("ctb", "dtc"),
+  person("David L.", "Borchers", email = "dlb@st-andrews.ac.uk",
+         role = c("ctb", "dtc", "cph"),
          comment = "David Borchers wrote code for Gorilla data import and sampling, multiplot tool"),
-  person("Daniel", "Simpson", email = "dp.simpson@gmail.com", role = c("ctb"),
+  person("Daniel", "Simpson", email = "dp.simpson@gmail.com",
+         role = c("ctb", "cph"),
          comment = "Daniel Simpson wrote the basic LGCP sampling method"),
-  person("Lindesay", "Scott-Howard", email = "lass@st-andrews.ac.uk", role = c("ctb", "dtc"),
+  person("Lindesay", "Scott-Howard", email = "lass@st-andrews.ac.uk",
+         role = c("ctb", "dtc", "cph"),
          comment = "Lindesay Scott-Howard provided MRSea data import code"),
   person("Seaton", "Andy", email = "andy.e.seaton@gmail.com", role = c("ctb"),
          comment = "Andy Seaton provided testing and bugfixes")
@@ -31,8 +36,8 @@ Encoding: UTF-8
 Depends:
     ggplot2,
     methods,
-    R (>= 3.3),
-    sp,
+    R (>= 3.5),
+    sp (>= 1.4-2),
     stats
 Imports:
     Matrix,

NAMESPACE

@@ -100,6 +100,7 @@ export(bincount)
 export(bru)
 export(bru_call_options)
 export(bru_compute_linearisation)
+export(bru_fill_missing)
 export(bru_info)
 export(bru_int_polygon)
 export(bru_log)
@@ -196,6 +197,7 @@ export(multiplot)
 export(pixels)
 export(plotsample)
 export(point2count)
+export(row_kron)
 export(sample.lgcp)
 export(sline)
 export(spatial.to.ppp)

NEWS.md

@@ -1,3 +1,22 @@
+# inlabru 2.2.8
+
+* Add `_eval` suffix feature for `generate.bru` and `predict.bru`, that
+  provides a general evaluator function for each component, allowing evaluation
+  of e.g. nonlinear effects of spatial covariates as a function of the covariate
+  value instead of the by the spatial evaluator used in the component definition.
+  For example, with `components = ~ covar(spatial_grid_df, model = "rw1")`, the
+  prediction expression can have `~ covar_eval(covariate)`, where `covariate`
+  is a data column in the prediction data object.
+
+  For components with `group` and `replicate` features, these also need to be
+  provided to the `_eval` function, with
+  `..._eval(..., group = ..., replicate = ...)`
+
+  This feature is built on top of the `_latent` suffix feature, that gives
+  direct access to the latent state variables of a component, so in order to
+  use `_eval` in the model predictor itself, you must use
+  `like(..., allow_latent = TRUE)` in the model definition.
+
 # inlabru 2.2.7
 
 * Add support for `ngroup` and `nrep` in component definitions

R/bru.gof.R

@@ -13,13 +13,13 @@
 #' @aliases bincount
 #' @export
 #' @importFrom graphics hist
-#' @param result A result object from a [bru] or [lgcp] call
-#' @param predictor A formula describing the prediction of a 1D LGCP via [predict].
+#' @param result A result object from a [bru()] or [lgcp()] call
+#' @param predictor A formula describing the prediction of a 1D LGCP via [predict()].
 #' @param observations A vector of observed values
 #' @param breaks A vector of bin boundaries
 #' @param nint Number of integration points per bin. Increase this if the bins are wide and
 #' @param probs numeric vector of probabilities with values in `[0,1]`
-#' @param \dots arguments passed on to [predict.bru]
+#' @param \dots arguments passed on to [predict.bru()]
 #' @return An `data.frame` with a ggplot attribute `ggp`
 #'
 #' @examples

R/bru.inference.R

@@ -272,9 +272,9 @@ bru_info.bru <- function(object, ...) {
 #'
 #' @author Fabian E. Bachl \email{bachlfab@@gmail.com}
 #'
-#' @param components A [formula]-like specification of latent components.
+#' @param components A `formula`-like specification of latent components.
 #'   Also used to define a default linear additive predictor.  See
-#'   [component] for details.
+#'   [component()] for details.
 #' @param ... Likelihoods, each constructed by a calling [like()], or named
 #'   parameters that can be passed to a single [like()] call.
 #' @param options A [bru_options] options object or a list of options passed
@@ -428,14 +428,14 @@ parse_inclusion <- function(thenames, include = NULL, exclude = NULL) {
 
 
 
-#' Likelihood construction for usage with [bru]
+#' Likelihood construction for usage with [bru()]
 #'
 #' @aliases like
 #' @export
 #'
 #' @author Fabian E. Bachl \email{bachlfab@@gmail.com}
 #'
-#' @param formula a [formula] where the right hand side is a general R
+#' @param formula a `formula` where the right hand side is a general R
 #'   expression defines the predictor used in the model.
 #' @param family A string identifying a valid `INLA::inla` likelihood family.
 #' The default is
@@ -467,13 +467,17 @@ parse_inclusion <- function(thenames, include = NULL, exclude = NULL) {
 #'   any components from the inclusion list)
 #' @param allow_latent logical. If `TRUE`, the latent state of each component is
 #' directly available to the predictor expression, with a `_latent` suffix.
+#' This also makes evaluator functions with suffix `_eval` available, taking
+#' parameters `main`, `group`, and `replicate`, taking values for where to
+#' evaluate the component effect that are different than those defined in the
+#' component definition itself.
 #' @param allow_combine logical; If `TRUE`, the predictor expression may
 #' involve several rows of the input data to influence the same row.
 #' (TODO: review what's needed to allow the result to also be of a different size)
 #' @param options A [bru_options] options object or a list of options passed
 #' on to [bru_options()]
 #'
-#' @return A likelihood configuration which can be used to parameterize [bru].
+#' @return A likelihood configuration which can be used to parameterize [bru()].
 #'
 #' @example inst/examples/like.R
 
@@ -764,7 +768,7 @@ joint_stackmaker <- function(model, lhoods, state) {
 #' approximation of the posterior.
 #' @param E Single numeric used rescale all integration weights by a fixed factor
 #' @param options See [bru_options_set()]
-#' @return An [bru] object
+#' @return An [bru()] object
 #' @examples
 #'
 #' \donttest{
@@ -871,7 +875,7 @@ expand_to_dataframe <- function(x, data = NULL) {
 #
 #' Prediction from fitted bru model
 #'
-#' Takes a fitted `bru` object produced by the function [bru]() and produces
+#' Takes a fitted `bru` object produced by the function [bru()] and produces
 #' predictions given a new set of values for the model covariates or the
 #' original values used for the model fit. The predictions can be based on any
 #' R expression that is valid given these values/covariates and the joint
@@ -888,12 +892,17 @@ expand_to_dataframe <- function(x, data = NULL) {
 #'
 #' @aliases predict.bru
 #' @export
-#' @param object An object obtained by calling [bru] or [lgcp].
+#' @param object An object obtained by calling [bru()] or [lgcp()].
 #' @param data A data.frame or SpatialPointsDataFrame of covariates needed for
 #' the prediction.
 #' @param formula A formula defining an R expression to evaluate for each generated
 #' sample. If `NULL`, the latent and hyperparameter states are generated
-#' as named list elements.
+#' as named list elements. In addition to the component names (that give the effect
+#' of each component evaluated for the input data), the suffix `_latent` can be used
+#' to directly access the latent state for a component, and the suffix `_eval`
+#' can be used to evaluate a component at other input values than the expressions
+#' defined in the component definition itself, e.g. `field_eval(cbind(x,y))` for a
+#' component defined with `field(coordinates, ...)`.
 #' @param n.samples Integer setting the number of samples to draw in order to
 #' calculate the posterior statistics. The default is rather low but provides
 #' a quick approximate result.
@@ -1029,7 +1038,7 @@ predict.bru <- function(object,
 #' Sampling based on bru posteriors
 #'
 #' @description
-#' Takes a fitted `bru` object produced by the function [bru]() and produces
+#' Takes a fitted `bru` object produced by the function [bru()] and produces
 #' samples given a new set of values for the model covariates or the original
 #' values used for the model fit. The samples can be based on any R expression
 #' that is valid given these values/covariates and the joint
@@ -1038,12 +1047,17 @@ predict.bru <- function(object,
 #' @aliases generate.bru
 #' @export
 #' @family sample generators
-#' @param object A `bru` object obtained by calling [bru].
+#' @param object A `bru` object obtained by calling [bru()].
 #' @param data A data.frame or SpatialPointsDataFrame of covariates needed for
 #' sampling.
 #' @param formula A formula defining an R expression to evaluate for each generated
 #' sample. If `NULL`, the latent and hyperparameter states are returned
-#' as named list elements.
+#' as named list elements. In addition to the component names (that give the effect
+#' of each component evaluated for the input data), the suffix `_latent` can be used
+#' to directly access the latent state for a component, and the suffix `_eval`
+#' can be used to evaluate a component at other input values than the expressions
+#' defined in the component definition itself, e.g. `field_eval(cbind(x,y))` for a
+#' component defined with `field(coordinates, ...)`.
 #' @param n.samples Integer setting the number of samples to draw in order to
 #' calculate the posterior statistics.
 #' The default, 100, is rather low but provides a quick approximate result.

R/deltaIC.R

@@ -3,7 +3,8 @@
 #' @description
 #' Calculates DIC and WAIC differences and produces an ordered summary.
 #'
-#' @param ... Comma-separated objects inheriting from class `inla` and obtained from a run of [inla][INLA::inla], [bru] or [lgcp]
+#' @param ... Comma-separated objects inheriting from class `inla` and obtained
+#' from a run of `INLA::inla()`, [bru()] or [lgcp()]
 #' @param criterion If 'DIC', plots DIC differences; If 'WAIC', plots WAIC differences.
 #'
 #' @return A data frame with each row containing the model name, DIC, WAIC, deltaDIC, and

R/effect.R

@@ -98,7 +98,7 @@ ibm_amatrix <- function(mapper, input, ...) {
 #'
 #' @description
 #'
-#' Similar to `glm()`, `gam()` and `inla()`, [bru] models can be constructed via
+#' Similar to `glm()`, `gam()` and `inla()`, [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 `INLA::inla`, `bru`
 #' components offer additional functionality which facilitates modelling, and
@@ -116,9 +116,9 @@ ibm_amatrix <- function(mapper, input, ...) {
 #'
 #' @details
 #'
-#' [bru] will understand formulae describing fixed effect models just like the other methods. For instance, the
+#' [bru()] will understand formulae describing fixed effect models just like the other methods. For instance, the
 #' formula `y ~ x` will fit the linear combination of an effect named `x` and an intercept to
-#' the response `y` with respect to the likelihood family stated when calling [bru]. Mathematically,
+#' the response `y` with respect to the likelihood family stated when calling [bru()]. Mathematically,
 #' the linear predictor \eqn{\eta} would be written down as
 #'
 #' \deqn{\eta = \beta * x + c,}
@@ -152,7 +152,7 @@ ibm_amatrix <- function(mapper, input, ...) {
 #' \itemize{\item{`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, [bru] and the prediction method [predict.bru]
+#' bru offers. The formula parameters of both, [bru()] and the prediction method [predict.bru]
 #' are interpreted in the mathematical sense. For instance, `predict` may be used to analyze the
 #' an analytical combination of the covariate \eqn{x} and the intercept using
 #'
@@ -1666,7 +1666,7 @@ ibm_amatrix.bru_mapper_multi <- function(mapper, input, multi = 0L, ...) {
     # Combine the matrices (A1, A2, A3) -> rowkron(A3, rowkron(A2, A1))
     A_ <- A[[1]]
     for (k in seq_len(length(mapper[["mappers"]]) - 1)) {
-      A_ <- INLA::inla.row.kron(A[[k + 1]], A_)
+      A_ <- row_kron(A[[k + 1]], A_)
     }
     return(A_)
   }

R/environment.R

@@ -155,7 +155,7 @@ bru_log_message <- function(..., domain = NULL, appendLF = TRUE,
 #'   to run inference.}
 #' \item{bru_max_iter}{maximum number of inla iterations}
 #' \item{bru_initial}{An `inla` object returned from previous calls of
-#'   `INLA::inla`, [bru] or [lgcp], or a list of named vectors of starting
+#'   `INLA::inla`, [bru()] or [lgcp()], or a list of named vectors of starting
 #'   values for the latent variables. This will be used as a
 #'   starting point for further improvement of the approximate posterior.}
 #' \item{bru_int_args}{List of arguments passed all the way to the
@@ -334,7 +334,7 @@ bru_options_deprecated <- function(args) {
 }
 
 
-#' Additional [bru] options
+#' Additional bru options
 #'
 #' Construct a `bru_options` object including the default and global options,
 #' and converting deprecated option names.

R/ggplot.R

@@ -93,7 +93,7 @@ gg <- function(data, ...) {
 #' @name gm
 #' @export
 #' @param data an object for which to generate a geom.
-#' @param ... Arguments passed on to [gg].
+#' @param ... Arguments passed on to [gg()].
 #' @return The form of the value returned by gm depends on the class of its argument. See the documentation of the particular methods for details of what is produced by that method.
 #' @family geomes for inla and inlabru predictions
 #' @family geomes for spatial data
@@ -156,8 +156,8 @@ gg.matrix <- function(data, mapping = NULL, ...) {
 #' @name gg.data.frame
 #' @export
 #' @import ggplot2
-#' @param ... Arguments passed on to [gg.prediction].
-#' @return Concatenation of a [geom_line] value and optionally a [geom_ribbon] value.
+#' @param ... Arguments passed on to [gg.prediction()].
+#' @return Concatenation of a `geom_line` value and optionally a `geom_ribbon` value.
 #' @family geomes for inla and inlabru predictions
 #' @example inst/examples/gg.prediction.R
 
@@ -171,11 +171,11 @@ gg.data.frame <- function(...) {
 #' @description
 #'
 #' This geom serves to visualize `prediction` objects which usually results from a call to
-#' [predict.bru]. Predictions objects provide summary statistics (mean, median, sd, ...) for
+#' [predict.bru()]. Predictions objects provide summary statistics (mean, median, sd, ...) for
 #' one or more random variables. For single variables (or if requested so by setting `bar = TRUE`),
 #' a boxplot-style geom is constructed to show the statistics. For multivariate predictions the
 #' mean of each variable (y-axis) is plotted agains the row number of the varriable in the prediction
-#' data frame (x-axis) using [geom_line]. In addition, a [geom_ribbon] is used to show
+#' data frame (x-axis) using `geom_line`. In addition, a `geom_ribbon` is used to show
 #' the confidence interval.
 #'
 #' Note: `gg.prediction` also understands the format of INLA-style posterior summaries, e.g.
@@ -186,13 +186,13 @@ gg.data.frame <- function(...) {
 #' @export
 #' @import ggplot2
 #' @importFrom utils modifyList
-#' @param data A prediction object, usually the result of a [predict.bru] call.
-#' @param mapping a set of aesthetic mappings created by [aes] or [aes_]. These are passed on to [geom_line].
+#' @param data A prediction object, usually the result of a [predict.bru()] call.
+#' @param mapping a set of aesthetic mappings created by `aes` or `aes_`. These are passed on to [geom_line].
 #' @param ribbon If TRUE, plot a ribbon around the line based on the upper and lower 2.5 percent quantiles.
 #' @param alpha The ribbons numeric alpha level in `[0,1]`.
 #' @param bar If TRUE plot boxplot-style summary for each variable.
-#' @param \dots Arguments passed on to [geom_line].
-#' @return Concatenation of a [geom_line] value and optionally a [geom_ribbon] value.
+#' @param \dots Arguments passed on to `geom_line`.
+#' @return Concatenation of a `geom_line` value and optionally a `geom_ribbon` value.
 #' @family geomes for inla and inlabru predictions
 #' @example inst/examples/gg.prediction.R
 
@@ -745,7 +745,7 @@ gg.RasterLayer <- function(data, mapping = aes_string(x = "x", y = "y", fill = "
   geom_tile(data = df, mapping = mapping, ...)
 }
 
-#' Plot method for posterior marginals estimated by [bru]
+#' Plot method for posterior marginals estimated by bru
 #'
 #' @description
 #'

R/inla.R

@@ -39,8 +39,8 @@ bru_standardise_names <- function(x) {
 #'
 #' @aliases predict.inla
 #' @export
-#' @param object A `bru` object obtained by calling [bru] or [lgcp].
-#' @param ... Arguments passed on to [predict.bru].
+#' @param object A `bru` object obtained by calling [bru()] or [lgcp()].
+#' @param ... Arguments passed on to [predict.bru()].
 #' @return A `prediction` object.
 #' @seealso [predict.inla()]
 #' @keywords internal

R/inlabru.R

@@ -4,14 +4,24 @@
 #'
 #' @details
 #'
-#' `inlabru` facilitates Bayesian spatial modeling using integrated nested Laplace approximations. It
-#' is heavily based on R-inla (<https://www.r-inla.org>) but adds additional modeling abilities.
-#' Tutorials and more information can be found at <http://www.inlabru.org/>.
+#' `inlabru` facilitates Bayesian spatial modelling using integrated nested
+#' Laplace approximations. It is heavily based on R-inla
+#' (<https://www.r-inla.org>) but adds additional modelling abilities and simplified
+#' syntax for (in particular) spatial models.
+#' Tutorials and more information can be found at
+#' <https://inlabru-org.github.io/inlabru/> and <http://www.inlabru.org/>.
+#' The iterative method used for non-linear predictors is documented in the
+#' `method` vignette.
 #'
-#' The main function for inference using inlabru is [bru]. For point process inference [lgcp] is
-#' a good starting point. The package comes with multiple real world data sets, namely [gorillas],
+#' The main function for inference using inlabru is [bru()]. For point process inference [lgcp()] is
+#' a good starting point.
+#' The general model specification details is documented in [component()] and [like()].
+#' Posterior quantities beyond the basic summaries can be calculated with
+#' a `predict()` method, documented in [predict.bru()].
+#' 
+#' The package comes with multiple real world data sets, namely [gorillas],
 #' [mexdolphin], [seals]. Plotting these data sets is straight forward using inlabru's extensions
-#' to `ggplot2`, e.g. the [gg] function. For educational purposes some simulated data sets are available
+#' to `ggplot2`, e.g. the [gg()] function. For educational purposes some simulated data sets are available
 #' as well, e.g. [Poisson1_1D], [Poisson2_1D], [Poisson2_1D] and [toygroups].
 #'
 #' @aliases inlabru
@@ -20,5 +30,6 @@
 #' @import methods
 #' @importFrom Matrix diag
 #' @author Fabian E. Bachl \email{bachlfab@@gmail.com}
+#'   and Finn Lindgren \email{finn.lindgren@@gmail.com}
 #' @name inlabru
 NULL