Title:	Access to the List of Bird Species of Peru
Version:	0.1.0
Description:	Provides access to the species checklist published in 'List of the Birds of Peru' by Plenge, M. A. and Angulo, F. (version 29-12-2025) https://sites.google.com/site/boletinunop/checklist. The package exposes the current Peru bird checklist as an R dataset and includes tools for species lookup, taxonomic reconciliation, and fuzzy matching of scientific names. These features help streamline taxonomic validation for researchers and conservationists.
License:	MIT + file LICENSE
Suggests:	DT, readxl, shiny, testthat (≥ 3.0.0), withr, writexl, xml2
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://github.com/PaulESantos/avesperu, https://paulesantos.github.io/avesperu/
BugReports:	https://github.com/PaulESantos/avesperu/issues
Depends:	R (≥ 3.5)
LazyData:	true
Maintainer:	Paul E. Santos Andrade <paulefrens@gmail.com>
Imports:	cli, parallel
NeedsCompilation:	no
Packaged:	2026-03-23 04:04:39 UTC; PC
Author:	Paul E. Santos Andrade [aut, cre, cph]
Repository:	CRAN
Date/Publication:	2026-03-23 08:30:09 UTC

.onAttach hook

Description

Hook function that runs when the package is attached via library(). It displays the package version and checks for UNOP checklist updates.

Usage

.onAttach(lib, pkg)

Arguments

.onLoad hook

Description

Hook function that runs when the package is loaded. It sets default options for the package.

Usage

.onLoad(libname, pkgname)

Arguments

aves_peru_2025_v4

Description

The aves_peru_2025_v4 dataset provides an updated tibble of bird species recorded in Peru, based on the most recent taxonomic revisions by the South American Checklist Committee (SACC).

Usage

aves_peru_2025_v4

Format

A tibble with 1,917 rows and 6 columns:

order_name

Taxonomic order to which the bird species belongs.

family_name

Taxonomic family to which the bird species belongs.

scientific_name

Scientific name of the bird species.

english_name

English common name of the bird species.

spanish_name

Spanish common name of the bird species.

status

Category indicating the species' status, based on the following codes:

• X: Resident species.

• E: Endemic species. A species is considered endemic to Peru until a record outside its borders is published.

• NB: Non-breeding (migratory) species. Species that occur regularly in Peru but only during their non-breeding period.

• V: Vagrant species. Species that occasionally occur in Peru but are not part of the usual avifauna.

• IN: Introduced species. Species introduced to Peru by humans (or have colonized from introduced populations elsewhere) and have established self-sustaining breeding populations.

• H: Hypothetical species. Records based only on observations, specimens of dubious origin, or unpublished photographs or recordings kept in private hands.

• EX: Extinct or extirpated species. Species that have gone extinct or have been extirpated from Peru.

Details

This object is kept as a historical dataset. For the current checklist, use aves_peru_2025_v5.

This version reflects dramatic taxonomic changes and category updates based on published articles, photographs, and sound recordings archived in accredited institutions. It also includes a classification criterion following the SACC guidelines. Species without a specific code are considered resident species, equivalent to the "X" category of the SACC.

• Total species: 1,917

• Distribution by status:

  • X: 1,547 species

  • E: 120 species

  • NB: 139 species

  • V: 85 species

  • IN: 3 species

  • EX: 0 species

  • H: 23 species

These updates reflect the SACC’s continuous evaluation process, which now recognizes several former subspecies as full species.

Author(s)

Data compilation: Manuel A. Plenge Package implementation: Paul Efren Santos Andrade

References

Plenge, M. A. Version (29-09-2025) List of the birds of Peru / Lista de las aves del Perú. Unión de Ornitólogos del Perú: https://sites.google.com/site/boletinunop/checklist

See Also

For more information about the data, visit: https://sites.google.com/site/boletinunop/checklist

Examples

# Load the dataset
data("aves_peru_2025_v4")

aves_peru_2025_v5

Description

The aves_peru_2025_v5 dataset provides the most current and comprehensive tibble of bird species recorded in Peru, based on the latest taxonomic revisions by the South American Checklist Committee (SACC) as of December 22, 2025.

Usage

