---
title: "Main functions: binary data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Main functions: binary data}
  %\VignetteEngine{knitr::knitr}
  %\VignetteEncoding{UTF-8}
---

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" integrity="sha512-2SwdPD6INVrV/lHTZbO2nodKhrnDdJK9/kg2XD1r9uGqPo1cUbujc+IYdlYdEErWNu69gVcYgdxlmVmzTWnetw==" crossorigin="anonymous" referrerpolicy="no-referrer" />


## <i class="fa-solid fa-code"></i> Complete code example

Here are presented, in a full and complete example, all main functions (starting with `BIOMOD_[...]`) of `biomod2`.

The data set used is the [DataSpecies](../reference/DataSpecies.html) containing presence/absence data. <br/> Similar examples are presented for count data on the [Main functions (abund) webpage](examples_1_mainFunctions_AB.html).


<br/><br/>


### <i class="fa-solid fa-truck-ramp-box"></i> Load dataset and variables

```R
library(biomod2)
library(terra)

# Load species occurrences (6 species available)
data('DataSpecies')
head(DataSpecies)

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

# Get corresponding presence/absence data
myResp <- as.numeric(DataSpecies[, myRespName])

# Get corresponding XY coordinates
myRespXY <- DataSpecies[, c('X_WGS84', 'Y_WGS84')]

# Load environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
data('bioclim_current')
myExpl <- rast(bioclim_current)
```


<br/><br/>


### <i class="fa-solid fa-list-check"></i> Prepare data & parameters

#### <i class="fa-solid fa-spell-check"></i> Format data (observations & explanatory variables)

```R
# Format data with true absences
myBiomodData <- BIOMOD_FormatingData(resp.name = myRespName,
                                     resp.var = myResp,
                                     resp.xy = myRespXY,
                                     expl.var = myExpl)
myBiomodData
myPlot <- plot(myBiomodData)
```

#### <i class="fa-solid fa-shuffle"></i> Pseudo-absences extraction

Single or multiple set of pseudo-absences can be selected with the [`BIOMOD_FormatingData`](../reference/BIOMOD_FormatingData.html) function, which calls the [`bm_PseudoAbsences`](../reference/bm_PseudoAbsences.html) function to do so. More examples are presented on the [Auxiliary functions webpage](examples_2_auxiliaryFunctions.html).

```R
# # Transform true absences into potential pseudo-absences
# myResp.PA <- ifelse(myResp == 1, 1, NA)
# 
# # Format data with pseudo-absences : random method
# myBiomodData.r <- BIOMOD_FormatingData(resp.var = myResp.PA,
#                                        expl.var = myExpl,
#                                        resp.xy = myRespXY,
#                                        resp.name = myRespName,
#                                        PA.nb.rep = 4,
#                                        PA.nb.absences = 1000,
#                                        PA.strategy = 'random')
# 
# myBiomodData.r
# myPlot <- plot(myBiomodData.r)
```

```R
# # Select multiple sets of pseudo-absences
#
# # Transform true absences into potential pseudo-absences
# myResp.PA <- ifelse(myResp == 1, 1, NA)
# 
# # Format Data with pseudo-absences : random method
# myBiomodData.multi <- BIOMOD_FormatingData(resp.var = myResp.PA,
#                                            expl.var = myExpl,
#                                            resp.xy = myRespXY,
#                                            resp.name = myRespName,
#                                            PA.nb.rep = 4,
#                                            PA.nb.absences = c(1000, 500, 500, 200),
#                                            PA.strategy = 'random')
# myBiomodData.multi
# summary(myBiomodData.multi)
# myPlot <- plot(myBiomodData.multi)
```

#### <i class="fa-solid fa-scissors"></i> Cross-validation datasets

Several cross-validation methods are available and can be selected with the [`BIOMOD_Modeling`](../reference/BIOMOD_Modeling.html) function, which calls the [`bm_CrossValidation`](../reference/bm_CrossValidation.html) function to do so. More examples are presented on the [Auxiliary functions webpage](examples_2_auxiliaryFunctions.html).

