library(kewr)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

The International Plant Names Index (IPNI) is a service that provides nomenclatural information for vascular plant names.

It provides information on published plant names, as well as authors and publications. The type of information that it holds for plant names includes when it was published, the publication, the author, as well as any nomenclatural remarks.

Searching IPNI for a record

Searching for IPNI operates on exact matching.

For example, Poa anua will not return any results:

results <- search_ipni("Poa anua")
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: 'Poa anua', filters: 'none'>
#> total results: 0
#> returned results: 0
#> total pages: 0
#> current page: 0

But Poa annua will:

results <- search_ipni("Poa annua")
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: 'Poa annua', filters: 'none'>
#> total results: 13
#> returned results: 13
#> total pages: 1
#> current page: 1
#> List of 1
#>  $ :List of 33
#>   ..$ name                 : chr "Poa annua"
#>   ..$ authors              : chr "L."
#>   ..$ publishingAuthor     : chr "L."
#>   ..$ authorTeam           :List of 1
#>   ..$ rank                 : chr "spec."
#>   ..$ url                  : chr "/n/320035-2"
#>   ..$ family               : chr "Poaceae"
#>   ..$ genus                : chr "Poa"
#>   ..$ species              : chr "annua"
#>   ..$ citationType         : chr "tax. nov."
#>   ..$ hybrid               : logi FALSE
#>   ..$ hybridGenus          : logi FALSE
#>   ..$ inPowo               : logi TRUE
#>   ..$ linkedPublication    :List of 18
#>   ..$ publication          : chr "Sp. Pl."
#>   ..$ publicationYear      : int 1753
#>   ..$ publicationYearNote  : chr "1 May 1753"
#>   ..$ referenceCollation   : chr "1: 68"
#>   ..$ publicationId        : chr "1071-2"
#>   ..$ recordType           : chr "citation"
#>   ..$ reference            : chr "Sp. Pl. 1: 68. 1753 [1 May 1753] "
#>   ..$ remarks              : chr "[Gandhi 30 Jun 2000]"
#>   ..$ suppressed           : logi FALSE
#>   ..$ topCopy              : logi TRUE
#>   ..$ typeLocations        : chr "lectotype LINN (NO. 87.17, RIGHT-HAND PLANT) (NO. 87.17, RIGHT-HAND PLANT)"
#>   ..$ version              : chr "1.5"
#>   ..$ id                   : chr "320035-2"
#>   ..$ fqId                 : chr "urn:lsid:ipni.org:names:320035-2"
#>   ..$ hasNomenclaturalNotes: logi FALSE
#>   ..$ hasTypeData          : logi TRUE
#>   ..$ hasOriginalData      : logi FALSE
#>   ..$ hasLinks             : logi FALSE
#>   ..$ bhlLink              : chr "http://www.biodiversitylibrary.org/openurl?ctx_ver=Z39.88-2004&rft.date=1753&rft.spage=68&rft.volume=1&rft_id=h"| __truncated__

The exact matching does, however, work on fragments of a name. For instance, Poa will return results for the everything that includes that term:

results <- search_ipni("Poa")
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: 'Poa', filters: 'none'>
#> total results: 2936
#> returned results: 50
#> total pages: 59
#> current page: 59
#> List of 1
#>  $ :List of 13
#>   ..$ abbreviation   : chr "Poa France Belgique Suisse"
#>   ..$ date           : chr "15 Jan 2005"
#>   ..$ fqId           : chr "urn:lsid:ipni.org:publications:20001827-1"
#>   ..$ id             : chr "20001827-1"
#>   ..$ recordType     : chr "publication"
#>   ..$ suppressed     : logi FALSE
#>   ..$ title          : chr "Poa de France, Belgique et Suisse"
#>   ..$ tl2Author      : chr "Portal, Robert"
#>   ..$ url            : chr "/p/20001827-1"
#>   ..$ version        : chr "1.1"
#>   ..$ hasBhlLinks    : logi FALSE
#>   ..$ hasBhlTitleLink: logi FALSE
#>   ..$ hasBhlPageLink : logi FALSE

It should be noted that this will return results for authors and publications as well as taxon names. We can see the first result for this search is the publication “Poa de France, Begique et Suisse”.

