Using_bRacatus

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 three examples. The first example uses GIFT checklist data as reference regions. Afterwards, a second example, containing data that are more complex, will be introduced to compare the functions’ performance when dealing with a bigger data volume, still using the GIFT API. Finally, the third 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 the bRacatus from GitHub

The package is available at the GitHub server https://github.com/EduardoArle/bRacatus. To install bRacatus from GitHub, the devtools package is required, which can be installed and loaded by the following steps.

install.packages ("devtools")
library (devtools)
devtools::install_github ("EduardoArle/bRacatus")
library (bRacatus)

bRacatus is also available on CRAN.

install.packages ("bRacatus")
library (bRacatus)

Example 1 - GIFT checklist data as reference regions

1 - Obtaining, preparing and visualising the input data

pts <- getOcc ("Babiana tubulosa")
head(pts)[,c(1:4)]
#>           key                       scientificName decimalLatitude
#> 1: 2856692924 Babiana tubulosa (Burm.f.) Ker Gawl.       -33.20938
#> 2: 2242791467 Babiana tubulosa (Burm.f.) Ker Gawl.       -33.93429
#> 3: 2366114241 Babiana tubulosa (Burm.f.) Ker Gawl.       -33.12861
#> 4: 2366129558 Babiana tubulosa (Burm.f.) Ker Gawl.       -33.51111
#> 5: 2597704808 Babiana tubulosa (Burm.f.) Ker Gawl.       -33.18015
#> 6: 1899793587 Babiana tubulosa (Burm.f.) Ker Gawl.       -32.94962
#>    decimalLongitude
#> 1:         18.08737
#> 2:         18.38712
#> 3:         18.01611
#> 4:         18.32110
#> 5:         18.06211
#> 6:         17.98334

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

plotOcc (pts)
#> world is invalid
#> Attempting to make world valid by zero-width buffering

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

ref_reg <- giftRegions ("Babiana tubulosa")
ref_reg
#> $Presence
#> class       : SpatialPolygonsDataFrame 
#> features    : 3 
#> extent      : 11.75274, 129, -35.19272, -13.68923  (xmin, xmax, ymin, ymax)
#> crs         : +proj=longlat +datum=WGS84 +no_defs 
#> variables   : 22
#> names       : entity_ID,        geo_entity,    point_x,    point_y,           area,       x_min,       x_max,        y_min,        y_max, suit_geo, suit_geo_rst, entity_class,       entity_type, overlap_checked, overlap_glonaf_checked, ... 
#> min values  :     10526,    Cape Provinces,  22.532481, -30.902179,  661495.380275, 11.71634462, 30.19264462,   -35.192768, -24.76539484,        0,            0,     Mainland, Botanical Country,               1,                      1, ... 
#> max values  :     10918, Western Australia, 122.178368, -25.470892, 2670674.376922,  112.919724,  129.000015, -34.82199484,    -13.68923,        1,            1,     Mainland, Botanical Country,               1,                      1, ... 
#> 
#> $Native
#> class       : SpatialPolygonsDataFrame 
#> features    : 2 
#> extent      : 11.75274, 32.89044, -34.82199, -16.97359  (xmin, xmax, ymin, ymax)
#> crs         : +proj=longlat +datum=WGS84 +no_defs 
#> variables   : 22
#> names       : entity_ID,      geo_entity,   point_x,    point_y,           area,       x_min,       x_max,        y_min,        y_max, suit_geo, suit_geo_rst, entity_class,       entity_type, overlap_checked, overlap_glonaf_checked, ... 
#> min values  :     10526,  Cape Provinces, 22.532481, -30.902179,  661495.380275, 11.71634462, 30.19264462, -34.82199484, -24.76539484,        0,            0,     Mainland, Botanical Country,               1,                      1, ... 
#> max values  :     10646, Southern Africa, 22.534039, -25.486517, 2670674.376922, 16.48334462, 32.89044462, -34.82199484, -16.95279484,        0,            0,     Mainland, Botanical Country,               1,                      1, ... 
#> 
#> $Alien
#> class       : SpatialPolygonsDataFrame 
#> features    : 1 
#> extent      : 112.9669, 129, -35.19272, -13.68923  (xmin, xmax, ymin, ymax)
#> crs         : +proj=longlat +datum=WGS84 +no_defs 
#> variables   : 22
#> names       : entity_ID,        geo_entity,    point_x,    point_y,           area,      x_min,      x_max,      y_min,     y_max, suit_geo, suit_geo_rst, entity_class,       entity_type, overlap_checked, overlap_glonaf_checked, ... 
#> value       :     10918, Western Australia, 122.178368, -25.470892, 2525437.318199, 112.919724, 129.000015, -35.192768, -13.68923,        1,            1,     Mainland, Botanical Country,               1,                      1, ...

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.

