Skip to content

Latest commit

 

History

History
208 lines (146 loc) · 4.93 KB

README.md

File metadata and controls

208 lines (146 loc) · 4.93 KB
Raw

kewr

R build status

An R package to access data from RGB Kew’s APIs.

Overview

kewr is meant to make accessing data from one of RGB Kew easier and to provide a consistent interface their public APIs.

This package should cover:

New sources will be added as they come up.

Installation

kewr is not on CRAN yet but you can install the latest development version from GitHub:

# install.packages("devtools")
devtools::install_github("barnabywalker/kewr")

Usage

Functions in this package all start with a prefix specifying what action you want to perform and a suffix referring to the resource.

Four of the resources (POWO, WCVP, IPNI, and ToL) are databases storing flora, taxonomic, nomenclatural, or genetic information. These three resources all have a search_* and lookup_*.

Retrieving records

The lookup_ functions can be used to retrieve a particular record by its unique IPNI ID:

lookup_powo("320035-2")
lookup_wcvp("320035-2")
lookup_ipni("320035-2")

IPNI contains records for authors and publications, which can also be retrieved using the lookup_ipni function:

lookup_ipni("20885-1", type="author")
lookup_ipni("987-2", type="publication")

The ToL uses its own ID system. These IDs can be found by first searching the database.

lookup_tol("2717")

Searching databases

All four of these databases can be searched as well:

search_powo("Poa annua")
search_wcvp("Poa annua")
search_ipni("Poa annua")
search_tol("Poa annua")

And all, except the ToL, use filters and keywords for more advanced searches:

search_powo(list(genus="Poa", distribution="Madagascar"), 
            filters=c("accepted", "species"))
search_wcvp(list(genus="Poa"), filters=c("accepted", "species"))
search_ipni(list(genus="Poa", published=1920),
            filters=c("species"))

The number of search results returned are determined by the limit keyword:

search_powo(list(genus="Poa"), limit=20)
search_wcvp(list(genus="Poa"), limit=20)
search_ipni(list(genus="Poa"), limit=20)
search_tol("Poa", limit=20)

The next page for a set of search results can be requested using the request_next function:

results <- search_powo(list(genus="Poa"))
request_next(results)

Loading data from ToL

Tree and gene data can be loaded directly from ToL into R.

For instance, you can load the whole Tree of Life.

load_tol()

Or a gene tree for a particular gene.

gene_info <- lookup_tol("51", type="gene")
load_tol(gene_info$tree_file_url)

Or a FASTA file for a specimen.

specimen_info <- lookup_tol("1296")
load_tol(specimen_info$fasta_file_url)

Downloading from the ToL

The corresponding files can also be downloaded for use later or in other programmes.

specimen_info <- lookup_tol("1296")
download_tol(specimen_info$fasta_file_url)

Downloading the WCVP

The whole of WCVP can be download to a directory using:

download_wcvp()

Matching names

The KNMS resource is only used for matching names to records in POWO/WCVP:

match_knms(c("Poa annua", "Magnolia grandifolia", "Bulbophyllum sp."))

Single names can also be matched to IPNI using the KRS resources.

match_krs("Poa annua")

KRS is slower for matching many names, as a request needs to be made for each one. But it has the advantage of allowing more complex matching:

match_krs(list(genus="Solanum", species="sanchez-vegae", author="S.Knapp"))

Tidying results

Each function in this package returns an object that stores the original response as well as the content of the response parsed into a list. This is to give the user as much flexibility as possible and to make debugging things a bit easier.

But this can be hard to use, so all the results objects can be tidied as a tibble:

results <- search_powo("Poa annua")
tidy(results)

Citing

You can get information about how to cite kewr by using:

citation("kewr")

You can also get the citation to use for each data service using the different results objects:

r <- search_wcvp("Poa")
kew_citation(r)