1. Versions and metadata for checklists

All functions in the package have a version argument. This argument allows you to retrieve different instances of the GIFT database and thus make all previous studies using the GIFT database reproducible. For example, the version used in Weigelt et al. (2020) is "1.0". To get more information about the contents of the different versions, you can go here and click on the Version Log tab.

To access all the available versions of the database, you can run the following function:

versions <- GIFT_versions()
kable(versions, "html") %>%
  kable_styling(full_width = FALSE)

The version column of this table is the one to use if you want to retrieve past versions of the GIFT database. By default, the argument used is GIFT_version = "latest" which leads to the current latest stable version of the database (“2.0” in October 2022).

The GIFT_lists() function can be run to retrieve metadata about the GIFT checklists. In the next chunk, we call it with different values for the GIFT_version argument.

list_latest <- GIFT_lists(GIFT_version = "latest") # default value
list_1 <- GIFT_lists(GIFT_version = "1.0")

The number of available checklists was 3122 in the version 1.0 and equals 4475 in the version 2.0.

2. References

When using the GIFT database in a research article, it is a good practice to cite the references used, and list them in an Appendix. The following function retrieves the reference for each checklist, as well as some metadata. References are documented in the ref_long column.

ref <- GIFT_references()
ref <- ref[which(ref$ref_ID %in% c(22, 10333, 10649)),
           c("ref_ID", "ref_long", "geo_entity_ref")]

# 3 first rows of that table
kable(ref, "html") %>%
  kable_styling(full_width = FALSE)

The next chunk describes the steps to retrieve the publication sources when you start from specific regions, let’s say the Canary islands.

# List of all regions
regions <- GIFT_regions()

# Example
can <- 1036 # entity ID for Canary islands

# What references
gift_lists <- GIFT_lists()

can_ref <- gift_lists[which(gift_lists$entity_ID %in% c(can)), "ref_ID"]

# What sources
kable(ref[which(ref$ref_ID %in% can_ref), ], "html") %>%
  kable_styling(full_width = TRUE)

3. Checklist data

The main wrapper function for retrieving checklists and their species composition is GIFT_checklists() but you can also retrieve individual checklists using GIFT_checklists_raw(). You would need to know the identification number list_ID of the checklists you want to retrieve.
To quickly see all the list_ID available in the database, you can run GIFT_lists() as shown in Section 1.

When calling GIFT_checklists_raw(), you can set the argument namesmatched to TRUE in order to get additional columns informing about the taxonomic harmonization that was performed when the list was uploaded to the GIFT database.

listID_1 <- GIFT_checklists_raw(list_ID = c(11926))
listID_1_tax <- GIFT_checklists_raw(list_ID = c(11926), namesmatched = TRUE)

ncol(listID_1) # 16 columns
ncol(listID_1_tax) # 33 columns
length(unique(listID_1$work_ID)); length(unique(listID_1_tax$orig_ID))

In the list we called up, you can see that we “lost” some species after the taxonomic harmonization since we went from 1331 in the source to 1106 after the taxonomic harmonization. This means that several species were considered as synonyms or unknown plant species in the taxonomic backbone used for harmonization.

Note: the main service used for taxonomic harmonization of species names was The Plant List up to version 2.0 and World checklist of Vascular Plants afterwards.

4. Spatial subset

In the main vignette, we illustrated how to retrieve checklists that fall into a provided shapefile, using the western Mediterranean basin provided with the GIFT R package.

data("western_mediterranean")

Here we provide more details on the different values the overlap argument can take, using the GIFT_spatial() function. The following figure illustrates how this argument works:

Figure 1. GIFT spatial

We now illustrate this by retrieving checklists falling in the western Mediterranean basin using the four options available.

med_centroid_inside  <- GIFT_spatial(shp = western_mediterranean,
                                     overlap = "centroid_inside")
med_extent_intersect <- GIFT_spatial(shp = western_mediterranean,
                                     overlap = "extent_intersect")
med_shape_intersect <- GIFT_spatial(shp = western_mediterranean,
                                    overlap = "shape_intersect")
med_shape_inside <- GIFT_spatial(shp = western_mediterranean,
                                 overlap = "shape_inside")

length(unique(med_extent_intersect$entity_ID))
length(unique(med_shape_intersect$entity_ID))
length(unique(med_centroid_inside$entity_ID))
length(unique(med_shape_inside$entity_ID))

We see here that we progressively lose lists as we apply more selective criterion on the spatial overlap. The most restrictive option being overlap = "shape_inside" with 72 regions, then overlap = "centroid_inside" with 84 regions, overlap = "shape_intersect" with 104 regions and finally the less restrictive one being overlap = "extent_intersect" with 108 regions.
Using the functions GIFT_shapes() and calling it for the entity_IDs retrieved in each instance, we can download the shape files for each region.