Pagination

Looking at the search above, we can see that there were a total of 2936 records found but only the first 50 were returned. There are two possible ways to get the rest of the search results.

The first is to increase the record limit to ensure we get everything:

results <- search_ipni("Poa", limit=1000)
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: 'Poa', filters: 'none'>
#> total results: 2936
#> returned results: 1000
#> total pages: 3
#> current page: 3
#> List of 1
#>  $ :List of 13
#>   ..$ abbreviation   : chr "Poa France Belgique Suisse"
#>   ..$ date           : chr "15 Jan 2005"
#>   ..$ fqId           : chr "urn:lsid:ipni.org:publications:20001827-1"
#>   ..$ id             : chr "20001827-1"
#>   ..$ recordType     : chr "publication"
#>   ..$ suppressed     : logi FALSE
#>   ..$ title          : chr "Poa de France, Belgique et Suisse"
#>   ..$ tl2Author      : chr "Portal, Robert"
#>   ..$ url            : chr "/p/20001827-1"
#>   ..$ version        : chr "1.1"
#>   ..$ hasBhlLinks    : logi FALSE
#>   ..$ hasBhlTitleLink: logi FALSE
#>   ..$ hasBhlPageLink : logi FALSE

However, IPNI caps the limit at a maximum of 1000 records. Also, we often don’t know how many records a search will return, or whether it will return a large number of records.

In those cases, we can ask IPNI for the next page of results.

query <- "Poa"
page1 <- search_ipni(query)
#> No encoding supplied: defaulting to UTF-8.
page2 <- request_next(page1)
#> No encoding supplied: defaulting to UTF-8.

bind_rows(
  tidy(page1),
  tidy(page2)
)
#> # A tibble: 100 × 54
#>    abbreviation  date   fqId   id    recordType suppressed title tl2Author url  
#>    <chr>         <chr>  <chr>  <chr> <chr>      <lgl>      <chr> <chr>     <chr>
#>  1 Poa France B… 15 Ja… urn:l… 2000… publicati… FALSE      Poa … Portal, … /p/2…
#>  2 NA            NA     urn:l… 3851… citation   FALSE      NA    NA        /n/3…
#>  3 NA            NA     urn:l… 3931… citation   FALSE      NA    NA        /n/3…
#>  4 NA            NA     urn:l… 3933… citation   FALSE      NA    NA        /n/3…
#>  5 NA            NA     urn:l… 4014… citation   FALSE      NA    NA        /n/4…
#>  6 NA            NA     urn:l… 4032… citation   FALSE      NA    NA        /n/4…
#>  7 NA            NA     urn:l… 4032… citation   FALSE      NA    NA        /n/4…
#>  8 NA            NA     urn:l… 4092… citation   FALSE      NA    NA        /n/4…
#>  9 NA            NA     urn:l… 3000… citation   FALSE      NA    NA        /n/3…
#> 10 NA            NA     urn:l… 8481… citation   FALSE      NA    NA        /n/8…
#> # … with 90 more rows, and 45 more variables: version <chr>, hasBhlLinks <lgl>,
#> #   hasBhlTitleLink <lgl>, hasBhlPageLink <lgl>, name <chr>, authors <chr>,
#> #   publishingAuthor <chr>, authorTeam <list>, originalRemarks <chr>,
#> #   rank <chr>, family <chr>, genus <chr>, species <chr>, citationType <chr>,
#> #   hybrid <lgl>, hybridGenus <lgl>, inPowo <lgl>, linkedPublication <list>,
#> #   publication <chr>, publicationYear <int>, referenceCollation <chr>,
#> #   publicationId <chr>, reference <chr>, topCopy <lgl>, …

Keywords and filtering

You can perform more complicated searches using keywords and filters. For example, you can search for all genera names published for a particular family.

