rredlist (version 1.1.0)

rl_assessment_extract: Extract an assessment element

Description

Extract a given element from each of a list of assessments, such as the output of rl_assessment_list(). This is useful for extracting specific details from the assessments, such as taxonomy (el_name = "taxon"), synonyms (el_name = "taxon__synonyms"), habitats (el_name = "habitats"), or the red list category (el_name = "red_list_category").

Usage

rl_assessment_extract(lst, el_name, format = c("list", "df"), flatten = FALSE)

Value

A list or data.frame containing the extracted element from each assessment.

Arguments

lst

(list) A list of assessments, as returned by rl_assessment_list(). If lst contains any NULL elements, they will be removed.

el_name

(character) The name of the element to extract from each assessment. Supports multilevel extraction using "__" as the separator. For example, to extract the synonyms table, you could use "taxon__synonyms".

format

(character) The format of the output. Either "list" or "df" (for a data.frame).

flatten

(logical) If TRUE, the output will be flattened to a data.frame. Note that this may not work for all elements, especially complex multilevel list elements. Only used when format = "df". The dplyr, tidyr, and tibble packages are required to use this feature. Note that fields with no data across all assessments may be lost.

Details

The following top-level element names can be extracted as of 2025-07-27:

• assessment_date

• assessment_id

• assessment_points

• assessment_ranges

• biogeographical_realms

• citation

• conservation_actions

• credits

• criteria

• documentation

• errata

• faos

• growth_forms

• habitats

• latest

• lmes

• locations

• population_trend

• possibly_extinct

• possibly_extinct_in_the_wild

• red_list_category

• references

• researches

• scopes

• sis_taxon_id

• stresses

• supplementary_info

• systems

• taxon

• threats

• url

• use_and_trade

• year_published

Note that there are also sublevels of the assessment hierarchy, but they would be unwieldy to display here. A complete and up-to-date list can be found by inspecting the return of an rl_assessment() call.

Examples

if (FALSE) {
lst <- rl_assessment_list(ids = c(166290968, 136250858))
# get complex elements as a list
ex1 <- rl_assessment_extract(lst, "taxon")
# get simple elements as a data.frame
ex2 <- rl_assessment_extract(lst, "red_list_category__code", format = "df")
# get complex elements as a data.frame
ex3 <- rl_assessment_extract(lst, "threats", format = "df")
# get the same elements flattened to a single data.frame
ex4 <- rl_assessment_extract(lst, "threats", format = "df", flatten = TRUE)
# get subelements flattened to a data.frame
ex5 <- rl_assessment_extract(lst, "taxon__order_name", format = "df",
                             flatten = TRUE)
# get a data frame with taxon name and red list category code
ex6 <- merge(
 rl_assessment_extract(lst, "taxon", format = "df", flatten = TRUE),
 rl_assessment_extract(lst, "red_list_category__code", format = "df"),
 by = "assessment_id"
)
}