```R
# # k-fold selection
# cv.k <- bm_CrossValidation(bm.format = myBiomodData,
#                            strategy = 'kfold',
#                            nb.rep = 2,
#                            k = 3)
# 
# # stratified selection (geographic)
# cv.s <- bm_CrossValidation(bm.format = myBiomodData,
#                            strategy = 'strat',
#                            k = 3,
#                            balance = 'presences',
#                            strat = 'x')
#
# head(cv.k)
# head(cv.s)
# myPlot <- plot(myBiomodData, plot.eval = TRUE, calib.lines = cv.k)
# myPlot <- plot(myBiomodData, plot.eval = TRUE, calib.lines = cv.s)
```

#### <i class="fa-solid fa-rectangle-list"></i> Retrieve modeling options

Modeling options are automatically retrieved from selected models within the [`BIOMOD_Modeling`](../reference/BIOMOD_Modeling.html) function, which calls the [`bm_ModelingOptions`](../reference/bm_ModelingOptions.html) function to do so. Model parameters can also be automatically tuned to a specific dataset, by calling the [`bm_Tuning`](../reference/bm_Tuning.html) function, however it can be quite long. More examples are presented on the [Auxiliary functions webpage](examples_2_auxiliaryFunctions.html).

```R
# # bigboss parameters
# opt.b <- bm_ModelingOptions(data.type = 'binary',
#                             models = c('RF', 'XGBOOST'),
#                             strategy = 'bigboss')
# 
# # tuned parameters with formated data
# opt.t <- bm_ModelingOptions(data.type = 'binary',
#                             models = c('RF', 'XGBOOST'),
#                             strategy = 'tuned',
#                             bm.format = myBiomodData)
# 
# opt.b
# opt.t
```

<br/><br/>


### <i class="fa-solid fa-gear"></i> Run modeling

#### <i class="fa-solid fa-virus"></i> Single models

```R
# Model single models
myBiomodSM <- BIOMOD_Modeling(bm.format = myBiomodData,
                              modeling.id = 'AllModels',
                              CV.strategy = 'random',
                              CV.nb.rep = 2,
                              CV.perc = 0.8,
                              OPT.strategy = 'bigboss',
                              metric.eval = c('AUCroc', 'AUCprg', 'BOYCE', 'TSS'),
                              var.import = 3)
                              # seed.val = 123)
                              # nb.cpu = 8)
myBiomodSM

# Get evaluation scores & variables importance
get_evaluations(myBiomodSM)
get_variables_importance(myBiomodSM)

# Represent evaluation scores & variables importance
myPlot <- bm_PlotEvalMean(bm.out = myBiomodSM, dataset = 'calibration')
myPlot <- bm_PlotEvalMean(bm.out = myBiomodSM, dataset = 'validation')
myPlot <- bm_PlotEvalBoxplot(bm.out = myBiomodSM, dataset = 'calibration', group.by = c('algo', 'algo'))
myPlot <- bm_PlotEvalBoxplot(bm.out = myBiomodSM, dataset = 'calibration', group.by = c('algo', 'run'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodSM, group.by = c('expl.var', 'algo', 'algo'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodSM, group.by = c('expl.var', 'algo', 'run'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodSM, group.by = c('algo', 'expl.var', 'run'))
names(myPlot)

# Create model subsets
mySet1 <- get_built_models(myBiomodSM)[c(1, 4, 8, 10, 13)]
mySet2 <- get_built_models(myBiomodSM)[4]

# Represent response curves
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodSM, models.chosen = mySet1, fixed.var = 'median')
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodSM, models.chosen = mySet1, fixed.var = 'min')
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodSM, models.chosen = mySet2, do.bivariate = TRUE)
                      
# Explore models' outliers & residuals
myPlot <- bm_ModelAnalysis(bm.mod = myBiomodSM, models.chosen = mySet1)
names(myPlot)
```


#### <i class="fa-solid fa-viruses"></i> Ensemble models

