diff --git a/NAMESPACE b/NAMESPACE index 327c345..ad93962 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -22,6 +22,8 @@ export(rl_family) export(rl_family_) export(rl_faos) export(rl_faos_) +export(rl_green) +export(rl_green_) export(rl_growth_forms) export(rl_growth_forms_) export(rl_habitats) @@ -32,6 +34,8 @@ export(rl_order) export(rl_order_) export(rl_phylum) export(rl_phylum_) +export(rl_pop_trends) +export(rl_pop_trends_) export(rl_realms) export(rl_realms_) export(rl_research) diff --git a/R/rl_assessment.R b/R/rl_assessment.R index 75dc23a..471c8be 100644 --- a/R/rl_assessment.R +++ b/R/rl_assessment.R @@ -5,7 +5,7 @@ #' @export #' @param id (integer) The unique identifier of the assessment. #' @template all -#' @template info_new +#' @template info #' @examples \dontrun{ #' # Get assessment details for Fratercula arctica #' ex1 <- rl_assessment(id = 166290968) diff --git a/R/rl_categories.R b/R/rl_categories.R index ef25bdd..b0eb24e 100644 --- a/R/rl_categories.R +++ b/R/rl_categories.R @@ -12,7 +12,7 @@ #' @param code (character) The code of the Red List category to look up. If not #' supplied, a list of all categories will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @examples \dontrun{ #' # Get all Red List categories @@ -52,3 +52,28 @@ rl_categories_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, rr_GET(path, key, query = list(page = page), ...) } } + +#' Green Status assessment summary +#' +#' List all Green Status assessments. +#' +#' @export +#' @template all +#' @template info +#' @examples \dontrun{ +#' # Get list of Green Status assessments +#' rl_green() +#' } +rl_green <- function(key = NULL, parse = TRUE, ...) { + assert_is(parse, 'logical') + + rl_parse(rl_green_(key, ...), parse) +} + +#' @export +#' @rdname rl_green +rl_green_ <- function(key = NULL, ...) { + assert_is(key, 'character') + + rr_GET("green_status/all", key, ...) +} diff --git a/R/rl_comp_groups.R b/R/rl_comp_groups.R index 7e2dc5d..9922121 100644 --- a/R/rl_comp_groups.R +++ b/R/rl_comp_groups.R @@ -6,7 +6,7 @@ #' @param name (character) The code of the comprehensive group to look up. If #' not supplied, a list of all comprehensive groups will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @examples \dontrun{ #' # Get list of all comprehensive groups diff --git a/R/rl_conservation.R b/R/rl_conservation.R index c89bdd9..e123f5b 100644 --- a/R/rl_conservation.R +++ b/R/rl_conservation.R @@ -1,4 +1,4 @@ -#' Conservations actions needed assessment summary +#' Conservation actions needed assessment summary #' #' Return the latest assessments with a given conservation action needed (e.g., #' Land/water management or Species recovery). These conservation action codes @@ -9,7 +9,7 @@ #' @param code (character) The code of the conservation action to look up. If #' not supplied, a list of all conservation actions will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family conservation #' @examples \dontrun{ @@ -61,7 +61,7 @@ rl_actions_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the research type to look up. If not #' supplied, a list of all research types will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family conservation #' @examples \dontrun{ diff --git a/R/rl_countries.R b/R/rl_countries.R index f9fe490..9abb269 100644 --- a/R/rl_countries.R +++ b/R/rl_countries.R @@ -6,7 +6,7 @@ #' @param code (character) The ISO alpha-2 code of the country to look up. If #' not supplied, a list of all countries will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family geo #' @examples \dontrun{ diff --git a/R/rl_growth_forms.R b/R/rl_growth_forms.R index 54bb37f..c1e2c9c 100644 --- a/R/rl_growth_forms.R +++ b/R/rl_growth_forms.R @@ -6,7 +6,7 @@ #' @param code (character) The code of the growth form to look up. If not #' supplied, a list of all growth forms will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @examples \dontrun{ #' # Get list of all growth forms diff --git a/R/rl_habitats.R b/R/rl_habitats.R index 3ab8cd5..e23a388 100644 --- a/R/rl_habitats.R +++ b/R/rl_habitats.R @@ -8,7 +8,7 @@ #' @param code (character) The code of the habitat to look up. If not supplied, #' a list of all habitats will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family habitat #' @examples \dontrun{ @@ -59,7 +59,7 @@ rl_habitats_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the system to look up. If not supplied, a #' list of all systems will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family habitat #' @examples \dontrun{ diff --git a/R/rl_realms.R b/R/rl_realms.R index 75e5e5f..4cba66e 100644 --- a/R/rl_realms.R +++ b/R/rl_realms.R @@ -7,7 +7,7 @@ #' @param code (character) The code of the biogeographical realm to look up. If #' not supplied, a list of all biogeographical realms will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family geo #' @examples \dontrun{ @@ -58,7 +58,7 @@ rl_realms_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the scope to look up. If not supplied, a #' list of all scopes will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family geo #' @examples \dontrun{ @@ -111,7 +111,7 @@ rl_scopes_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the FAO region to look up. If not #' supplied, a list of all FAO regions will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family geo #' @examples \dontrun{ diff --git a/R/rl_sp_count.R b/R/rl_sp_count.R index 2e0b32e..97ffe0e 100644 --- a/R/rl_sp_count.R +++ b/R/rl_sp_count.R @@ -3,10 +3,12 @@ #' Returns a count of the number of unique species which have assessments #' #' @export -#' @template all -#' @template info_new +#' @param key (character) An IUCN API token. See \code{\link{rl_use_iucn}}. +#' @param ... Curl options passed to \code{\link[crul]{HttpClient}} +#' @template info #' @family stats #' @examples \dontrun{ +#' # Get count of species with assessments #' rl_sp_count() #' } rl_sp_count <- function(key = NULL, ...) { diff --git a/R/rl_taxa.R b/R/rl_taxa.R index a61570b..9bd2964 100644 --- a/R/rl_taxa.R +++ b/R/rl_taxa.R @@ -24,7 +24,7 @@ #' Infraspecific ranks such as formas, subvarieties, cultivars, etc are not #' included in the Red List. #' @template all -#' @template info_new +#' @template info #' @family taxa #' @examples \dontrun{ #' # Get assessment summary for species @@ -67,7 +67,7 @@ rl_species_ <- function(genus, species, infra = NULL, subpopulation = NULL, #' @param family (character) The name of the family to look up. If not supplied, #' a list of all family names will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -116,7 +116,7 @@ rl_family_ <- function(family = NULL, key = NULL, all = TRUE, page = 1, #' @param order (character) The name of the order to look up. If not supplied, a #' list of all order names will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -165,7 +165,7 @@ rl_order_ <- function(order = NULL, key = NULL, all = TRUE, page = 1, #' @param class (character) The name of the class to look up. If not supplied, a #' list of all class names will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -214,7 +214,7 @@ rl_class_ <- function(class = NULL, key = NULL, all = TRUE, page = 1, #' @param phylum (character) The name of the phylum to look up. If not supplied, #' a list of all phylum names will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -263,7 +263,7 @@ rl_phylum_ <- function(phylum = NULL, key = NULL, all = TRUE, page = 1, #' @param kingdom (character) The name of the kingdom to look up. If not #' supplied, a list of all kingdom names will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -295,7 +295,7 @@ rl_kingdom_ <- function(kingdom = NULL, key = NULL, all = TRUE, page = 1, assert_is(all, 'logical') assert_is(quiet, 'logical') - path <- paste("taxa/kingdom", phylum, sep = "/") + path <- paste("taxa/kingdom", kingdom, sep = "/") if (all) { page_assessments(path, key, quiet, ...) @@ -310,7 +310,7 @@ rl_kingdom_ <- function(kingdom = NULL, key = NULL, all = TRUE, page = 1, #' #' @export #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ @@ -353,7 +353,7 @@ rl_extinct_ <- function(key = NULL, all = TRUE, page = 1, quiet = FALSE, ...) { #' #' @export #' @template all -#' @template info_new +#' @template info #' @template page #' @family taxa #' @examples \dontrun{ diff --git a/R/rl_threats.R b/R/rl_threats.R index 5a56d54..ecb3bbd 100644 --- a/R/rl_threats.R +++ b/R/rl_threats.R @@ -10,7 +10,7 @@ #' @param code (character) The code of the threat to look up. If not supplied, a #' list of all threats will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family threats #' @examples \dontrun{ @@ -61,7 +61,7 @@ rl_threats_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the stress to look up. If not supplied, a #' list of all stresses will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family threats #' @examples \dontrun{ @@ -112,7 +112,7 @@ rl_stresses_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, #' @param code (character) The code of the use and trade to look up. If not #' supplied, a list of all uses and trades will be returned. #' @template all -#' @template info_new +#' @template info #' @template page #' @family threats #' @examples \dontrun{ diff --git a/R/rl_trends.R b/R/rl_trends.R new file mode 100644 index 0000000..58cc466 --- /dev/null +++ b/R/rl_trends.R @@ -0,0 +1,49 @@ +#' Population trend assessment summary +#' +#' Return a list of the latest assessments based on a population trend (i.e. +#' increasing, decreasing, stable or unknown). +#' +#' @export +#' @param code (character) The code of the growth form to look up. If not +#' supplied, a list of all growth forms will be returned. +#' @template all +#' @template info +#' @template page +#' @examples \dontrun{ +#' # Get list of all population trends +#' rl_pop_trends() +#' # Get assessment summary for stable population trends +#' rl_pop_trends("2") +#' } +rl_pop_trends <- function(code = NULL, key = NULL, parse = TRUE, all = TRUE, + page = 1, quiet = FALSE,...) { + assert_is(parse, 'logical') + assert_is(all, 'logical') + + res <- rl_pop_trends_(code, key, all, page, quiet, ...) + if (all) { + combine_assessments(res, parse) + } else { + rl_parse(res, parse) + } +} + +#' @export +#' @rdname rl_pop_trends +rl_pop_trends_ <- function(code = NULL, key = NULL, all = TRUE, page = 1, + quiet = FALSE, ...) { + assert_is(key, 'character') + assert_is(code, 'character') + assert_is(page, c('integer', 'numeric')) + assert_n(page, 1) + assert_is(all, 'logical') + assert_is(quiet, 'logical') + + path <- paste("population_trends", code, sep = "/") + + if (all) { + page_assessments(path, key, quiet, ...) + } else { + rr_GET(path, key, query = list(page = page), ...) + } +} diff --git a/R/rredlist-package.R b/R/rredlist-package.R index 7e2bd01..5d1be05 100644 --- a/R/rredlist-package.R +++ b/R/rredlist-package.R @@ -2,17 +2,11 @@ "_PACKAGE" #' @title rredlist -#' @section Taxonomic Names vs. IUCN IDs: -#' From the documentation (quoting): "It is advisable wherever possible to use -#' the taxon name (species name) to make your API calls, rather than using IDs. -#' IDs are not immovable are expected to be used mainly by organizations -#' that work closely with the IUCN Red List." -#' #' @section Authentication: #' IUCN requires you to get your own API key, an alphanumeric string that you #' need to send in every request. See key A IUCN API token. See [rl_use_iucn()] #' for help getting and storing it. Get it at -#' https://apiv3.iucnredlist.org/api/v3/token +#' https://api.iucnredlist.org/users/sign_up #' Keep this key private. You can pass the key in to each function via the #' `key` parameter, but it's better to store the key either as a #' environment variable (`IUCN_REDLIST_KEY`) or an R option @@ -22,13 +16,13 @@ #' **High level API** #' High level functions do the HTTP request and parse data to a data.frame for #' ease of downstream use. The high level functions have no underscore on -#' the end of the function name, e.g., [rl_search()] +#' the end of the function name, e.g., [rl_species()] #' #' **Low level API** #' The parsing to data.frame in the high level API does take extra time. #' The low level API only does the HTTP request, and gives back JSON without #' doing any more parsing. The low level functions DO have an underscore on -#' the end of the function name, e.g., [rl_search_()] +#' the end of the function name, e.g., [rl_species_()] #' #' @section No Spatial: #' This package does not include support for the spatial API, described at diff --git a/man-roxygen/info.R b/man-roxygen/info.R index 050e73e..38049b2 100644 --- a/man-roxygen/info.R +++ b/man-roxygen/info.R @@ -1,4 +1,3 @@ -#' @return A list, with the data in the \code{result} slot, unless using -#' a function with a trailing underscore, in which case json as character -#' string is returned. -#' @references API docs at https://apiv3.iucnredlist.org/api/v3/docs. +#' @return A list unless using a function with a trailing underscore, in which +#' case json as character string is returned. +#' @references API docs at . diff --git a/man-roxygen/info_new.R b/man-roxygen/info_new.R deleted file mode 100644 index 38049b2..0000000 --- a/man-roxygen/info_new.R +++ /dev/null @@ -1,3 +0,0 @@ -#' @return A list unless using a function with a trailing underscore, in which -#' case json as character string is returned. -#' @references API docs at . diff --git a/man/rl_actions.Rd b/man/rl_actions.Rd index 3879472..40fedff 100644 --- a/man/rl_actions.Rd +++ b/man/rl_actions.Rd @@ -3,7 +3,7 @@ \name{rl_actions} \alias{rl_actions} \alias{rl_actions_} -\title{Conservations actions needed assessment summary} +\title{Conservation actions needed assessment summary} \usage{ rl_actions( code = NULL, diff --git a/man/rl_green.Rd b/man/rl_green.Rd new file mode 100644 index 0000000..18eeb29 --- /dev/null +++ b/man/rl_green.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rl_categories.R +\name{rl_green} +\alias{rl_green} +\alias{rl_green_} +\title{Green Status assessment summary} +\usage{ +rl_green(key = NULL, parse = TRUE, ...) + +rl_green_(key = NULL, ...) +} +\arguments{ +\item{key}{(character) An IUCN API token. See \code{\link{rl_use_iucn}}.} + +\item{parse}{(logical) Whether to parse the output to list (\code{FALSE}) or, +where possible, data.frame (\code{TRUE}). Default: \code{TRUE}} + +\item{...}{Curl options passed to \code{\link[crul]{HttpClient}}} +} +\value{ +A list unless using a function with a trailing underscore, in which +case json as character string is returned. +} +\description{ +List all Green Status assessments. +} +\examples{ +\dontrun{ +# Get list of Green Status assessments +rl_green() +} +} +\references{ +API docs at \url{https://api.iucnredlist.org/}. +} diff --git a/man/rl_pop_trends.Rd b/man/rl_pop_trends.Rd new file mode 100644 index 0000000..0ee9b85 --- /dev/null +++ b/man/rl_pop_trends.Rd @@ -0,0 +1,67 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rl_trends.R +\name{rl_pop_trends} +\alias{rl_pop_trends} +\alias{rl_pop_trends_} +\title{Population trend assessment summary} +\usage{ +rl_pop_trends( + code = NULL, + key = NULL, + parse = TRUE, + all = TRUE, + page = 1, + quiet = FALSE, + ... +) + +rl_pop_trends_( + code = NULL, + key = NULL, + all = TRUE, + page = 1, + quiet = FALSE, + ... +) +} +\arguments{ +\item{code}{(character) The code of the growth form to look up. If not +supplied, a list of all growth forms will be returned.} + +\item{key}{(character) An IUCN API token. See \code{\link{rl_use_iucn}}.} + +\item{parse}{(logical) Whether to parse the output to list (\code{FALSE}) or, +where possible, data.frame (\code{TRUE}). Default: \code{TRUE}} + +\item{all}{(logical) Whether to retrieve all results at once or not. If +\code{TRUE} we do the paging internally for you and bind all of the results +together. If \code{FALSE}, only a single page of results will be retrieved.} + +\item{page}{(integer/numeric) Page to get if \code{all} is \code{FALSE}. Default: 1. +Each page returns up to 100 records. Paging is required because it's too +much burden on a server to just "get all the data" in one request.} + +\item{quiet}{(logical) Whether to give progress for download or not. Default: +\code{FALSE} (that is, give progress). Ignored if \code{all = FALSE}.} + +\item{...}{Curl options passed to \code{\link[crul]{HttpClient}}} +} +\value{ +A list unless using a function with a trailing underscore, in which +case json as character string is returned. +} +\description{ +Return a list of the latest assessments based on a population trend (i.e. +increasing, decreasing, stable or unknown). +} +\examples{ +\dontrun{ +# Get list of all population trends +rl_pop_trends() +# Get assessment summary for stable population trends +rl_pop_trends("2") +} +} +\references{ +API docs at \url{https://api.iucnredlist.org/}. +} diff --git a/man/rl_sp_count.Rd b/man/rl_sp_count.Rd index 33f5ab5..b637f6b 100644 --- a/man/rl_sp_count.Rd +++ b/man/rl_sp_count.Rd @@ -13,9 +13,6 @@ rl_sp_count_(key = NULL, ...) \item{key}{(character) An IUCN API token. See \code{\link{rl_use_iucn}}.} \item{...}{Curl options passed to \code{\link[crul]{HttpClient}}} - -\item{parse}{(logical) Whether to parse the output to list (\code{FALSE}) or, -where possible, data.frame (\code{TRUE}). Default: \code{TRUE}} } \value{ A list unless using a function with a trailing underscore, in which @@ -26,6 +23,7 @@ Returns a count of the number of unique species which have assessments } \examples{ \dontrun{ +# Get count of species with assessments rl_sp_count() } } diff --git a/man/rl_stresses.Rd b/man/rl_stresses.Rd index d12fea4..f6a5a09 100644 --- a/man/rl_stresses.Rd +++ b/man/rl_stresses.Rd @@ -59,7 +59,7 @@ rl_stresses("1_2") API docs at \url{https://api.iucnredlist.org/}. } \seealso{ -Threats and use/trade: +Threats, stresses, and use/trade: \code{\link{rl_threats}()}, \code{\link{rl_use_and_trade}()} } diff --git a/man/rl_threats.Rd b/man/rl_threats.Rd index e94e751..9a2bd84 100644 --- a/man/rl_threats.Rd +++ b/man/rl_threats.Rd @@ -62,7 +62,7 @@ rl_threats("5_1_1") API docs at \url{https://api.iucnredlist.org/}. } \seealso{ -Threats and use/trade: +Threats, stresses, and use/trade: \code{\link{rl_stresses}()}, \code{\link{rl_use_and_trade}()} } diff --git a/man/rl_use_and_trade.Rd b/man/rl_use_and_trade.Rd index eb376ce..501ba90 100644 --- a/man/rl_use_and_trade.Rd +++ b/man/rl_use_and_trade.Rd @@ -66,7 +66,7 @@ rl_use_and_trade("3") API docs at \url{https://api.iucnredlist.org/}. } \seealso{ -Threats and use/trade: +Threats, stresses, and use/trade: \code{\link{rl_stresses}()}, \code{\link{rl_threats}()} } diff --git a/man/rredlist-package.Rd b/man/rredlist-package.Rd index fe23eb7..bbab4a4 100644 --- a/man/rredlist-package.Rd +++ b/man/rredlist-package.Rd @@ -8,20 +8,12 @@ \description{ 'IUCN' Red List (\url{https://api.iucnredlist.org/}) client. The 'IUCN' Red List is a global list of threatened and endangered species. Functions cover all of the Red List 'API' routes. An 'API' key is required. } -\section{Taxonomic Names vs. IUCN IDs}{ - -From the documentation (quoting): "It is advisable wherever possible to use -the taxon name (species name) to make your API calls, rather than using IDs. -IDs are not immovable are expected to be used mainly by organizations -that work closely with the IUCN Red List." -} - \section{Authentication}{ IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. See key A IUCN API token. See \code{\link[=rl_use_iucn]{rl_use_iucn()}} for help getting and storing it. Get it at -https://apiv3.iucnredlist.org/api/v3/token +https://api.iucnredlist.org/users/sign_up Keep this key private. You can pass the key in to each function via the \code{key} parameter, but it's better to store the key either as a environment variable (\code{IUCN_REDLIST_KEY}) or an R option @@ -33,13 +25,13 @@ environment variable (\code{IUCN_REDLIST_KEY}) or an R option \strong{High level API} High level functions do the HTTP request and parse data to a data.frame for ease of downstream use. The high level functions have no underscore on -the end of the function name, e.g., \code{\link[=rl_search]{rl_search()}} +the end of the function name, e.g., \code{\link[=rl_species]{rl_species()}} \strong{Low level API} The parsing to data.frame in the high level API does take extra time. The low level API only does the HTTP request, and gives back JSON without doing any more parsing. The low level functions DO have an underscore on -the end of the function name, e.g., \code{\link[=rl_search_]{rl_search_()}} +the end of the function name, e.g., \code{\link[=rl_species_]{rl_species_()}} } \section{No Spatial}{