geodata_extent_intersect <- GIFT_shapes(med_extent_intersect$entity_ID)

geodata_shape_inside <-
  geodata_extent_intersect[which(geodata_extent_intersect$entity_ID %in%
                                   med_shape_inside$entity_ID), ]
geodata_centroid_inside <-
  geodata_extent_intersect[which(geodata_extent_intersect$entity_ID %in%
                                   med_centroid_inside$entity_ID), ]
geodata_shape_intersect <-
  geodata_extent_intersect[which(geodata_extent_intersect$entity_ID %in%
                                   med_shape_intersect$entity_ID), ]

And then make a map.

par_overlap <- par(mfrow = c(2, 2), mai = c(0, 0, 0.5, 0))
plot(sf::st_geometry(geodata_shape_inside),
     col = geodata_shape_inside$entity_ID,
     main = paste("shape inside\n",
                  length(unique(med_shape_inside$entity_ID)),
                  "polygons"))
plot(sf::st_geometry(western_mediterranean), lwd = 2, add = TRUE)

plot(sf::st_geometry(geodata_centroid_inside),
     col = geodata_centroid_inside$entity_ID,
     main = paste("centroid inside\n",
                  length(unique(med_centroid_inside$entity_ID)),
                  "polygons"))
points(geodata_centroid_inside$point_x, geodata_centroid_inside$point_y)
plot(sf::st_geometry(western_mediterranean), lwd = 2, add = TRUE)

plot(sf::st_geometry(geodata_shape_intersect),
     col = geodata_shape_intersect$entity_ID,
     main = paste("shape intersect\n",
                  length(unique(med_shape_intersect$entity_ID)),
                  "polygons"))
plot(sf::st_geometry(western_mediterranean), lwd = 2, add = TRUE)

plot(sf::st_geometry(geodata_extent_intersect),
     col = geodata_extent_intersect$entity_ID,
     main = paste("extent intersect\n",
                  length(unique(med_extent_intersect$entity_ID)),
                  "polygons"))
plot(sf::st_geometry(western_mediterranean), lwd = 2, add = TRUE)
par(par_overlap)

5. Remove overlapping regions

GIFT comprises many polygons and for some regions, there are several polygons overlapping. How to remove overlapping polygons and the associated parameters are two things detailed in the main vignette. We here provide further details:

length(med_shape_inside$entity_ID)

## [1] 72

length(GIFT_no_overlap(med_shape_inside$entity_ID, area_threshold_island = 0,
                       area_threshold_mainland = 100, overlap_threshold = 0.1))

## [1] 53

# The following polygons are overlapping:
GIFT_no_overlap(med_shape_inside$entity_ID, area_threshold_island = 0,
                area_threshold_mainland = 100, overlap_threshold = 0.1)

##  [1]   145   146   147   148   149   150   151   414   415   416   417   547
## [13]   548   549   550   551   552   586   591   592   736   738   739 10001
## [25] 10072 10104 10184 10303 10422 10430 10978 11029 11030 11031 11033 11035
## [37] 11038 11039 11042 11044 11045 11046 11434 11474 11477 11503 12231 12232
## [49] 12233 12632 12633 12634 12635

# Example of two overlapping polygons: Spain mainland and Andalusia
overlap_shape <- GIFT_shapes(entity_ID = c(10071, 12078))

par_overlap_shp <- par(mfrow = c(1, 1))
plot(sf::st_geometry(overlap_shape),
     col = c(rgb(red = 1, green = 0, blue = 0, alpha = 0.5),
             rgb(red = 0, green = 0, blue = 1, alpha = 0.3)),
     lwd = c(2, 1),
     main = "Overlapping polygons")

par(par_overlap_shp)

GIFT_no_overlap(c(10071, 12078), area_threshold_island = 0,
                area_threshold_mainland = 100, overlap_threshold = 0.1)

## [1] 12078

GIFT_no_overlap(c(10071, 12078), area_threshold_island = 0,
                area_threshold_mainland = 100000, overlap_threshold = 0.1)

## [1] 10071

ex <- GIFT_checklists(taxon_name = "Tracheophyta", by_ref_ID = FALSE,
                      list_set_only = TRUE, GIFT_version = "3.0")
ex2 <- GIFT_checklists(taxon_name = "Tracheophyta",
                       remove_overlap = TRUE, by_ref_ID = TRUE,
                       list_set_only = TRUE, GIFT_version = "3.0")
ex3 <- GIFT_checklists(taxon_name = "Tracheophyta",
                       remove_overlap = TRUE, by_ref_ID = FALSE,
                       list_set_only = TRUE, GIFT_version = "3.0")

