Skip to contents

Extract an assessment element

Source: R/rl_assessment.R
rl_assessment_extract.Rd

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)

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.

Value

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

Details

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

  • 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) { # \dontrun{
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"
)
} # }