---
title: "Using_bRacatus"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using_bRacatus}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

# Tutorial to install and use bRacatus

This tutorial aims to guide the user from the installation to the data visualisation of bRacatus. We will walk the user through two examples. The first example uses GIFT checklist data as reference regions. The second example uses range maps as reference regions. bRacatus allows users to input their own data or to obtain these data from online repositories. In this tutorial, we will show how to use GBIF-facilitated point data and checklists provided by GIFT. We will also show an example in which range maps are input by the user. We ran all tests in a computer with 8GB of RAM, the execution times of each function may vary depending on the computer configuration, as well as on the internet connection for the functions requesting data through an API.

## Installing bRacatus 

```{r, eval = FALSE}
install.packages ("bRacatus")
library (bRacatus)
```

## Example 1 - GIFT checklist data as reference regions

1 - Obtaining, preparing and visualising the input data

```{r, eval = FALSE}
pts <- getOcc ("Babiana tubulosa")
head (pts)[,c(1:4)]
```

Running time: ≈ 1s.
Output: a data.frame containing georeferenced records from GBIF.

```{r, echo = FALSE}
data (pts)
head (pts)[,c(1:4)]
```

```{r}
plotOcc (pts)
```

Running time: ≈ 1s.
Output: a map showing the occurrence points. 

```{r, warning = FALSE}
ref_reg <- giftRegions ("Babiana tubulosa")
ref_reg
```

Running time: ≈ 3s.
Output: a list with three SpatialPolygonsDataFrame objects, one containing all the features of the regions where the species is present, one containing only the regions where the species is known to be native, and the last one containing the regions where it is alien.

```{r}
plotRefReg (ref_reg)
```

Running time: ≈ 2s.
Output: a figure with three occurrence maps, showing the regions where the species is present, native and alien.

```{r, eval = FALSE}
signals <- signalCalculation (ref_reg,pts,biogeo = TRUE)
```

Running time: ≈ 2s.
Output: The data.frame of species occurrences with extra columns containing the location ID and presence signals for each point. If biogeo=TRUE, the  data.frame also includes the nativeness and alienness indices.

```{r, echo = FALSE}
data(signals)
```

Running time: ≈ 3s.
Output: the dataFrame occID with an extra column containing the presence signals for each point. If biogeo=TRUE, the dataFrame also includes the nativeness and alienness indices.

2- Applying the models and visualising the results

```{r}
acc <- accuracy (signals)
```

Running time: < 1s.
Output: the dataFrame downloaded from GBIF containing the species occurrence information and an extra column indicating the estimated accuracy of each point.

```{r}
biogeo <- biogeoStatus (signals)
```

Running time: < 1s.
Output: the dataFrame  downloaded from GBIF containing the species occurrence information and an extra column indicating the estimated biogeographical status of each point.

```{r}
plotAccuracy (acc)
```

Running time: < 1s.
Output: a map showing the accuracy of the records in a gradient from most likely false (0) to most likely true (1).

```{r}
plotBiogeoStatus (biogeo)
```

Running time: < 1s.
Output: a map showing the nativeness of the  points in a gradient from most likely alien (0) to most likely native (1).


## Example 2 - User input range map as reference regions

```{r,  eval = FALSE}
pts2 <- getOcc ("Phalanger orientalis")   # Running time: ≈ 1s.
```

```{r, echo = FALSE}
data (pts2)
```

Simulate points for visualisation purposes

```{r}
pts2 <- data.frame(species=pts2$species,
                     decimalLongitude=pts2$decimalLongitude,
                     decimalLatitude=pts2$decimalLatitude,
                     origin="GBIF")       # Running time: < 1s.

extra_points <- data.frame(species="Phalanger orientalis",
                    decimalLongitude=c(125.257,112.765,110.632,112.192,121.130,
                                       142.607,126.877,164.761,109.036),
                    decimalLatitude=c(8.261,2.396,-1.518,-7.821,-20.655,-13.639,
                                      -17.904,-20.671,12.938),
                           origin="Simulated")     # Running time: < 1s.

pts3 <- rbind(pts2,extra_points)     # Running time: < 1s.

plotOcc (pts3)  # Running time: < 1s.
```

The range map for this species is part of the package as an example. The user can introduce their own range maps for other species.

```{r, warning = FALSE}
ref_reg <- Range_Phalanger_orientalis
range_map_ref_reg <- rangeMaps(ref_reg)  # Running time: < 1s.
plotRefReg (range_map_ref_reg)  # Running time: < 1s.
```

```{r, eval = FALSE}
signals_3 <- signalCalculation (range_map_ref_reg,pts3,biogeo = TRUE) 
# Running time: ≈ 40s.
```

```{r, echo = FALSE}
data(signals_3)
```

```{r}
acc <- accuracy (signals_3)   # Running time: < 1s.
biogeo <- biogeoStatus (signals_3)   # Running time: < 1s.
```

```{r}
plotAccuracy (acc, regional=T, reg.by="points", borders=F, 
              col.features="gray80",col.bg="white",plot.range=T,
              range=Range_Phalanger_orientalis, box=T)
# Running time: < 1s.
```

```{r}
plotBiogeoStatus (biogeo, regional=T, reg.by="points", borders=F,
                  col.features="gray80", col.bg="white", plot.range=T, 
                  range=Range_Phalanger_orientalis, box=T)
# Running time: < 1s.
```

