biomod2 (version 3.3-7.1)

BIOMOD_Projection: Project the calibrated models within biomod2 into new space or time

Description

For all the models currently implemented, biomod2 is able to project potential distributions of species in other areas, other resolutions or other time scales.

Usage

BIOMOD_Projection(modeling.output,
                  new.env,
                  proj.name,
                  xy.new.env = NULL,
                  selected.models = 'all',
                  binary.meth = NULL,
                  filtered.meth = NULL,
                  compress = TRUE,
                  build.clamping.mask = TRUE,
                  ...)

Arguments

modeling.output

"BIOMOD.models.out" object produced by a BIOMOD_Modeling run

new.env

A set of explanatory variables onto which models will be projected . It could be a data.frame, a matrix, or a rasterStack object. Make sure the column names (data.frame or matrix) or layer Names (rasterStack) perfectly match with the names of variables used to build the models in the previous steps.

proj.name

a character defining the projection name (a new folder will be created with this name)

xy.new.env

optional coordinates of new.env data. Ignored if new.env is a rasterStack

selected.models

'all' when all models have to be used to render projections or a subset vector of modelling.output models computed (accessing with the slot @models.computed of your "BIOMOD.models.out" object)

binary.meth

a vector of a subset of models evaluation method computed before (see BIOMOD_Modeling). If NULL then no binary transformation computed, else the given binary techniques will be used to transform the projection into 0/1 data.

filtered.meth

a vector of a subset of models evaluation method computed before (see BIOMOD_Modeling). if NULL then no filtering transformation computed, else the given binary techniques will be used to transform the projection by stetting to 0 the probability values below a specific threshold.

compress

Boolean or character, the compression format of objects stored on your hard drive. May be one of ‘TRUE’, ‘FALSE’, ‘xz’ or ‘gzip’ (see save)

build.clamping.mask

if TRUE, a clamping mask will be saved on hard drive different (see details)

...

Additional arguments (see details section)

Value

Returns the projections for all selected model ("BIOMOD.projection.out" object), and stored in the hard drive on the specific directory names by the name of the projection. The data is a 4-dimensions array (see ...) if new.env is a matrix or a data.frame. It is a rasterStack if new.env is a rasterStack and or several rasterLayers if the rasterStack is too large.

A new folder is also created on your hard drive. This folder contains the created projection object (basic one and binary and filtered ones if selected). The object are loaded with the load function. The loaded object can be then plotted and analysed.

Details

Projections are done for all selected models, that means (by default) for all evaluation run, and pseudo absences selections if applicable. This projections may be used later to compute ensemble forecasting.

If build.clamping.mask is set to TRUE a file (same type than new.env arg) will be saved in your projection folder. This mask will identifies locations where predictions are uncertain because the values of the variables are outside the range used for calibrating the models. The ‘build.clamping.mask’ values correspond to the number of variables that are out of their calibrating/training range. (see vignette for more details)

… may be :

• silent:logical, if TRUE, console outputs are turned off

• do.stack: logical, if TRUE, attempt to save all projections in a unique object i.e RasterStack. If FALSE or if objects are too heavy to be load all together in memory, projections will be stored into separated files.

• keep.in.memory:logical, if FALSE only the link pointing to a hard drive copy of projections are stored in output object. That can be useful to prevent memory issues.

• output.format:whether ‘.RData’, ‘.grd’ or ‘.img’ defining projections saving format (on hard drive). If new.env argument is under table format (data.frame or matrix), the only choice you have is ‘.RData’

• omit.na:logical, if TRUE (default), all not fully referenced environmental points will get a NA as prediction. If FALSE, models that can produce predictions with incomplete data will return a prediction value for this points.

• on_0_1000:logical, if TRUE (default), 0 - 1 probabilities are converted into a 0 - 1000 integer scale. This implies a lot of memory saving. User that want to comeback on a 0 - 1 scale latter will just have to divide all projections by 1000

See Also

BIOMOD_Modeling, BIOMOD_FormatingData, BIOMOD_ModelingOptions

Examples

# NOT RUN {
# species occurrences
DataSpecies <- read.csv(system.file("external/species/mammals_table.csv",
                                    package="biomod2"), row.names = 1)
head(DataSpecies)

# the name of studied species
myRespName <- 'GuloGulo'

# the presence/absences data for our species 
myResp <- as.numeric(DataSpecies[,myRespName])

# the XY coordinates of species data
myRespXY <- DataSpecies[,c("X_WGS84","Y_WGS84")]


# Environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
myExpl = stack( system.file( "external/bioclim/current/bio3.grd", 
                     package="biomod2"),
                system.file( "external/bioclim/current/bio4.grd", 
                             package="biomod2"), 
                system.file( "external/bioclim/current/bio7.grd", 
                             package="biomod2"),  
                system.file( "external/bioclim/current/bio11.grd", 
                             package="biomod2"), 
                system.file( "external/bioclim/current/bio12.grd", 
                             package="biomod2"))
# 1. Formatting Data
myBiomodData <- BIOMOD_FormatingData(resp.var = myResp,
                                     expl.var = myExpl,
                                     resp.xy = myRespXY,
                                     resp.name = myRespName)

# 2. Defining Models Options using default options.
myBiomodOption <- BIOMOD_ModelingOptions()

# 3. Doing Modelisation

myBiomodModelOut <- BIOMOD_Modeling( myBiomodData, 
                                       models = c('SRE','RF'), 
                                       models.options = myBiomodOption, 
                                       NbRunEval=1, 
                                       DataSplit=70,
                                       models.eval.meth = c('TSS'),
                                       do.full.models = FALSE)


# 4.1 Projection on current environemental conditions

myBiomodProjection <- BIOMOD_Projection(modeling.output = myBiomodModelOut,
                                          new.env = myExpl,
                                          proj.name = 'current',
                                          selected.models = 'all',
                                          binary.meth = 'TSS',
                                          compress = FALSE,
                                          build.clamping.mask = FALSE)

# }
# NOT RUN {
# 4.2 Projection on future environemental conditions
myExplFuture = stack(system.file("external/bioclim/future/bio3.grd",package="biomod2"),
                     system.file("external/bioclim/future/bio4.grd",package="biomod2"),
                     system.file("external/bioclim/future/bio7.grd",package="biomod2"),
                     system.file("external/bioclim/future/bio11.grd",package="biomod2"),
                     system.file("external/bioclim/future/bio12.grd",package="biomod2"))

myBiomodProjectionFuture <- BIOMOD_Projection(modeling.output = myBiomodModelOut,
                                              new.env = myExplFuture,
                                              proj.name = 'future',
                                              selected.models = 'all',
                                              binary.meth = 'TSS',
                                              compress = FALSE,
                                              build.clamping.mask = TRUE)

# print summary and plot projections
myBiomodProjectionFuture
plot(myBiomodProjectionFuture)
# }
# NOT RUN {
                                       
# }