---
title: "Getting Started with iucnr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with iucnr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

The **`iucnr`** package provides high-performance, offline tools for querying and integrating data from the **IUCN Red List of Threatened Species** directly within R workflows.

By pairing with the local data provider package **`iucnrdata`**, `iucnr` enables researchers, ecologists, and conservationists to perform exact and fuzzy taxonomic matching, retrieve conservation statuses, and fetch preferred vernacular (common) names for both **flora and fauna**—without requiring API keys or an active internet connection.

---

## Key Features

- ⚡ **Ultra-Fast Performance**: Sub-2ms median query times via pre-indexed in-memory data tables and $O(1)$ Fast-Path binary key lookup.
- 🌐 **100% Offline Execution**: Query IUCN data anywhere in the field without internet dependencies, API quotas, or network latency.
- 🔀 **Fuzzy Taxonomic Matching**: Automatically resolves typographical errors in genus and specific epithet names.
- 🌿 **Comprehensive Coverage**: Fully supports both flora (plants, trees, fungi) and fauna (mammals, birds, amphibians, reptiles, fish, invertebrates).
- 🧹 **Silent Output by Default**: `verbose = FALSE` by default ensures clean pipeline integration with `dplyr` and `tidyverse`.

---

## Installation

To access the complete offline IUCN Red List database snapshot, install the `iucnrdata` data package from R-Universe:

```r
install.packages(
  "iucnrdata",
  repos = c("https://paulesantos.r-universe.dev", "https://cloud.r-project.org")
)
```

Next, install `iucnr`:

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

---

## Core Workflows

```{r load-pkg}
library(iucnr)
```

### 1. Fauna Conservation Status & Common Names

Query iconic wild fauna species across various taxonomic classes:

```{r}
fauna <- c(
  "Panthera onca",        # Jaguar
  "Tremarctos ornatus",   # Andean Bear
  "Vultur gryphus",       # Andean Condor
  "Spheniscus humboldti", # Humboldt Penguin
  "Ambystoma mexicanum"  # Axolotl
)

# Retrieve conservation status as a tibble
get_iucn_status(splist = fauna, format = "tbl")
```


Retrieve common names:

```{r}
get_iucn_common_name(splist = fauna, format = "tbl")
```

---

### 2. Flora Conservation Status

Retrieve conservation categories for threatened Andean and tropical tree/plant species:

```{r}
flora <- c(
  "Swietenia macrophylla",  # Big-leaf Mahogany
  "Puya raimondii",        # Queen of the Andes
  "Cedrela odorata",       # Spanish Cedar
  "Polylepis racemosa"     # Quenoa Tree
)

get_iucn_status(splist = flora, format = "tbl")
```

---

### 3. Automatic Fuzzy Matching for Typos

`iucnr` automatically detects and corrects typographical errors in genus or species names:

```{r}
splist_typos <- c(
  "Pantera onca",          # Typo in genus: Panthera -> Pantera
  "Puya raimondi",         # Typo in epithet: raimondii -> raimondi
  "Escallonia ressinosa"   # Typo in epithet: resinosa -> ressinosa
)

get_iucn_status(splist = splist_typos, format = "tbl")
```

---

### 4. Direct Filtering by Threat Category

Extract all species registered under a specific IUCN Red List category (e.g., `CR` for Critically Endangered, `EN` for Endangered, `VU` for Vulnerable):

```{r}
cr_species <- get_iucn_by_category("CR")
head(cr_species)
```

---

### 5. Higher Taxonomy & Dataset Version Metadata

Filter by higher taxonomic ranks (Kingdom, Phylum, Class, Order, Family):

```{r}
pinaceae_species <- get_iucn_by_taxonomy(family = "Pinaceae")
head(pinaceae_species)
```

Check the packaged IUCN snapshot version details:

```{r}
iucn_data_version()
```

---

## Integration with Tidyverse Workflows

`iucnr` functions return vector output when `format = "vect"`, enabling seamless integration with `dplyr::mutate()`:

```{r}
library(dplyr)

survey_data <- tibble::tibble(
  species = c("Panthera onca", "Swietenia macrophylla", "Vultur gryphus")
)

survey_data %>%
  mutate(
    status = get_iucn_status(species, format = "vect"),
    common_name = get_iucn_common_name(species, format = "vect")
  )
```

---

## Performance Benchmark

Below is a median query execution time comparison between `iucnr` (offline) and online API R packages (`iucnredlist` and `redlist`):

| Package / Mode | Execution Time (Median) | Acceleration vs Online API |
| :--- | :--- | :--- |
| `redlist` (Online API) | 996.7 ms | 1.0x (Baseline) |
| `iucnredlist` (Online API) | 418.6 ms | 2.4x |
| **`iucnr` (Offline Fast-Path)** | **1.45 ms** | **>680x Faster** |

---

## Citation

When using `iucnr` in scientific publications, please cite both the package and the underlying IUCN Red List dataset:

```{r}
citation("iucnr")
```

> IUCN. 2026. The IUCN Red List of Threatened Species. Version 2026-1. Data retrieved via GBIF (https://www.gbif.org/dataset/19491596-35ae-4a91-9a98-85cf505f1bd3).