Skip to contents

Add predictors to a Biodiversity distribution object

Source: R/add_predictors.R
add_predictors.Rd

This function allows to add predictors to distribution or BiodiversityScenario objects. Predictors are covariates that in spatial projection have to match the geographic projection of the background layer in the distribution object. This function furthermore allows to transform or create derivates of provided predictors.

Usage

add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityDistribution,SpatRasterCollection'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityDistribution,SpatRaster'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityDistribution,stars'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityDistribution,data.frame'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityScenario,SpatRaster'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

# S4 method for class 'BiodiversityScenario,stars'
add_predictors(
  x,
  env,
  names = NULL,
  transform = "none",
  derivates = "none",
  derivate_knots = 4,
  int_variables = NULL,
  bgmask = TRUE,
  harmonize_na = FALSE,
  explode_factors = FALSE,
  priors = NULL,
  state = NULL,
  ...
)

Arguments

x

distribution() (i.e. BiodiversityDistribution) object.

env

A SpatRaster, stars or data.frame object.

names

A vector of character names describing the environmental stack in case they should be renamed.

transform

A vector stating whether predictors should be preprocessed in any way (Options: 'none','pca', 'scale', 'norm')

derivates

A Boolean check whether derivate features should be considered (Options: 'none', 'thresh', 'hinge', 'quad') )

derivate_knots

A single numeric or vector giving the number of knots for derivate creation if relevant (Default: 4).

int_variables

A vector with length greater or equal than 2 specifying the covariates (Default: NULL).

bgmask

Check whether the environmental data should be masked with the background layer (Default: TRUE).

harmonize_na

A logical value indicating of whether NA values should be harmonized among predictors (Default: FALSE).

explode_factors

logical of whether any factor variables should be split up into binary variables (one per class). (Default: FALSE).

priors

A PriorList object. Default is set to NULL which uses default prior assumptions.

state

A matrix with one value per variable (column) providing either a ( stats::mean(), stats::sd() ) for each variable in env for option 'scale' or a range of minimum and maximum values for option 'norm'. Effectively applies their value range for rescaling. In the case of provided stars data to a BiodiversityScenario object, the state variables are attempted to be compiled from the predictor ranges used for model inferrence (Default: NULL).

...

Other parameters passed down

Details

A transformation takes the provided rasters and for instance rescales them or transforms them through a principal component analysis (prcomp). In contrast, derivates leave the original provided predictors alone, but instead create new ones, for instance by transforming their values through a quadratic or hinge transformation. Note that this effectively increases the number of predictors in the object, generally requiring stronger regularization by the used Engine. Both transformations and derivates can also be combined. Available options for transformation are:

  • 'none' - Leaves the provided predictors in the original scale.

  • 'pca' - Converts the predictors to principal components. Note that this results in a renaming of the variables to principal component axes!

  • 'scale' - Transforms all predictors by applying scale on them.

  • 'norm' - Normalizes all predictors by transforming them to a scale from 0 to 1.

  • 'windsor' - Applies a windsorization to the target predictors. By default this effectively cuts the predictors to the 0.05 and 0.95, thus helping to remove extreme outliers.

Available options for creating derivates are:

  • 'none' - No additional predictor derivates are created.

  • 'quad' - Adds quadratic derivate predictors.

  • 'interaction' - Add interacting predictors. Interactions need to be specified ("int_variables")!

  • 'thresh' - Add threshold derivate predictors.

  • 'hinge' - Add hinge derivate predictors.

  • 'kmeans' - Add k-means derived factors.

  • 'bin' - Add predictors binned by their percentiles.

Note

Important: Not every Engine supported by the ibis.iSDM R-package allows missing data points among extracted covariates. Thus any observation with missing data is generally removed prior from model fitting. Thus ensure that covariates have appropriate no-data settings (for instance setting NA values to 0 or another out of range constant).

Not every engine does actually need covariates. For instance it is perfectly legit to fit a model with only occurrence data and a spatial latent effect (add_latent_spatial). This correspondents to a spatial kernel density estimate.

Certain names such "offset" are forbidden as predictor variable names. The function will return an error message if these are used.

Some engines use binary variables regardless of the parameter "explode_factors" set here.

Examples

if (FALSE) { # \dontrun{
 obj <- distribution(background) |>
        add_predictors(covariates, transform = 'scale')
 obj
} # }