CHNOSZ (version 1.4.3)

util.expression: Functions to Express Chemical Formulas and Properties

Description

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

Usage

expr.species(species, state = "aq", value=NULL, log=FALSE, molality=FALSE,
    use.state=FALSE, use.makeup=FALSE)
  expr.property(property, molality = FALSE)
  expr.units(property, prefix = "", per = "mol")
  axis.label(label, units = NULL, basis = thermo()$basis, prefix = "",
    molality = FALSE)
  describe.basis(basis = thermo()$basis, ibasis = 1:nrow(basis),
    digits = 1, oneline = FALSE, molality = FALSE, use.pH = TRUE)
  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="-")
  ratlab(top = "K+", bottom = "H+", molality = FALSE)

Arguments

species

character, formula of a chemical species

state

character, designation of physical state

value

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

log

logical, write logarithm of activity/fugacity/molality?

molality

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

use.state

logical, include state in expression?

use.makeup

logical, use makeup to count the elements?

use.pH

logical, use pH instead of log activity of H+?

property

character, description of chemical property

prefix

character, prefix for units

per

character, denominator in units

label

character, description of species, condition or property

units

character, description of units

basis

data frame, definition of basis species

ibasis

numeric, which basis species to include

digits

numeric, number of digits to show after decimal point

oneline

logical, make descriptions occupy a single line?

ret.val

logical, return only the value with the units?

reaction

data frame, definition of reaction

iname

numeric, show names instead of formulas for these species

states

character, if all, show states for all species; numeric, which species to show states for

system

character, thermodynamic components

dash

character to use for dash between components

top

character, the ion in the numerator of the ratio

bottom

character, the ion in the denominator of the ratio

Details

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 constructs a formatted expression using the formula or name of a single chemical species. With no other arguments, the formula is just formatted with the appropriate subscripts and superscripts. Providing the physical state adds a variable to the expression (a for aqueous species and pure phases, except f for gases). Set molality to TRUE to write m instead of a for aqueous species. The state itself is written in the expression if use.state is TRUE. If log is TRUE, the expression includes a log prefix. Finally, provide a value in value to write an equation (something like logfO2 = -70), or set it to NA to only write the variable itself (e.g. logfO2). Set use.makeup to TRUE to use makeup to parse the chemical formula. This was an older default action that had 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 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 a reaction double arrow (Unicode U+21CC). Coefficients equal to 1 are not shown. Chemical formulas of species include the physical state if states is all, or a numeric value indicating which species to label with the state. 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 between the ions in the top and bottom arguments. The default is a ratio with H⁺, i.e. (activity of the ion) / [(activity of H+) ^ (charge of the ion)].

See Also

util.legend for other functions to make legends. demo("saturation") for examples of syslab and ratlab.

Examples

reset()
## 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", use.state=TRUE))
text0(1, 3, expr.species("CO2", log=TRUE, use.state=TRUE))
text0(1, 4, expr.species("CO2", log=TRUE))
text0(1, 5, expr.species("CO2", log=TRUE, 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
basis("CHNOS+")
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")