---
title: "dynamicSDM: Dynamic distribution projections"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{dynamicSDM: Dynamic distribution projections}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```


```{r setup}
library(dynamicSDM)
```

## Stage 4: Dynamic projections of species distribution

In this tutorial, we will learn about functions within the *dynamicSDM* package for projecting
intra- and inter-annual geographical distributions and abundances at high spatiotemporal
resolution. This will involve extracting rasters for each explanatory variable across southern
Africa at various intervals. Then we can project our dynamic SDMs onto these data to visualise
species distribution patterns through space and time.

The *dynamicSDM* functions for extracting dynamic rasters require Google Earth Engine and Google
Drive to be initialised. Fill in the code below with your Google account email, and run the code to
check that *rgee* and *googledrive* have been correctly installed and authorised.

```{r check Google, eval = FALSE}
library(rgee)
rgee::ee_check()

library(googledrive)
googledrive::drive_user()
#user.email<-"your_google_email_here"
```

Note: You will need internet connection for this tutorial. Raster extraction may take some time
depending on your internet connection strength.

## Directory organisation

We will be extracting rasters, generating projection covariate data frames, exporting projection
rasters and saving GIFs. Let’s first make separate folders in our project directory to save this
various outputs too. This is especially important as this suite of *dynamicSDM* functions rely on
unique naming of files in the local directory or drive folder.

```{r create directories}
variablenames <- c("eight_sum_prec", "year_sum_prec", "grass_crop_percentage")

project_directory <- file.path(tempdir(), "dynamicSDM_vignette")
# project_directory<-"your_path_here"
dir.create(project_directory, showWarnings = FALSE)

projection_directories <- file.path(project_directory, "projection")
dir.create(projection_directories, showWarnings = FALSE)

projectionrasters <- file.path(project_directory, "projectionrasters")
dir.create(projectionrasters, showWarnings = FALSE)

projection_covariates <- file.path(project_directory, "projectioncovariates")
dir.create(projection_covariates, showWarnings = FALSE)

projection_GIF <- file.path(project_directory, "projection_GIF")
dir.create(projection_GIF, showWarnings = FALSE)
```


### a)	Generate projection dates

`dynamic_proj_dates()` generates all dates in a given period at the interval type and size
specified. This can be used to create a vector of dates that you want to project a species
distribution at.

```{r example-dynamic_proj_dates}
# 5 day intervals
dynamic_proj_dates(startdate = "2018-01-01",
                   enddate = "2018-12-01",
                   interval = 5, 
                   interval.level = "day")

# 2 week intervals
dynamic_proj_dates(startdate = "2018-01-01",
                   enddate = "2018-12-01",
                   interval = 2, 
                   interval.level = "week")
```

For this tutorial, we will use the following projection dates to explore the intra-annual
distribution patterns of red-billed quelea in southern Africa.

```{r case study dynamic_proj_dates}
projectiondates <- dynamic_proj_dates(startdate = "2018-01-01",
                                      enddate = "2018-12-01",
                                      interval = 3,
                                      interval.level = "month")
```


### b)	Extract projection rasters

`extract_dynamic_raster()` and `extract_buffered_raster()` are sister functions to those used in
stage 2 to extract explanatory variables. They require largely the same arguments input, but with
arguments to specify the temporal (projection dates) and spatial extents for the rasters.

Run the following code to extract rasters for each explanatory variable and projection date.

```{r example-extract_dynamic_raster, eval = FALSE}
data("sample_extent_data")

extract_dynamic_raster(dates = projectiondates,
                       datasetname = "UCSB-CHG/CHIRPS/DAILY",
                       bandname = "precipitation",
                       user.email = user.email,
                       spatial.res.metres = 5566,
                       GEE.math.fun = "sum",
                       temporal.direction = "prior",
                       temporal.res = 56,
                       spatial.ext = sample_extent_data,
                       varname = variablenames[1],
                       save.directory = projectionrasters)

extract_dynamic_raster(dates = projectiondates,
                       datasetname = "UCSB-CHG/CHIRPS/DAILY",
                       bandname = "precipitation",
                       user.email = user.email,
                       spatial.res.metres = 5566,
                       GEE.math.fun = "sum",
                       temporal.direction = "prior",
                       temporal.res = 364,
                       spatial.ext = sample_extent_data,
                       varname = variablenames[2],
                       save.directory = projectionrasters)

matrix<-dynamicSDM::get_moving_window(radial.distance = 10000,
                                      spatial.res.degrees = 0.05,
                                      spatial.ext = sample_extent_data)

