---
title: "Introduction to reptiledbr: Accessing The Reptile Database in R"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to reptiledbr: Accessing The Reptile Database in R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(reptiledbr)
```


`reptiledbr` is an R package that provides an interface to The Reptile Database, allowing researchers and reptile enthusiasts to easily access taxonomic information, distribution data, and other details about reptile species. This tutorial will walk you through the basic usage of the package.

## Installation

You can install the `reptiledbr` package from GitHub using:

```r
# install.packages("pak")
pak::pak("PaulESantos/reptiledbr")
```

## Basic Usage

### 1. Loading the package

Let's start by loading the package:

```{r}
library(reptiledbr)
```

### 2. Retrieving data for specific species

The main function of the package is `get_reptiledb_data()`, which allows you to search for one or more species:

```{r}
# Create a list of species to search
species_list <- c(
  "Lachesis muta",
  "Python bivittatus",
  "Crotalus atrox"
)
```

This function will connect to The Reptile Database, search for each species, and download the available information. During the process, you'll see progress messages like:

```{r}
# Get data for these species
reptile_data <- get_reptiledb_data(species_list)
```


### 3. Understanding the returned data

The `get_reptiledb_data()` function returns a tibble with columns containing both metadata about the search and the actual data retrieved:

```{r}
reptile_data
```


The `data` column contains nested tibbles with all the information scraped from each species page.

### 4. Formatting data with specialized functions

`reptiledbr` provides several specialized functions to extract and format specific types of information:

#### Synonyms

```{r}
format_synonyms(reptile_data)
```


#### Distribution information

```{r}
format_distribution(reptile_data)
```


#### Higher taxonomic classifications

```{r}
format_higher_taxa(reptile_data)
```


#### Subspecies information

```{r}
format_subspecies(reptile_data)
```


#### Common names

```{r}
format_common_names(reptile_data)
```


#### Reproduction information

```{r}
format_reproduction(reptile_data)
```


#### Type specimens

```{r}
format_types(reptile_data)
```


#### Diagnosis information

```{r}
format_diagnosis(reptile_data)
```


#### Comments

```{r}
format_comments(reptile_data)
```

#### Etymology

```{r}
format_etymology(reptile_data)
```


#### References

```{r}
format_references(reptile_data)
```

## Handling Special Cases

The package provides proper error handling for various cases:

### 1. Trinomial names (subspecies)

If you search for a trinomial name (genus + species + subspecies), the package will issue a warning and skip the search:

```{r}
species_list <- c(
  "Lachesis muta",
  "Bothrops atrox insularis"  # Trinomial name
)
reptile_data <- get_reptiledb_data(species_list)
```


### 2. Incomplete species names

The package can also handle incomplete species names, but it will warn you if no data is found:

```{r}
species_list <- c(
  "Lachesis muta",
  "Lachesis sp"  # Incomplete species name
)
reptile_data <- get_reptiledb_data(species_list)
```



## Conclusion

`reptiledbr` provides an easy and structured way to access reptile species information from [The Reptile Database](http://www.reptile-database.org/). The package handles many common edge cases and provides specialized functions to extract and format specific types of information. This makes it a valuable tool for herpetologists, ecologists, and other researchers working with reptile data.

For more information about the package, including advanced usage and complete function documentation, please refer to the package's [documentation](https://github.com/PaulESantos/reptiledbr).