```R
# Model ensemble models
myBiomodEM <- BIOMOD_EnsembleModeling(bm.mod = myBiomodSM,
                                      models.chosen = 'all',
                                      em.by = 'all',
                                      em.algo = c('EMmedian', 'EMmean', 'EMwmean',
                                                  'EMca', 'EMci', 'EMcv'),
                                      metric.select = 'BOYCE',
                                      metric.select.thresh = c(0.8),
                                      metric.eval = c('AUCroc', 'AUCprg', 'BOYCE', 'TSS'),
                                      var.import = 3,
                                      EMci.alpha = 0.05,
                                      EMwmean.decay = 'proportional')
myBiomodEM

# Get evaluation scores & variables importance
get_evaluations(myBiomodEM)
get_variables_importance(myBiomodEM)

# Represent evaluation scores & variables importance
myPlot <- bm_PlotEvalMean(bm.out = myBiomodEM, dataset = 'calibration', group.by = 'full.name')
myPlot <- bm_PlotEvalBoxplot(bm.out = myBiomodEM, dataset = 'calibration', group.by = c('full.name', 'full.name'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodEM, group.by = c('expl.var', 'full.name', 'full.name'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodEM, group.by = c('expl.var', 'algo', 'merged.by.run'))
myPlot <- bm_PlotVarImpBoxplot(bm.out = myBiomodEM, group.by = c('algo', 'expl.var', 'merged.by.run'))

# Create model subsets
mySet1 <- get_built_models(myBiomodEM)[c(1, 6, 7)]
mySet2 <- get_built_models(myBiomodEM)[7]

# Represent response curves
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodEM, models.chosen = mySet1, fixed.var = 'median')
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodEM, models.chosen = mySet1, fixed.var = 'min')
myPlot <- bm_PlotResponseCurves(bm.out = myBiomodEM, models.chosen = mySet2, do.bivariate = TRUE)
```

<br/><br/>


### <i class="fa-solid fa-earth-europe"></i> Project models

#### <i class="fa-solid fa-virus"></i> Single models

```R
# Project single models
myBiomodProj <- BIOMOD_Projection(bm.mod = myBiomodSM,
                                  proj.name = 'Current',
                                  new.env = myExpl,
                                  models.chosen = 'all',
                                  metric.binary = 'all',
                                  metric.filter = 'all',
                                  build.clamping.mask = TRUE)
myBiomodProj
plot(myBiomodProj)
```

#### <i class="fa-solid fa-viruses"></i> Ensemble models

```R
# Project ensemble models (from single projections)
myBiomodEMProj <- BIOMOD_EnsembleForecasting(bm.em = myBiomodEM, 
                                             bm.proj = myBiomodProj,
                                             models.chosen = 'all',
                                             metric.binary = 'all',
                                             metric.filter = 'all')
                                             
# Project ensemble models (building single projections)
myBiomodEMProj <- BIOMOD_EnsembleForecasting(bm.em = myBiomodEM,
                                             proj.name = 'CurrentEM',
                                             new.env = myExpl,
                                             models.chosen = 'all',
                                             metric.binary = 'all',
                                             metric.filter = 'all')
myBiomodEMProj
plot(myBiomodEMProj)
```

<br/><br/>


### <i class="fa-solid fa-ruler-combined"></i> Compare range sizes

```R
# Load environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
data('bioclim_future')
myExplFuture = rast(bioclim_future)

# Project onto future conditions
myBiomodProjFuture <- BIOMOD_Projection(bm.mod = myBiomodSM,
                                        proj.name = 'Future',
                                        new.env = myExplFuture,
                                        models.chosen = 'all',
                                        metric.binary = 'TSS',
                                        build.clamping.mask = TRUE)

# Compute differences
myBiomodRangeSize <- BIOMOD_RangeSize(proj.current = myBiomodProj, 
                                      proj.future = myBiomodProjFuture,
                                      metric.binary = 'TSS')

myBiomodRangeSize@Compt.By.Models
plot(myBiomodRangeSize@Diff.By.Pixel)

# Represent main results 
myPlot <- bm_PlotRangeSize(bm.range = myBiomodRangeSize, 
                           do.count = TRUE,
                           do.perc = TRUE,
                           do.maps = TRUE,
                           do.mean = TRUE)
```

<br/><br/>


### <i class="fa-solid fa-file-export"></i> Export a report

```R
# Get a summary report
BIOMOD_Report(bm.out = myBiomodEM, strategy = 'report')

# Get a pre-filled ODMAP
BIOMOD_Report(bm.out = myBiomodEM, strategy = 'ODMAP')

# Get a code report
BIOMOD_Report(bm.out = myBiomodEM, strategy = 'code')
```

<br/><br/>