aves_peru_2025_v5

Format

A tibble with 1,919 rows and 9 columns:

order_name

Character. Taxonomic order to which the bird species belongs.

family_name

Character. Taxonomic family to which the bird species belongs.

genus

Character. Genus name of the bird species.

species_epithet

Character. Specific epithet (species name without genus).

scientific_name

Character. Complete scientific name of the bird species (binomial nomenclature: genus + species epithet).

english_name

Character. Common name in English.

spanish_name

Character. Common name in Spanish (Peruvian usage).

status

Character. Conservation and occurrence status category in Spanish. See Details section for complete descriptions.

status_code

Character. Original SACC status code. Values: X, E, NB, V, IN, U, EX. See Details section for code definitions.

Details

All records are based on published evidence (specimens, photographs, videos, or recordings) deposited in accredited institutional collections. The dataset follows strict inclusion criteria established by the SACC and the Unión de Ornitólogos del Perú (UNOP).

Dataset Summary

• Total species: 1,919

• Version date: December 29, 2025

• SACC baseline date: December 22, 2025

Distribution by Status

Status Categories (Detailed)

Residente (X - Resident)

Species that breed in Peru and maintain permanent or seasonal populations. This is the default category for species without a specific status code.

Endémico (E - Endemic)

Species whose entire known range is within Peru. A species is considered endemic until a published record documents its occurrence outside Peruvian borders.

Migratorio (NB - Non-breeding)

Species that occur regularly in Peru but only during their non-breeding period. These are typically austral or boreal migrants that breed elsewhere.

Divagante (V - Vagrant)

Species that occur occasionally in Peru and are not part of the regular avifauna. These represent extralimital records or irregular visitors.

Introducido (IN - Introduced)

Species introduced to Peru by humans (directly or colonized from introduced populations elsewhere) that have established self-sustaining breeding populations.

No confirmado (U - Unconfirmed)

Records that lack definitive published evidence. This includes:

• Sight records without corroborating physical evidence

• Specimens of dubious or uncertain origin

• Unpublished photographs or recordings in private collections

Extirpado (EX - Extirpated/Extinct)

Species that have gone extinct globally or have been extirpated from Peru.

Taxonomic Authority

The taxonomic sequence and species limits follow the South American Checklist Committee (SACC) of the American Ornithological Society, reflecting the committee's decisions through December 22, 2025.

To compare this local dataset version against the latest UNOP checklist available online, run unop_check_update().

Note

This dataset is updated periodically as new species are documented and taxonomic revisions are published. Check the UNOP website for the most current version.

Author(s)

Data compilation: Manuel A. Plenge & Fernando Angulo Package implementation: Paul Efren Santos Andrade

Source

Data compiled by Manuel A. Plenge and Fernando Angulo (UNOP). For corrections or updates, contact: chamaepetes@gmail.com

References

Plenge, M. A. & F. Angulo. Version 29-12-2025. Lista de las aves del Perú / List of the birds of Peru. Unión de Ornitólogos del Perú: https://sites.google.com/site/boletinunop/checklist

See Also

• UNOP Checklist: https://sites.google.com/site/boletinunop/checklist

• SACC: http://www.museum.lsu.edu/~Remsen/SACCBaseline.htm

• search_avesperu for species name validation

Examples

# Load the dataset
data("aves_peru_2025_v5")

# View structure
str(aves_peru_2025_v5)

# Summary by status
table(aves_peru_2025_v5$status)

Parse a UNOP checklist date

Description

Parse a UNOP checklist date

Usage

parse_unop_date(fecha_str)

Arguments

Value

A Date vector of length 1, or NA if parsing fails.

Run a TNRS-style Shiny app for avesperu

Description

Launches an interactive Shiny application for batch resolution of bird scientific names against the avesperu checklist. The interface is inspired by the BIEN TNRS workflow, but uses the local avesperu dataset and matching engine.

Usage

run_avesperu_app(
  host = "127.0.0.1",
  port = NULL,
  launch.browser = interactive()
)

Arguments

Details

The app supports:

• Batch input via pasted text or uploaded CSV/TXT/TSV files

• Name parsing and standardization

• Exact or fuzzy matching through search_avesperu

