revised for CRAN

quexiang · Feb 13, 2024 · 512bdde · 512bdde
1 parent a3462b6
commit 512bdde
Show file tree

Hide file tree

Showing 29 changed files with 83 additions and 27 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/CRAN-SUBMISSION b/CRAN-SUBMISSION
@@ -1,3 +1,3 @@
 Version: 1.0.0
-Date: 2024-02-03 18:39:42 UTC
-SHA: b47b6493634784d308ad7d93dbef9ca27fd00990
+Date: 2024-02-13 08:02:41 UTC
+SHA: a3462b63013001929c02da3dd360be66d5fde3c8
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: OpenMindat
 Type: Package
-Title: Quickly Retrieve Datasets from the 'Mindat' API
+Title: Quickly Retrieve Datasets from the 'mindat.org' API
 Version: 1.0.0
 Imports:
     httr (>= 1.4.4),
@@ -16,7 +16,7 @@ Authors@R: c(
       person(given = "Xiaogang",family = "Ma",email = "max@uidaho.edu",role = c("aut"),comment = c(ORCID = "0000-0002-9110-7369"))
     )
 Maintainer: Xiang Que <xiangq@uidaho.edu>
-Description: The OpenMindat R package is used to retrieve datasets from the 'mindat.org' API (<https://api.mindat.org/schema/redoc/>).
+Description: Mindat ('mindat.org') is one of the world's most widely used databases of mineral species and their distribution. Many scientists in mineralogy, geochemistry, petrology, and other Earth and planetary disciplines have been using the Mindat data. Still, an open data service and the machine interface have never been fully established. To meet the overwhelming data needs, the Mindat team has built an API (<https://api.mindat.org/schema/redoc/>) for data access.'OpenMindat' R package provides valuable functions to bridge the data highway, connecting users's data requirements to the Mindat API server and assist with retrieval and initial processing to improve efficiency further and lower the barrier of data query and access to scientists. 'OpenMindat' provides friendly and extensible data retrieval functions, including the subjects of geomaterials (e.g., rocks, minerals, synonyms, variety, mixture, and commodity), localities, and the IMA (International Mineralogical Association)-approved mineral list. 'OpenMindat' R package will accelerate the process of data-intensive studies in mineral informatics and lead to more scientific discoveries.
 VignetteBuilder: knitr
 Encoding: UTF-8
 LazyData: true

diff --git a/NAMESPACE b/NAMESPACE
@@ -61,6 +61,7 @@ export(localities_list_updated_at)
 export(localities_retrieve_id)
 export(localities_status_list)
 export(localities_status_retrieve)
+export(localitiy_type_retrieve)
 export(locality_age)
 export(locality_age_list)
 export(locality_type_list)
@@ -96,6 +97,7 @@ export(minerals_ima_list)
 export(minerals_ima_list_expand)
 export(minerals_ima_list_ima)
 export(minerals_ima_retrieve)
+export(minerals_ima_updated_at)
 export(params_to_string)
 export(saveMindatDataAs)
 export(set_api_base)

diff --git a/NEWS.Rmd b/NEWS.Rmd
@@ -15,7 +15,7 @@ knitr::opts_chunk$set(echo = TRUE)
 ### NEW features
 
 
-* OpenMindat R package is useful for retrieving and processing data from [mindat.org Database](https://www.mindat.org/) through its open data API.
+* 'OpenMindat' R package is useful for retrieving and processing data from [mindat.org Database](https://www.mindat.org/) through its open data API.
 
 
 ## OpenMindat 0.1.0

diff --git a/R/OpenMindat.R b/R/OpenMindat.R
@@ -8,6 +8,7 @@
 #' @param base_url  string.The base url of mindat API, default is "https://api.mindat.org".
 #' @param page_size interger, setting the page size of responsed data from the API server.
 #' @param fmt  string. The format of the request and response, default is json.
+#' @return No return value. A connection to the Mindat server will be established with your input token cached.
 #' @examples
 #' mindat_connection("9ce67655d74bcd981e937be80dcea9cb",page_size = 1500)
 #' @export

diff --git a/R/mindat_api_tools.R b/R/mindat_api_tools.R
@@ -50,6 +50,7 @@ mindat_api_endpoint<-function(name,epb,ubuilder = default_uri_builder,qparams=li
 #' @usage stop_not_param (comp_params, query)
 #' @param comp_params list. list of compulsory, the internal params in the mindat api.
 #' @param query list of query name/value pairs.
+#' @return No return value.It will stop and report the errors if the query param is not in the list of mindat api.
 #' @noRd
 stop_not_param<-function(comp_params, query){
  q_params <- names(query)
@@ -100,6 +101,7 @@ build_uri<-function(endpoint, query = list(), api_base = NULL,...){
 #' @description set base uri of current environment
 #' @usage set_api_base (api_base)
 #' @param api_base string. The base uri of mindat api.
+#' @return No return value. The api based url (api_base) will be cached. Users can retrieve the value by calling mindat_cache_get('api_base').
 #' @examples
 #' set_api_base("9ce67655d74bcd981e937be80dcea9cb")
 #' @export
@@ -111,6 +113,7 @@ set_api_base<-function(api_base){
 #' @description set the token of current environment
 #' @usage set_api_token (api_token)
 #' @param api_token string. The token of mindat api.
+#' @return No return value. The api_token will be cached. Users can retrieve the value by calling mindat_cache_get('api_token').
 #' @examples
 #' set_api_token("9ce67655d74bcd981e937be80dcea9cb")
 #' @export
@@ -122,6 +125,8 @@ set_api_token<-function(api_token){
 #' @description set the page_size of response records.
 #' @usage set_page_size (page_size)
 #' @param page_size string. The token of mindat api.
+#' @return No return value. The 'page_size' will be cached.
+#'        The page_size information is added to the query string of every request sent to the Mindat server via the "OpenMindat" package.
 #' @examples
 #' set_page_size(800)
 #' @export

diff --git a/R/mindat_cache.R b/R/mindat_cache.R
@@ -9,6 +9,7 @@ mindat_cache <- new.env()
 #' @usage mindat_cache_set(varname, value)
 #' @param varname  string. The cached varname.
 #' @param value  string.
+#' @return No return value. The value will be cached in memory, and the cached value can be fetched by calling the function mindat_cache_get with the assigned varname.
 #' @examples
 #' mindat_cache_set('api_token',"9ce67655d74bcd981e937be80dcea9cb")
 #' @export
@@ -34,6 +35,7 @@ mindat_cache_get<-function(varname)
 #' @description Remove (clear) the cache named varname in current environment.
 #' @usage mindat_cache_delete(varname)
 #' @param varname string input a cached name.Set a cached value empty by the given varname. A string, list or other objects.
+#' @return No return value. The cached variable named varname will be clear.
 #' @examples
 #' mindat_cache_delete('api_token')
 #' @export
@@ -45,6 +47,7 @@ mindat_cache_delete<-function(varname)
 #' Remove all cached values
 #' @description Clear all current cached values. Set current environment cache empty.
 #' @usage mindat_cache_empty()
+#' @return No return value. All cached content will be cleared.
 #' @examples
 #' mindat_cache_empty()
 #' @export

diff --git a/R/minda_data_maker.R → R/mindat_data_maker.R b/R/minda_data_maker.R → R/mindat_data_maker.R
@@ -8,6 +8,7 @@
 #' @examples
 #' filename<- "fname.txt"
 #' fname_extension<- getExtension(filename)
+#' @return 'getExtension()' returns a string which is the suffix string of a file name.
 #' @export
 getExtension <- function(filename){
   ext<- strsplit(filename, ".", fixed=T)[[1]][-1]
@@ -21,6 +22,7 @@ getExtension <- function(filename){
 #' @usage ConvertDF2JsonLD(inputdata,template = NULL)
 #' @param inputdata R dataframe of retrieived data from Mindat database.
 #' @param template filepath to the template
+#' @return 'ConvertDF2JsonLD()' returns a string written in Json-LD format converted from an input R data frame (df).
 #' @examples
 #' \dontrun{
 #' df <-geomaterials_search_name("Quartz")
@@ -142,6 +144,7 @@ ConvertDF2JsonLD<- function(inputdata,template = NULL ){ #"/inst/extdata/OpenMin
 #' @usage ConvertDF2TTL (inputdata,template = NULL)
 #' @param inputdata R dataframe of retrieived data from Mindat database.
 #' @param template filepath to the template
+#' @return 'ConvertDF2TTL()' returns a string written in TTL (pronounced 'turtle') format converted from an input R data frame (df).
 #' @examples
 #' \dontrun{
 #' df <-geomaterials_search_name("Quartz")
@@ -245,6 +248,7 @@ ConvertDF2TTL<- function(inputdata,template = NULL){
 #' @usage saveMindatDataAs (inputdata,outputfname)
 #' @param inputdata R dataframe of retrieived data from Mindat database.
 #' @param outputfname string. the output file name.
+#' @return No return value.If successful, the input data frame(df) will be saved to the specified file. Otherwise, it will report an error.
 #' @examples
 #' \dontrun{
 #' df <-geomaterials_search_name("Quartz")

diff --git a/R/mindat_endpoint.R b/R/mindat_endpoint.R
@@ -5,6 +5,7 @@
 #' @param api_base_url list. The base url of mindat api.
 #' @param config list. config of current environment.
 #' @param querystring list. list of query fields and conditions.
+#' @return uri string.
 #' @noRd
 mindat_uri_builder<- function(api_base_url, config, querystring = ''){
   if(querystring != ''){
@@ -20,6 +21,7 @@ mindat_uri_builder<- function(api_base_url, config, querystring = ''){
 #' mindat_set_up_endpoints
 #' @description Set up the basic mindat endpoints for current mindat API.
 #' @usage mindat_set_up_endpoints ()
+#' @return No return value. The default endpoints will be set up.
 #' @noRd
 mindat_set_up_endpoints<-function(){
   # single ima mineral
@@ -89,6 +91,7 @@ mindat_set_up_endpoints<-function(){
 #' @usage mindat_setup(base_uri = 'https://api.mindat.org',page_size = 800)
 #' @param base_uri base uri of mindat API.
 #' @param page_size interger,setting the page size of responsed data from the API server.
+#' @return No return value. Mindat basic configuration will be set up.
 #' @examples
 #' \dontrun{
 #' mindat_setup()

diff --git a/R/mindat_ima_minerals.R b/R/mindat_ima_minerals.R
@@ -71,6 +71,7 @@ minerals_ima_list_ima<- function(intValue,...){
 #' @details
 #' This function is related to the filed "updated_at" of ima minerals.
 #' retrieve the localities that have the latest updated at the given time.
+#' @export
 minerals_ima_updated_at <- function(updateDate,...){
   df_out <-mindat_mineral_ima_list(ids = c(''),updated_at = updateDate,...)
   df_out

diff --git a/R/mindat_localities.R b/R/mindat_localities.R
@@ -303,7 +303,7 @@ localities_status_retrieve<- function(id,...){
 #' }
 #' @details
 #'  This function is to retrieve the locality types by an given id of locality.
-#'  @export
+#' @export
 localitiy_type_retrieve <- function(id,...){
   df_out <- mindat_locality_type( id = id,...)
   df_out

diff --git a/README.md b/README.md
@@ -4,14 +4,14 @@ R package for OpenMindat
 ### Overview
 `OpenMindat` is a package for retrieving and processing data from ['mindat.org' Database](https://www.mindat.org/) through its open data API.
 
-Mindat and University of Idaho collaborate on '[OpenMindat](https://www.mindat.org/mesg-567769.html)'
+University of Idaho and 'mindat.org' collaborate on '['OpenMindat'](https://www.mindat.org/mesg-567769.html)' project.
 
 ### Quick start
 
 
 **Install and load necessary packages**
 
-This package can be installed directly through the `remotes` package:
+`OpenMindat` can be installed directly through the `remotes` package:
 
 ```coffee
 install.packages("remotes")
@@ -22,9 +22,9 @@ remotes::install_github("quexiang/OpenMindat")
 Or through devtools:
 
 ```coffee
-install.packages("devtools")
-library("devtools")
-install_github("quexiang/OpenMindat")
+install.packages('devtools')
+library('devtools')
+install_github('quexiang/OpenMindat')
 ```
 
 Or download the source code locally and install it as follows:
@@ -44,21 +44,21 @@ Then, you can create a new file to load the dependent package, and then call the
 
 
 ```coffee
-#install.packages("httr")
-#install.packages("jsonlite")
-#install.packages("usethis")
-#install.packages("readxl")
-#install.packages("OpenMindat")
+#install.packages('httr')
+#install.packages('jsonlite')
+#install.packages('usethis')
+#install.packages('readxl')
+#install.packages('OpenMindat')
 library(OpenMindat)
 library(httr)
 library(usethis)
 library(jsonlite)
 library(readxl)
 ```
 
-**Set up API connection with your Mindat API token and use the functions**
+**Set up API connection with your 'mindat.org' API token and use the functions**
 
-1. You should first get your own Mindat api token `YourToken` . ([How to get your mindat API token ?](https://www.mindat.org/a/how_to_get_my_mindat_api_key))
+1. You should first get your own 'mindat.org' API token `YourToken` . ([How to get your 'mindat.org' API token ?](https://www.mindat.org/a/how_to_get_my_mindat_api_key))
 
 2. Set up your token `YourToken`
 

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -3,4 +3,5 @@ template:
   bootstrap: 5
   bootswatch: cerulean
 deploy:
-  install_metadata: true
+  install_metadata: yes
+
diff --git a/inst/pkgdown.yml b/inst/pkgdown.yml
@@ -4,7 +4,7 @@ pkgdown_sha: ~
 articles:
   Mindat_data: Mindat_data.html
   OpenMindat: OpenMindat.html
-last_built: 2024-02-03T18:16Z
+last_built: 2024-02-13T07:19Z
 urls:
   reference: https://quexiang.github.io/OpenMindat/reference
   article: https://quexiang.github.io/OpenMindat/articles

diff --git a/man/ConvertDF2JsonLD.Rd b/man/ConvertDF2JsonLD.Rd
diff --git a/man/ConvertDF2TTL.Rd b/man/ConvertDF2TTL.Rd
diff --git a/man/OpenMindat-package.Rd b/man/OpenMindat-package.Rd
diff --git a/man/getExtension.Rd b/man/getExtension.Rd
diff --git a/man/localitiy_type_retrieve.Rd b/man/localitiy_type_retrieve.Rd
diff --git a/man/mindat_cache_delete.Rd b/man/mindat_cache_delete.Rd
diff --git a/man/mindat_cache_empty.Rd b/man/mindat_cache_empty.Rd
diff --git a/man/mindat_cache_set.Rd b/man/mindat_cache_set.Rd
diff --git a/man/mindat_connection.Rd b/man/mindat_connection.Rd
diff --git a/man/mindat_setup.Rd b/man/mindat_setup.Rd
diff --git a/man/saveMindatDataAs.Rd b/man/saveMindatDataAs.Rd