Package 'rcatfish'

Title: An R Interface to the California Academy of Sciences Eschmeyer's Catalog of Fishes
Description: Accesses the California Academy of Sciences Eschmeyer's Catalog of Fishes in R using web requests. The Catalog of fishes is the leading authority in fish taxonomy. Functions in the package allow users to search for fish taxa and valid names, retrieve taxonomic references, retrieve monthly taxonomic changes, obtain natural history collection information, and see the number of species by taxonomic group. For more information on the Catalog: Fricke, R., Eschmeyer, W. N. & R. van der Laan (eds) 2025. ESCHMEYER'S CATALOG OF FISHES <https://researcharchive.calacademy.org/research/ichthyology/catalog/fishcatmain.asp>.
Authors: Samuel R. Borstein [aut, cre], Brandon Dominy [aut], Brian O'Meara [aut]
Maintainer: Samuel R. Borstein <[email protected]>
License: GPL (>= 2)
Version: 1.0.2
Built: 2026-05-20 09:00:28 UTC
Source: https://github.com/cran/rcatfish

Help Index


Access the Eschmeyer's Catalog of Fishes Classification

Description

This function is used to access the Eschmeyer's Catalog of Fishes classification of fishes

Usage

rcatfish_classification()

Details

This function displays the classification tab of Eschmeyer's Catalog of Fishes. The data are returned in a tabular framework that progresses from most to least inclusive from left to right. The function will return the class, order, suborder, family, subfamily, author, and common name of the family or subfamily.

Value

A dataframe with seven columns. From left to right (and most inclusive to least inclusive), the columns represent class, order, suborder, family, subfamily, author, and the common name of the family or subfamily.

Author(s)

Samuel R. Borstein

References

van der Laan, R., Fricke, R. & Eschmeyer, W.N. (Year Accessed). Eschmeyer's Catalog of Fishes: Classification. https://www.calacademy.org/scientists/catalog-of-fishes-classification/.

Examples

#Obtain the Eschmeyer's Catalog of Fishes Classification

myClassification <- rcatfish_classification()

Accesses the Eschmeyer's Catalog of Fishes Guide to Fish Collections

Description

Accesses the Eschmeyer's Catalog of Fishes Guide to Fish Collections

Usage

rcatfish_collections(
  query = NULL,
  abbreviation = NULL,
  country = NULL,
  phrase = FALSE,
  sleep.time = 10,
  verbose = TRUE
)

Arguments

query

Character Vector of search terms to search for. Default is NULL.

abbreviation

Character vector containing the musuem collection code(s). Default is NULL.

country

Character vector of country names to search for. Default is NULL.

phrase

Logical. Should query be passed as a quoted phrase (e.g. "Museum of Zoology"). Default is FALSE.

sleep.time

Numeric. Time in seconds to sleep between query calls to the California Academy of Sciences page. This is set by default to 10 seconds, which is in their robots.txt. Adjust at your own risk.

verbose

Logical. Should query progress be messaged to the screen? Default is TRUE.

Details

This function retrieves and parses natural history collection data from the Eschmeyer's Catalog of Fishes. Returned information includes the collection abbreviation, country, alternate abbreviations, old and new collection names, websites and databases associated with the collection, remarks, and publications associated with the collection.

It is important that search criteria match exactly how they are on the Catalog of Fishes, otherwise data will not be found (case must match, spelling, etc.). Users wishing to query more than one query mixed with either a country or abbreviation should note that all parameters must be of equal length, so if searching two queries both in U.S.A., the country should be supplied twice (see the final example in the examples below).

Value

Data frame, in which each row is a natural history collection and each column the corresponding collection information (see itemized list below).

  • Code - Character. Natural history collection abbreviation code.

  • Name - Character. Full name of the natural history collection.

  • Country - Character. Country of the natural history collection.

  • OtherAbbr - Character. Other and previous abbreviation(s) used for that natural history collection.

  • OldName - Character. Previous name(s) used by the natural history.

  • NewName - Character. New name(s) of the natural history collection.

  • WebPage - Character. URL for the webpage of the natural history collection if one exists.

  • CollectionDB - Character. URL for accessing the collection database of the natural history collection if one exists.

  • TypesDB - Character. URL for accessing the type database of the natural history collection if one exists.

  • Remarks - Character. Additional information about the natural history collection (e.g. includes specimens from other collections, closed, etc.).

  • Publications - Character. Comma separated character vector of Eschmeyer's Catalog of Fishes reference numbers citing the natural history collection.

Author(s)

Samuel R. Borstein

References

Fricke, R. & Eschmeyer, W.N. (Year Accessed). Eschmeyer's Catalog of Fishes: Guide to Fish Collections. https://researcharchive.calacademy.org/research/ichthyology/catalog/collections.asp.

Examples

#Search Museum Code For UMMZ (University of Michigan Museum of Zoology)
my.collections <- rcatfish_collections(abbreviation = "UMMZ", country = NULL, 
query = NULL, verbose = TRUE)