results <- search_ipni(list(family="Ephedraceae"), 
                       filters="genera")
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: family='Ephedraceae', filters: 'genera'>
#> total results: 3
#> returned results: 3
#> total pages: 1
#> current page: 1
#> List of 1
#>  $ :List of 30
#>   ..$ name                 : chr "Chaetocladus"
#>   ..$ authors              : chr "J.Nelson"
#>   ..$ publishingAuthor     : chr "J.Nelson"
#>   ..$ authorTeam           :List of 1
#>   ..$ rank                 : chr "gen."
#>   ..$ url                  : chr "/n/328161-2"
#>   ..$ family               : chr "Ephedraceae"
#>   ..$ genus                : chr "Chaetocladus"
#>   ..$ citationType         : chr "tax. nov."
#>   ..$ hybrid               : logi FALSE
#>   ..$ hybridGenus          : logi FALSE
#>   ..$ inPowo               : logi TRUE
#>   ..$ linkedPublication    :List of 16
#>   ..$ publication          : chr "Pinaceae [Nelson]"
#>   ..$ publicationYear      : int 1866
#>   ..$ referenceCollation   : chr "161"
#>   ..$ publicationId        : chr "19531-2"
#>   ..$ recordType           : chr "citation"
#>   ..$ reference            : chr "Pinaceae [Nelson] 161. 1866 "
#>   ..$ remarks              : chr "nom. syn. of Ephedra Linnaeus (1753)"
#>   ..$ suppressed           : logi FALSE
#>   ..$ topCopy              : logi TRUE
#>   ..$ typeName             : chr "C. distachyus (Linnaeus) J. Nelson ('distachys') (Ephedra distachya Linnaeus)"
#>   ..$ version              : chr "1.3"
#>   ..$ id                   : chr "328161-2"
#>   ..$ fqId                 : chr "urn:lsid:ipni.org:names:328161-2"
#>   ..$ hasNomenclaturalNotes: logi FALSE
#>   ..$ hasTypeData          : logi TRUE
#>   ..$ hasOriginalData      : logi FALSE
#>   ..$ hasLinks             : logi FALSE

Or for all species names published in a particular year.

results <- search_ipni(list(published=1989),
                       filters=c("species"))
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: published='1989', filters: 'species'>
#> total results: 4251
#> returned results: 50
#> total pages: 86
#> current page: 86
#> List of 1
#>  $ :List of 34
#>   ..$ name                 : chr "Abies colimensis"
#>   ..$ authors              : chr "Rushforth & Narave"
#>   ..$ publishingAuthor     : chr "Rushforth & Narave"
#>   ..$ authorTeam           :List of 2
#>   ..$ rank                 : chr "spec."
#>   ..$ url                  : chr "/n/271459-2"
#>   ..$ family               : chr "Pinaceae"
#>   ..$ genus                : chr "Abies"
#>   ..$ species              : chr "colimensis"
#>   ..$ citationType         : chr "tax. nov."
#>   ..$ collectionNumber     : chr "647"
#>   ..$ collectorTeam        : chr "M.Rushforth"
#>   ..$ distribution         : chr "Nevada de Colima, 3150 m, Jalisco (Mexico, Northern America)"
#>   ..$ hybrid               : logi FALSE
#>   ..$ hybridGenus          : logi FALSE
#>   ..$ inPowo               : logi TRUE
#>   ..$ linkedPublication    :List of 16
#>   ..$ publication          : chr "Notes Roy. Bot. Gard. Edinburgh"
#>   ..$ publicationYear      : int 1989
#>   ..$ referenceCollation   : chr "46: 105, fig. 2"
#>   ..$ publicationId        : chr "758-2"
#>   ..$ recordType           : chr "citation"
#>   ..$ reference            : chr "Notes Roy. Bot. Gard. Edinburgh 46: 105, fig. 2. 1989 "
#>   ..$ suppressed           : logi FALSE
#>   ..$ topCopy              : logi TRUE
#>   ..$ typeLocations        : chr "holotype E"
#>   ..$ version              : chr "1.6"
#>   ..$ id                   : chr "271459-2"
#>   ..$ fqId                 : chr "urn:lsid:ipni.org:names:271459-2"
#>   ..$ hasNomenclaturalNotes: logi FALSE
#>   ..$ hasTypeData          : logi TRUE
#>   ..$ hasOriginalData      : logi FALSE
#>   ..$ hasLinks             : logi FALSE
#>   ..$ bhlLink              : chr "http://www.biodiversitylibrary.org/openurl?ctx_ver=Z39.88-2004&rft.date=1989&rft.spage=105&rft.volume=46&rft_id"| __truncated__

