[CHNOSZ-commits] r146 - in pkg/CHNOSZ: . R data inst man vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Feb 13 04:26:38 CET 2017
Author: jedick
Date: 2017-02-13 04:26:37 +0100 (Mon, 13 Feb 2017)
New Revision: 146
Modified:
pkg/CHNOSZ/DESCRIPTION
pkg/CHNOSZ/R/util.data.R
pkg/CHNOSZ/data/OBIGT.csv
pkg/CHNOSZ/inst/NEWS
pkg/CHNOSZ/man/CHNOSZ-package.Rd
pkg/CHNOSZ/man/data.Rd
pkg/CHNOSZ/man/util.data.Rd
pkg/CHNOSZ/man/util.water.Rd
pkg/CHNOSZ/vignettes/anintro.Rmd
pkg/CHNOSZ/vignettes/vig.bib
Log:
anintro.Rmd: add thermodynamic data
Modified: pkg/CHNOSZ/DESCRIPTION
===================================================================
--- pkg/CHNOSZ/DESCRIPTION 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/DESCRIPTION 2017-02-13 03:26:37 UTC (rev 146)
@@ -1,6 +1,6 @@
-Date: 2017-02-12
+Date: 2017-02-13
Package: CHNOSZ
-Version: 1.0.8-35
+Version: 1.0.8-36
Title: Chemical Thermodynamics and Activity Diagrams
Author: Jeffrey Dick
Maintainer: Jeffrey Dick <j3ffdick at gmail.com>
Modified: pkg/CHNOSZ/R/util.data.R
===================================================================
--- pkg/CHNOSZ/R/util.data.R 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/R/util.data.R 2017-02-13 03:26:37 UTC (rev 146)
@@ -165,12 +165,13 @@
return(invisible(inew))
}
-browse.refs <- function(key=NULL) {
- ## browse to web page associated with a given source
- ## of thermodynamic data. first version: 20110615
+thermo.refs <- function(key=NULL) {
+ ## return references for thermodynamic data.
+ ## 20110615 browse.refs() first version
+ ## 20170212 thermo.refs() remove browsing (except for table of all sources)
# 'key' can be
# NULL: show a table of all sources in a browser
- # character: open a web page for each listed source
+ # character: return data for each listed source key
# numeric: open one or two web pages for each listed species
# list: the output of subcrt()
## first retrieve the sources table
@@ -252,36 +253,26 @@
### end adaptation from print.findFn
# show table in browser
browseURL(File)
- cat("browse.refs: table of references is shown in browser\n")
+ cat("thermo.refs: table of references is shown in browser\n")
} else if(is.character(key)) {
- # open the URL(s) of the given source(s)
- for(i in seq_along(key)) {
- ix <- match(key[i],x$key)
- if(is.na(ix)) {
- cat(paste("browse.refs: reference key",key[i],"not found\n"))
- next
- }
- URL <- x$URL[ix]
- if(URL=="" | is.na(URL)) {
- cat(paste("browse.refs: no URL available for reference key",key[i],"\n"))
- next
- }
- cat(paste("browse.refs: opening URL for ",key[i]," (",x$author[ix],", ",x$year[ix],")\n",sep=""))
- browseURL(x$URL[ix])
- }
- return(invisible(URL))
+ # return citation information for the given source(s)
+ ix <- match(key, x$key)
+ ina <- is.na(ix)
+ if(any(is.na(ix))) message(paste("thermo.refs: reference key(s)",
+ paste(key[ina], collapse = ","), "not found"))
+ return(x[ix, ])
} else if(is.numeric(key)) {
- # open the URL(s) of sources associated with the indicated species
+ # get the source keys for the indicated species
sinfo <- suppressMessages(info(key))
- mysources <- unique(c(sinfo$ref1,sinfo$ref2))
+ mysources <- unique(c(sinfo$ref1, sinfo$ref2))
mysources <- mysources[!is.na(mysources)]
- return(browse.refs(mysources))
+ return(thermo.refs(mysources))
} else if(is.list(key)) {
if("species" %in% names(key)) ispecies <- key$species$ispecies
else if("reaction" %in% names(key)) ispecies <- key$reaction$ispecies
else stop("list does not appear to be a result from subcrt()")
if(is.null(ispecies)) stop("list does not appear to be a result from subcrt()")
- return(browse.refs(ispecies))
+ return(thermo.refs(ispecies))
}
}
Modified: pkg/CHNOSZ/data/OBIGT.csv
===================================================================
--- pkg/CHNOSZ/data/OBIGT.csv 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/data/OBIGT.csv 2017-02-13 03:26:37 UTC (rev 146)
@@ -1,5 +1,5 @@
name,abbrv,formula,state,ref1,ref2,date,G,H,S,Cp,V,a1.a,a2.b,a3.c,a4.d,c1.e,c2.f,omega.lambda,z.T
-water,NA,H2O,liq,WP02,NA,25.Oct.06,-56687.711481,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA
+water,NA,H2O,liq,NA,NA,25.Oct.06,-56687.711481,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA,NA
e-,NA,Z0-1,aq,NA,NA,28.Oct.06,0,0,15.6166,0,0,0,0,0,0,0,0,0,0
H+,H+,H+,aq,SH88,NA,06.Nov.97,0,0,0,0,0,0,0,0,0,0,0,0,0
Li+,Li+,Li+,aq,SH88,NA,06.Nov.97,-69933,-66552,2.7,14.2,-0.87,-0.0237,-0.069,11.58,-2.7761,19.2,-0.24,0.4862,1
Modified: pkg/CHNOSZ/inst/NEWS
===================================================================
--- pkg/CHNOSZ/inst/NEWS 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/inst/NEWS 2017-02-13 03:26:37 UTC (rev 146)
@@ -1,13 +1,13 @@
-CHANGES IN CHNOSZ 1.0.8-35 (2017-02-12)
+CHANGES IN CHNOSZ 1.0.8-36 (2017-02-13)
---------------------------------------
DOCUMENTATION:
-- Add eos-regress.Rmd vignette; update related functions.
-
- Replace anintro.Rnw (Sweave) with rewritten anintro.Rmd (knitr, Tufte
style).
+- Add eos-regress.Rmd vignette; update related functions.
+
- Demos: add bugstab.R, rename buffer.R to protbuff.R, add new buffer.R,
remove nucleobase.R.
@@ -85,6 +85,9 @@
- Remove the bold formatting for "A" in expr.property(); "A" is
italicized like most other uppercase letters.
+- Rename browse.refs() to thermo.refs(); remove URL browsing (except for
+ summary table).
+
CHANGES IN CHNOSZ 1.0.8 (2016-05-28)
------------------------------------
Modified: pkg/CHNOSZ/man/CHNOSZ-package.Rd
===================================================================
--- pkg/CHNOSZ/man/CHNOSZ-package.Rd 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/man/CHNOSZ-package.Rd 2017-02-13 03:26:37 UTC (rev 146)
@@ -24,7 +24,7 @@
By combining data taken from different sources, it is possible to build an inconsistent and/or nonsensical calculation.
An attempt has been made to provide a primary database (OBIGT.csv) that is internally consistent, but no guarantee can be made.
Where possible, data with known or suspected inconsistencies have been placed into a secondary database (OBIGT-2.csv) that should be regarded as experimental.
-If there is any doubt about the accuracy or suitability of data for a particular problem, please \emph{consult the primary sources} (see \code{\link{browse.refs}}).
+If there is any doubt about the accuracy or suitability of data for a particular problem, please \emph{consult the primary sources} (see \code{\link{thermo.refs}}).
Do not assume that by adding any species to your calculation (or to any of the examples), you will necessarily obtain a reasonable answer.
Do not assume that the examples are correct, or that they can be applied to your problem.
As with the data, please \emph{compare the construction and output of the examples to the primary sources}, cited in the reference list in each help page.
Modified: pkg/CHNOSZ/man/data.Rd
===================================================================
--- pkg/CHNOSZ/man/data.Rd 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/man/data.Rd 2017-02-13 03:26:37 UTC (rev 146)
@@ -80,7 +80,7 @@
This dataframe is a thermodynamic database of standard molal thermodynamic properties and equations of state parameters of species. \acronym{OBIGT} is an acronym for \samp{OrganoBioGeoTherm}, which refers to a software package produced by Harold C. Helgeson and coworkers at the Laboratory of Theoretical Geochemistry and Biogeochemistry at the University of California, Berkeley. (There may be an additional meaning for the acronym: \dQuote{One BIG Table} of thermodynamic data.)
- As of CHNOSZ version 0.7, the data in \code{OBIGT.csv} represent 179 minerals, 16 gases, and 294 aqueous (largely inorganic) species taken from the data file included in the \acronym{SUPCRT92} distribution (Johnson et al., 1992), an additional 14 minerals, 6 gases, and 1049 aqueous organic and inorganic species from the \acronym{slop98.dat} file (Shock et al., 1998), and approximately 50 other minerals, 175 crystalline organic and biochemical species, 220 organic gases, 300 organic liquids, 650 aqueous inorganic, organic, and biochemical species, and 40 organic groups taken from the recent literature. Each entry is referenced to one or two literature sources listed in \code{thermo$refs}. Use \code{\link{browse.refs}} to display the references in a browser window.
+ As of CHNOSZ version 0.7, the data in \code{OBIGT.csv} represent 179 minerals, 16 gases, and 294 aqueous (largely inorganic) species taken from the data file included in the \acronym{SUPCRT92} distribution (Johnson et al., 1992), an additional 14 minerals, 6 gases, and 1049 aqueous organic and inorganic species from the \acronym{slop98.dat} file (Shock et al., 1998), and approximately 50 other minerals, 175 crystalline organic and biochemical species, 220 organic gases, 300 organic liquids, 650 aqueous inorganic, organic, and biochemical species, and 40 organic groups taken from the recent literature. Each entry is referenced to one or two literature sources listed in \code{thermo$refs}. Use \code{\link{thermo.refs}} to lookup the citation information for the references.
Note the following additional modifications:
Modified: pkg/CHNOSZ/man/util.data.Rd
===================================================================
--- pkg/CHNOSZ/man/util.data.Rd 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/man/util.data.Rd 2017-02-13 03:26:37 UTC (rev 146)
@@ -3,7 +3,7 @@
\alias{util.data}
\alias{add.obigt}
\alias{mod.obigt}
-\alias{browse.refs}
+\alias{thermo.refs}
\alias{checkEOS}
\alias{checkGHS}
\alias{check.obigt}
@@ -20,7 +20,7 @@
package = "CHNOSZ"), force = FALSE, E.units = "cal")
mod.obigt(...)
today()
- browse.refs(key=NULL)
+ thermo.refs(key=NULL)
checkEOS(eos, state, prop, ret.diff = FALSE)
checkGHS(ghs, ret.diff = FALSE)
check.obigt()
@@ -64,7 +64,10 @@
\code{change} is a wrapper function to \code{mod.obigt} and \code{\link{mod.buffer}}. The \code{name} provided in the argument refers to the name or numeric index of the species to update or add using \code{mod.obigt}, unless the \code{name} begins with an underscore character, in which case the remaining part of the name (after the underscore) is passed to \code{mod.buffer}. The arguments in \code{...} are sent without change to the subordinate function.
- \code{browse.refs} with default arguments uses \code{\link{browseURL}} to display the sources of thermodynamic data in \code{thermo$refs}, with the URLs in that table showing as hyperlinks in the browser. Otherwise, if \code{key} is character, the URLs of those reference \code{key}s are opened in the browser. If \code{key} is numeric, the values refer to the species in those rows of \code{thermo$obigt}, and the URLs for each listed reference (\code{thermo$obigt$ref1}, \code{thermo$obigt$ref2}) are opened. If \code{key} is a list, it is interpreted as the result of a call to \code{subcrt}, and the reference URLs for each species involved in the calculation are opened.
+\code{thermo.refs} with default arguments uses \code{\link{browseURL}} to display the sources of thermodynamic data in \code{thermo$refs}, with the URLs in that table showing as hyperlinks in the browser.
+Otherwise, if \code{key} is character, the citation information for those reference \code{key}s (including URLs) are returned.
+If \code{key} is numeric, the values refer to the species in those rows of \code{thermo$obigt}, and the citation information for each listed reference (\code{thermo$obigt$ref1}, \code{thermo$obigt$ref2}) is returned.
+If \code{key} is a list, it is interpreted as the result of a call to \code{subcrt}, and the citation information for each species involved in the calculation is returned.
\code{checkEOS} compares heat capacity and volume calculated from equation-of-state parameters with reference (tabulated) values at 25 \eqn{^{\circ}}{°}C and 1 bar and prints a message and returns the calculated value if tolerance is exceeded. The Helgeson-Kirkham-Flowers equations of state parameters are in \code{eos}, which is a data frame with columns (and column names) in the same format as \code{\link{thermo}$obigt}. The \code{prop}erty can be one of \samp{Cp} or \code{V}. The code only distinguishes between \code{state}s of \samp{aq} and all others. The default tolerances, given in \code{thermo$opt$Cp.tol} and \code{thermo$opt$V.tol}, are 1 cal/K.mol for Cp and 1 cm3/mol for V. If \code{ret.diff} is TRUE, the differences are returned irrespective of their values, and no messages are printed.
@@ -104,18 +107,19 @@
info(iCl2O)
# add a species with a name that is distinct from the formula
mod.obigt("buckminsterfullerene", formula="C60", state="cr")
+
+# citation information for Helgeson et al., 1998
+thermo.refs("HOK+98")
+# two references for alanine
+thermo.refs(info("alanine"))
+# three references for species in the reaction
+s <- subcrt(c("O2","O2"),c("gas","aq"),c(-1,1))
+thermo.refs(s)
\dontrun{
-## marked dontrun because they open pages in a browser
+## marked dontrun because it opens a browser
# show the contents of thermo$refs
-browse.refs()
-# Internet needed for the following examples:
-# open URL for Helgeson et al., 1998
-browse.refs("HOK+98")
-# open two URLs for alanine
-browse.refs(info("alanine"))
-# open three URLs for species in the reaction
-s <- subcrt(c("O2","O2"),c("gas","aq"),c(-1,1))
-browse.refs(s) }
+thermo.refs()
+}
## calculate thermodynamic properties of organic compounds
## using group additivity, after Richard and Helgeson, 1998
Modified: pkg/CHNOSZ/man/util.water.Rd
===================================================================
--- pkg/CHNOSZ/man/util.water.Rd 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/man/util.water.Rd 2017-02-13 03:26:37 UTC (rev 146)
@@ -73,7 +73,7 @@
\references{
- Archer, D. G. and Wang, P. M. (1990) The dielectric constant of water and Debye-Hückel limiting law slopes. \emph{J. Phys. Chem. Ref. Data} \bold{19}, 371--411. \url{http://www.nist.gov/data/PDFfiles/jpcrd383.pdf}
+ Archer, D. G. and Wang, P. M. (1990) The dielectric constant of water and Debye-Hückel limiting law slopes. \emph{J. Phys. Chem. Ref. Data} \bold{19}, 371--411. \url{https://www.nist.gov/data/PDFfiles/jpcrd383.pdf}
Wagner, W. and Pruß, A. (2002) The IAPWS formulation 1995 for the thermodynamic properties of ordinary water substance for general and scientific use. \emph{J. Phys. Chem. Ref. Data} \bold{31}, 387--535. \url{http://dx.doi.org/10.1063/1.1461829}
Modified: pkg/CHNOSZ/vignettes/anintro.Rmd
===================================================================
--- pkg/CHNOSZ/vignettes/anintro.Rmd 2017-02-12 09:43:41 UTC (rev 145)
+++ pkg/CHNOSZ/vignettes/anintro.Rmd 2017-02-13 03:26:37 UTC (rev 146)
@@ -111,16 +111,16 @@
Suggestions for accessing the documentation are indicated here with <span style="color:blue">blue text</span>.
For example, read <span style="color:blue">`?"CHNOSZ-package"`</span> to get an overview of the package and a list of features.
```{marginfigure}
-That page identifies some features as experimental, i.e. not based on published algorithms or extensively compared with published results.
+That page identifies some features as experimental, i.e. that implement new algorithms and/or have not been extensively compared with published results.
```
## Organization of major functions
CHNOSZ is made up of a set of functions and supporting datasets.
-The major components of the package are shown in the figure below, which is an updated version of the flowchart from @Dic08.
+The major components of the package are shown in the figure below, which is an updated version of the diagram in @Dic08.
Rectangles and ellipses represent functions and datasets; bold text indicates primary functions.
-
+
Many functions in CHNOSZ have no side effects.
That is, the function only returns a result; to use the result elsewhere, it can be assigned to a variable with `<-`.
@@ -155,16 +155,12 @@
data(thermo) ## clear system settings
```
-Some experimental functions are available:
-
-* (**experimental**) using <span style="color:green">`revisit()`</span> to calculate/plot summary statistics of the chemical activities of the species of interest and <span style="color:red">`findit()`</span> to search for combinations of activities of basis species, temperature and/or pressure that optimize those statistics.
-
# Thermodynamic database and chemical formulas
While an attempt has been made to provide a primary database (`OBIGT.csv`) that is generally internally consistent, all thermodynamic data, calculations, and examples are provided *as is*.
```{marginfigure}
For crucial problems, check not only the accuracy of the database, but also the *suitability of the data* for your problem.
-If there is any doubt about the suitability of data, please consult the primary sources (see <span style="color:blue">?`browse.refs`</span>).
+If there is any doubt about the suitability of data, please consult the primary sources (see <span style="color:blue">?`thermo.refs`</span>).
```
Where possible, data with known or suspected inconsistencies have been placed into a secondary database (`OBIGT-2.csv`) that should be regarded as experimental.
@@ -369,7 +365,7 @@
## Automatically balancing reactions
-Methanogenic metabolism in reducing environments may take advantage of acetoclastic or hydrogenotrophic processes.
+Methanogenic metabolism in reducing environments may proceed by acetoclastic or hydrogenotrophic processes.
To consider reactions involving a charged species (acetate), let's define a basis with H<sup>+</sup>:
```{r basis_CHOZ}
basis(c("CO2", "H2", "H2O", "H+"))
@@ -477,10 +473,12 @@
```{r data_thermo, message=FALSE}
```
-# <span style="color:green">`affinity()`</span>, species of interest, and potential diagrams
+# Using affinity
<span style="color:green">`affinity()`</span> offers calculations of chemical affinity of formation reactions over a configurable range of T, P, and activities of basis species.
+## Species of interest
+
By *formation reaction* is meant the stoichiometric requirements for formation of one mole of any species from the basis species.
The <span style="color:red">`species()`</span> function is used to set these *species of interest*.
Let's consider the stoichiometry of some aqueous sulfur-bearing species.
@@ -501,7 +499,7 @@
The values returned by <span style="color:green">`affinity()`</span> are dimensionless, i.e. *A*/2.303*RT*.
```
```{r affinity}
-affinity()$values
+unlist(affinity()$values)
```
The same result (in energetic units) could be obtained using <span style="color:green">`subcrt()`</span>, but <span style="color:green">`affinity()`</span> has the advantage of being able to perform calculations on a grid of *T*, *P*, or activities of basis species.
@@ -521,10 +519,13 @@
a <- affinity(pH = c(0, 12), Eh = c(-1, 1))
diagram(a, fill = "heat")
```
+
Now we can calculate the affinities on an Eh-pH grid:
```{r EhpH_plot, echo=1, eval=FALSE}
```
+## Potential diagrams
+
Given values of affinity, the <span style="color:green">`diagram()`</span> function uses the maximum affinity method to make a potential diagram (i.e. a Pourbaix diagram):
```{r EhpH_plot_echo, eval=FALSE}
diagram(a)
@@ -889,7 +890,7 @@
```{r groups_diagram, fig.fullwidth=TRUE, fig.width=9, fig.height=3, small.mar=TRUE, dpi=dpi, out.width="85%", echo=FALSE, message=FALSE, results="hide", cache=TRUE, pngquant=pngquant}
```
-## Choosing a different balance
+## Using a different balance
How about the choice between balancing constraints?
Be default, <span style="color:green">`equilibrate()`</span> and <span style="color:green">`diagram()`</span> balance reactions on the first basis species that is present in each of the species of interest.
@@ -1103,7 +1104,7 @@
```{marginfigure}
The calculation of *Z*<sub>C</sub>, which sums elemental ratios, is not affected by the choice of basis species.
```
-The "QEC" keyword to <span style="color:red">`basis()`</span> loads basis species with a particular combination of three amino acids (glutamine, glutamic acid, cysteine, `r h2o`, `r o2`) that strengthens the relationship between `r zc` and *n*̅<sub>`r o2`</sub>, but weakens that between *n*̅<sub>`r o2`</sub> and *n*̅<sub>`r h2o`</sub> (right column).
+The `QEC` keyword to <span style="color:red">`basis()`</span> loads basis species with a particular combination of three amino acids (glutamine, glutamic acid, cysteine, `r h2o`, `r o2`) that strengthens the relationship between `r zc` and *n*̅<sub>`r o2`</sub>, but weakens that between *n*̅<sub>`r o2`</sub> and *n*̅<sub>`r h2o`</sub> (right column).
```{r rubisco_O2, fig.margin=TRUE, fig.width=4, fig.height=4, small.mar=TRUE, dpi=dpi, out.width="100%", echo=FALSE, results="hide", message=FALSE, fig.cap="Compositions of proteins projected into different sets of basis species.", cache=TRUE, pngquant=pngquant}
layout(matrix(1:4, nrow = 2))
@@ -1125,7 +1126,7 @@
```{r rubisco_O2, echo=-(1:2), eval=FALSE}
```
-By projecting the compositions of proteins into the "QEC" set of basis species, *n*̅<sub>`r o2`</sub> emerges as a strong indicator of oxidation state, while *n*̅<sub>`r h2o`</sub> is a relatively non-correlated (i.e. independent) compositional variable.
+By projecting the compositions of proteins into the `QEC` set of basis species, *n*̅<sub>`r o2`</sub> emerges as a strong indicator of oxidation state, while *n*̅<sub>`r h2o`</sub> is a relatively non-correlated (i.e. independent) compositional variable.
These independent variables make it easier to distinguish the effects of oxidation and hydration state in proteomic experiments [@Dic17].
## Normalization to residues
@@ -1328,7 +1329,7 @@
a <- affinity(iprotein = ip)
```
-As shown above, the `iprotein` argument of <span style="color:green">`affinity()`</span> can be used to calculate the affinities of reactionsto form the indicated proteins, bypassing the <span style="color:red">`species()`</span> step.
+As shown above, the `iprotein` argument of <span style="color:green">`affinity()`</span> can be used to calculate the affinities of reactions to form the indicated proteins, bypassing the <span style="color:red">`species()`</span> step.
Let's see this in action using amino acid compositions deduced from metagenomic sequences in the Bison Pool hot spring in Yellowstone [@DS11].
We read a data file of amino acid compositions produced in that study, taking those labelled "transferase".
Then we add the proteins and get their indices using <span style="color:red">`add.protein()`</span>, set the basis, calculate the affinities, and make a potential diagram with temperature and activity of dissolved hydrogen as variables:
@@ -1354,7 +1355,7 @@
```
Site numbers 1--5 correspond to a cooling gradient along the outflow channel of the hot spring.
The colors represent the relative `r zc` of the proteins (red is more reduced).
-The dashed line and points show the *T* and log*a*<sub>H<sub>2</sub></sub> that optimize a thermodynamic model for the relative abundances of phyla in the microbial communities [@DS13].
+The dashed line and points show the *T* and log*a*<sub>H<sub>2</sub></sub> that optimize a thermodynamic model for the relative abundances of phyla in the microbial communities [@DS13]:
```{r bison_transferase, eval=FALSE, echo=12:15}
```
@@ -1473,7 +1474,7 @@
```
While running, <span style="color:red">`findit()`</span> sets the activities of basis species, so we can immediately call `ourfun()` to make make a scatter plot.
```{marginfigure}
-The text for <span style="color:red">`findit()`</span> is red because it has side effects (changing the activities of basis species).
+This side effect (changing the activities of basis species) is why the text for <span style="color:red">`findit()`</span> is colored red.
```
```{r smoker_plot, eval=FALSE, echo=23:25}
```
@@ -1485,22 +1486,155 @@
According these calculations, two amino acids, serine and threonine, are very far from metastable equilibrium with the others.
There is a danger of using too many, or unrepresentative variables, but in some systems, calculations of this type may provide insight on processes affecting reactions of organic compounds.
-# Thermodynamic data options
+# Functions outside of the main workflow
-## Source of data: <span style="color:green">`browse.refs()`</span>
+transfer, wjd, eqdata, RH2obigt, EOSregress, anim, taxonomy
-e.g. browse.refs(1)
+Gibbs energy minimization with amino acids: [Cob13]?
-## water: IAPWS or SUPCRT
+# Thermodynamic data
-## secondary database: OBIGT-2
+## Viewing data sources: <span style="color:green">`thermo.refs()`</span>
-## Modifying the database: <span style="color:red">`mod.obigt()`</span>, <span style="color:red">`mod.buffer()`</span>
+The database in CHNOSZ lists one or two sources for each entry, and citation information for the sources is listed in `thermo$refs`.
+You can locate and view the references with <span style="color:green">`thermo.refs()`</span>.
+Running the function without any arguments opens a new window in the web browser with the complete table of references.
+Where available, links to the web page for the article or book are displayed.
+```{r thermo_refs_table, eval=FALSE}
+thermo.refs() ## shows table in a browser
+```
+A numeric argument to <span style="color:green">`thermo.refs()`</span> is one or more species indices for which to get the references:
+```{r thermo_refs_numeric}
+iATP <- info("ATP-4")
+iMgATP <- info("MgATP-2")
+thermo.refs(c(iATP, iMgATP))
+```
+
+A character argument gives the source key(s):
+```{r thermo_refs_character}
+thermo.refs(c("HDN+78", "MGN03"))
+```
+
+For a list, the result of <span style="color:green">`subcrt()`</span>, references for all species in the reaction are returned:
+```{marginfigure}
+The exception is H<sub>2</sub>O.
+With the default settings, thermodynamic properties for H<sub>2</sub>O are derived from SUPCRT92 (Johnson et al., 1992).
+```
+```{r thermo_refs_subcrt, message=FALSE}
+sout <- subcrt(c("C2H5OH", "O2", "CO2", "H2O"), c(-1, -3, 2, 3))
+thermo.refs(sout)
+```
+
+The URLs of the references can be copied to a browser, or opened using R's `browseURL()`:
+```{r thermo_refs_browse, eval=FALSE}
+iFo <- info("forsterite")
+ref <- thermo.refs(iFo)
+browseURL(ref$URL) ## opens a page on worldcat.org
+```
+
+## Water: IAPWS or SUPCRT
+
+XXX
+
+## Adding data
+
+Use <span style="color:red">`add.obigt()`</span> to add data to the database in the current session.
+
+Without any arguments, <span style="color:red">`add.obigt()`</span> adds data from the secondary data file (`OBIGT-2.csv`).
+There are ca. 300 species listed here, many of which are not present in the main database.
+However, many of these datasets include one or more species that are already present in the main database, but have different parameters.
+Therefore, these data could not be included in the main database without breaking internal consistency.
+Some of the datasets here may have incomplete or have provisional data.
+Please check the references!
+
+Given a file name, <span style="color:red">`add.obigt()`</span> adds data in that file to database in the running session.
+The file must be a CSV (comma separated value) file with column headers that match those in the main database.
+To show the requred format, we print here the first few lines of `OBIGT-2.csv`.
+Note that missing values are assigned `NA`:
+```{marginfigure}
+R's `read.csv()` has a useful option: `as.is = TRUE`.
+This prevents columns with character data from being read as factors (i.e. categorical data).
+Passing factor arguments to some functions that are designed for character data can give unexpected results or errors.
+```
+```{r obigt_file, echo=1:2}
+file <- system.file("extdata/thermo/OBIGT-2.csv", package = "CHNOSZ")
+dat <- read.csv(file, as.is = TRUE)
+head(dat, 3)
+```
+
+The column names with a dot (`.`) refer to different sets of equations for calculating standard thermodynamic properties.
+Aqueous species use the revised Helgeson-Kirkham-Flowers (HKF) equations (symbols before the dot), and crystalline, gas and liquid species other than `r h2o` use a general heat capacity equation.
+See <span style="color:blue">`?thermo`</span> for details about what's in the data table, and <span style="color:blue">`?hkf`</span> and <span style="color:blue">`?cgl`</span> for information about the thermodynamic equations.
+
+## Modifying data
+
+Use <span style="color:red">`mod.obigt()`</span> to add or modify the database in the current session.
+The function requires the name of a species and one or more properties to change.
+Let's add data for the S<sub>3</sub><sup>-</sup> ion from @PD15.
+Although we could choose anything for the name (e.g. "trisulfur radical anion"), here we make it the same as the formula.
+The date for the entry is <span style="color:green">`today()`</span> (i.e. today's date using the date format inherited from SUPCRT92):
+```{r mod_obigt_S3_ghs, echo=1:2}
+mod.obigt("S3-", formula = "S3-", state = "aq", ref1 = "PD15", date = today(),
+ G = 13160, H = 10840, S = 28.6, Cp = 62.3, V = 37.7)
+```
+
+The function prints a message saying that the species was added, and returns the species index of the new species.
+Now let's modify the same species by adding the HKF coefficients:
+```{r mod_obigt_S3_eos, echo=1:2}
+mod.obigt("S3-", state = "aq", a1 = 2.5, a2 = 19.9, a3 = 9.2, a4 = -3.6,
+ c1 = 50.2, c2 = 9.6, omega = 0.8, z = -1)
+```
+
+Let's add it as a basis species to automatically balance the reaction of SO<sub>4</sub><sup>-2</sup> and 2 H<sub>2</sub>S:
+```{r S3_reaction, message=FALSE}
+basis(c("S3-", "O2", "H2O", "H+"))
+basis("O2", "gas")
+subcrt(c("H2S", "SO4-2"), c(-2, -1), T = c(25, 500), P = c(1, 700))
+```
+
+The reaction coefficients are identical to Reaction 4 of Pokrovski and Dubessy (2015), and the calculated values of log*K* match those shown in their Figure 5.
+
+## Cross-checking data entries
+
+<span style="color:green">`info()`</span> automatically performs some cross-checks of the thermodynamic data.
+```{marginfigure}
+This only checks the parameters for individual species, not the internal consistency of the database itself.
+```
+Let's do this for the new S<sub>3</sub><sup>-</sup> species:
+```{r info_S3}
+iS3 <- info("S3-")
+info(iS3)
+```
+
+Here, <span style="color:green">`checkGHS()`</span> calculated the value of Δ*G*°<sub>*f*</sub> from those of Δ*H*°<sub>*f*</sub> and *S*° entered for the species and from the entropy of the elements [@CWM89] in the formula entered for the species.
+If the difference between the entered and calculated values of Δ*G*°<sub>*f*</sub> is greater than 100 cal mol<sup>-1</sup>, <span style="color:green">`checkGHS()`</span> prints a message.
+Here, the calculated value of Δ*G*°<sub>*f*</sub> was found to be 661 cal mol<sup>-1</sup> higher than the entered value.
+Besides double-checking the values entered for Δ*G*°<sub>*f*</sub>, Δ*H*°<sub>*f*</sub>, *S*°, and the chemical formula, the source should be consulted for further clarification.
+
+Some species in the main and secondary databases are known to have inconsistent entries.
+For example, the entry for cyclohexane has *C*<sub>*P*</sub>° and *V*° that differ from those calculated from the HKF parameters.
+<span style="color:green">`checkEOS()`</span> is a function that cross-checks these parameters and reports the differences (greater than 1 cm<sup>3</sup> mol<sup>-1</sup> or 1 cal K<sup>-1</sup> mol<sup>-1</sup>) when <span style="color:green">`info()`</span> is run:
+```{r info_cyclohexane, message=FALSE, results="hide"}
+info(info("cyclohexane"))
+## checkEOS: Cp of cyclohexane aq (1762) differs by 9.35 cal K-1 mol-1 from tabulated value
+## checkEOS: V of cyclohexane aq (1762) differs by 6.64 cm3 mol-1 from tabulated value
+```
+
+The species in with detected inconsistencies in `OBIGT.csv` and `OBIGT-2.csv` are listed in the file `obigt_check.csv`.
+```{r check_obigt}
+file <- system.file("extdata/thermo/obigt_check.csv", package = "CHNOSZ")
+dat <- read.csv(file, as.is=TRUE)
+nrow(dat)
+```
+
+Without additional information, there is often no clear strategy for "fixing" these entries, and they are provided as-is.
+```{marginfigure}
+See the [Numerical Tools at GEOPIG](http://geopig.asu.edu/tools) for SUPCRT updates (slop files), including corrections that have not yet been ported to CHNOSZ.
+```
+
# Diagnosing problems
-## Checking database consistency
-
## Tests; errors
e.g. "variables define a transect but their lengths are not all equal"
@@ -1508,17 +1642,15 @@
## Messages from functions
(Look at messages in calculation above: groups, ER-to-Golgi?)
+subcrt(c("C2H5OH", "O2", "CO2", "H2O"), c(-1, -3, 2, 3))
-# Functions outside of the main workflow
-
-transfer, wjd, eqdata, RH2obigt, EOSregress, anim, taxonomy
-
-Gibbs energy minimization with amino acids: [Cob13]?
-
# Document history
* 2010-09-30 Initial version.
* 2011-08-15 Add <span style="color:green">`browse.refs()`</span>; modifying database hint changed to <span style="color:blue">`help(thermo)`</span>.
+```{marginfigure}
+<span style="color:green">`browse.refs()`</span> changed to <span style="color:green">`thermo.refs()`</span> in 2017.
+```
* 2012-06-16 Add “More activity diagrams”.
* 2015-05-14 Add warning about internal consistency of thermodynamic data.
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/chnosz -r 146
More information about the CHNOSZ-commits
mailing list