• Interactive review of matches and export of results and metadata

Synonym retrieval is not currently available because avesperu ships the accepted Peru checklist, not a synonymy backbone.

Value

The value returned by shiny::runApp.

Examples

## Not run: 
run_avesperu_app()

## End(Not run)

Search for Bird Species Data in the Birds of Peru Dataset

Description

This function searches for bird species information in the dataset provided by the avesperu package, given a list of species names. It supports approximate (fuzzy) matching to handle typographical errors or minor variations in species names using optimized agrep() matching. The function is optimized for both small and large lists through intelligent pre-filtering and optional parallel processing, while maintaining exact agrep() precision.

Usage

search_avesperu(
  splist,
  max_distance = 0.1,
  return_details = FALSE,
  batch_size = 100,
  parallel = TRUE,
  n_cores = NULL
)

Arguments

Details

The function performs the following steps:

1. Validates input and converts factors to character vectors

2. Standardizes species names using standardize_names()

3. Identifies and reports duplicate entries in the input list

4. Uses intelligent pre-filtering to reduce search space:

   • Filters by string length (mathematically guaranteed to preserve matches)

   • Optionally filters by first character for very large candidate sets

5. Performs precise agrep() fuzzy matching on filtered candidates

6. Calculates exact edit distances using adist()

7. Selects the best match (minimum distance) for each query

8. For large lists (>batch_size), processes in batches with optional parallelization

Value

The return value depends on the return_details parameter:

If return_details = FALSE (default):

A character vector with the same length as splist, containing the conservation/occurrence status for each species. NA values indicate no match was found.

If return_details = TRUE:

A data frame (tibble-compatible) with the following columns:

name_submitted

Character. The species name provided as input (standardized).

accepted_name

Character. The closest matching species name from the database, or NA if no match found within max_distance.

order_name

Character. The taxonomic order of the matched species.

family_name

Character. The taxonomic family of the matched species.

english_name

Character. Common name in English.

spanish_name

Character. Common name in Spanish.

status

Character. Conservation or occurrence status (e.g., "Endemic", "Resident", "Migrant", "Vagrant").

dist

Character. Edit distance between submitted and matched names. Lower values indicate better matches. NA if no match found.

Warning

For very large lists (>10,000 species) with parallel processing enabled, ensure sufficient system memory is available. Each parallel worker maintains a copy of the reference database (~5-10 MB).

See Also

agrep for the underlying fuzzy matching algorithm

Examples

# Basic usage - returns status vector
splist <- c("Falco sparverius", "Tinamus osgodi", "Crypturellus soui")
status <- search_avesperu(splist)
print(status)

# Get detailed reconciliation information
details <- search_avesperu(splist, return_details = TRUE)
print(details)

# Exact matching only (no fuzzy matching)
exact_results <- search_avesperu(splist, max_distance = 0)

# Handle species with typos
typo_list <- c("Falco sparveruis", "Tinamus osgoodi", "Crypturellus sui")
corrected <- search_avesperu(typo_list, return_details = TRUE)

# View submitted vs accepted names
print(corrected[, c("name_submitted", "accepted_name", "dist")])

Determine whether to show progress bar Return logical TRUE/FALSE depending on options and interactive session

Description

Determine whether to show progress bar Return logical TRUE/FALSE depending on options and interactive session

Usage

show_progress()

Standardize Species Names

Description

Standardize Species Names

Usage

standardize_names(splist)

Arguments

Value

Standardized species names

Check whether the local dataset is up to date against UNOP

Description

This function compares the local dataset version date stored in aves_peru_2025_v5 against the latest update date published on the UNOP checklist website. It is designed to be called explicitly by the user, or enabled through the avesperu.check_updates option.

Usage

unop_check_update(verbose = interactive())

Arguments

Value

An invisible named list with the fields success, is_up_to_date, has_update, current_version_date, online_version_date, checked_at, source_url, and message.

Get Last Update Date from UNOP Checklist Website

Description

This function scrapes the "Boletin UNOP" checklist page and extracts the last update date mentioned in the text.

Usage

unop_update_date()

Value

A character string with the date in the format "dd de mes de yyyy", or NA if no date is found.