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

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

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

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")

Search for genera and species in the Eschmeyer's Catalog of Fishes

Description

Search for genera and species in the Eschmeyer's Catalog of Fishes

Usage

rcatfish_search(
  query,
  type,
  unavailable = FALSE,
  taxon.history = FALSE,
  resolve = FALSE,
  sleep.time = 10,
  phrase = FALSE,
  verbose = TRUE,
  common.name = FALSE,
  language = "English"
)

Arguments

Details

This function searches for genera or species in the Catalog of Fishes and returns its valid status, synonyms, and taxonomic history as well as reference numbers for the authority of the citations. By default, the function returns basic information on a taxon, such as who described it, its current taxonomic status, type locality, gender of the name, etc. If users choose taxon.history = TRUE, a detailed list of taxonomic information regarding nomenclature acts associated with the taxa is also returned. Note that the function will take longer to run, sometimes twice as long if taxon.history = TRUE.

One problem a user may encounter using the Catalog of Fishes website is that the input taxon name must match directly to a term in the database or the database will not return any information. While this remains true using this package, users can attempt to resolve names by setting resolve = TRUE. When resolve = TRUE, rcatfish_search will use the Global Names Resolver (GNR) in an attempt to resolve the name, which will then be passed to downstream function calls. This is meant to be useful, but we recommend using this option be cautious about what the GNR returns. A message will print to the screen notifying you what name the GNR resolved to be the best match and will be used, though we strongly recommend users check the resolved name does not deviate from their expectations (i.e. a homonym or similar name for a different group is not returned).

Value

Data frames. If taxon.history = TRUE, a list of two data frames. In this case, the first data frame TaxonSummary contains information on the description and current status of the taxa in the query, references to descriptions, and information on the type locality, types, family/subfamily, distribution, and habitat for species and type species gender, status, and authorities for genera searches. The second data frame, TaxonHistory contains detailed information on the taxonomic history of a taxon, such as which authorities have viewed it as a synonym or valid since its description. An itemized list describing the contents in the columns of the data returned is described below.

• Query - Character. The submitted query.

• Nominal Taxa - Character. Nominal taxonomic names.

• Author - Character. Authorship of the species/Genus description.

• DescriptionRef - Character. Eschmeyer Catalog of Fishes reference number for the genus or species description.

• DescriptionYear - Numeric. Year in which taxon was described.

• Status - Character. Current status of the nominal taxon.

• CurrentNomenclature - Character. Currently recognized taxonomic name of the taxon.

• CurrentAuthority - Character. Current authority for the valid name of the taxon.

• Holotype - Character. Catalog number of the holotype.

• Paratype - Character. Catalog number(s) of the paratypes.

• Lectotype - Character. Catalog number of the lectotype.

• Paralectotype - Character. Catalog number(s) of the paralectotype.

• Neotype - Character. Catalog number of the neotype.

• Syntype - Character. Catalog number(s) of the syntypes.

• NoTypes - Character. Specifies entries with currently no known types.

• TypeLocality - Character. Type locality of the taxon.

• Family - Character. Family the taxon belongs to.

• Subfamily - Character. Subfamily the taxon belongs to.

• Distribution - Character. Distribution of the species.

• Fresh - Numeric. Binary presence (1) or absence (0) in freshwater.

• Brackish - Numeric. Binary presence (1) or absence (0) in brackish water.

• Marine - Numeric. Binary presence (1) or absence (0) in marine water.

• IUCNYear - Numeric. Year in which IUCN status was assessed.

• IUCNStatus - Character. Status in the IUCN list of threatened species.

• NomenclatureNotes - Character. Descriptive tags identifying status as a homonym, hybrid, nomen protectum, etc.

• TypeSpecies - Character. Type Species of the genus.

• Gender - Character. Gender of the taxon.

• TypeBy - Character. Type designation.

• Notes - Character. Any notes related to the taxon or taxonomic history (e.g. treated as a subspecies, availability of name, authorship issues, etc.).

• AsSubgenus - Character. If the taxon was described as a subgenus of another genus, provides information on the genus.

• Infrasubspecific - Character. Infrasubspecific designation if it exists.

Author(s)

Samuel R. Borstein, Brandon E. Dominy, Brian C. O'Meara

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

http://gnrd.globalnames.org/api http://gnrd.globalnames.org/

Examples

#Note that for Windows OS, OpenSSL must be used as a backend for curl. 
#Please see vignette on how to do this with vignette('rcatfish').

#Search for Abactochromis and return taxon history

if((.Platform$OS.type == "windows") & (grepl(pattern = "\\(OpenSSL", 
  curl::curl_version()$ssl_version) == TRUE)){
cat("openSSL backend for curl is required for the Windows version of this package, but it not 
detected as being active. Please see the vignette on how to configure curl with openSSL for this
function to work. You can access the vignette with the following: vignette('rcatfish').")
}else{
my.search <- rcatfish_search(type = "Species", query = "Abactochromis", 
  taxon.history = FALSE, resolve = FALSE, sleep.time = 0)
}

#Search for the genera Astatheros and Gasteropelecidae

if((.Platform$OS.type == "windows") & (grepl(pattern = "\\(OpenSSL", 
  curl::curl_version()$ssl_version) == TRUE)){
cat("openSSL backend for curl is required for the Windows version of this package, but it not 
detected as being active. Please see the vignette on how to configure curl with openSSL for this
function to work. You can access the vignette with the following: vignette('rcatfish').")
}else{
  my.search <- rcatfish_search(type = "Genus", query = c("Astatheros","Gasteropelecidae"), 
    taxon.history = TRUE, resolve = FALSE, sleep.time = 10)
  }

#Perform a species search for two different taxa

if((.Platform$OS.type == "windows") & (grepl(pattern = "\\(OpenSSL", 
  curl::curl_version()$ssl_version) == TRUE)){
cat("openSSL backend for curl is required for the Windows version of this package, but it not 
detected as being active. Please see the vignette on how to configure curl with openSSL for this
function to work. You can access the vignette with the following: vignette('rcatfish').")
}else{
my.search<-rcatfish_search(type = "Species", query = c("Ctenopharynx",
  "Pseudocrenilabrus multicolor victoriae"), taxon.history = TRUE, resolve = FALSE, 
  sleep.time = 10)
  }

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

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

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()