Help for package letsHerp

Title:

An Interface to the Reptile Database

Version:

0.1.0

URL:

https://github.com/joao-svalencar/letsHerp

BugReports:

https://github.com/joao-svalencar/letsHerp/issues

Description:

Provides tools to retrieve and summarize taxonomic information and synonymy data for reptile species using data scraped from The Reptile Database website (https://reptile-database.reptarium.cz/). Outputs include clean and structured data frames useful for ecological, evolutionary, and conservation research.

License:

MIT + file LICENSE

Encoding:

UTF-8

RoxygenNote:

7.3.2

Imports:

dplyr, httr, parallel, pbapply, pbmcapply, rvest, stringr, tidyr, utils, xml2

Depends:

R (≥ 3.5)

LazyData:

true

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

VignetteBuilder:

knitr

Config/testthat/edition:

NeedsCompilation:

Packaged:

2025-06-18 16:13:43 UTC; joaosvalencar

Author:

João Paulo dos Santos Vieira-Alencar

[aut, cre], Christoph Liedtke

[aut]

Maintainer:

João Paulo dos Santos Vieira-Alencar <joaopaulo.valencar@gmail.com>

Repository:

CRAN

Date/Publication:

2025-06-23 10:30:02 UTC

letsHerp: An R Interface to the Reptile Database

Description

The letsHerp package provides functions to interact with and extract taxonomic and distributional data from the Reptile Database (https://reptile-database.reptarium.cz). It supports advanced search queries, extraction of species names, synonyms, higher taxa, and related metadata for herpetological research.

Author(s)

Maintainer: João Paulo dos Santos Vieira-Alencar joaopaulo.valencar@gmail.com (ORCID)

Authors:

Christoph Liedtke christoph.liedtke@ebd.csic.es (ORCID)

Example dataset: allReptiles

Description

This dataset contains the valid names and url addresses for all reptile species cataloged in The Reptile Database.

Usage

allReptiles

Format

A dataframe (download: May 23th, 2025) with 12440 rows and 8 variables:

order: A species current order
suborder: A species current suborder
family: A species current family
genus: A species current genus
species: A character vector with known current valid name for all reptile species cataloged in The Reptile Database website
year: A species description year
author: The authors that described the species under the current valid name
url: A character column with the respective url to access all reptile species cataloged in The Reptile Database website information

Source

The data was sampled from The Reptile Database website https://reptile-database.reptarium.cz using function letsHerp::herpSpecies() with the url obtained from an 'Advanced search' set to exclude all reptile species described to the fictional planet Arrakis (-Arrakis).

Example dataset: allSynonyms

Description

This dataset contains the valid names and respective listed synonyms for all reptile species cataloged in The Reptile Database.

Usage

allSynonyms

Format

A dataframe with 53,159 rows and 2 variables:

species: A character vector with known current valid name for all reptile species cataloged in The Reptile Database website (download: May 23rd, 2025)
synonym: A character column with the respective synonyms for all reptile species cataloged in The Reptile Database website information (download: May 23rd, 2025)

Source

The data was sampled from The Reptile Database website https://reptile-database.reptarium.cz using function letsHerp::herpSynonyms(letsHerp::allReptiles)

Example dataset: allSynonymsRef

Description

This dataset contains the valid names and respective listed synonyms for all reptile species cataloged in The Reptile Database.

Usage

allSynonymsRef

Format

A dataframe with 110,413 rows and 3 variables:

species: A character vector with known current valid name for all reptile species cataloged in The Reptile Database website (download: May 23rd, 2025)
synonym: A character column with the respective synonyms for all reptile species cataloged in The Reptile Database website information (download: May 23rd, 2025)
ref: A charater column with the synonyms and respective references that used it

Source

The data was sampled from The Reptile Database website https://reptile-database.reptarium.cz using function letsHerp::herpSynonyms(letsHerp::allReptiles)

Search The Reptile Database website (RDB): Advanced

Description

Creates a search URL for retrieving species lists from RDB based on multiple filters. This URL is primarily used by herpSpecies, but can also be used manually for advanced queries.

If a synonym is provided and can be unambiguously matched to a valid species, the function also prints detailed information for that species.

Usage

herpAdvancedSearch(higher=NULL,
                          genus=NULL,
                          year=NULL,
                          common_name=NULL,
                          synonym=NULL,
                          location=NULL)

Arguments

higher

Character string. A higher-level reptile taxon above genus (e.g., "snakes" or "Boidae").

genus

Character string. The current valid name of a reptile genus (e.g., "Apostolepis").

year

Character string. Filters the search by year of species description (e.g., "2025").

common_name

Character string. A common name potentially linked to a species or genus (e.g., "tree boa").

synonym

Character string. A name potentially regarded as a synonym of a valid taxon (e.g., "Boa diviniloqua").

location

Character string. A country or region name used to list species expected to occur there.

Value

A character string containing the URL to be used in herpSpecies.

If a provided synonym corresponds unambiguously to a valid species, the function also prints species information retrieved from RDB to the console.

Note

This function does not automatically quote input values. If you want to force an exact match (e.g., "Boa" as a phrase), you must manually include quotes in the input string, e.g., "\"Boa\"".

Logical operators (e.g., OR, AND) are supported and will be properly formatted in the search. To exclude terms, use a leading minus sign (e.g., higher = "-snakes") following RDB's query syntax, instead of using NOT.

When a synonym is matched to a single valid species, the function will also display the species' full information as a side effect.

Examples


herpAdvancedSearch(higher = "snakes", year = "2010", location = "Brazil")
herpAdvancedSearch(year = "2010 OR 2011 OR 2012")
herpAdvancedSearch(genus = "Apostolepis OR \"Boa\" OR Atractus") #quotes "Boa"

Search for a Single Reptile Species in The Reptile Database (RDB)

Description

Queries The Reptile Database (RDB) for information about a single reptile species using its binomial name.

Usage

herpSearch(binomial=NULL, ref=FALSE, verbose=TRUE)

Arguments

binomial

Character string. The valid binomial name of a reptile species (e.g., "Boa constrictor").

ref

Logical. If TRUE, returns the list of references from RDB associated with the species. Default is FALSE.

verbose

Logical. If TRUE, prints species information in the console. Default is TRUE.

Value

A list containing species information retrieved from The Reptile Database. If ref = TRUE, returns references related to the species.

References

Uetz, P., Freed, P., & Hošek, J. (Eds.). (2025). The Reptile Database. Retrieved from http://www.reptile-database.org

Examples


herpSearch("Boa constrictor")
herpSearch("Boa constrictor", ref = TRUE)

Retrieve Reptile Species and Taxonomic Information from RDB

Description

Retrieves a list of reptile species from The Reptile Database (RDB) based on a search URL, and optionally returns detailed taxonomic information for each species. This function can also save progress to disk during sampling and extract species-specific URLs for further use.

Usage

herpSpecies(url,
                   showProgress = TRUE,
                   dataList = NULL, 
                   taxonomicInfo=FALSE, 
                   fullHigher=FALSE, 
                   getLink=FALSE,
                   cores = max(1, parallel::detectCores() - 1),
                   checkpoint = NULL,
                   backup_file = NULL
                   )

Arguments

url

Character string. A search URL generated via an advanced search on the RDB website or with herpAdvancedSearch.

showProgress

Logical. If TRUE, prints sampling progress in the console. Default is FALSE.

dataList

Optional. A data frame with columns species and url, used to extract taxonomic information from previously sampled species links.

taxonomicInfo

Logical. If TRUE, returns taxonomic information for each species, including order, suborder, family, genus, author, and year. Default is FALSE.

fullHigher

Logical. If TRUE, includes the full higher taxonomic hierarchy as reported by RDB (e.g., including subfamilies). Requires taxonomicInfo = TRUE. Default is FALSE.

getLink

Logical. If TRUE, includes the RDB URL for each species (useful for follow-up functions like herpSynonyms). Default is FALSE.

cores

Integer. Number of CPU cores to use for parallel processing. Default is one less than the number of available cores.

checkpoint

Optional. Integer specifying the number of species to process before saving a temporary backup. Backup is only saved if cores = 1. If set to 1, saves progress after each species (safest but slowest).

backup_file

Optional. Character string specifying the path to an .rds file for saving intermediate results when checkpoint is set. Must end in .rds.

Value

If taxonomicInfo = FALSE (default), returns a character vector of species names.

If taxonomicInfo = TRUE, returns a data frame with columns: order, suborder (if available), family, genus, species, author, and year.

If fullHigher = TRUE, includes an additional column with the full higher taxa classification.

If getLink = TRUE, includes a column with the URL for each species’ page on RDB.

Note

If checkpoint is used, progress will only be saved when cores = 1. This prevents potential write conflicts in parallel mode.

Examples


boa <- herpSpecies(herpAdvancedSearch(genus = "Boa"),
                                      taxonomicInfo = TRUE, 
                                      cores = 2)

Synchronize species names using synonym reference table

Description

Compares a user-provided list of reptile taxon names against a synonym table from The Reptile Database and returns an updated list of valid names. Particularly useful to standardize names before analyses or when integrating heterogeneous taxonomic sources.

Supports interactive disambiguation in cases where multiple valid names are found for a given synonym. Optionally, unmatched names can be retained or returned as blank.

Usage

herpSync(query, synonym, interactive = FALSE, return.no.matches = FALSE)

Arguments

query

A character vector of taxon names to be processed (e.g., species list, phylogenetic tip labels, or trait table entries).

synonym

A data frame with a synonym reference table (e.g., output from herpSynonyms). If not provided, the function uses the internal dataset letsHerp::allSynonyms, which may not be the most up-to-date.

interactive

Logical. If TRUE, the function allows real-time selection when a synonym matches multiple valid names. If FALSE (default), all possible matches are returned as concatenated strings.

return.no.matches

Logical. If TRUE, species not found in the synonym table will be returned as originally provided in the query. If FALSE (default), unmatched entries will be left blank.

Value

A data frame with the following columns:

input: original input names from the query.
stripped: standardized versions of the input names (e.g., without authors or formatting).
status: description of the outcome (e.g., "updated", "not found", "multiple matches").
updated: best-matching valid names according to the synonym table.

Note

The internally stored synonym table letsHerp::allSynonyms was last updated on May 23rd, 2025.

References

Liedtke, H. C. (2018). AmphiNom: an amphibian systematics tool. Systematics and Biodiversity, 17(1), 1–6. https://doi.org/10.1080/14772000.2018.1518935

Examples

boa_syn <- letsHerp::allSynonyms[grep("^Boa\\s", allSynonyms$species), ]
query <- c("Vieira-Alencar authoristicus", "Boa atlantica", "Boa diviniloqua", "Boa imperator")
herpSync(query, boa_syn)

Retrieve Synonyms for Reptile Species from RDB

Description

Retrieves a data frame containing the current valid names of reptile species along with all their recognized synonyms, as listed in The Reptile Database (RDB). Optionally, the references citing each synonym can also be included.

Usage

herpSynonyms(x,
                    getRef = FALSE,
                    showProgress = TRUE,
                    checkpoint = NULL,
                    backup_file = NULL,
                    resume = FALSE,
                    cores = max(1, parallel::detectCores() - 1))

Arguments

x

A data frame with columns species and url, typically the output of herpSpecies with getLink = TRUE.

getRef

Logical. If TRUE, includes the reference(s) in which each synonym was mentioned. Default is FALSE.

showProgress

Logical. If TRUE, prints data sampling progress. Default is TRUE.

checkpoint

backup_file

Optional. Character string specifying the path to an .rds file used to save or resume intermediate results. Required if using checkpoint or resume.

resume

Logical. If TRUE, resumes sampling from a previous run using the file provided in backup_file. Only works when cores = 1.

cores

Integer. Number of CPU cores to use for parallel processing. Default is one less than the total available cores.

Value

A data frame with columns:

species: The valid species name according to RDB.
synonym: A recognized synonym for the species.
reference (optional): If getRef = TRUE, the citation where the synonym was reported.

Note

To enable safe resuming or backup progress saving, set cores = 1. Parallel processing does not support backups.

References

Uetz, P., Freed, P., Aguilar, R., Reyes, F., Kudera, J., & Hošek, J. (eds.) (2025). The Reptile Database. Retrieved from http://www.reptile-database.org Liedtke, H. C. (2018). AmphiNom: an amphibian systematics tool. Systematics and Biodiversity, 17(1), 1–6. doi:10.1080/14772000.2018.1518935

Examples

# Filter species belonging to genus Boa
boa <- letsHerp::allReptiles[grep("^Boa\\s", letsHerp::allReptiles$species), ]


# Retrieve synonyms (without references)
boa_syn <- herpSynonyms(boa, getRef = FALSE, cores = 2)

letsHerp: An R Interface to the Reptile Database

Description

Author(s)

See Also

Example dataset: allReptiles

Description

Usage

Format

Source

Example dataset: allSynonyms

Description

Usage

Format

Source

Example dataset: allSynonymsRef

Description

Usage

Format

Source

Search The Reptile Database website (RDB): Advanced

Description

Usage

Arguments

Value

Note

Examples

Search for a Single Reptile Species in The Reptile Database (RDB)

Description

Usage

Arguments

Value

References

See Also

Examples

Retrieve Reptile Species and Taxonomic Information from RDB

Description

Usage

Arguments

Value

Note

See Also

Examples

Synchronize species names using synonym reference table

Description

Usage

Arguments

Value

Note

References

Examples

Retrieve Synonyms for Reptile Species from RDB

Description

Usage

Arguments

Value

Note

References

See Also

Examples