util.expression {CHNOSZ}R Documentation

Functions to Express Chemical Formulas and Properties


Generate expressions suitable for axis labels and plot legends describing chemical species, properties and reactions.


  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 = "",
    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,
    ret.val = FALSE)
  describe.reaction(reaction, iname = numeric(), states = NULL)
  syslab(system = c("K2O", "Al2O3", "SiO2", "H2O"), dash="\u2013")
  ratlab(ion = "K+")



character, formula of a chemical species


character, designation of physical state


character, designation of physical state (for logarithm of activity or fugacity)


numeric, logarithm of activity or fugacity of species, or value of other property


logical, use makeup to count the elements?


logical, use molality (m) instead of activity (a) for aqueous species?


character, description of chemical property


character, prefix for units


character, denominator in units


character, description of species, condition or property


character, description of units


data frame, definition of basis species


numeric, which basis species to include


numeric, number of digits to show after decimal point


logical, make descriptions occupy a single line?


logical, return only the value with the units?


data frame, definition of reaction


numeric, show names instead of formulas for these species


character, if all, show states for all species


character, thermodynamic components


character to use for dash between components


character, an ion


The expr.* functions create expressions using the plotmath syntax to describe the names and states and logarithms of activity or fugacity of chemical species, conditions including temperature and pressure and chemical properties such as Gibbs energy and volume.

expr.species takes as input the formula of a single chemical species and constructs an expression including subscripted coefficients, and a suffixed designation of physical state (italicized, in parentheses) if provided. If log designates a physical state (as in thermo$obigt$state), the expression includes a log prefix, followed by f for fugacity of gaseous species, or a for activity of species in all other states. Set use.makeup to TRUE to use makeup to parse the chemical formula. This can have the undesirable effect of reordering and grouping all the elements, and has been replaced with a different splitting algorithm so that coefficients and charges are sub/superscripted without affecting the intervening text.

expr.property accepts a description in property that indicates the chemical property of interest. Uppercase letters are italicized, and lowercase letters are italicized and subscripted. Other specific characters are parsed as follows (case-sensitive):

D Delta
A bold A (chemical affinity)
p subscript italic P (for isobaric heat capacity)
0 degree sign (for a standard-state property)
l subscript lambda
' prime symbol

A 0 gets interpreted as a degree sign only if it does not immediately follow a number (so that e.g. 2.303 can be included in an expression).

Every other character that is one of the letters or LETTERS in the description of the property is italicized in the expression; other characters such as numerals or mathematical operators are shown without any special formatting. Special cases for the property argument (logK, Eh, pH, pe, IS and ZC) are interpreted as simple expressions, and are not parsed according to the above rules.

expr.units returns an expression for the units, based on one or more characters appearing in the property:

A, G, H energy
Cp, S energy per Kelvin
V volume
E volume per Kelvin
P pressure
T temperature
Eh electrical potential
IS ionic strength

If none of those characters appears in the property, the expression is an empty character (no units). If a prefix is given, it is added to the expression. The denominator of the units (default mol) is taken from the per argument; it is applied to all units except for P, T, Eh, and IS.

axis.label accepts a generic description of a label. If this matches the chemical formula of one of the basis species in the basis argument, the expression for the label is generated using expr.species with log set to the physical state of the basis species. Otherwise, the expression is built by combining the output of expr.property with expr.units (or the value in units, if it is supplied), placing a comma between the two. This function is used extensively in diagram and also appears in many of the examples. Note that diagram sets use.molality to TRUE if IS was supplied as an argument to affinity.

describe.basis makes an expression summarizing the basis species definition (logarithms of activity or fugacity of the basis species) provided in basis; only the basis species identified by ibasis are included.

describe.property makes an expression summarizing the properties supplied in property, along with their values. The expressions returned by both functions consist of a property, an equals sign, and a value (with units where appropriate); the expressions have a length equal to the number of property/value pairs. If oneline is TRUE, the property/value pairs are combined into a single line, separated by commas. The number of digits shown after the decimal point in the values is controlled by digits. If ret.val is TRUE, only the values and their units are returned; this is useful for labeling plots with values of temperature.

describe.reaction makes an expression summarizing a chemical reaction. The reaction data frame can be generated using subcrt. Based on the sign of their reaction coefficients, species are placed on the reactant (left) or product (right) side of the reaction, where the species with their coefficients are separated by plus signs; the two sides of the reaction are separated by an equals sign. Coefficients equal to 1 are not shown. Chemical formulas of species include a designation of physical state if states is all. Names of species (as provided in reaction) are shown instead of chemical formulas for the species identified by iname.

syslab formats the given thermodynamic components (using expr.species) and adds intervening en dashes.

ratlab produces a expression for the activity ratio, viz. (activity of the ion) / [(activity of H+) ^ (charge of the ion)].

See Also

demo("activity_ratios") for examples of syslab and ratlab.


## show descriptions of species and properties on a plot
plot(0, 0, xlim=c(1,5), ylim=c(1,5), xlab="function", ylab="example")
text0 <- function(...) text(..., adj=0)
# species
text0(1, 1, expr.species("CO2"))
text0(1, 2, expr.species("CO2", state="aq"))
text0(1, 3, expr.species("CO2", state="aq", log="aq"))
text0(1, 4, expr.species("CO2", log="aq"))
text0(1, 5, expr.species("CO2", log="aq", value=-3))
# properties
text0(2, 1, expr.property("A"))
text0(2, 2, expr.property("DV"))
text0(2, 3, expr.property("DG0f"))
text0(2, 4, expr.property("DCp0,r"))
text0(2, 5, expr.property("T"))
# units
text0(3, 1, expr.units("A", prefix="k"))
text0(3, 2, expr.units("DV"))
text0(3, 3, expr.units("DG0f", prefix="k"))
text0(3, 4, expr.units("DCp0,r"))
text0(3, 5, expr.units("T"))
# axis.label
text0(4, 1, axis.label("DG0f"))
text0(4, 2, axis.label("T"))
text0(4, 3, axis.label("pH"))
text0(4, 4, axis.label("Eh"))
text0(4, 5, axis.label("IS"))
# describe.basis
dbasis <- describe.basis(oneline=TRUE, digits=0)
property <- c("P", "T", "Eh", "pH", "IS")
value <- c(1, 42.42, -1, 7, 0.1)
dprop <- describe.property(property, value, oneline=TRUE)
text(3, 1.5, dbasis)
text(3, 2.5, dprop)
dbasis <- describe.basis(ibasis=c(1, 5))
dprop <- describe.property(property[1:2], value[1:2])
legend(2.4, 3.9, legend=c(dbasis, dprop), bty="n")
# describe.reaction
# reaction is automatically balanced since basis species are defined
reaction <- subcrt("glucose", -1)$reaction
text(3, 4.25, describe.reaction(reaction))
text(3, 4.5, describe.reaction(reaction, states="all"))
text(3, 4.75, describe.reaction(reaction, iname=1:4))
title(main="Plot labels for chemical species and thermodynamic properties")

[Package CHNOSZ version 1.1.3 Index]