Help for package letsRept

Title:

An Interface to the Reptile Database

Version:

1.0.0

URL:

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

BugReports:

https://github.com/joao-svalencar/letsRept/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

LazyDataCompression:

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

VignetteBuilder:

knitr

Config/testthat/edition:

NeedsCompilation:

Packaged:

2025-08-18 23:49:05 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-08-22 17:40:09 UTC

letsRept: An Interface to the Reptile Database

Description

The letsRept 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 letsRept::reptSpecies() 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 letsRept::reptSynonyms(letsRept::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 letsRept::reptSynonyms(letsRept::allReptiles)

Example dataset: letsRept_ReptTraits

Description

This dataset is a version of ReptTraits (Oskyrko et al. 2024) with two additional columns.

Usage

letsRept_ReptTraits

Format

A dataframe with 12,060 rows and 50 variables. The first three columns are:

species: Species name as in the original ReptTraits database
RDB: Current valid name according to the May 2025 version of the Reptile Database
nomenclature.status: Status from reptSync and reptSplitCheck. Additional status are: "extinct" and "manual_fix"

Source

The original data source is from Oskyrko et al. (2024); The new nomenclature in the RDB column was collected from the Reptile Database website https://reptile-database.reptarium.cz using functions reptSync and reptSplitCheck

Example dataset: letsRept_SquamBase

Description

This dataset is a version of SquamBase (Meiri, 2024) with two additional columns.

Usage

letsRept_SquamBase

Format

A dataframe with 11,744 rows and 86 variables. The first three columns are:

species: Species name as in the original SquamBase database
RDB: Current valid name according to the May 2025 version of the Reptile Database
nomenclature.status: Status from reptSync and reptSplitCheck. Additional status are: "extinct" and "manual_fix"

Source

The original data source is from Meiri (2024); The new nomenclature in the RDB column was collected from the Reptile Database website https://reptile-database.reptarium.cz using functions reptSync and reptSplitCheck

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 reptSpecies, 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

reptAdvancedSearch(
  higher = NULL,
  genus = NULL,
  year = NULL,
  common_name = NULL,
  synonym = NULL,
  location = NULL,
  verbose = TRUE,
  exact = FALSE
)

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.

verbose

Logical. To be passed to reptSpecies() in the case of a provided synonym corresponds unambiguously to a valid species. If TRUE, prints status messages and species information in the console. Default is TRUE.

exact

Logical. To return outputs that matches exactly the searched term (e.g., avoid returning genus "Boaedon" when searching for "Boa"). Default is FALSE.

Value

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

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

Note

The argument exact does not work properly for searches using logical arguments (e.g. AND/OR). If you want to force an exact match (e.g., "Boa" as a phrase) with multiple terms (e.g., "Boa OR Apostolepis"), you must manually include quotes in the input string, e.g., "\"Boa\" OR Apostolepis".

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


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

Compare a Species nomenclature with Reptile Database Data

Description

This function compares a list of species (x) with another list (y), typically from the Reptile Database (RDB). If y is not provided, it defaults to using the internal object allReptiles. The function returns species that are either unmatched ("review") or matched with the RDB list, or both.

Usage

reptCompare(x = NULL, y = NULL, filter = NULL)

Arguments

x

A character vector or a data frame containing a column named species with species names to be compared.

y

Optional. A character vector or a data frame containing a column named species to compare against. Defaults to the internal object allReptiles.

filter

Optional. A character string. If "review", returns only unmatched species. If "matched", returns only matched species. If NULL (default), returns a data frame of both.

Value

A character vector (if filter is "review" or "matched"), or a data frame with columns:

species: Species names from x
status: Comparison result: "review" or "matched"

Examples

my_species <- data.frame(species = c("Boa constrictor", "Pantherophis guttatus", "Fake species"))
reptCompare(my_species)
reptCompare(my_species, filter = "review")
reptCompare(my_species, filter = "matched")

Extract references from the Reptile Database

Description

Extract references from the Reptile Database

Usage

reptRefs(x = NULL, getLink = TRUE)

Arguments

x

A binomial species name (e.g., "Boa constrictor").

getLink

Logical; if TRUE, also returns associated links to references.

Value

A character vector of references (if getLink = FALSE), or a data frame with columns reference and link.

Examples


df <- reptRefs("Apostolepis adhara")

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

reptSearch(binomial=NULL, getRef=FALSE, verbose=TRUE)

Arguments

binomial

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

getRef

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 getRef = 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


reptSearch("Boa constrictor")
reptSearch("Boa constrictor", getRef = 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

reptSpecies(
  url = NULL,
  showProgress = TRUE,
  dataList = NULL,
  taxonomicInfo = FALSE,
  fullHigher = FALSE,
  getLink = FALSE,
  cores = max(1L, floor(parallel::detectCores()/2)),
  checkpoint = NULL,
  backup_file = NULL
)

Arguments

url

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

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 reptSynonyms). Default is FALSE.

cores

Integer. Number of CPU cores to use for parallel processing. Default is half of available cores (min = 1).

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 <- reptSpecies(reptAdvancedSearch(genus = "Boa"),
                                      taxonomicInfo = TRUE, 
                                      cores = 2)

Check for potential taxonomic splits in a query

Description

Check for potential taxonomic splits in a query

Usage

reptSplitCheck(
  x,
  pubDate = NULL,
  includeAll = FALSE,
  verbose = TRUE,
  cores = max(1L, floor(parallel::detectCores()/2)),
  showProgress = TRUE
)

Arguments

x

A character vector of species names to check. Usually from a database.

pubDate

Integer. An year (e.g., 2019) used as a reference date from when to check potential taxonomic split

includeAll

Logical; If TRUE, include all species described since pubDate regardless of if it is already included in the queried species list. Default is FALSE

verbose

Logical; If TRUE, prints progress messages. Default is TRUE.

cores

Integer. Number of CPU cores to use for parallel processing. Default is half of available cores (min = 1).

showProgress

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

Value

A data frame with the following columns:

query: the original input names.
RDB: the best-matching valid names according to The Reptile Database.
status: a status label indicating the result of the match ("up_to_date", "updated", "ambiguous", or "not_found").

Examples

query <- c(
"Atractus dapsilis",
"Atractus trefauti",
"Atractus snethlageae",
"Tantilla melanocephala",
"Oxybelis aeneus",
"Oxybelis rutherfordi",
"Vieira-Alencar authoristicus",
"Oxybelis aeneus",
"Bothrops pauloensis")


result <- reptSplitCheck(x=query,
                        pubDate = 2019,
                        cores = 2,
                        showProgress = FALSE)

result <- reptSplitCheck(x=query,
                        pubDate = 2019,
                        cores = 2,
                        showProgress = FALSE,
                        includeAll = TRUE)

Summarize Taxonomic Composition

Description

This function summarizes the taxonomic content of a species list, typically an object created with reptSpecies with higher taxa information. If no object is provided it summarizes the internal dataset allReptiles.

Usage

reptStats(
  x = letsRept::allReptiles,
  verbose = FALSE,
  order = NULL,
  suborder = NULL,
  family = NULL,
  genus = NULL
)

Arguments

x

A data frame containing reptile taxonomy data. Defaults to the internal dataset letsRept::allReptiles.

verbose

Logical. If TRUE, returns a list of taxon names by rank. If FALSE (default), returns a summary table of counts.

order

Optional. A character string specifying a taxonomic order to filter by (e.g., "Squamata").

suborder

Optional. A character string specifying a taxonomic suborder to filter by (e.g., "Serpentes").

family

Optional. A character string specifying a family to filter by (e.g., "Elapidae").

genus

Optional. A character string specifying a genus to filter by (e.g., "Micrurus").

Details

The output can be either a compact table with taxonomic unit counts or a verbose list of names within each rank.

Optional arguments allow the user to filter the dataset by specific taxonomic levels (e.g., order, suborder, family, genus) before summarizing.

Value

Either a named list of taxonomic units (verbose = TRUE) or a data frame with taxonomic ranks and the number of units per rank (verbose = FALSE).

Examples

# Basic usage with default dataset
reptStats()

# Verbose summary listing elements in each rank
reptStats(verbose = TRUE)

# Filter by family and return summary table
reptStats(family = "Elapidae")

# Combine filters and return list
reptStats(suborder = "Serpentes", verbose = TRUE)

Synchronize Species Names Using The Reptile Database

Description

Queries a list of species names through reptSearch() and returns a data frame with the currently valid names and taxonomic status for each input.

Usage

reptSync(
  x,
  solveAmbiguity = TRUE,
  cores = max(1L, floor(parallel::detectCores()/2)),
  showProgress = TRUE,
  getLink = FALSE
)

Arguments

x

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

solveAmbiguity

Logical. If TRUE, attempts to resolve ambiguous names by retrieving all possible valid species to which the query may refer. Default is TRUE.

cores

Integer. Number of CPU cores to use for parallel processing. Default is half of available cores (min = 1).

showProgress

Logical. If TRUE, displays progress updates during processing. Default is TRUE.

getLink

Logical. If TRUE, retrieves searched species URLs. Defaults if FALSE.

Value

A data frame with the following columns:

query: the original input names.
RDB: the best-matching valid names according to The Reptile Database.
status: a status label indicating the result of the match ("up_to_date", "updated", "ambiguous", or "not_found").
url: Optional, if getLink = TRUE returns the URL of the species page retrieved for each match, or a list of possible matches if ambiguous.

Note

reptSync() does not make authoritative taxonomic decisions. It matches input names against currently accepted names in The Reptile Database (RDB). A name marked as "up_to_date" may still refer to a taxon that has been split, and thus may not reflect the most recent population-level taxonomy.

For ambiguous names, the url field may contain multiple links corresponding to all valid species to which the queried name is considered a synonym.

See package vignettes for more details.

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

query <- c("Vieira-Alencar authoristicus", "Boa atlantica", "Boa diviniloqua", "Boa imperator")


reptSync(x = query, cores = 2)

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

reptSynonyms(
  x,
  getRef = FALSE,
  showProgress = TRUE,
  checkpoint = NULL,
  backup_file = NULL,
  resume = FALSE,
  cores = max(1L, floor(parallel::detectCores()/2))
)

Arguments

x

A character string with a species binomial or a data frame with columns species and url, typically the output of reptSpecies 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 half of available cores (min = 1).

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 <- letsRept::allReptiles[grep("^Boa\\s", letsRept::allReptiles$species), ]


# Retrieve synonyms (without references)
boa_syn <- reptSynonyms(boa, getRef = FALSE, cores = 2)
Bconstrictor_syn <- reptSynonyms(x = "Boa constrictor")

Printing reptSync and reptSplitCheck outcomes in a tidy way

Description

Prints the data frame derived from reptSync or reptSplitCheck in a tidy way. Optionally, it filters the data frame for species with unresolved nomenclature only.

Usage

reptTidySyn(df, filter = NULL)

Arguments

df

The data frame derivated from reptSync

filter

Logical. If TRUE will print only the species entries with unresolved nomenclature (e.g.: ambiguous or not_found). Default is TRUE

Value

Invisibly returns NULL. Used for side-effect printing only.

Examples

df <- data.frame(
  species = c("Genus epithet 1", 
              "Genus epithet 2",
              "Genus epithet 3",
              "Genus epithet 4",
              "Genus epithet 5"),
  synonyms = c("Genus epithet 1.1; Genus epithet 1.2",
                "Genus epithet 2",
                "Genus epithet 3",
                "Not found",
                "Genus epithet 5.1; Genus epithet 5.2; Genus epithet 5.3"),
  status = c("ambiguous", 
             "updated",
             "up_to_date",
             "not_found",
             "ambiguous"),
  stringsAsFactors = FALSE
)
reptTidySyn(df, filter = c("ambiguous", "not_found"))

letsRept: An 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

Example dataset: letsRept_ReptTraits

Description

Usage

Format

Source

Example dataset: letsRept_SquamBase

Description

Usage

Format

Source

Search The Reptile Database website (RDB): Advanced

Description

Usage

Arguments

Value

Note

Examples

Compare a Species nomenclature with Reptile Database Data

Description

Usage

Arguments

Value

Examples

Extract references from the Reptile Database

Description

Usage

Arguments

Value

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

Check for potential taxonomic splits in a query

Description

Usage

Arguments

Value

Examples

Summarize Taxonomic Composition

Description

Usage

Arguments

Details

Value

Examples

Synchronize Species Names Using The Reptile Database

Description

Usage