Nothing
#' Taxonomic and trait coverage per geographic region and taxonomic group in
#' GIFT
#'
#' Retrieve taxonomic or trait coverage (for a given trait) of all species,
#' native species, naturalized species and endemic species per taxonomic group
#' and geographic region combination. This function works with taxonomic groups
#' above the genus level.
#'
#' @param what character indicating whether `taxonomic_coverage` or
#' `trait_coverage` shall be retrieved.
#'
#' @param taxon_name Name of the taxonomic group you want to retrieve coverage
#' for. See [GIFT::GIFT_taxonomy()] for options. The function accepts family
#' names and higher taxonomic groups.
#'
#' @param trait_ID Identification number of the trait you want to retrieve
#' coverage for. See [GIFT::GIFT_traits_meta()] for details.
#'
#' @template GIFT_version_api
#'
#' @return A data frame with either taxonomic or trait coverage per
#' GIFT polygon.
#'
#' @details The output has 9 columns:
#'
#' \emph{entity_ID} - Identification number of GIFT polygons\cr
#' \emph{total} - taxonomic or trait coverage for all species\cr
#' \emph{total_rst} - taxonomic or coverage for all species considering
#' restricted resources\cr
#' \emph{native} - taxonomic or trait coverage for native species\cr
#' \emph{native_rst} - taxonomic or trait coverage for native species
#' considering restricted resources\cr
#' \emph{naturalized} - taxonomic or trait coverage for naturalized species\cr
#' \emph{naturalized_rst} - taxonomic or trait coverage for naturalized species
#' considering restricted resources\cr
#' \emph{endemic_min} - taxonomic or trait coverage for endemic species\cr
#' \emph{endemic_min_rst} - taxonomic or trait coverage for endemic species
#' considering restricted resources
#'
#' In the case of taxonomic coverage, a '1' means that species composition data
#' is available for the given combination of taxonomic group and geographic
#' region while 'NA' means that no data is available. This can differ depending
#' on whether restricted data in GIFT is considered or not (columns with or
#' without _rst at the end).
#'
#' In the case of trait coverage, the proportion of species of a given
#' taxonomic group with information on the defined trait is reported per
#' geographic region.
#'
#' @references
#' Denelle, P., Weigelt, P., & Kreft, H. (2023). GIFT—An R package to
#' access the Global Inventory of Floras and Traits. Methods in Ecology
#' and Evolution, 14, 2738-2748.
#' https://doi.org/10.1111/2041-210X.14213
#'
#' Weigelt, P, König, C, Kreft, H. GIFT – A Global Inventory of Floras and
#' Traits for macroecology and biogeography. J Biogeogr. 2020; 47: 16– 43.
#' https://doi.org/10.1111/jbi.13623
#'
#' @seealso [GIFT::GIFT_traits_meta()]
#'
#' @examples
#' \donttest{
#' ex <- GIFT_coverage(what = "taxonomic_coverage", taxon_name = "Angiospermae")
#' ex2 <- GIFT_coverage(what = "trait_coverage", taxon_name = "Angiospermae",
#' trait_ID = "1.2.1")
#' }
#'
#' @importFrom jsonlite read_json
#' @importFrom dplyr mutate_at mutate
#'
#' @export
GIFT_coverage <- function(
what = "taxonomic_coverage", taxon_name = "Embryophyta",
trait_ID = "1.1.1", GIFT_version = "latest",
api = "https://gift.uni-goettingen.de/api/extended/"){
# 1. Controls ----
api_check <- check_api(api)
if(is.null(api_check)){
return(NULL)
} else{
if(length(what) != 1 || is.na(what) || !is.character(what) ||
!(all(what %in% c("taxonomic_coverage", "trait_coverage")))){
stop("'what' is incorrect. It must be a character string equal to either
'taxonomic_coverage' or 'trait_coverage'.")
}
if(length(taxon_name) != 1 || is.na(taxon_name) ||
!is.character(taxon_name)){
stop(
"'taxon_name' is incorrect. It must be a character string among one of
the taxonomic groups available in GIFT. To check them all, run
'GIFT_taxonomy()'.")
}
if(length(trait_ID) != 1){
stop("Please provide one trait_ID only.")
}
if(is.na(trait_ID) || !is.character(trait_ID)){
stop("'trait_ID' is incorrect. It must be a character string of the
identification number of a trait. To check these IDs, run
'GIFT_traits_meta()'.")
}
GIFT_version <- check_gift_version_simple(GIFT_version)
# 2. Query ----
# Taxonomy query
taxonomy <- jsonlite::read_json(
paste0(api, "index", ifelse(GIFT_version == "beta", "", GIFT_version),
".php?query=taxonomy"), simplifyVector = TRUE)
# Define tax_group
tax_group <- taxonomy[which(taxonomy$taxon_name == taxon_name), "taxon_ID"]
# Query
if(what == "trait_coverage"){
tmp <- jsonlite::read_json(paste0(
api, "index", ifelse(GIFT_version == "beta", "", GIFT_version),
".php?query=traits_cov&traitid=",
paste(trait_ID, collapse = ","), "&taxonid=", tax_group),
simplifyVector = TRUE)
} else if(what == "taxonomic_coverage"){
tmp <- jsonlite::read_json(paste0(
api, "index", ifelse(GIFT_version == "beta", "", GIFT_version),
".php?query=species_cov&taxonid=", tax_group), simplifyVector = TRUE)
}
tmp <- dplyr::mutate_at(tmp, c("entity_ID", "total", "total_rst", "native",
"native_rst", "naturalized",
"naturalized_rst", "endemic_min",
"endemic_min_rst"), as.numeric)
return(tmp)
}
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.