---
title: "Local Taxonomic Searches with reptiledbr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Local Taxonomic Searches with reptiledbr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", 
  fig.width = 7,
  fig.height = 5
)
```

## Introduction

The `reptiledbr` package allows users to access taxonomic information of reptiles directly from R without the constant need to make web queries to [The Reptile Database](http://www.reptile-database.org/) server. This provides several advantages:

- Faster processing when working offline
- Ability to efficiently verify large taxonomic datasets
- Reduction of requests to The Reptile Database server
- Consistency in results, even without a stable internet connection

This vignette demonstrates how to perform local searches using the package's main functions.

## Main Functions for Local Searches

The `reptiledbr` package offers three key functions for performing local taxonomic searches:

1. `reptiledbr_exact()`: For exact searches of scientific names
2. `reptiledbr_partial()`: For searches that allow partial matches (fuzzy matching)
3. `search_reptiledbr()`: Flexible function that combines exact and partial search capabilities
4. `list_subspecies_reptiledbr()`: To obtain information about subspecies

## Practical Examples

### Exact Search for Species Names

The `reptiledbr_exact()` function verifies if the provided species names exist exactly as written in the database. This function is useful when you need to verify the validity of specific taxonomic names.

```{r}
library(reptiledbr)

# Define a vector of species names to search
species_names <- c(
  "Lachesis muta",
  "Python bivittatus",
  "Crotalus atrox",
  "Bothrops atrox insularis", # Trinomial (with subspecies) - will generate an error
  "Lachesis sp",
  "Crotalus atroxx", # Intentional typo
  "Anolis liogaster",
  "Lachesis mutta", # Intentional typo
  "Python bivitatus" # Intentional typo
)

# Perform exact search
reptiledbr_exact(species_names)
```

As can be observed, the exact search only returns matches for names that are correctly written. Names with typos or incorrect formats (such as trinomials) are not recognized.

### Partial Match Search

The `reptiledbr_partial()` function is more flexible and uses fuzzy matching techniques to identify species even when there are minor typos or variations in spelling.

```{r}
# Perform search with partial matching
reptiledbr_partial(species_names)
```

Notice how `reptiledbr_partial()` was able to find matches for "Crotalus atroxx", "Lachesis mutta", and "Python bivitatus" despite the typos, but still does not recognize incorrect formats such as trinomials or incomplete names (e.g., "Lachesis sp").

### Flexible Search with Additional Options

The `search_reptiledbr()` function offers greater flexibility, allowing you to specify whether to use partial matching or not:

```{r}
# Define a list of valid species
subspecies_names <- c("Lachesis muta", 
                     "Anilius scytale",
                     "Anolis bahorucoensis",
                     "Anolis baleatus",
                     "Crotalus atrox",
                     "Anolis barahonae",
                     "Anolis bremeri")

# Exact search (without fuzzy matching)
search_reptiledbr(subspecies_names, use_fuzzy = FALSE)
```

### Obtaining Subspecies Information

A particularly useful feature is the ability to list all recognized subspecies for a given species using `list_subspecies_reptiledbr()`:

```{r}
# List all subspecies for the found species
search_reptiledbr(subspecies_names, use_fuzzy = FALSE) |> 
  list_subspecies_reptiledbr()
```

We can also combine partial matching search and subspecies retrieval:

```{r}
# Partial matching search followed by subspecies listing
reptiledbr_partial(c("Lachesis mutta", 
                    "Python bivitatus",
                    "Anolis barahonae")) |> 
  list_subspecies_reptiledbr()
```

## Recommended Workflow

For working with large taxonomic datasets, we recommend the following workflow:

1. Perform an initial search with `reptiledbr_exact()` to identify names that match exactly
2. For names not found, use `reptiledbr_partial()` to capture possible typos
3. Finally, use `list_subspecies_reptiledbr()` to obtain detailed information about subspecies when needed

## Conclusions

The `reptiledbr` package provides efficient tools for verifying and obtaining taxonomic information about reptiles without the need to make constant queries to [The Reptile Database](http://www.reptile-database.org/) serverusing `reptiledbr::search_reptiledbr()`. This greatly facilitates working with large datasets and allows for consistent taxonomic verification even without an internet connection.

The local search functions are particularly useful for researchers and professionals working with herpetological data, enabling efficient cleaning and validation of species lists, identification of common typos, and access to up-to-date taxonomic information about reptiles.