CHNOSZ (version 1.0.8)

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 = "", log = "", value=NULL) expr.property(property) expr.units(property, prefix = "", per = "mol") axis.label(label, units = NULL, basis = get("thermo")$basis, prefix = "") describe.basis(basis = get("thermo")$basis, ibasis = 1:nrow(basis), digits = 1, oneline = FALSE) describe.property(property, value, digits = 1, oneline = FALSE, ret.val = FALSE) describe.reaction(reaction, iname = numeric(), states = NULL)

Arguments

species

character, formula of a chemical species

state

character, designation of physical state

log

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

value

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

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

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 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.

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 (isobaric heat capacity)

0

degree sign (standard-state property)

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.

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.

Examples

## 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
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))