#Search For Collections in France
my.collections <- rcatfish_collections(abbreviation = NULL, country = "France", query = NULL)
#Search For Collections in The United States that are in Illinois
my.collections <- rcatfish_collections(abbreviation = NULL, country = "U.S.A.", query = "Illinois")
#Search For Collections in the United States that are in California & Alaska.
my.collections <- rcatfish_collections(abbreviation = NULL, country = rep("U.S.A.",2), 
query = c("California","Alaska"), sleep.time = 10)
#Search for Collections with Museum of Zoology in the name
my.collections <- rcatfish_collections(query = "Museum of Zoology", phrase = TRUE)

Access the Eschmeyer's Catalog of Fishes Glossary

Description

This function is used to access the Eschmeyer's Catalog of Fishes Glossary.

Usage

rcatfish_glossary()

Details

This function displays the Glossary tab of Eschmeyer's Catalog of Fishes. The glossary contains definitions for various terms that are important to the discussion of taxonomy and are mentioned throughout the database.

Value

A dataframe with three columns. Some terms have sub-terms (e.g. synonym will have definitions for junior, objective, and subjective in addition to defining synonym itself). The first column represents the name of the main term, the second column represents the name of sub-terms, and the final column provides the definition for these terms.

Author(s)

Samuel R. Borstein

References

van der Laan, R., Fricke, R. & Fong, J. (Year Accessed). Eschmeyer's Catalog of Fishes: Glossary. https://www.calacademy.org/scientists/catalog-of-fishes-glossary/.

Examples

# Obtain the Eschmeyer's Catalog of Fishes Glossary
myGlossary <- rcatfish_glossary()

Search for journals in the Catalog of Fishes

Description

Search for journals in the Catalog of Fishes

Usage

rcatfish_journals(query, phrase = FALSE, sleep.time = 10, verbose = TRUE)

Arguments

query

Character vector to search for.

phrase

Logical. Should query be passed as a quoted phrase (e.g. "Journal of Zoology"). Default is FALSE.

sleep.time

Numeric. Time in seconds to sleep between query calls to the California Academy of Sciences page. This is set by default to 10 seconds, which is in their robots.txt. Adjust at your own risk.

verbose

Logical. Should query progress be messaged to the screen? Default is TRUE.

Details

This function returns information on the journals cited in the Eschmeyer's Catalog of Fishes.

Value

Two column data frame. The first column contains the name of the query and the second column contains information on the journal.

Author(s)

Samuel R. Borstein

References

Fricke, R. & Eschmeyer, W.N. (Year Accessed). Eschmeyer’s Catalog of Fishes: Journals. https://researcharchive.calacademy.org/research/ichthyology/catalog/journals.asp

Examples

my.journals<-rcatfish_journals(query="Cichlid")
my.journals<-rcatfish_journals(query="Evolution")

Search for references in Eschmeyer's Catalog of Fishes

Description

Search for references in the Catalog of Fishes by keyword or reference number.

Usage

rcatfish_references(query, type, sleep.time = 10, verbose = TRUE)

Arguments

query

Either a character vector of keywords to search for or a numeric vector with reference numbers

type

Either "RefNo" if searching for a reference number or "keyword" if searching by keywords reference numbers.

sleep.time

Numeric. Time in seconds to sleep between query calls to the California Academy of Sciences page. This is set by default to 10 seconds, which is in their robots.txt. Adjust at your own risk.

verbose

Logical. Should query progress be messaged to the screen? Default is TRUE.

Details

This function searches Catalog of Fishes references. Users can supply either a keyword (i.e. cichlidae, revision, etc.) or a reference number to retrieve reference information.

Value

A data.frame containing columns for the query, reference number, and full citation.

Author(s)

Samuel R. Borstein, Brian C. O'Meara

References

Fricke, R. (Year Accessed). Eschmeyer's Catalog of Fishes: References. https://researcharchive.calacademy.org/research/ichthyology/catalog/fishcatmain.asp

Examples

#Perform a search of references that contain the keyword Amphilophus.
my.refs<-rcatfish_references(query = "Amphilophus", type = "keyword")
#Perform a search of references based on a Catalog of Fishes reference number
my.refs<-rcatfish_references(query = 2787, type = "RefNo")

Find number of available fish names, number of valid species, and number of descriptions in the last 10 years by family or subfamily

Description

This function retrieves and parses data on the number of genera and species per family from the Eschmeyer's Catalog of Fishes. It returns a table containing the number of genera and species that are available, valid, and described in the last 10 years in its columns. Each row represents either a class, order, family, or subfamily, so some columns for higher taxonomic groups may have NA for lower taxonomic groups (e.g. if you Search for Cypriniformes, the row containing Cypriniformes will have NA for family and subfamily as it is above those taxonomic levels).

Given the function reads in the page containing the table, for speed, it is highly recommended that if a user wishes to obtain information on numerous orders, families, or subfamilies that they pass them in as a single query. To do this, see the last example.

Usage

rcatfish_species_by(query, verbose = TRUE)

Arguments

query

A character vector of taxa to search for. For users wishing to obtain the information for all fishes please query "Totals".

verbose

Logical. Should query progress be messaged to the screen? Default is TRUE.

Value