extract_buffered_raster(dates=projectiondates,
                        datasetname = "MODIS/006/MCD12Q1",
                        bandname = "LC_Type5",
                        spatial.res.metres = 500,
                        GEE.math.fun = "sum",
                        moving.window.matrix = matrix,
                        user.email = user.email,
                        categories = c(6,7),
                        agg.factor = 12,
                        spatial.ext = sample_extent_data,
                        varname = variablenames[3],
                        save.directory = projectionrasters)
```

### c)	Combine dynamic projection covariates

Now we need to combine the rasters for each variable into single projection covariate data frames
for each projection date.

```{r example-dynamic_proj_covariates, eval = FALSE}
dynamic_proj_covariates(dates = projectiondates,
                        varnames = variablenames,
                        local.directory = projectionrasters,
                        spatial.ext = sample_extent_data,
                        spatial.mask = sample_extent_data,
                        spatial.res.degrees = 0.05,
                        resample.method = c("bilinear","bilinear","ngb"),
                        cov.file.type = "csv",
                        prj="+proj=longlat +datum=WGS84",
                        save.directory = projection_covariates)
```


### d)	Project models onto covariates

To project distribution onto these covariates, our fitted boosted regression tree models from stage
3 need to be imported and input into `dynamic_proj()`. You can read these in from your local
directory, or simply rerun the code here.

We choose to project distribution suitability (`projection.method = proportional`) but this function
can also generate binary projections if given threshold (`sdm.thresh`) or abundance if given fitted
species abundance models (`sam.mod`).

```{r example-dynamic_proj, eval = FALSE}
#sample_brt_models<- readRDS(paste0(project_directory, "/fitted_quelea_SDMs.rds"))
data("sample_explan_data")
sample_explan_data$weights <- (1 - sample_explan_data$REL_SAMP_EFFORT)

sample_brt_models <- brt_fit(sample_explan_data,
                             response.col = "presence.absence",
                             varnames = variablenames,
                             block.col = "BLOCK.CATS",
                             weights.col = "weights",
                             distribution = "bernoulli")

dynamic_proj(dates = projectiondates,
             projection.method = c("proportional"),
             local.directory = projection_covariates,
             cov.file.type = "csv",
             sdm.mod = sample_brt_models,
             spatial.mask = sample_extent_data,
             save.directory = projection_directories)
```


Let’s read in and plot our projections!

```{r plot projections, eval = FALSE}
terra::plot(terra::rast(list.files(projection_directories)[1]))
terra::plot(terra::rast(list.files(projection_directories)[2]))
terra::plot(terra::rast(list.files(projection_directories)[3]))
terra::plot(terra::rast(list.files(projection_directories)[4]))
```


### e)	Visualise projections with a GIF

To better visualise our dynamic distribution projections through time, `dynamic_proj_GIF()` can
generate animated GIFs from the projection rasters.

We will set our own colour scheme and add borders for the southern African countries. 

```{r example-dynamic_proj_GIF, eval = FALSE}

cols1<- c("#F0F0F0","#40863A","#FBF357","#ED8E07","#cc0000","#660000")
border.countries<- c('South Africa', 'Botswana','Lesotho', 'Swaziland','Mozambique','Namibia'
                     ,'Zimbabwe','Angola','Zambia','Malawi')

dynamic_proj_GIF(
  dates = projectiondates,
  projection.type = "proportional",
  local.directory = projection_directories,
  save.directory = projection_GIF,
  width = 7,
  height = 5,
  colour.palette.custom = cols1,
  borders = TRUE,
  border.regions = border.countries,
  border.colour = "grey50",
  legend.max = 1,
  legend.min = 0,
  legend.name =  "Distribution\n suitability",
  file.name = "RBQ_proportional_GIF")

```

## Summary
+ This concludes the *dynamicSDM* tutorial. We hope that you have been able to utilise the package
to model the dynamic distributions of our case study species, the red-billed quelea, and can now
apply these functions to your own study species!

+ We have demonstrated a variety of options across our functions, but even more are available with
the diverse and flexible arguments. Please see our package manual for full details of each
*dynamicSDM* function [manual](
https://github.com/r-a-dobson/dynamicSDM/blob/main/man/figures/dynamicSDM_1.3.pdf).

+ Also, please visit the GitHub discussion page for *dynamicSDM* if you have any questions or are
facing errors with any of our functions
[github](https://github.com/r-a-dobson/dynamicSDM/issues). We also have a quick guide to common
bugs that are thrown up when installing and running *dynamicSDM*.
