util.expression: Functions to Express Chemical Formulas and Properties
In CHNOSZ: Thermodynamic Calculations and Diagrams for Geochemistry
util.expression R Documentation
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(ibasis = 1:nrow(basis), basis = thermo()$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
ibasis
numeric, which basis species to include
basis
data frame, definition of basis species
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 \Hplus, 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
## 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(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 because 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")
CHNOSZ documentation built on May 29, 2024, 3:30 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| util.expression | R Documentation |
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(ibasis = 1:nrow(basis), basis = thermo()$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 |
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 |
ibasis |
numeric, which basis species to include |
basis |
data frame, definition of basis species |
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 \Hplus, 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
## 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(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 because 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")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.