rcatfish_search: Search for genera and species in the Eschmeyer's Catalog of...
In rcatfish: An R Interface to the California Academy of Sciences Eschmeyer's Catalog of Fishes
View source: R/rcatfish_search.R
rcatfish_search R Documentation
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
query
Character or Character Vector containing the name or names of the taxon to search. Note, you can not mix common and scientific names as a query.
type
Character either "Genus" or "Species" to search for genera and species respectively.
Note that only one of these options can be chosen.
unavailable
Logical. Should the query be run with unavailable names include? Default is FALSE.
taxon.history
Should a detailed history of taxonomic changes per taxa be returned (i.e. synonymization, raised to validity, authority, etc.). Default is FALSE.
resolve
Logical. If a match for the query isn't found, should an attempt be made to resolve the name using taxize?
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.
phrase
Logical. Should query be passed as a quoted phrase (e.g. "Synonym of Cyprinus carpio"). Default is FALSE.
verbose
Logical. Should query progress be messaged to the screen? Default is TRUE.
common.name
Is the query a common name? Common names will be converted to scientific names for searching through rfishbase. Note, you can not mix common and scientific names as a query. This likely will only work for species searches. Default is FALSE.
language
Language to perform common name search. Default is English.
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)
}
rcatfish documentation built on Feb. 3, 2026, 5:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/rcatfish_search.R
| rcatfish_search | R Documentation |
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
query |
Character or Character Vector containing the name or names of the taxon to search. Note, you can not mix common and scientific names as a query. |
type |
Character either "Genus" or "Species" to search for genera and species respectively. Note that only one of these options can be chosen. |
unavailable |
Logical. Should the query be run with unavailable names include? Default is FALSE. |
taxon.history |
Should a detailed history of taxonomic changes per taxa be returned (i.e. synonymization, raised to validity, authority, etc.). Default is FALSE. |
resolve |
Logical. If a match for the query isn't found, should an attempt be made to resolve the name using taxize? |
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. |
phrase |
Logical. Should query be passed as a quoted phrase (e.g. "Synonym of Cyprinus carpio"). Default is FALSE. |
verbose |
Logical. Should query progress be messaged to the screen? Default is TRUE. |
common.name |
Is the query a common name? Common names will be converted to scientific names for searching through rfishbase. Note, you can not mix common and scientific names as a query. This likely will only work for species searches. Default is FALSE. |
language |
Language to perform common name search. Default is English. |
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)
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.