plotRefReg (ref_reg)

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

ref_reg_rast <- rasteriseChecklists (ref_reg)

Running time: ≈ 6s. Output: A list containing data on the checklists, categorised as “Presence”, “Native” or “Alien”. These are stored in half a degree rasters and provide information on the prior confidence of detection in each cell.

occ_ID <- occID (pts)

Running time: < 1s. Output: a dataFrame containing the original data and the cellID of each point record.

ref_reg_ID <- valueID (ref_reg_rast)

Running time: < 1s. Output: a list with cell IDs and a priori confidence values for all cells where the species is present, native and alien.

signals <- signalCalculation (ref_reg_ID,occ_ID,biogeo = TRUE)

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

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.

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.

plotAccuracy (acc)
#> world is invalid
#> Attempting to make world valid by zero-width buffering

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).

plotBiogeoStatus (biogeo)
#> world is invalid
#> Attempting to make world valid by zero-width buffering

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 - GIFT checklist data as reference regions, a more complex example with more records and reference regions.

pts <- getOcc ("Senna bicapsularis")   # Running time: ≈ 7s.
plotOcc (pts)  # Running time: < 1s.
#> world is invalid
#> Attempting to make world valid by zero-width buffering

ref_reg <- giftRegions ("Senna bicapsularis")   # Running time: ≈ 120s.
plotRefReg (ref_reg)  # Running time: ≈ 2s.

ref_reg_rast <- rasteriseChecklists (ref_reg)   # Running time: ≈ 40s.
occ_ID <- occID (pts)   # Running time: < 1s.
ref_reg_ID <- valueID (ref_reg_rast)   # Running time: < 1s.
signals_2 <- signalCalculation (ref_reg_ID,occ_ID,biogeo = TRUE)   # Running time: ≈ 18s.
acc <- accuracy (signals_2)   # Running time: < 1s.
biogeo <- biogeoStatus (signals_2)   # Running time: < 1s.
plotAccuracy (acc)   # Running time: < 1s.
#> world is invalid
#> Attempting to make world valid by zero-width buffering

plotBiogeoStatus (biogeo)   # Running time: < 1s.
#> world is invalid
#> Attempting to make world valid by zero-width buffering

Example 3 - User input range map as reference regions

pts <- getOcc ("Phalanger orientalis")   # Running time: ≈ 1s.

Simulate points for visualisation purposes

pts2 <- data.frame(species=pts$species,
                       decimalLongitude=pts$decimalLongitude,
                       decimalLatitude=pts$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.
#> world is invalid
#> Attempting to make world valid by zero-width buffering

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.

ref_reg <- Range_Phalanger_orientalis
range_map_ref_reg <- rangeMaps(ref_reg)  # Running time: < 1s.
plotRefReg (range_map_ref_reg)  # Running time: < 1s.

ref_reg_rast <- rasteriseChecklists (range_map_ref_reg) # Running time: ≈ 10s.
occ_ID <- occID (pts3)   # Running time: < 1s.
ref_reg_ID <- valueID (ref_reg_rast)   # Running time: < 1s.
signals_3 <- signalCalculation (ref_reg_ID,occ_ID,biogeo = TRUE)   # Running time: ≈ 3s.
data(signals_3)
acc <- accuracy (signals_3)   # Running time: < 1s.
biogeo <- biogeoStatus (signals_3)   # Running time: < 1s.
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.
#> world is invalid
#> Attempting to make world valid by zero-width buffering

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.
#> world is invalid
#> Attempting to make world valid by zero-width buffering