ReadMe.Rmd

---
title: "BAMexploreR"
author: "Melina Houle"
date: "`r Sys.Date()`"
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  warning = FALSE
)
```


<!-- badges: start -->
<!-- badges: end -->

`BAMexploreR` provides a set of functions for manipulating version 4 and 5 of the BAM's landbird models.

You can visit the package website here: https://github.com/borealbirds/BAMexploreR.

## Installation

You can install the development version of `BAMexploreR` from [GitHub](https://github.com/) with:

```{r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("borealbirds/BAMexploreR", force = TRUE, dependencies = TRUE)
devtools::document()
devtools::install()
```

## Citation

Please cite the _BAMexploreR_ package when using it in publications. To cite the latest official version, please use:


```{r, echo = FALSE, results = "asis"}
dev_version <- packageDescription("BAMexploreR")$Version
cat(paste0("\\> Houle M, Boehm M, Wu SC, Knight E, ... (", format(Sys.time(), "%Y"),"). BAMexploreR: Evaluating boreal birds density in Canada using R. R package version ", dev_version, ". Available at https://github.com/borealbirds/BAMexploreR\n"))
```

## Quick Start
This quick start guides shows how to identify species available per version, identify subregion(s) that intersect a area of interest (AOI) and download species specific density maps at the right scale.

The package includes demo dataset `vignette.shp` and `vignette.rast` that represent simulated AOI to demonstrate the workflow of the different functions.

```{r load_libraries, message=FALSE}
library(BAMexploreR)
devtools::load_all()
library(googledrive)
library(tmap)
```


Function : sppList

The function produce a character vector of species available to download. To retrieve available species, the function derive the list using the version, and type of output. The function allow to have the output either by "species_code", "common_name", "family_name" or "scientific_name". 

```{r sppList, message=FALSE}
# Check which species are part of the National Model v4
#drive_auth()
#ttt <- drive_auth()
#saveRDS(ttt, "token.rds")
if (!googledrive::drive_has_token()) {
    googledrive::drive_auth(cache= TRUE)
}
spp <- sppList("v4", "mean", "species_code")
print(spp)

print(guild_opt)
spp <- sppList("v5", "mean", "species_code")
spp <- sppList("v5", "mean", "species_code", guild ="Forest_Birds")
spp <- sppList("v5", "mean", "species_code", guild ="Long_Distance_Migrants")

spp <- sppList("v5", "mean", "species_code", guild =c("Forest_Birds","Waterfowl"))
print(spp)
```

Function : mapBCR

Retrieve list of BCR overlaid by the AOI. If no AOI is provided, the user can either get a list of everything that is available or look at the map of how subunit are divided. 

```{r mapBCR, message=FALSE}
# NO AOI provided
tmap_mode("plot")
subUnitsv4_results <- mapBCR("v4") 
print(subUnitsv4_results$map)
print(subUnitsv4_results$subUnits)

subUnitsv5_results <- mapBCR("v5") 
print(subUnitsv5_results$map)
print(subUnitsv5_results$subUnits)

# with AOI provided
aoi_shp <- system.file("extdata", "vignette_poly_LAEA.shp", package = "BAMexploreR")
aoi_sf <- vect(aoi_shp)
subUnits_results <- mapBCR("v5", ext=aoi_sf) 
print(subUnits_results$map)
print(subUnits_results$subUnits)
```