diff --git a/man/SP2000-package.Rd b/man/SP2000-package.Rd index 0919be6..e0fe755 100644 --- a/man/SP2000-package.Rd +++ b/man/SP2000-package.Rd @@ -15,24 +15,26 @@ This package is designed for mining the checklist of animals, plants, fungi and \examples{ \dontrun{ -#Note: You need to apply for the apiKey +# Note: You need to apply for the apiKey to run search_* functions of this package. -##Load "SP2000" +## Load "SP2000" library('SP2000') -##Set your key +## Set your key set_search_key <- "your apiKey" -##Search family IDs via family name, supports Latin and Chinese names +## Search family IDs via family name, supports Latin and Chinese names familyid <- search_family_id(query = "Anguillidae") -##Search taxon IDs via familyID ,scientificName and commonName +## Search taxon IDs via familyID ,scientificName and commonName -taxonid <- search_taxon_id(query = familyid$familyIDs,name = "familyID") +query <- familyid$Anguillidae$data$record_id + +taxonid <- search_taxon_id(query = query,name = "familyID") queries = c("Anguilla marmorata","Anguilla japonica", "Anguilla bicolor","Anguilla nebulosa", @@ -40,29 +42,30 @@ queries = c("Anguilla marmorata","Anguilla japonica", search_taxon_id(query = queries,name = "scientificName") -#Download detailed lists via species or infraspecies ID +## Download detailed lists via species or infraspecies ID + +query <- taxonid[["3851c5311bed46c19529cb155d37aa9b"]][["data"]][["namecode"]] -checklist1 <- search_checklist(query = taxonid$taxonIDs) +checklist <- search_checklist(query = query) -checklist1 <- list_df(checklist1,db = "colchina") -##Get Catalogue of Life Global checklist via species name and id +## Get Catalogue of Life Global checklist via species name and id -checklist2 <- get_col_global(query = queries, option = "name") +x <- get_col_global(query = "Anguilla", response = "full") -str(checklist2) +str(x) -checklist2 <- list_df(checklist2,db = "colglobal") +x[["Anguilla"]][["meta"]][["total_number_of_results"]] [1] -##Find synonyms via species name from Catalogue of Life Global +## Find synonyms via species name from Catalogue of Life Global find_synonyms(query = queries) -##Search Catalogue of Life Taiwan checklist +## Search Catalogue of Life Taiwan checklist -get_col_taiwan(query = "Anguilla",tree = "name",option = "contain") +get_col_taiwan(query = "Anguillidae", level = "family") -##Query Redlist of Chinese Biodiversity +## Query Redlist of Chinese Biodiversity get_redlist_china(query = "Anguilla", option = "Scientific Names") @@ -70,7 +73,7 @@ get_redlist_china(query = "Anguilla", option = "Scientific Names") } \references{ -Ding LY, Li H, Tao J, Zhang JL, Huang MR, Yang K, Wang J, He DM, Ding CZ (2020) SP2000: A package written in R and Python for downloading catalogue of life. Biodiversity Science. +Ding LY, Li H, Tao J, Zhang JL, Huang MR, Yang K, Wang J, He DM, Ding CZ (2020) SP2000: An open source R package for querying the catalogue of life. Biodiversity Science. https://cran.r-project.org/package=SP2000 diff --git a/man/api_key.Rd b/man/api_key.Rd index 1080325..3cb3a01 100644 --- a/man/api_key.Rd +++ b/man/api_key.Rd @@ -17,6 +17,9 @@ when the function is called. \description{ Apply for the apiKey variable to be used by all search_* functions, register for \url{http://sp2000.org.cn/api/document} and use an API key. This function allows users to set this key. +Note: The daily API visits of ordinary users are 2000, +If you want to apply for increasing the daily API request limit, +please fill in the application form \url{http://col.especies.cn/doc/API.docx} and send an email to \email{SP2000CN@ibcas.ac.cn} entitled "Application for increasing API Request Times". } \examples{ \dontrun{ @@ -25,3 +28,6 @@ set_search_key("your apiKey") } } +\author{ +Liuyong Ding \email{ly_ding@126.com} +} diff --git a/man/download_col_china.Rd b/man/download_col_china.Rd index fac1684..321b285 100644 --- a/man/download_col_china.Rd +++ b/man/download_col_china.Rd @@ -11,7 +11,7 @@ download_col_china(version = "2020", OS = "MacOS", dir = tempdir()) \item{OS}{\code{character} Supported operating system,c("MacOS", "Ubuntu" ,"Windows"),the default value is "MacOS".} -\item{dir}{a non-empty character vector giving the directory name by user,the default value is dir = tempdir(),see [tempdir()] for details.} +\item{dir}{a non-empty character vector giving the directory name by user,the default value is dir = tempdir(),see \code{\link{tempdir}} for details.} } \value{ URL @@ -29,5 +29,5 @@ download_col_china(version = "2020",OS = "MacOS", dir = dir) } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/find_synonyms.Rd b/man/find_synonyms.Rd index c962832..cf11d18 100644 --- a/man/find_synonyms.Rd +++ b/man/find_synonyms.Rd @@ -7,9 +7,9 @@ find_synonyms(query, mc.cores = 2) } \arguments{ -\item{query}{\code{character} species name,The function is similar to [get_col_global()].} +\item{query}{\code{character} species name,The function is similar to \code{\link{get_col_global}}.} -\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see [mclapply()] for details.} +\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see \code{\link{mclapply}} for details.} } \value{ object @@ -21,13 +21,17 @@ Find synonyms via species name from Catalogue of Life Global. Visit the website \url{http://webservice.catalogueoflife.org/col/webservice} for more details. } \examples{ -\donttest{ +\dontrun{ ##Get Catalogue of Life Global checklist via species name -x <- get_col_global(query = c("Anguilla marmorata","Anguilla japonica", +x1 <- get_col_global(query = c("Anguilla marmorata","Anguilla japonica", "Anguilla bicolor","Anguilla nebulosa", "Anguilla luzonensis"), option = "name") -str(x) +str(x1) + +##full queries +x2 <- get_col_global(query = "Anguilla", response = "full") + ##Find synonyms via species name find_synonyms(query = c("Anguilla marmorata","Anguilla japonica", @@ -35,6 +39,9 @@ find_synonyms(query = c("Anguilla marmorata","Anguilla japonica", "Anguilla luzonensis")) } } +\references{ +\url{https://github.com/lutteropp/SpeciesSynonymFinder/blob/master/find_synonyms.r} +} \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/get_col_global.Rd b/man/get_col_global.Rd index e6894d7..a9302ef 100644 --- a/man/get_col_global.Rd +++ b/man/get_col_global.Rd @@ -9,6 +9,7 @@ get_col_global( option = "name", response = "terse", start = 0, + limit = 500, mc.cores = 2 ) } @@ -19,9 +20,11 @@ get_col_global( \item{response}{\code{character} Type of response returned. Valid values are response=terse and response=full. if the response parameter is omitted, the results are returned in the default terse format. If format=terse then a minimum set of results are returned (this is faster and smaller, enough for name lookup), if format=full then all available information is returned, response=c("full","terse"),the default value is "terse".} -\item{start}{\code{integer} The first record to return. If omitted, the results are returned from the first record (start=0). This is useful if the total number of results is larger than the maximum number of results returned by a single Web service query (currently the maximum number of results returned by a single query is 500 for terse queries and 50 for full queries,the default value is 0.} +\item{start}{\code{integer} Record number to start at. If omitted, the results are returned from the first record (start=0). Use in combination with limit to page through results. Note that we do the paging internally for you, but you can manually set the start parameter.} -\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see [mclapply()] for details.} +\item{limit}{\code{integer} Number of records to return. This is useful if the total number of results is larger than the maximum number of results returned by a single Web service query (currently the maximum number of results returned by a single query is 500 for terse queries and 50 for full queries,the default value is 500.Note that there is a hard maximum of 10,000, which is calculated as the limit+start, so start=99,00 and limit=2000 won't work.} + +\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see \code{\link{mclapply}} for details.} } \value{ object @@ -33,13 +36,17 @@ Get Catalogue of Life Global checklist via species name and id. Visit the website \url{http://webservice.catalogueoflife.org/col/webservice} for more details. } \examples{ -\donttest{ +\dontrun{ ##Get Catalogue of Life Global checklist via species name -x <- get_col_global(query = c("Anguilla marmorata","Anguilla japonica", +x1 <- get_col_global(query = c("Anguilla marmorata","Anguilla japonica", "Anguilla bicolor","Anguilla nebulosa", "Anguilla luzonensis"), - option = "name") -str(x) + option = "name") +str(x1) + +##full queries +x2 <- get_col_global(query = "Anguilla", response = "full") + ##Find synonyms via species name find_synonyms(query = c("Anguilla marmorata","Anguilla japonica", @@ -48,5 +55,5 @@ find_synonyms(query = c("Anguilla marmorata","Anguilla japonica", } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/get_col_taiwan.Rd b/man/get_col_taiwan.Rd index 07cb71f..56c0c6b 100644 --- a/man/get_col_taiwan.Rd +++ b/man/get_col_taiwan.Rd @@ -4,12 +4,17 @@ \alias{get_col_taiwan} \title{Search Catalogue of Life Taiwan checklist} \usage{ -get_col_taiwan(query, tree, option = "equal", include_synonyms = TRUE) +get_col_taiwan( + query, + level = "species", + option = "equal", + include_synonyms = TRUE +) } \arguments{ \item{query}{\code{string} The string to search for.} -\item{tree}{\code{character} Query by category tree, tree=c("kingdom","phylum","class","order","family","genus","name"),the default value is "name".} +\item{level}{\code{character} Query by category level, level=c("kingdom","phylum","class","order","family","genus","species"),the default value is "species".} \item{option}{\code{character} Query format, option=c("contain","equal","beginning"),the default value is "equal".} @@ -22,15 +27,15 @@ object Get Catalogue of Life Taiwan checklist via advanced query. } \details{ -Visit the website \url{http://taibnet.sinica.edu.tw/eng/taibnet_species_query.php?} for more details. +Visit the website \url{http://taibnet.sinica.edu.tw/eng/taibnet_species_query.php} for more details. } \examples{ -\donttest{ -get_col_taiwan(query="Anguilla",tree="name",option = "contain") +\dontrun{ +get_col_taiwan(query="Anguilla",level="species",option = "contain") -get_col_taiwan(query="Giganthorhynchidae",tree="family") +get_col_taiwan(query="Anguillidae",level="family") } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/get_province.Rd b/man/get_province.Rd index 1a7635d..03442ef 100644 --- a/man/get_province.Rd +++ b/man/get_province.Rd @@ -23,4 +23,6 @@ get_province() } \author{ Liuyong Ding + +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/get_redlist_china.Rd b/man/get_redlist_china.Rd index beb5ad0..538b9db 100644 --- a/man/get_redlist_china.Rd +++ b/man/get_redlist_china.Rd @@ -20,17 +20,17 @@ assessment status: \usage{ get_redlist_china( query = NULL, - option = NULL, - taxon = "Amphibians", + option = "Scientific Names", + group = "Amphibians", viewDT = FALSE ) } \arguments{ \item{query}{\code{string} The string to query for.} -\item{option}{\code{character} There is one required parameter, which is either Chinese Names or Scientific Names. Give eithera Chinese Names or Scientific Names. If an Scientific Names is given, the Chinese Names parameter may not be used. Only exact matches found the name given will be returned. option=c("Chinese Names","Scientific Names").} +\item{option}{\code{character} There is one required parameter, which is either Chinese Names or Scientific Names. Give eithera Chinese Names or Scientific Names. If an Scientific Names is given, the Chinese Names parameter may not be used. Only exact matches found the name given will be returned. option=c("Chinese Names","Scientific Names"),,the default value is "Scientific Names".} -\item{taxon}{\code{character} There is one required parameter, taxon=c("Amphibians","Angiospermae","Ascomycetes","Basidiomycetes","Birds","Bryophyta","Gymnospermae","Inland Fishes","Lichens","Mammals","Pteridophyta","Reptiles").} +\item{group}{\code{character} There is one required parameter, group=c("Amphibians","Birds","Inland Fishes","Mammals","Reptiles","Plants","Fungi").} \item{viewDT}{\code{logic} TRUE or FALSE,the default value is FALSE.} } @@ -50,6 +50,20 @@ get_redlist_china(query = "Anguilla", option = "Scientific Names") get_redlist_china(query = "Anguilla nebulosa", option = "Scientific Names") #creates an HTML widget to display rectangular data -get_redlist_china(taxon = "Inland Fishes", viewDT = TRUE) +get_redlist_china(group = "Inland Fishes", viewDT = TRUE) } } +\references{ +\url{http://www.mee.gov.cn} + +\url{http://www.mee.gov.cn/xxgk2018/xxgk/xxgk01/201805/t20180524_629586.html} + +\url{http://www.mee.gov.cn/gkml/hbb/bgg/201309/t20130912_260061.html} + +\url{http://www.mee.gov.cn/gkml/hbb/bgg/201505/t20150525_302233.html} +} +\author{ +Liuyong Ding \email{ly_ding@126.com} + +Ke Yang \email{ydyangke@163.com} +} diff --git a/man/list_df.Rd b/man/list_df.Rd index b5c6cea..4c451c8 100644 --- a/man/list_df.Rd +++ b/man/list_df.Rd @@ -34,7 +34,7 @@ Visit the website \url{http://sp2000.org.cn/api/document} for more details list_df(x, db = c("colchina", "colglobal")) } \arguments{ -\item{x}{\code{list} The result returned by the function [search_checklist] or [get_col_global].} +\item{x}{\code{list} Results returned by the function \code{\link{search_checklist}} and \code{\link{get_col_global}}.} \item{db}{\code{character} db = c("colchina","colglobal")} } @@ -50,10 +50,11 @@ set_search_key <- "your apiKey" familyid <- search_family_id(query = "Anguillidae") ##Search taxon IDs via familyID -taxonid <- search_taxon_id(query = familyid$familyIDs,name = "familyID") +taxonid <- search_taxon_id(query = familyid$Anguillidae$data$record_id, name = "familyID") #Download detailed lists via species or infraspecies ID -x1 <- search_checklist(query = taxonid$taxonIDs) +query <- taxonid[["3851c5311bed46c19529cb155d37aa9b"]][["data"]][["namecode"]] +x1 <- search_checklist(query = query) str(x1) x1 <- list_df(x1,db = "colchina") @@ -67,5 +68,5 @@ x2 <- list_df(x2,db = "colglobal") } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/open_url.Rd b/man/open_url.Rd index 19fd3dd..9babbf6 100644 --- a/man/open_url.Rd +++ b/man/open_url.Rd @@ -27,4 +27,6 @@ open_url(query = "Anguilla marmorata",name = "scientificName",language = 'zh') } \author{ Liuyong Ding + +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/search_checklist.Rd b/man/search_checklist.Rd index 85c8071..c110847 100644 --- a/man/search_checklist.Rd +++ b/man/search_checklist.Rd @@ -7,9 +7,9 @@ search_checklist(query = NULL, mc.cores = 2) } \arguments{ -\item{query}{\code{string} single or more query, see [search_family_id()] and [search_taxon_id()] for more details.} +\item{query}{\code{string} One or more queries, see \code{\link{search_family_id}} and \code{\link{search_taxon_id}} for more details.} -\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see [mclapply()] for details.} +\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see \code{\link{mclapply}} for details.} } \value{ Catalogue of Life China list(s) @@ -29,13 +29,14 @@ set_search_key <- "your apiKey" familyid <- search_family_id(query = "Anguillidae") ##Search taxon IDs via familyID -taxonid <- search_taxon_id(query = familyid$familyIDs,name = "familyID") +taxonid <- search_taxon_id(query = familyid$Anguillidae$data$record_id,name = "familyID") #Download detailed lists via species or infraspecies ID -x <- search_checklist(query = taxonid$taxonIDs) +query <- taxonid[["3851c5311bed46c19529cb155d37aa9b"]][["data"]][["namecode"]] +x <- search_checklist(query = query) str(x) } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/search_family_id.Rd b/man/search_family_id.Rd index 8969889..7b88825 100644 --- a/man/search_family_id.Rd +++ b/man/search_family_id.Rd @@ -4,12 +4,16 @@ \alias{search_family_id} \title{Search family IDs} \usage{ -search_family_id(query = NULL, mc.cores = 2) +search_family_id(query = NULL, start = 1, limit = 20, mc.cores = 2) } \arguments{ -\item{query}{\code{character} Family name, or part of family name, supports Latin and Chinese names.} +\item{query}{\code{character} One and more queries,support Family name, or part of family name, supports Latin and Chinese names.} -\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see [mclapply()] for details.} +\item{start}{\code{integer} Record number to start at. If omitted, the results are returned from the first record (start=1). Use in combination with limit to page through results. Note that we do the paging internally for you, but you can manually set the start parameter.} + +\item{limit}{\code{integer} Number of records to return, the default value is 20.} + +\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see \code{\link{mclapply}} for details.} } \value{ dataframe @@ -30,5 +34,5 @@ familyid <- search_family_id(query = "Anguillidae") } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} } diff --git a/man/search_taxon_id.Rd b/man/search_taxon_id.Rd index 84a1295..a79e041 100644 --- a/man/search_taxon_id.Rd +++ b/man/search_taxon_id.Rd @@ -13,14 +13,24 @@ query: } } \usage{ -search_taxon_id(query = NULL, name = "scientificName", mc.cores = 2) +search_taxon_id( + query = NULL, + name = "scientificName", + start = 1, + limit = 20, + mc.cores = 2 +) } \arguments{ \item{query}{\code{string} familyID ,scientificName or commonName.} \item{name}{\code{character} name = c("familyID","scientificName","commonName"),the default value is "scientificName".} -\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see [mclapply] for details.} +\item{start}{\code{intenger} Record number to start at. If omitted, the results are returned from the first record (start=1). Use in combination with limit to page through results. Note that we do the paging internally for you, but you can manually set the start parameter.} + +\item{limit}{\code{intenger} Number of records to return. This is passed across all sources,when you first query, set the limit to something smallish so that you can get a result quickly, then do more as needed.} + +\item{mc.cores}{The number of cores to use, i.e. at most how many child processes will be run simultaneously. The option is initialized from environment variable MC_CORES if set. Must be at least one, and parallelization requires at least two cores,see \code{\link{mclapply}} for details.} } \value{ dataframe @@ -40,16 +50,10 @@ set_search_key <- "your apiKey" familyid <- search_family_id(query = "Anguillidae") ##Search taxon IDs via familyID -taxonid <- search_taxon_id(query = familyid$familyIDs,name = "familyID") - -##Search taxon IDs via scientificName -taxonid <- search_taxon_id(query = c("Anguilla marmorata","Anguilla japonica", - "Anguilla bicolor","Anguilla nebulosa", - "Anguilla luzonensis"), - name = "scientificName") +taxonid <- search_taxon_id(query = familyid$Anguillidae$data$record_id,name = "familyID") } } \author{ -Liuyong Ding +Liuyong Ding \email{ly_ding@126.com} }