# Add predictions from a fitted model to a Biodiversity distribution object

Source:`R/add_predictors_model.R`

`add_predictors_model.Rd`

This function is a convenience wrapper to add the output from a
previous fitted `DistributionModel`

to another `BiodiversityDistribution`

object. Obviously only works if a prediction was fitted in the model. Options
to instead add thresholds, or to transform / derivate the model outputs are
also supported.

## Usage

```
add_predictors_model(
x,
model,
transform = "scale",
derivates = "none",
threshold_only = FALSE,
priors = NULL,
...
)
# S4 method for BiodiversityDistribution
add_predictors_model(
x,
model,
transform = "scale",
derivates = "none",
threshold_only = FALSE,
priors = NULL,
...
)
```

## Arguments

- x
`distribution()`

(i.e.`BiodiversityDistribution`

) object.- model
A

`DistributionModel`

object.- 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'`

) )- threshold_only
A

`logical`

flag indicating whether to add thresholded layers from the fitted model (if existing) instead (Default:`FALSE`

).- priors
A

`PriorList`

object. Default is set to`NULL`

which uses default prior assumptions.- ...
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 transformed predictors.`'interaction'`

- Add interacting predictors. Interactions need to be specified (`"int_variables"`

)!`'thresh'`

- Add threshold transformed predictors.`'hinge'`

- Add hinge transformed predictors.`'bin'`

- Add predictors binned by their percentiles.

## Examples

```
if (FALSE) {
# Fit first model
fit <- distribution(background) |>
add_predictors(covariates) |>
add_biodiversity_poipa(species) |>
engine_glmnet() |>
train()
# New model object
obj <- distribution(background) |>
add_predictors_model(fit)
obj
}
```