[CHNOSZ-commits] r274 - in pkg/CHNOSZ: . R inst man vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Nov 1 05:17:03 CET 2017
Author: jedick
Date: 2017-11-01 05:17:02 +0100 (Wed, 01 Nov 2017)
New Revision: 274
Modified:
pkg/CHNOSZ/DESCRIPTION
pkg/CHNOSZ/R/affinity.R
pkg/CHNOSZ/R/diagram.R
pkg/CHNOSZ/R/util.expression.R
pkg/CHNOSZ/inst/NEWS
pkg/CHNOSZ/man/diagram.Rd
pkg/CHNOSZ/man/util.expression.Rd
pkg/CHNOSZ/vignettes/anintro.Rmd
Log:
axis.label() etc.: add 'use.molality' argument; update and reorganize diagram.Rd
Modified: pkg/CHNOSZ/DESCRIPTION
===================================================================
--- pkg/CHNOSZ/DESCRIPTION 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/DESCRIPTION 2017-11-01 04:17:02 UTC (rev 274)
@@ -1,6 +1,6 @@
-Date: 2017-10-31
+Date: 2017-11-01
Package: CHNOSZ
-Version: 1.1.0-72
+Version: 1.1.0-73
Title: Thermodynamic Calculations for Geobiochemistry
Author: Jeffrey Dick
Maintainer: Jeffrey Dick <j3ffdick at gmail.com>
Modified: pkg/CHNOSZ/R/affinity.R
===================================================================
--- pkg/CHNOSZ/R/affinity.R 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/R/affinity.R 2017-11-01 04:17:02 UTC (rev 274)
@@ -247,9 +247,12 @@
# content of return value depends on buffer request
if(return.buffer) return(c(tb, list(vars=vars, vals=vals)))
- a <- list(sout=sout, property=property, basis=mybasis, species=myspecies, T=T, P=P, vars=vars, vals=vals, values=a)
+ # add IS value only if it given as an argument 20171101
+ # (even if its value is 0, the presence of IS will trigger diagram() to use "m" instead of "a" in axis labels)
+ iIS <- match("IS", names(args.orig))
+ if(!is.na(iIS)) a <- list(sout=sout, property=property, basis=mybasis, species=myspecies, T=T, P=P, IS=args$IS, vars=vars, vals=vals, values=a)
+ else a <- list(sout=sout, property=property, basis=mybasis, species=myspecies, T=T, P=P, vars=vars, vals=vals, values=a)
if(buffer) a <- c(a, list(buffer=tb))
return(a)
-
}
Modified: pkg/CHNOSZ/R/diagram.R
===================================================================
--- pkg/CHNOSZ/R/diagram.R 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/R/diagram.R 2017-11-01 04:17:02 UTC (rev 274)
@@ -5,6 +5,11 @@
# gather plotvals independently of plot parameters (including nd),
# single return statement
+## if this file is interactively sourced, the following are also needed to provide unexported functions:
+#source("equilibrate.R")
+#source("util.plot.R")
+#source("util.character.R")
+
diagram <- function(
# primary input
eout,
@@ -84,6 +89,9 @@
# length(dim(eout$values[[1]])) - nd=1 if it was a transect along multiple variables
nd <- min(length(eout$vars), length(dim(eout$values[[1]])))
+ ## use molality instead of activity if the affinity calculation include ionic strength 20171101
+ use.molality <- "IS" %in% names(eout)
+
## when can normalize and as.residue be used
if(normalize | as.residue) {
if(normalize & as.residue) stop("'normalize' and 'as.residue' can not both be TRUE")
@@ -246,7 +254,7 @@
### 0-D diagram - bar graph of properties of species or reactions
# plot setup
- if(missing(ylab)) ylab <- axis.label(plotvar, units="")
+ if(missing(ylab)) ylab <- axis.label(plotvar, units="", use.molality=use.molality)
barplot(unlist(plotvals), names.arg=names, ylab=ylab, cex.names=cex.names, col=col, ...)
if(!is.null(main)) title(main=main)
@@ -256,9 +264,9 @@
xvalues <- eout$vals[[1]]
# initialize the plot
if(!add) {
- if(missing(xlab)) xlab <- axis.label(eout$vars[1], basis=eout$basis)
+ if(missing(xlab)) xlab <- axis.label(eout$vars[1], basis=eout$basis, use.molality=use.molality)
if(missing(xlim)) xlim <- range(xvalues) # TODO: this is backward if the vals are not increasing
- if(missing(ylab)) ylab <- axis.label(plotvar, units="")
+ if(missing(ylab)) ylab <- axis.label(plotvar, units="", use.molality=use.molality)
# to get range for y-axis, use only those points that are in the xrange
if(is.null(ylim)) {
isx <- xvalues >= min(xlim) & xvalues <= max(xlim)
@@ -499,8 +507,8 @@
ylim <- c(ys[1], tail(ys, 1))
# initialize the plot
if(!add) {
- if(is.null(xlab)) xlab <- axis.label(eout$vars[1], basis=eout$basis)
- if(is.null(ylab)) ylab <- axis.label(eout$vars[2], basis=eout$basis)
+ if(is.null(xlab)) xlab <- axis.label(eout$vars[1], basis=eout$basis, use.molality=use.molality)
+ if(is.null(ylab)) ylab <- axis.label(eout$vars[2], basis=eout$basis, use.molality=use.molality)
if(tplot) thermo.plot.new(xlim=xlim, ylim=ylim, xlab=xlab, ylab=ylab,
cex=cex, cex.axis=cex.axis, mar=mar, yline=yline, side=side, ...)
else plot(0, 0, type="n", xlim=xlim, ylim=ylim, xlab=xlab, ylab=ylab, ...)
Modified: pkg/CHNOSZ/R/util.expression.R
===================================================================
--- pkg/CHNOSZ/R/util.expression.R 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/R/util.expression.R 2017-11-01 04:17:02 UTC (rev 274)
@@ -2,7 +2,7 @@
# write descriptions of chemical species, properties, reactions, conditions
# modified from describe(), axis.label() 20120121 jmd
-expr.species <- function(species, state="", log="", value=NULL, use.makeup=FALSE) {
+expr.species <- function(species, state="", log="", value=NULL, use.makeup=FALSE, use.molality=FALSE) {
# make plotting expressions for chemical formulas
# that include subscripts, superscripts (if charged)
# and optionally designations of states +/- loga or logf prefix
@@ -54,8 +54,12 @@
else expr <- substitute(a[group('(',italic(b),')')],list(a=expr, b=state))
}
# write logarithm of activity or fugacity
+ # (or molality 20171101)
if(log != "") {
- if(log %in% c("aq", "cr", "liq", "cr2", "cr3", "cr4")) acity <- "a"
+ if(log == "aq") {
+ if(use.molality) acity <- "m"
+ else acity <- "a"
+ } else if(log %in% c("cr", "liq", "cr2", "cr3", "cr4")) acity <- "a"
else if(log %in% c("g", "gas")) acity <- "f"
else stop(paste("'", log, "' is not a recognized state", sep=""))
logacity <- substitute(log~italic(a), list(a=acity))
@@ -68,7 +72,7 @@
return(expr)
}
-expr.property <- function(property) {
+expr.property <- function(property, use.molality=FALSE) {
# a way to make expressions for various properties
# e.g. expr.property('DG0r') for standard molal Gibbs
# energy change of reaction
@@ -77,7 +81,10 @@
# some special cases
if(property=="logK") return(quote(log~italic(K)))
# grepl here b/c diagram() uses "loga.equil" and "loga.basis"
- if(grepl("loga", property)) return(quote(log~italic(a)))
+ if(grepl("loga", property)) {
+ if(use.molality) return(quote(log~italic(m)))
+ else return(quote(log~italic(a)))
+ }
if(property=="alpha") return(quote(alpha))
if(property=="Eh") return("Eh")
if(property=="pH") return("pH")
@@ -149,7 +156,7 @@
return(expr)
}
-axis.label <- function(label, units=NULL, basis=get("thermo")$basis, prefix="") {
+axis.label <- function(label, units=NULL, basis=get("thermo")$basis, prefix="", use.molality=FALSE) {
# make a formatted axis label from a generic description
# it can be a chemical property, condition, or chemical activity in the system
# if the label matches one of the basis species
@@ -161,11 +168,11 @@
# 20090215: the state this basis species is in
state <- basis$state[match(label, rownames(basis))]
# get the formatted label
- desc <- expr.species(label, log=state)
+ desc <- expr.species(label, log=state, use.molality=use.molality)
} else {
# the label is for a chemical property or condition
# make the label by putting a comma between the property and the units
- property <- expr.property(label)
+ property <- expr.property(label, use.molality=use.molality)
if(is.null(units)) units <- expr.units(label, prefix=prefix)
# no comma needed if there are no units
if(units=="") desc <- substitute(a, list(a=property))
Modified: pkg/CHNOSZ/inst/NEWS
===================================================================
--- pkg/CHNOSZ/inst/NEWS 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/inst/NEWS 2017-11-01 04:17:02 UTC (rev 274)
@@ -1,4 +1,4 @@
-CHANGES IN CHNOSZ 1.1.0-70 (2017-10-30)
+CHANGES IN CHNOSZ 1.1.0-73 (2017-11-01)
---------------------------------------
MAJOR CHANGES:
@@ -116,9 +116,34 @@
OTHER CHANGES:
+- Add test-logmolality.R to demonstrate transformation of variables from
+ activity to molality in the main workflow; refer to this test and
+ describe these transformations in anintro.Rmd; remove "experimental"
+ labeling of activity coefficient calculations in CHNOSZ-package.Rd.
+
+- Add 'use.molality' argument to axis.label() and supporting functions.
+ So that the labels on diagrams are changed from activity (a) to
+ molality (m), this argument is set to TRUE by diagram() when IS is
+ supplied as an argument to affinity().
+
+- Add demo TCA.R for standard Gibbs energies of steps of the
+ citric acid cycle (Canovas and Shock, 2016).
+
+- Components of subcrt() output indicating the stable polymorph of
+ minerals with phase transitions are now named 'polymorph', not
+ 'state'.
+
+- Add maxdiff() and expect_maxdiff() for calculating and testing the
+ maximum absolute pairwise difference between two objects.
+ expect_maxdiff() is used in tests/testthat/*.R as a more
+ straightforward alternative for checking differences than using
+ 'tolerance' in expect_equal().
+
- Add 'tol' argument to equil.reaction() (convergence tolerance for
uniroot()).
+REFACTORING AND CLEANUP:
+
- In hkf() and cgl(), combine 'ghs' and 'eos' arguments into single
argument named 'parameters'.
@@ -133,23 +158,6 @@
- In water.* functions, rename the "diel" variable to "epsilon".
-- Components of subcrt() output indicating the stable polymorph of
- minerals with phase transitions are now named 'polymorph', not
- 'state'.
-
-- Add maxdiff() and expect_maxdiff() for calculating and testing the
- maximum absolute pairwise difference between two objects.
-
-- Add demo TCA.R for standard Gibbs energies of steps of the
- citric acid cycle (Canovas and Shock, 2016).
-
-- Add test-logmolality.R to demonstrate transformation of variables from
- activity to molality in the main workflow; refer to this test and
- describe these transformations in anintro.Rmd; remove "experimental"
- labeling of activity coefficient calculations in CHNOSZ-package.Rd.
-
-CLEANUP:
-
- To save space, taxid_names.csv has been trimmed to hold only those
taxids listed in extdata/bison/gi.taxid.txt.
Modified: pkg/CHNOSZ/man/diagram.Rd
===================================================================
--- pkg/CHNOSZ/man/diagram.Rd 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/man/diagram.Rd 2017-11-01 04:17:02 UTC (rev 274)
@@ -79,16 +79,31 @@
2-D diagrams, for two variables, are plotted as predominance fields.
The allowed variables are any that \code{\link{affinity}} accepts: temperature, pressure, or the chemical activities of the basis species
-If \code{alpha} is TRUE, the fractional degrees of formation (ratios of activities to total activity) are plotted.
-Or, setting \code{alpha} to \samp{balance} allows the activities to be multiplied by the number of the balancing component; this is useful for making \dQuote{percent carbon} diagrams where the species differ in carbon number.
If \code{groups} is supplied, the activities of the species identified in each numeric element of this list are multiplied by the balance coefficients of the species, then summed together.
The names of the list are used to label the lines or fields for the summed activities of the resulting groups.
+For all diagrams, the \code{names} of the species and their colors in \code{col.names} can be changed, as can \code{cex}, \code{cex.names}, and \code{cex.axis} to adjust the overall character expansion factors (see \code{\link{par}}) and those of the species names and axis labels.
+The x- and y-axis labels are automatically generated unless they are supplied in \code{xlab} and \code{ylab}.
+A new plot is started unless \code{add} is TRUE.
+If \code{plot.it} is FALSE, no plot will be generated but all the intermediate computations will be performed and the results returned.
+
+\code{find.tp} finds the locations in a matrix of integers that are surrounded by the greatest number of different values.
+The function counts the unique values in a 3x3 grid around each point and returns a matrix of indices (similar to \code{\link{which}(..., arr.ind = TRUE)}) for the maximum count (ties result in more than one pair of indices).
+It can be used with the output from \code{diagram} for calculations in 2 dimensions to approximately locate the triple points on the diagram.
+
+}
+
+\section{1-D diagrams}{
For 1-D diagrams, the default setting for the y-axis is a logarithmic scale (unless \code{alpha} is TRUE) with limits corresponding to the range of logarithms of activities (or 0,1 if \code{alpha} is TRUE); these actions can be overridden by \code{ylog} and \code{ylim}.
If \code{legend.x} is NA (the default), the lines are labeled with the names of the species near the maximum value.
Otherwise, a \code{\link{legend}} is placed at the location identified by \code{legend.x}, or omitted if \code{legend.x} is NULL.
+
+If \code{alpha} is TRUE, the fractional degrees of formation (ratios of activities to total activity) are plotted.
+Or, setting \code{alpha} to \samp{balance} allows the activities to be multiplied by the number of the balancing component; this is useful for making \dQuote{percent carbon} diagrams where the species differ in carbon number.
The line type and line width can be controlled with \code{lty} and \code{lwd}, respectively.
+}
+\section{2-D diagrams}{
On 2-D diagrams, the fields represent the species with the highest equilibrium activity.
\code{fill} determines the color of the predominance fields, \code{col} that of the boundary lines.
By default, \code{\link{heat.colors}} are used to fill the predominance fields in diagrams on the screen plot device.
@@ -97,8 +112,7 @@
\code{fill.NA} is also used to specify the color outside the water stability limits on Eh-pH or pe-pH diagrams, when \code{limit.water} is TRUE.
Note that the default for \code{fill.NA} is automatically changed to \samp{transparent} when \code{add} is TRUE.
-In CHNOSZ 1.1.0, a new default line-drawing procedure has been implemented.
-This uses \code{\link{contour}} to draw smooth-looking diagonal and curved lines, at the expense of not coinciding exactly with the rectangular grid (which is still used for drawing colors).
+The default line-drawing algorithm uses \code{\link{contour}} to draw smooth-looking diagonal and curved lines, at the expense of not coinciding exactly with the rectangular grid (which is still used for drawing colors).
\code{lty}, \code{col}, and \code{lwd} can be specified, but limiting the lines via \code{xrange} is not currently supported.
To go back to the old behavior for drawing lines, set \code{dotted} to \samp{0}.
The old behavior does not follow \code{lty}; instead, the style of the boundary lines on 2-D diagrams can be altered by supplying one or more non-zero integers in \code{dotted}, which indicates the fraction of line segments to omit; a value of \samp{1} or NULL for \code{dotted} has the effect of not drawing the boundary lines.
@@ -106,25 +120,28 @@
\code{normalize} and \code{as.residue} apply only to the 2-D diagrams, and only when \code{eout} is the output from \code{affinity}.
With \code{normalize}, the activity boundaries are calculated as between the residues of the species (the species divided by the balance coefficients), then the activities are rescaled to the whole species formulas.
With \code{as.residue}, the activity boundaries are calculated as between the residues of the species, and no rescaling is performed.
+}
-For all diagrams, the \code{names} of the species and their colors in \code{col.names} can be changed, as can \code{cex}, \code{cex.names}, and \code{cex.axis} to adjust the overall character expansion factors (see \code{\link{par}}) and those of the species names and axis labels.
-The x- and y-axis labels are automatically generated unless they are supplied in \code{xlab} and \code{ylab}.
-A new plot is started unless \code{add} is TRUE.
-If \code{plot.it} is FALSE, no plot will be generated but all the intermediate computations will be performed and the results returned.
+\section{Affinity Diagrams}{
+The function behaves differently when the output from \code{affinity} is being used instead of the equilibrium activities from \code{equilibrate}.
+If \code{what} is missing, and the number of dimensions is 0 or 1, a property of a reaction, such as the equilibrium constant (\samp{logK}), is plotted.
-\code{diagram} also accepts the output from \code{\link{affinity}}, for which three actions are possible:
-1) plot a property of a reaction, such as the equilibrium constant (\samp{logK}) (0-D or 1-D);
-2) plot the equilibrium activity of a selected basis species in all of the formation reactions (0-D, 1-D or 2-D);
-3) plot predominance fields, based on the relative magnitudes of the affinities of the formation reactions (2-D only).
+If \code{what} is missing, and the number of dimensions is 2, then highest potential (equilibrium predominance) fields are plotted.
+This algorithm is based on comparing the relative magnitudes of the affinities of the formation reactions, also referred to as the maximum affinity method.
+In this case, the balancing coefficients are determined usingi the \code{balance} argument.
-Some of the arguments have different effects when the output from \code{affinity} is being used instead of the equilibrium activities from \code{equilibrate}.
-If \code{what} is missing, option (1) is selected if the number of dimensions is 0 or 1, and option (3) is selected if the number of dimensions is 2.
-The latter is referred to as the maximum affinity method.
-In cases where it applies (see Warning), the maximum affinity method is much faster than an equilibrium calculation.
-\code{balance} is the option that determines the balancing coefficients (this argument has no effect on the calculations of equilibrium activities.)
-If \code{what} is the name of a basis species, it refers to option (2) above.
+If \code{what} is the name of a basis species, it indicates to plot the equilibrium activity of a selected basis species in all of the formation reactions.
A contour plot is made in the case of 2-D diagrams of the equilibrium activity of a basis species (see the \CO2-acetic acid example in \code{\link{buffer}}, and only the first species of interest is used in the calculation; a warning is produced if there is more than one.
+}
+\section{Activity Coefficients}{
+The wording in this page and names of variables in functions refer exclusively to \samp{activities} of aqueous species.
+However, if activity coefficients are calculated (using the \code{IS} argument in \code{\link{affinity}}), then these variables are effectively transformed to molalities (see \code{tests/testthat/test-logmolality.R}).
+So that the labels on diagrams are adjusted accordingly, \code{\link{diagram}} sets the \code{use.molality} argument of \code{\link{axis.label}} to TRUE if \code{IS} was supplied as an argument to \code{\link{affinity}}.
+The labeling as molality takes effect even if \code{IS} is set to 0; this way, by including (or not) the \code{IS = 0} argument to \code{affinity}, the user decides whether to label aqueous species variables as molality (or activity) for calculations at zero ionic strength (where molality = activity).
+}
+
+\section{Strip Diagrams}{
A different incarnation of 1-D speciation diagrams is provided by \code{strip}.
This function generates any number of strip diagrams in a single plot.
The diagrams are made up of colors bars whose heights represent the relative abundances of species; the color bars are arranged in order of abundance and the total height of the stack of colors bars is constant.
@@ -135,25 +152,13 @@
\code{ymin} can be decreased in order to add more space at the bottom of the plot, and \code{xpad} can be changed in order to increase or decrease the size of the x-axis relative to the width of the strips.
An inset dot-and-line plot is created below each strip if \code{ns} is given.
This argument has the same format as \code{ispecies}, and can be used e.g. to display the relative numbers of species for comparison with the stability calculations.
-
-\code{find.tp} finds the locations in a matrix of integers that are surrounded by the greatest number of different values.
-The function counts the unique values in a 3x3 grid around each point and returns a matrix of indices (similar to \code{\link{which}(..., arr.ind = TRUE)}) for the maximum count (ties result in more than one pair of indices).
-It can be used with the output from \code{diagram} for calculations in 2 dimensions to approximately locate the triple points on the diagram.
-
}
\value{
- For speciation diagrams, an \code{\link{invisible}} list of the chemical activities of the species, or their degrees of formation (if \code{alpha} is \code{TRUE}), at each point. For predominance diagrams, an invisible list with elements \code{species}, the dataframe describing the species, \code{out}, which species predominates at each grid point, and \code{A}, a list of the calculated values of the chemical affinity (per balanced quantity) (log10 dimensionless) at each point.
+For speciation diagrams (1-D), an \code{\link{invisible}} list of the chemical activities of the species, or their degrees of formation (if \code{alpha} is \code{TRUE}), at each point.
+For predominance diagrams (2-D), an invisible list with elements \code{species}, the dataframe describing the species, \code{out}, which species predominates at each grid point, and \code{A}, a list of the calculated values of the chemical affinity (per balanced quantity) (log10 dimensionless) at each point.
}
-\section{Warning}{
-The maximum affinity method is premised on the calculation of the affinities of formation reactions at equal activities of the species of interest.
-Then, the species with the highest affinity of formation, after normalization by the balancing coefficients, corresponds to the predominant species in an equilibrium calculation.
-The examples below \dQuote{work} because they are relatively simple - the balancing coefficients are unity or all the same value (aqueous aluminum example), or the species are solids with unit activities (the mineral examples).
-The examples shown for \code{\link{protein}s} elsewhere also take the balancing coefficients to unity, after normalizing by protein length.
-However, if aqueous species are present with different balancing coefficients, the maximum affinity method may produce unintended results.
-}
-
\seealso{
Other examples are present in the help for \code{\link{protein}} and \code{\link{buffer}}, and even more can be found in \code{\link{demos}}.
See the vignette \emph{Hot-spring proteins in CHNOSZ} for an example of the \code{strip} charts.
Modified: pkg/CHNOSZ/man/util.expression.Rd
===================================================================
--- pkg/CHNOSZ/man/util.expression.Rd 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/man/util.expression.Rd 2017-11-01 04:17:02 UTC (rev 274)
@@ -14,10 +14,12 @@
\description{Generate expressions suitable for axis labels and plot legends describing chemical species, properties and reactions.}
\usage{
- expr.species(species, state = "", log = "", value=NULL, use.makeup=FALSE)
- expr.property(property)
+ expr.species(species, state = "", log = "", value=NULL, use.makeup=FALSE,
+ use.molality = FALSE)
+ expr.property(property, use.molality = FALSE)
expr.units(property, prefix = "", per = "mol")
- axis.label(label, units = NULL, basis = get("thermo")$basis, prefix = "")
+ axis.label(label, units = NULL, basis = get("thermo")$basis, prefix = "",
+ use.molality = FALSE)
describe.basis(basis = get("thermo")$basis, ibasis = 1:nrow(basis),
digits = 1, oneline = FALSE)
describe.property(property, value, digits = 0, oneline = FALSE,
@@ -33,6 +35,7 @@
\item{log}{character, designation of physical state (for logarithm of activity or fugacity)}
\item{value}{numeric, logarithm of activity or fugacity of species, or value of other property}
\item{use.makeup}{logical, use \code{\link{makeup}} to count the elements?}
+ \item{use.molality}{logical, use molality (m) instead of activity (a) for aqueous species?}
\item{property}{character, description of chemical property}
\item{prefix}{character, prefix for units}
\item{per}{character, denominator in units}
@@ -92,7 +95,11 @@
If none of those characters appears in the property, the expression is an empty character (no units). If a \code{prefix} is given, it is added to the expression. The denominator of the units (default \samp{mol}) is taken from the \code{per} argument; it is applied to all units except for \samp{P}, \samp{T}, \samp{Eh}, and \samp{IS}.
- \code{axis.label} accepts a generic description of a \code{label}. If this matches the chemical formula of one of the basis species in the \code{basis} argument, the expression for the label is generated using \code{expr.species} with \code{log} set to the physical state of the basis species. Otherwise, the expression is built by combining the output of \code{expr.property} with \code{expr.units} (or the value in \code{units}, if it is supplied), placing a comma between the two. This function is used extensively in \code{\link{diagram}} and also appears in many of the examples.
+\code{axis.label} accepts a generic description of a \code{label}.
+If this matches the chemical formula of one of the basis species in the \code{basis} argument, the expression for the label is generated using \code{expr.species} with \code{log} set to the physical state of the basis species.
+Otherwise, the expression is built by combining the output of \code{expr.property} with \code{expr.units} (or the value in \code{units}, if it is supplied), placing a comma between the two.
+This function is used extensively in \code{\link{diagram}} and also appears in many of the examples.
+Note that \code{\link{diagram}} sets \code{use.molality} to TRUE if \code{IS} was supplied as an argument to \code{\link{affinity}}.
\code{describe.basis} makes an expression summarizing the basis species definition (logarithms of activity or fugacity of the basis species) provided in \code{basis}; only the basis species identified by \code{ibasis} are included.
Modified: pkg/CHNOSZ/vignettes/anintro.Rmd
===================================================================
--- pkg/CHNOSZ/vignettes/anintro.Rmd 2017-10-31 14:46:29 UTC (rev 273)
+++ pkg/CHNOSZ/vignettes/anintro.Rmd 2017-11-01 04:17:02 UTC (rev 274)
@@ -1047,7 +1047,7 @@
# Activity coefficients
-<span style="color:green">`nonideal()`</span> uses the extended Debye--Hückel equation as formulated by @HKF81 for NaCl-dominated solutions, or optionally using parameters described in Chapter 3 of @Alb03, to calculate activity coefficients of charged species.
+For calculating activity coefficients of charged species, <span style="color:green">`nonideal()`</span> uses the extended Debye--Hückel equation as parameterized by @HKF81 for NaCl-dominated solutions to high pressure and temperature, or optionally using parameters described in Chapter 3 of @Alb03, which are applicable to relatively low-temperature biochemical reactions.
The activity coefficients are calculated as a function of ionic strength (*I*), temperature, and charge of each species, without any other species-specific parameters.
Using the default `Helgeson` method, the extended term parameter ("B-dot") is derived from data of @Hel69 and Helgeson et al. (1981), and extrapolations of @MSS13.
@@ -1074,8 +1074,8 @@
In other words, the activation of activity coefficients effects a transformation from activity to molality in the main workflow.
A simple but comprehensive series of calculations demonstrating these tranformations is in `tests/testthat/test-logmolality.R`.
-Because it is not possible to dynamically change the names of arguments in the functions, the user should be aware of the effects mentioned above.
-As another consequence, activities of basis species or equilibrium activities of species shown on diagrams should be relabeled as molalities when `IS` is used in the calculation of <span style="color:green">`affinity()`</span>.
+Because it is not possible to dynamically change the names of arguments in the functions, the user should be aware of the transformations mentioned above.
+However, the labels on diagrams *can* be automatically adjusted; accordingly, activities of aqueous species are relabeled as molalities by <span style="color:green">`diagram()`</span> when `IS` is used in the calculation of <span style="color:green">`affinity()`</span>.
## Biochemical example
More information about the CHNOSZ-commits
mailing list