In ropensci/rredlist: 'IUCN' Red List Client

library("knitr")
library("rredlist")
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
   lines <- options$output.lines
   if (is.null(lines)) {
     return(hook_output(x, options))  # pass to default hook
   }
   x <- unlist(strsplit(x, "\n"))
   more <- "..."
   if (length(lines)==1) {        # first n lines
     if (length(x) > lines) {
       # truncate the output, but add ....
       x <- c(head(x, lines), more)
     }
   } else {
     x <- c(if (abs(lines[1])>1) more else NULL,
            x[lines],
            if (length(x)>lines[abs(length(lines))]) more else NULL
           )
   }
   # paste these lines together
   x <- paste(c(x, ""), collapse = "\n")
   hook_output(x, options)
 })

knitr::opts_chunk$set(
  warning = FALSE,
  message = FALSE,
  collapse = TRUE,
  fig.width = 7,
  fig.height = 5,
  fig.align = "center",
  comment = "#>"
)

## Introduction Once you have `rredlist` [set up](rredlist.html), it's very likely you'll want to use it for some sort of research workflow. This vignette gives examples of the kinds of data that users may be interested in downloading from the IUCN API, and how they might then use that data within a partial research workflow. I've given three worked examples, but because the possibilities are pretty endless, I've also cited some recent published works at the bottom of the vignette to cover a wider variety of use cases. Before we get started, we'll just load some packages that we'll need. We'll use `{dplyr}` for handling and cleaning our data, and we'll use `{ggplot2}` and `{patchwork}` for visualizing our data. wzxhzdk:1 ## How have mollusc assessments increased through time? For our first research workflow, we are interested in the assessment of molluscs through time. Specifically, we are interested in how many cumulative assessments have been completed each year, and how many cumulative species have then been assessed each year. First, we'll need to download an assessment summary for Mollusca. Note that while I've used `quiet = TRUE` here for the purposes of the vignette, you would likely want to skip that to get a lovely progress bar that keeps you apprised of the download's progress since there are quite a few pages of assessments to download. wzxhzdk:2 Now that we have our assessment summary, we can summarize the data by calculating the cumulative numbers of assessments through time. This is a fairly basic `{dplyr}` pipeline that counts the number of assessments for each year, then orders those counts from oldest to most recent, then calculates the cumulative sum of the counts. wzxhzdk:3 Now that we have our cumulative sums, we can make a simple plot. We'll save it for later to combine with our second plot. wzxhzdk:4 Now let's see how many cumulative _species_ are assessed by year. In order to do this, we'll first need to filter to only the first assessment for each species using `arrange()` and `slice()`. Then we can calculate the cumulative sum as we did for the assessments above. wzxhzdk:5 Now that we have our species cumulative sums, we can visualize that and combine the two plots together. wzxhzdk:6 Et voila! Now we have a fairly straightforward visualization of mollusc IUCN assessment through time, indicating that there were some booms and lulls over this interval. We also see one or two instances where the majority of the assessments were of previously assessed species instead of new species. ## What is the conservation status of Australian reptiles? That first workflow only used an assessment summary, but there is so much more data available via the IUCN API if we retrieve entire assessments. Of course, these assessments include the threat status of each species, so let's start with that. In this case, we'll assess the overall threat status of differences orders of Australian reptiles. First, we'll need to figure out which Australian reptiles have been assessed. Unfortunately, we can't do this in a single query, so we'll need to get the intersection of all reptiles that have been assessed and all Australian species that have been assessed. Let's get the Australian species assessment summary first. Hmm...what's the code for Australia, again? I can't remember, so let's look it up using the default behavior of `rl_countries()` which returns all country codes: wzxhzdk:7 Ah, "AU", of course! Now we can get an assessment summary for all species that occur in Australia. As opposed to the first use case above, we only care about which species have been assessed, so we'll only retrieve the latest assessments using `latest = TRUE`. wzxhzdk:8 You'll notice that the returned assessment actually contains more than just the assessment, it includes information about the query we made ("metadata", if you will). Let's check that it matches what we meant to search: wzxhzdk:9 Yep, that looks good! Now let's inspect the format of the assessment summary: wzxhzdk:10 We could go ahead and download the full assessments for all Australian species now, but downloading full assessments is the slowest part of the workflow, so let's get an assessment summary for reptiles first, then only download full assessments for Australian reptiles. wzxhzdk:11 OK, now we've got our assessment summaries for Australian species and for reptiles. We can take those two lists of assessments and find the intersection of them to get the list of assessment IDs for Australian reptiles. wzxhzdk:12 Now that we have this list of IDs, we can download the full assessment information. Before we download full assessments for all of these IDs, let's first take a look at what that looks like for the first assessment. We do that using `rl_assessment()`. wzxhzdk:13 Now you can see why downloading this information will take a while; that's a lot of data! The information available from the IUCN API spans ecology, threats, references, and more! Now we'll go ahead and download the full records for all of our assessments. Note that performing this many large queries over a short period of time may result in getting timed out by the API. If you do get timed out, `rredlist` will automatically retry the query after a short wait time. By default, if you get timed out more than 3 times for the same query, the query will be stopped and throw an error, forcing you to try the entire download again. However, you can customize the settings related to these retries, including the wait time and the number of retries. Since this is a pretty large download that we don't want to have to redo, we'll increase the number of retries to 10 (from the default of 3). wzxhzdk:14 Alternatively, if we know we might get timed out because of the download size, we can impose our own wait time between each query to proactively prevent timeouts. IUCN recommends a wait time of 0.5 seconds between queries to avoid timeouts. We can use `Sys.sleep()` to impose such a wait before each query. wzxhzdk:15 OK, now, after a bit of a wait, we have our full assessment records! Each item of this list is a single assessment record. And each assessment record is also a list, with each element representing a different kind of data in the record (e.g., habitats, taxonomy). For this workflow, we only really care about the taxonomic and threat category data, so let's extract those elements from each list item. We'll put all of this into a data.frame so it is easier to use. wzxhzdk:16 We'll do some very minor data cleaning and filtering. In this case, some of the assessments use old threat codes, so we'll exclude them from further analyses. We'll also convert the category column to an ordered factor for visualization purposes. wzxhzdk:17 Now let's make a plot! Here we are visualizing the number of reptiles in each threat category, split out by their order (crocs vs. lizards vs. turtles). Note that `rredlist` includes a custom color palette for use with `{ggplot2}` that matches the official IUCN threat category color scheme (`scale_fill_iucn()` for the fill aesthetic and `scale_color_iucn()` for the color aesthetic). wzxhzdk:18 We can do some quick data manipulation to calculate the proportions of species in each threat category instead of counts to make comparisons between the orders easier. wzxhzdk:19 And that's that! You'll see that Australian turtles are all threatened, whereas Australian crocodiles and lizards tend to be not threatened. ## What habitats do conifers and cycads occur in? Some taxonomic or functional groups are stored as "comprehensive groups" within the API. These often correspond to groups of taxa that groups of assessors care about. Many of these correspond to groups that are not otherwise query-able by taxonomy such as clades of plants. Let's take a look at what comprehensive groups exist in the database: wzxhzdk:20 OK, since we have gymnosperms split into conifers and cycads, let's compare these two groups. Let's also introduce another type of data in assessments: habitat. We'll start with the cycads and download a summary of their latest assessments. We'll then download the full assessment records based on that summary. Finally, we'll extract the entire `habitats` data.frame from each assessment record and add some taxonomic information from the `taxon` element of each record. Note that for each assessment, there are one or more habitats assigned to the species. There is also often habitat suitability data, although we'll ignore that for today. wzxhzdk:21 Now we can do the same thing for conifers: wzxhzdk:22 Now that we have habitat data for both clades, let's combine them and clean up the data a bit. We can also use `rl_habitats()` without any arguments to get descriptions of the different habitats. For visualization purposes, we'll shorten the descriptions to anything outside of parentheses. Also, we'll collapse all of the habitats into their major habitats (i.e., codes without underscores), since the visualization would be pretty messy otherwise. wzxhzdk:23 We'll now summarize the data, counting how many of each clade exist in each habitat. Like above, we'll calculate proportions so we can compare between the two clades. wzxhzdk:24 And now we can plot our proportions: wzxhzdk:25 Tada! As you maybe expected, cycads and conifers live in fairly similar habitats, although conifers tend to live in forests slightly more than cycads, whereas some cycads live in rocky areas. ## Some recent published uses of `rredlist` Since I can't cover all potential use cases of `rredlist`, here is a selection of publications that have recently used the `rredlist` as part of their research pipeline: - Bates, R., Taylor, E., Sun, Y., Gumbs, R., Böhm, M., Gray, C. and Rosindell, J. 2024. Quantifying the IUCN Red List: Using historical assessments to calculate future extinction risk. bioRxiv. https://doi.org/10.1101/2024.02.04.578808. - Collected species data and historical Red List assessment data - Divieso, R., Pie, M.R. and Hortal, J. 2024. On the macroecology of rarity and vulnerability to extinction in terrestrial mammals. Biological Conservation. 296. https://doi.org/10.1016/j.biocon.2024.110673. - Collected conservation status of species - Turner, J.A., Starkey, M., Dulvy, N.K., Hawkins, F., Mair, L., Serckx, A., Brooks, T., Polidoro, B., Butchart, S.H., Carpenter, K., Epps, M., Jabado, R.W., Macfarlane, N.B.W., and Bennun, L. 2024. Targeting ocean conservation outcomes through threat reduction. npj Ocean Sustainability 3(1). https://doi.org/10.1038/s44183-023-00040-8. - Collected habitat preferences and threat information for species - Pacifici, M., Cristiano, A., Lumbierres, M., Lucherini, M., Mallon, D., Meijaard, E., Solari, S., Tognelli, M.F., Belant, J.L., Butynski, T.M., Cronin, D., d'Huart, J.P., Da Re, D., de Jong, Y.A., Dheer, A., Fei, L., Gallina, S., Goodrich, J.M., Harihar, A., Lopez Gonzalez, C.A., King, S.R.B., Lewison, R.L., de Melo, F.R., Napolitano, C., Rahman, D.A., Robinson, P.T., Robinson, T., Rondinini, C., Semiadi, G., Strier, K., Talebi, M., Taylor, W.A., Thiel-Bender, C., Ting, N., and Wiesel, I. 2023. Drivers of habitat availability for terrestrial mammals: Unravelling the role of livestock, land conversion and intrinsic traits in the past 50 years. Global Change Biology, 29(24):6900-6911. https://doi.org/10.1111/gcb.16964. - Collected habitats for species - Schmidt, C., Hoban, S., Hunter, M., Paz‐Vinas, I. and Garroway, C.J. 2023. Genetic diversity and IUCN Red List status. Conservation Biology, 37(4). https://doi.org/10.1111/cobi.14064. - Collected conservation status of species - Toussaint, A., Brosse, S., Bueno, C.G., Pärtel, M., Tamme, R. and Carmona, C.P. 2021. Extinction of threatened vertebrates will lead to idiosyncratic changes in functional diversity across the world. Nature Communications, 12. https://doi.org/10.1038/s41467-021-25293-0. - Collected conservation statuses of species

{css echo = FALSE} p.caption { display: none; }

ropensci/rredlist documentation built on Feb. 7, 2025, 1:30 a.m.