You can also use the keywords to search for author records.

results <- search_ipni(list(author_surname="Gardiner"))
#> No encoding supplied: defaulting to UTF-8.

results
#> <IPNI search: author_surname='Gardiner', filters: 'none'>
#> total results: 2
#> returned results: 2
#> total pages: 1
#> current page: 1
#> List of 1
#>  $ :List of 17
#>   ..$ alternativeNames: chr ""
#>   ..$ dates           : chr "1981-"
#>   ..$ examples        : chr "Vanda longitepala D.L.Roberts, L.M.Gardiner & Motes in Kew Bull. 63(3): 495. 2009"
#>   ..$ forename        : chr "Lauren Maria"
#>   ..$ fqId            : chr "urn:lsid:ipni.org:authors:20014591-1"
#>   ..$ id              : chr "20014591-1"
#>   ..$ isoCountries    : chr ""
#>   ..$ recordType      : chr "author"
#>   ..$ source          : chr "Year of birth from author"
#>   ..$ standardForm    : chr "L.M.Gardiner"
#>   ..$ surname         : chr "Gardiner"
#>   ..$ suppressed      : logi FALSE
#>   ..$ taxonGroups     : chr "Spermatophytes"
#>   ..$ url             : chr "/a/20014591-1"
#>   ..$ version         : chr "1.2"
#>   ..$ summary         : chr "Gardiner, Lauren Maria (1981-)"
#>   ..$ hasBhlLink      : logi FALSE

And for publication records.

results <- search_ipni(list(title="Bulletin"))
#> No encoding supplied: defaulting to UTF-8.
results
#> <IPNI search: title='Bulletin', filters: 'none'>
#> total results: 920
#> returned results: 50
#> total pages: 19
#> current page: 19
#> List of 1
#>  $ :List of 13
#>   ..$ abbreviation   : chr "A'in Shams Sci. Bull."
#>   ..$ bphNumber      : chr "BPH/s p. 43"
#>   ..$ date           : chr "No. 1+, 1956+"
#>   ..$ fqId           : chr "urn:lsid:ipni.org:publications:12471-2"
#>   ..$ id             : chr "12471-2"
#>   ..$ recordType     : chr "publication"
#>   ..$ suppressed     : logi FALSE
#>   ..$ title          : chr "A'in Shams Science Bulletin.  Cairo"
#>   ..$ url            : chr "/p/12471-2"
#>   ..$ version        : chr "1.1"
#>   ..$ hasBhlLinks    : logi FALSE
#>   ..$ hasBhlTitleLink: logi FALSE
#>   ..$ hasBhlPageLink : logi FALSE

A full list of keywords and filters can be found in the help page for search_ipni.

Looking up a specific record

Specific records for taxon names, authors, and publications can be looked up using the IPNI ID. These IDs are specific to each individual type of record, so the type needs provided.

name <- lookup_ipni("385169-1", type="taxon")
#> No encoding supplied: defaulting to UTF-8.
name
#> <IPNI name id: 385169-1, type: citation>
#> Name: Agropyron poa
#> Authors: Chevall.
#> Publication: Fl. Gen. Env. Paris, ed. 2
#> Publication Year: 1836
#> Reference: Fl. Gen. Env. Paris, ed. 2 2: 193. 1836 
#> Rank: spec.
#> In POWO: TRUE
author <- lookup_ipni("20028192-1", type="author")
#> No encoding supplied: defaulting to UTF-8.
author
#> <IPNI name id: 20028192-1, type: author>
#> Name: Liam A. Trethowan
#> Standard form: Trethowan
#> Dates: fl. 2015
#> Focal groups: Spermatophytes
#> Example taxon: Schnella accrescens (Killip & J.F. Macbride) Trethowan & R. Clark in Phytotaxa 204(4): 240. 2015
pub <- lookup_ipni("12471-2", type="publication")
#> No encoding supplied: defaulting to UTF-8.
pub
#> <IPNI name id: 12471-2, type: publication>
#> Title: A'in Shams Science Bulletin.  Cairo
#> Abbreviation: A'in Shams Sci. Bull.
#> LC Number: 
#> BPH Number: BPH/s p. 43