Skip to contents

Search for Bird Species Data in the Birds of Peru Dataset

Source: R/get_avesperu.R
search_avesperu.Rd

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 edit-distance matching. The function is optimized for both small and large lists through intelligent pre-filtering and optional parallel processing.

Usage

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

Arguments

splist

A character vector or factor containing the scientific names of bird species to search for. Names can include minor variations or typos.

max_distance

Numeric. The maximum allowable distance for fuzzy matching. Can be either:

  • A proportion between 0 and 1 (e.g., 0.1 = 10\

  • An integer representing the maximum number of character differences

Default: 0.1.

return_details

Logical. If FALSE (default), returns only a character vector of species status. If TRUE, returns a detailed data frame with complete reconciliation information including taxonomic data and matching distances.

batch_size

Integer. Number of species to process per batch when handling large lists. Useful for memory management and progress tracking. Default: 100 species per batch.

parallel

Logical. Should parallel processing be used for large lists? Automatically disabled for small lists. Requires the parallel package. Default: TRUE.

n_cores

Integer or NULL. Number of CPU cores to use for parallel processing. Auto selection respects mc.cores, available batches and a limit of four workers. Unavailable core detection uses sequential execution.

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 unique match was found, or the input contains qualifiers or hybrid markers.

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.

The detailed result retains eight columns. Its reconciliation attribute is a row-aligned data frame containing the original and standardized names, qualifier/hybrid flags, match type, candidate count, candidate names and review reasons. The avesperu_result data-frame subclass keeps this attribute aligned when rows are selected using [. Ambiguous matches have no accepted name or status; candidates are sorted. Qualified and hybrid inputs can have a suggested match but always need review. Attributes execution and reference record actual workers, batches, fallback reason and the checklist identifier/date used. Empty input returns a typed zero-row table or character(0). Proportions strictly between 0 and 1 use ceiling(nchar(name) * distance); 0 means exact only and values at least 1 must be whole edit counts.

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)

  5. Performs exact matching before fuzzy matching to avoid unnecessary work

  6. Calculates edit distances using stringdist::stringdist()

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

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

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

stringdist::stringdist for the underlying edit-distance calculation

Examples

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

# Get detailed reconciliation information
details <- search_avesperu(splist, return_details = TRUE)
print(details)
#>      name_submitted     accepted_name    order_name family_name
#> 1  Falco sparverius  Falco sparverius Falconiformes  Falconidae
#> 2    Tinamus osgodi   Tinamus osgoodi  Tinamiformes   Tinamidae
#> 3 Crypturellus soui Crypturellus soui  Tinamiformes   Tinamidae
#>       english_name        spanish_name    status dist
#> 1 American Kestrel Cernícalo Americano Residente    0
#> 2    Black Tinamou        Perdiz Negra Residente    1
#> 3   Little Tinamou        Perdiz Chica Residente    0

# 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")])
#>     name_submitted     accepted_name dist
#> 1 Falco sparveruis  Falco sparverius    2
#> 2  Tinamus osgoodi   Tinamus osgoodi    0
#> 3 Crypturellus sui Crypturellus soui    1