length(unique(ex$lists$ref_ID)) # 369 checklists
length(unique(ex2$lists$ref_ID)) # 364 checklists
length(unique(ex3$lists$ref_ID)) # 336 checklists

unique(ex2$lists$ref_ID)[!(unique(ex2$lists$ref_ID) %in%
                             unique(ex3$lists$ref_ID))] # 28 references

# Pilbara region Australy and overlapping shapes
pilbara <- GIFT_shapes(entity_ID = c(10043, 12172, 11398, 11391, 10918))

ggplot(pilbara) +
  geom_sf(aes(fill = as.factor(entity_ID)), alpha = 0.5) +
  scale_fill_brewer("entity_ID", palette = "Set1")

6. Species

All the plant species present in the GIFT database can be retrieved using GIFT_species().

species <- GIFT_species()

To add additional information, like their order or family, we can call GIFT_taxgroup().

# Add Family
species$Family <- GIFT_taxgroup(
  as.numeric(species$work_ID), taxon_lvl = "family", return_ID = FALSE, 
  species = species)

Order or higher levels can also be retrieved.

GIFT_taxgroup(as.numeric(species$work_ID[1:5]), taxon_lvl = "order",
              return_ID = FALSE)
GIFT_taxgroup(as.numeric(species$work_ID[1:5]),
              taxon_lvl = "higher_lvl", return_ID = FALSE,
              species = species)

As mentioned above, plant species names may vary from the original sources they come from to the final work_species name they get, due to the taxonomic harmonization procedure. Looking up a species and the different steps of taxonomic harmonization is possible with the GIFT_species_lookup() function.

Fagus <- GIFT_species_lookup(genus = "Fagus", epithet = "sylvatica",
                             namesmatched = TRUE)

In this table, we can see that the first entry Fagus silvatica was later changed to the accepted name Fagus sylvatica.

sp_list <- c("Anemone nemorosa", "Fagus sylvatica")

gift_sp <- GIFT_species()

sapply(sp_list, function(x) grep(x, gift_sp$work_species))
gift_sp[sapply(sp_list, function(x) grep(x, gift_sp$work_species)), ]

# With fuzzy matching
# library("fuzzyjoin")
# library("dplyr")
sp_list <- data.frame(work_species = c("Anemona nemorosa", "Fagus sylvaticaaa"))

fuzz <- stringdist_join(sp_list, gift_sp,
                        by = "work_species",
                        mode = "left",
                        ignore_case = FALSE, 
                        method = "jw", 
                        max_dist = 99, 
                        distance_col = "dist") 

fuzz %>%
  group_by(work_species.x) %>%
  slice_min(order_by = dist, n = 1)

7. Taxonomy

The taxonomy used in GIFT database can be downloaded using GIFT_taxonomy().

taxo <- GIFT_taxonomy()

8. Overlap_GloNAF tables (and others)

Since other global databases of plant diversity exist and may be based on different polygons, we provide a function GIFT_overlap() than can look at the spatial overlap between GIFT polygons and polygons coming from other databases.
So far, only two resources are available: glonaf and gmba. glonaf stands for Global Naturalized Alien Flora and gmba for Global Mountain Biodiversity Assessment.

GIFT_overlap() returns the spatial overlap in percent for each pairwise combination of polygons between GIFT and the other resource.

Let’s illustrate this with the GMBA shapefile.

gmba_overlap <- GIFT_overlap(resource = "gmba")

kable(gmba_overlap[1:5, ], "html") %>%
  kable_styling(full_width = FALSE)

We see that two overlap columns are returned: overlap12 and overlap21.
The first column returns the overlap between the GIFT region and the other resource. The second column returns the overlap between the other resource and the GIFT region.
For example, if we look at the polygon 11861 of GIFT:

gmba_overlap[which(gmba_overlap$entity_ID == 11861 &
                     gmba_overlap$gmba_ID == 731), ]

## [1] entity_ID gmba_ID   overlap12 overlap21
## <0 rows> (or 0-length row.names)

The corresponding region is the Aisen province in Chile and it overlaps at 95% with the GMBA polygon number 731.
At the same time the GMBA polygon 731 only overlaps at 13% with the Aisen province of Chile.
This is because the corresponding mountain region is larger than the GIFT region and encompasses it as we can see on this plot (the dark polygon is the GIFT region):

References

Weigelt, P., König, C., & Kreft, H. (2020). GIFT – A Global Inventory of Floras and Traits for macroecology and biogeography. Journal of Biogeography, 47(1), 16–43.

Weigelt, Patrick, and Pierre Denelle. “GIFT: Access to the Global Inventory of Floras and Traits (GIFT),” March 15, 2023.