A list with each element containing a data frame for each query. List elements are named by the queried taxa. The list contains information on the number of genera and species available, valid, and described in the last 10 years. An itemized list describing the contents in the columns of the data frame(s) returned is described below. #'

  • Class - Character. Taxonomic class.

  • Order - Character. Taxonomic order.

  • Family - Character. Taxonomic family

  • Subfamily - Character. Taxonomic subfamily.

  • Available.Genera - Integer. Number of available genera for the taxonomic rank.

  • Valid.Genera - Integer. Number of valid genera for the taxonomic rank.

  • Genera.Last.Ten.Years - Integer. Number of genera described over the past ten years for the taxonomic rank.

  • Available.Species - Integer. Number of available species for the taxonomic rank.

  • Valid.Species - Integer. Number of valid species for the taxonomic rank.

  • Species.Last.Ten.Years - Integer. Number of species described over the past ten years for the taxonomic rank.

Author(s)

Samuel R. Borstein

References

Fricke, R., Eschmeyer, W.N. & Fong J.D. (Year Accessed). Eschmeyer’s Catalog of Fishes: Species by family/subfamily in the Catalog of Fishes. https://researcharchive.calacademy.org/research/ichthyology/catalog/SpeciesByFamily.asp.

Examples

#Search for the number of described Cypriniformes
MySearch <- rcatfish_species_by(query = "Cypriniformes") 
#Obtain the total number of genera and species available, valid, and described in the last 10 years
CofF_totals <- rcatfish_species_by(query = "Totals")
#Search for more than one family
MySearch <- rcatfish_species_by(query = c("Cichlidae","Embiotocidae"))

Access catalog changes and additions

Description

This function is used to access the Eschmeyer's Catalog of Fishes Summary of Changes and Additions.

Usage

rcatfish_updates(
  changes = TRUE,
  author.changes = TRUE,
  spell.changes = TRUE,
  added.genera = TRUE,
  added.species = TRUE
)

Arguments

changes

Logical. Should the function return the table of changes to the catalog? Default is TRUE.

author.changes

Logical. Should the function return the table of author and year changes to the catalog? Default is TRUE.

spell.changes

Logical. Should the function return the table of spelling changes to the catalog? Default is TRUE.

added.genera

Logical. Should the function return genera added to the catalog? Default is TRUE.

added.species

Logical. Should the function return species added to the catalog? Default is TRUE.

Details

This function displays the information on the "Changes and Additions" tab of Eschmeyer's Catalog of Fishes. The catalog updates this information monthly with changes to the catalog, new genus information, and new species information. Each updates removes the last month's information, so data obtained through this function is only representative of the changes and additions made since the previous update.

Value

A named list. Names include UpdateDate, Changes, AuthorshipChanges, AddedGenera, and AddedSpecies. UpdateDate will always be returned and is a character string of the date the catalog was updated. Changes, AddedGenera, and AddedSpecies summarize changes to the catalog, changes to authorship information, genera added to the catalog, and species added to the catalog respectively. The elements returned are based on which parameters are set to TRUE. An itemized list describing the contents in the columns of the data returned is described below.

  • Original.Taxon - Character. The original taxonomic name in the database.

  • Was - Character. Previous status of the taxon in the database.

  • Previous.Taxon - Character. Previous taxonomic name in the database.

  • Now - Character. Current status of the taxon in the database following the update.

  • Current.Taxon - Character. Current taxonomic name in the database for the taxon following the update.

  • Taxon - Character. Taxon (of any rank) whose citation was updated.

  • Previous.Author - Character. Authorship information of the citation before the update.

  • Current.Author - Character. Authorship information of the citation following the update.

  • Species.Name - Character. Current taxonomic name in the database for the taxon following the update.

  • Genus.Name - Character. Name of the new genus added to the database following the update.

  • Authors - Character. Authorship for new taxonomic names added to the database following the update.

  • Year - Character. Year for new taxonomic names added to the database following the update.

  • Region - Character. Region new taxa added to the database are known to occur in.

  • Was.Spelled - Character. Previous spelling of the taxon in the database.

  • Now.Spelled - Character. Revised spelling of the taxon in the database.

Author(s)

Brandon E. Dominy, Samuel R. Borstein

References

Fricke, R., van der Laan, R. & Fong, J.D. (Year Accessed). Eschmeyer’s Catalog of Fishes: Changes and Additions. https://researcharchive.calacademy.org/research/ichthyology/catalog/ChangeSummary.asp.

Examples

# return all available data
myList <- rcatfish_updates(changes = TRUE, added.genera = TRUE, added.species = TRUE)

Retrieve the current version Number of the Eschmeyer's Catalog of Fishes Being Used

Description

Returns the current version of Catalog of Fishes being used in the R session

Usage

rcatfish_version()

Value

Character Vector length of one with the Catalog of Fishes version

Author(s)

Samuel R. Borstein

References

Fricke, R., Eschmeyer, W.N. & van der Laan, R. (Year Accessed). Eschmeyer's Catalog of Fishes: Genera, Species, References. https://researcharchive.calacademy.org/research/ichthyology/catalog/fishcatmain.asp.

Examples

#' my.version <- rcatfish_version()