[CHNOSZ-commits] r395 - in pkg/CHNOSZ: . R inst man tests/testthat

[noreply at r-forge.r-project.org]

Author: jedick
Date: 2019-02-15 01:53:56 +0100 (Fri, 15 Feb 2019)
New Revision: 395

Added:
   pkg/CHNOSZ/R/retrieve.R
   pkg/CHNOSZ/man/retrieve.Rd
   pkg/CHNOSZ/tests/testthat/test-retrieve.R
Modified:
   pkg/CHNOSZ/DESCRIPTION
   pkg/CHNOSZ/NAMESPACE
   pkg/CHNOSZ/inst/NEWS
Log:
retrieve(): new function


Modified: pkg/CHNOSZ/DESCRIPTION
===================================================================
--- pkg/CHNOSZ/DESCRIPTION	2019-02-13 14:47:58 UTC (rev 394)
+++ pkg/CHNOSZ/DESCRIPTION	2019-02-15 00:53:56 UTC (rev 395)
@@ -1,6 +1,6 @@
-Date: 2019-02-13
+Date: 2019-02-15
 Package: CHNOSZ
-Version: 1.2.0-1
+Version: 1.2.0-2
 Title: Thermodynamic Calculations and Diagrams for Geochemistry
 Authors at R: c(
     person("Jeffrey", "Dick", , "j3ffdick at gmail.com", role = c("aut", "cre"),

Modified: pkg/CHNOSZ/NAMESPACE
===================================================================
--- pkg/CHNOSZ/NAMESPACE	2019-02-13 14:47:58 UTC (rev 394)
+++ pkg/CHNOSZ/NAMESPACE	2019-02-15 00:53:56 UTC (rev 395)
@@ -58,7 +58,7 @@
 # added 20171121 or later
   "dumpdata", "thermo.axis", "solubility", "NaCl",
 # added 20190213 or later
-  "CHNOSZ", "thermo", "reset", "obigt"
+  "CHNOSZ", "thermo", "reset", "obigt", "retrieve"
 )
 
 # Load shared objects

Added: pkg/CHNOSZ/R/retrieve.R
===================================================================
--- pkg/CHNOSZ/R/retrieve.R	                        (rev 0)
+++ pkg/CHNOSZ/R/retrieve.R	2019-02-15 00:53:56 UTC (rev 395)
@@ -0,0 +1,33 @@
+# CHNOSZ/retrieve.R
+# retrieve species with given elements
+# 20190214 initial version
+
+retrieve <- function(elements) {
+  # what are the formulas of species in the current database?
+  formula <- thermo()$obigt$formula
+  # get a previously calculated stoichiometric matrix, if it matches the current database
+  stoich <- thermo()$stoich
+  if(!is.null(stoich)) {
+    # if it doesn't match the current database, don't use it
+    if(!identical(rownames(stoich), formula)) stoich <- NULL
+  }
+  if(is.null(stoich)) {
+    # Create the stoichiometric matrix for the current database
+    # and suppress warning messages about missing elements
+    message("retrieve: creating stoichiometric matrix")
+    # NOTE: row names are the formulas, so we can detect if the database changes
+    stoich <- suppressWarnings(i2A(formula))
+    # store the stoichiometric matrix for later calculations
+    thermo("stoich" = stoich)
+  }
+  not.present <- ! elements %in% colnames(stoich)
+  if(any(not.present)) {
+    if(sum(not.present)==1) stop(elements[not.present], " is not an element that is present in any species")
+    else stop(paste(elements[not.present], collapse=", "), " are not elements that are present in any species")
+  }
+  # identify the species that have the elements
+  has.elements <- rowSums(stoich[, elements, drop = FALSE] != 0) == length(elements)
+  # which species are these (i.e. the species index)
+  which(has.elements)
+}
+

Modified: pkg/CHNOSZ/inst/NEWS
===================================================================
--- pkg/CHNOSZ/inst/NEWS	2019-02-13 14:47:58 UTC (rev 394)
+++ pkg/CHNOSZ/inst/NEWS	2019-02-15 00:53:56 UTC (rev 395)
@@ -1,4 +1,4 @@
-CHANGES IN CHNOSZ 1.2.0-1 (2019-02-13)
+CHANGES IN CHNOSZ 1.2.0-2 (2019-02-15)
 --------------------------------------
 
 CRAN COMPLIANCE
@@ -10,11 +10,14 @@
   that existing scripts beginning with data(thermo) still work (this
   command now has no effect other than producing a warning).
 
-OTHER CHANGES
+NEW FEATURES
 
 - Add thermo() as a convenience function to access or modify the
   package's data, especially various computational options.
 
+- Add retrieve() to retrieve all the species with given elements. Thanks
+  to Evgeniy Bastrakov for the suggestion.
+
 CHANGES IN CHNOSZ 1.2.0 (2019-02-09)
 ------------------------------------
 

Added: pkg/CHNOSZ/man/retrieve.Rd
===================================================================
--- pkg/CHNOSZ/man/retrieve.Rd	                        (rev 0)
+++ pkg/CHNOSZ/man/retrieve.Rd	2019-02-15 00:53:56 UTC (rev 395)
@@ -0,0 +1,37 @@
+\encoding{UTF-8}
+\name{retrieve}
+\alias{retrieve}
+\title{Retrieve Species by Element}
+\description{
+Retrieve species in the database containing one or more chemical elements.
+}
+
+\usage{
+  retrieve(elements)
+}
+
+\arguments{
+  \item{elements}{character, one or more chemical elements}
+}
+
+\details{
+This function retrieves the species in the thermodynamic database (see \code{\link{thermo}}) that have all of the elements specified in \code{elements}.
+The return value is a named numeric vector giving the species index (i.e. rownumber(s) of \code{thermo()$obigt}) with names corresponding to the chemical formulas of the species.
+
+The first time the function is run, it uses \code{\link{i2A}} to build the stoichiometric matrix for the current database.
+Following runs use the previously calculated stoichiometric matrix, unless a change to the database is detected, which triggers a recalculation.
+}
+
+\seealso{
+\code{\link{info}}
+}
+
+\examples{
+# species index of Ti-bearing minerals
+retrieve("Ti")
+
+# thermodynamic data for Au-Cl complexes
+info(retrieve(c("Au", "Cl")))
+}
+
+\concept{Extended workflow}

Added: pkg/CHNOSZ/tests/testthat/test-retrieve.R
===================================================================
--- pkg/CHNOSZ/tests/testthat/test-retrieve.R	                        (rev 0)
+++ pkg/CHNOSZ/tests/testthat/test-retrieve.R	2019-02-15 00:53:56 UTC (rev 395)
@@ -0,0 +1,12 @@
+context("retrieve")
+
+test_that("errors and recalculations produce expected messages", {
+  # this should give an error about one non-element
+  expect_error(retrieve(c("A", "B", "C")), "A is not an element")
+  # this should give an error about two non-elements
+  expect_error(retrieve(c("A", "B", "C", "D")), "A, D are not elements")
+  # this should recalculate the stoichiometric matrix
+  add.obigt("SUPCRT92")
+  expect_message(retrieve("Ti"), "creating stoichiometric matrix")
+  reset()
+})