[CHNOSZ-commits] r412 - in pkg/CHNOSZ: . R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Feb 25 02:39:52 CET 2019
Author: jedick
Date: 2019-02-25 02:39:51 +0100 (Mon, 25 Feb 2019)
New Revision: 412
Modified:
pkg/CHNOSZ/DESCRIPTION
pkg/CHNOSZ/R/retrieve.R
pkg/CHNOSZ/man/retrieve.Rd
Log:
retrieve(): add 'add.charge' argument and "all" keyword
Modified: pkg/CHNOSZ/DESCRIPTION
===================================================================
--- pkg/CHNOSZ/DESCRIPTION 2019-02-24 22:46:53 UTC (rev 411)
+++ pkg/CHNOSZ/DESCRIPTION 2019-02-25 01:39:51 UTC (rev 412)
@@ -1,6 +1,6 @@
-Date: 2019-02-24
+Date: 2019-02-25
Package: CHNOSZ
-Version: 1.2.0-19
+Version: 1.2.0-20
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/R/retrieve.R
===================================================================
--- pkg/CHNOSZ/R/retrieve.R 2019-02-24 22:46:53 UTC (rev 411)
+++ pkg/CHNOSZ/R/retrieve.R 2019-02-25 01:39:51 UTC (rev 412)
@@ -3,7 +3,7 @@
# 20190214 initial version
# 20190224 use ... for multiple arguments (define a chemical system)
-retrieve <- function(..., include.electron = FALSE, include.groups = FALSE, state = NULL) {
+retrieve <- function(..., state = NULL, add.charge = TRUE, hide.electron = TRUE, hide.proton = TRUE, hide.groups = TRUE) {
## stoichiometric matrix
# what are the formulas of species in the current database?
formula <- thermo()$obigt$formula
@@ -26,17 +26,26 @@
## species identification
args <- list(...)
ispecies <- numeric()
+ # automatically add charge to a system 20190225
+ if(add.charge & length(args) > 1) {
+ if(!"Z" %in% unlist(args)) args <- c(args, "Z")
+ }
for(elements in args) {
- 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')
+ if(identical(elements, "all")) {
+ ispecies <- 1:nrow(thermo()$obigt)
+ names(ispecies) <- thermo()$obigt$formula
+ } else {
+ 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)
+ ispecies <- c(ispecies, which(has.elements))
+ ispecies <- ispecies[!duplicated(ispecies)]
}
- # 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)
- ispecies <- c(ispecies, which(has.elements))
- ispecies <- ispecies[!duplicated(ispecies)]
}
# for a chemical system, defined by multiple arguments, the species can not contain any _other_ elements
if(length(args) > 1) {
@@ -45,21 +54,26 @@
notsysstoich <- thermo()$stoich[, !isyselements]
iother <- rowSums(notsysstoich[ispecies, ] != 0) > 0
ispecies <- ispecies[!iother]
- # include the species for "Z" (charge)
- if(!include.electron) {
- ielectron <- names(ispecies) == "(Z-1)"
- ispecies <- ispecies[!ielectron]
- }
}
- # exclude groups and filter states
- if(!include.groups) {
+ # exclude groups and electron and proton
+ if(hide.groups) {
igroup <- grepl("^\\[.*\\]$", thermo()$obigt$name[ispecies])
ispecies <- ispecies[!igroup]
}
+ if(hide.electron) {
+ ielectron <- names(ispecies) == "(Z-1)"
+ ispecies <- ispecies[!ielectron]
+ }
+ if(hide.proton) {
+ iproton <- names(ispecies) == "H+"
+ ispecies <- ispecies[!iproton]
+ }
+ # filter states
if(!is.null(state)) {
istate <- thermo()$obigt$state[ispecies] %in% state
ispecies <- ispecies[istate]
}
+ # for names, use e- instead of (Z-1)
+ names(ispecies)[names(ispecies)=="(Z-1)"] <- "e-"
ispecies
}
-
Modified: pkg/CHNOSZ/man/retrieve.Rd
===================================================================
--- pkg/CHNOSZ/man/retrieve.Rd 2019-02-24 22:46:53 UTC (rev 411)
+++ pkg/CHNOSZ/man/retrieve.Rd 2019-02-25 01:39:51 UTC (rev 412)
@@ -7,29 +7,36 @@
}
\usage{
- retrieve(..., include.electron = FALSE, include.groups = FALSE, state = NULL)
+ retrieve(..., state = NULL, add.charge = TRUE,
+ hide.electron = TRUE, hide.proton = TRUE, hide.groups = TRUE)
}
\arguments{
\item{...}{list, one or more arguments, each of which is a character vector with the names of one or more chemical elements}
- \item{include.electron}{logical, include the electron in the result for chemical systems?}
- \item{include.groups}{logical, include groups in the result?}
\item{state}{character, filter the result on these state(s).}
+ \item{add.charge}{logical, add charge to the system?}
+ \item{hide.electron}{logical, exclude the electron from the result?}
+ \item{hide.proton}{logical, exclude the proton from the result?}
+ \item{hide.groups}{logical, exclude groups from the result?}
}
\details{
This function retrieves the species in the thermodynamic database (see \code{\link{thermo}}) that have all of the elements specified in the arguments.
A single argument is interpreted as a combination of one or more elements that must be present in each species.
-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.
-If the argument list is empty, then the function returns an empty (length 0) numeric value.
+Results can be filtered on physical state by setting the \code{state} argument.
-If more than one argument is present, all of the species identified by each argument are combined, then any species containing any other elements are excluded.
+If more than one argument is present, all of the species identified by each argument are combined, and all species containing any other elements are excluded.
This can be used to retrieve all of the species in the database within a given chemical system.
-When searching for charged species in a chemical system (using the element named \samp{Z}), the electron is excluded unless \code{include.electron} is TRUE (note that the electron has a chemical formula of \samp{(Z-1)}).
+A chemical system includes charged species if \code{add.charge} is TRUE (the default) or the user supplies the \dQuote{element} of charge (\samp{Z}).
-Groups used in group-additivity calculations, which have names with square brackets (e.g. [-CH2-]), are excluded unless \code{include.groups} is TRUE.
-Results can be filtered on physical state by setting the \code{state} argument.
+The electron and proton are excluded from the result unless \code{hide.electron} and/or \code{hide.proton} is FALSE.
+Groups used in group-additivity calculations, which have names with square brackets (e.g. [-CH2-]), are also excluded unless \code{hide.groups} is FALSE.
+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.
+However, if electron is included in the result, the result uses its name (\samp{e-}) instead of its chemical formula (\samp{(Z-1)}).
+If the argument list is empty, then the function returns an empty (length 0) numeric value.
+A special argument value \samp{all} can be used to retrieve all species in the thermodynamic database, including filtering on state and hiding of the proton, electron, and/or groups.
+
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.
}
@@ -44,19 +51,16 @@
# thermodynamic data for those minerals
info(retrieve("Ti"))
-# thermodynamic data for Au-Cl complexes
-info(retrieve(c("Au", "Cl")))
-
# all species that have Au
retrieve("Au")
# all species that have both Au and Cl
retrieve(c("Au", "Cl"))
-# all species that have Au and/or Cl, and no other elements
+# all species that have Au and/or Cl, including charged species, but no other elements
retrieve("Au", "Cl")
-# all species that have Au and/or Cl and/or Z, and no other elements
-retrieve("Au", "Cl", "Z")
# include the electron with these species
-retrieve("Au", "Cl", "Z", include.electron = TRUE)
+retrieve("Au", "Cl", hide.electron = FALSE)
+# all uncharged species that have Au and/or Cl
+retrieve("Au", "Cl", add.charge = FALSE)
# minerals in the system SiO2-MgO-CaO-CO2
retrieve("Si", "Mg", "Ca", "C", "O", state="cr")
More information about the CHNOSZ-commits
mailing list