Skip to contents

Equivalent to train, this function acts as a wrapper to project the model stored in a BiodiversityScenario object to newly supplied (future) covariates. Supplied predictors are usually spatial-temporal predictors which should be prepared via add_predictors() (e.g. transformations and derivates) in the same way as they have been during the initial modelling with distribution(). Any constrains specified in the scenario object are applied during the projection.


project.BiodiversityScenario(x, ...)

# S4 method for BiodiversityScenario
  date_interpolation = "none",
  stabilize = FALSE,
  stabilize_method = "loess",
  layer = "mean",
  verbose = getOption("ibis.setupmessages", default = TRUE),



A BiodiversityScenario object with set predictors. Note that some constrains such as MigClim can still simulate future change without projections.


passed on parameters.


A character on whether dates should be interpolated. Options include "none" (Default), "annual", "monthly", "daily".


A logical value indicating whether the suitability projection should be stabilized (Default: FALSE).


character stating the stabilization method to be applied. Currently supported is `loess`.


A character specifying the layer to be projected (Default: "mean").


Setting this logical value to TRUE prints out further information during the model fitting (Default: FALSE).


Saves stars objects of the obtained predictions in mod.


In the background the function x$project() for the respective model object is called, where x is fitted model object. For specifics on the constraints, see the relevant constrain functions, respectively:

  • add_constraint() for generic wrapper to add any of the available constrains.

  • add_constraint_dispersal() for specifying dispersal constraint on the temporal projections at each step.

  • add_constraint_MigClim() Using the MigClim R-package to simulate dispersal in projections.

  • add_constraint_connectivity() Apply a connectivity constraint at the projection, for instance by adding a barrier that prevents migration.

  • add_constraint_minsize() Adds a constraint on the minimum area a given thresholded patch should have, assuming that smaller areas are in fact not suitable.

  • add_constraint_adaptability() Apply an adaptability constraint to the projection, for instance constraining the speed a species is able to adapt to new conditions.

  • add_constraint_boundary() To artificially limit the distribution change. Similar as specifying projection limits, but can be used to specifically constrain a projection within a certain area (e.g. a species range or an island).

Many constrains also requires thresholds to be calculated. Adding threshold() to a BiodiversityScenario object enables the computation of thresholds at every step based on the threshold used for the main model (threshold values are taken from there).

It is also possible to make a complementary simulation with the steps package, which can be provided via simulate_population_steps() to the BiodiversityScenario object. Similar as with thresholds, estimates values will then be added to the outputs.

Finally this function also allows temporal stabilization across prediction steps via enabling the parameter stabilize and checking the stablize_method argument. Stabilization can for instance be helpful in situations where environmental variables are quite dynamic, but changes in projected suitability are not expected to abruptly increase or decrease. It is thus a way to smoothen out outliers from the projection. Options are so far for instance 'loess' which fits a loess() model per pixel and time step. This is conducted at the very of the processing steps and any thresholds will be recalculated afterwards.

See also


if (FALSE) {
# Fit a model
fit <- distribution(background) |>
        add_biodiversity_poipa(surveydata) |>
        add_predictors(env = predictors) |>
        engine_breg() |>

# Fit a scenario
sc <- scenario(fit) |>
        add_predictors(env = future_predictors) |>