---
title: "ritis introduction"
author: "Scott Chamberlain"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ritis introduction}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, echo = FALSE, warning = FALSE, message = FALSE}
NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
knitr::opts_chunk$set(
  collapse  =  TRUE,
  comment  =  "#>",
  warning = FALSE,
  message = FALSE,
  purl  =  NOT_CRAN,
  eval  =  NOT_CRAN
)
```

An interface to the Integrated Taxonomic Information System (ITIS)

See also the [taxize book](https://taxize.dev/) for 
a manual on working with taxonomic data in R, including with ITIS data.

## Installation

Install from CRAN

```{r eval=FALSE}
install.packages("ritis")
```

Or install the development version from GitHub

```{r installgh, eval=FALSE}
devtools::install_github("ropensci/ritis")
```

Load `ritis`

```{r}
library("ritis")
```

## ITIS Solr interface

There are four methods.

* `itis_search()` - Search
* `itis_group()` - Group
* `itis_highlight()` - Hightlight
* `itis_facet()` - Facet

These four methods use the equivalent functions in the package `solrium`, e.g.,
`ritis::itis_search()` uses `solrium::solr_search()`, etc. The `itis_*()` functions
simply use `...` to allow users to pass on parameters to the wrapped `solrium`
functions. So do read the `solrium` docs.

ITIS Solr API docs: <https://www.itis.gov/solr_documentation.html>

Some examples:

matches only monomials

```{r}
itis_search(q = "nameWOInd:/[A-Za-z0-9]*[ ]{0,0}*/")
```

matches only binomials

```{r}
itis_search(q = "nameWOInd:/[A-Za-z0-9]*[ ]{1,1}[A-Za-z0-9]*/")
```

## ITIS REST API interface

ITIS REST API docs: <http://www.itis.gov/ws_description.html>

The following are some example uses. There are many more methods not shown below

-------

Get accepted names for a TSN

```{r}
accepted_names(tsn = 504239)
```

Get common names for a TSN

```{r}
common_names(tsn = 183833)
```

Full hierarchy for a TSN

```{r}
hierarchy_full(tsn = 37906)
```
