diagram: Chemical Activity Diagrams

Description Usage Arguments Details 1-D diagrams 2-D diagrams Activity Coefficients Other Functions Value References See Also Examples

View source: R/diagram.R

Description

Plot equilibrium chemical activity (1-D speciation) or equal-activity (2-D predominance) diagrams as a function of chemical activities of basis species, temperature and/or pressure.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
  diagram(
    # species affinities or activities
    eout,
    # type of plot
    type = "auto", alpha = FALSE, normalize = FALSE,
    as.residue = FALSE, balance = NULL, groups = as.list(1:length(eout$values)),
    # figure size and sides for axis tick marks
    xrange = NULL, mar = NULL, yline = par("mgp")[1]+0.3, side = 1:4,
    # axis limits and labels
    ylog = TRUE, xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL,
    # character sizes
    cex = par("cex"), cex.names = 1, cex.axis = par("cex"),
    # line styles
    lty = NULL, lty.cr = NULL, lty.aq = NULL, lwd = par("lwd"), dotted = NULL,
    spline.method = NULL, contour.method = "edge", levels = NULL,
    # colors
    col = par("col"), col.names = par("col"), fill = NULL,
    fill.NA = "gray80", limit.water = TRUE,
    # field and line labels
    names = NULL, format.names = TRUE, bold = FALSE, italic = FALSE, 
    font = par("font"), family = par("family"), adj = 0.5, dy = 0, srt = 0,
    # title and legend
    main = NULL, legend.x = NA,
    # plotting controls
    add = FALSE, plot.it = TRUE, tplot = TRUE, ...)
  find.tp(x)

Arguments

eout

list, object returned by equilibrate or affinity

type

character, type of plot, or name of basis species whose activity to plot

alpha

logical or character (balance), for speciation diagrams, plot degree of formation instead of activities?

normalize

logical, divide chemical affinities by balance coefficients (rescale to whole formulas)?

as.residue

logical, divide chemical affinities by balance coefficients (no rescaling)?

balance

character, balancing constraint; see equilibrate

groups

list of numeric, groups of species to consider as a single effective species

xrange

numeric, range of x-values between which predominance field boundaries are plotted

mar

numeric, margins of plot frame

yline

numeric, margin line on which to plot the y-axis name

side

numeric, which sides of plot to draw axes

xlim

numeric, limits of x-axis

ylim

numeric, limits of y-axis

xlab

character, label to use for x-axis

ylab

character, label to use for y-axis

ylog

logical, use a logarithmic y-axis (on 1D degree diagrams)?

cex

numeric, character expansion (scaling relative to current)

cex.names

numeric, character expansion factor to be used for names of species on plots

cex.axis

numeric, character expansion factor for names of axes

lty

numeric, line types to be used in plots

lty.cr

numeric, line types for cr-cr boundaries (between two minerals)

lty.aq

numeric, line types for aq-aq boundaries (between two aqueous species)

lwd

numeric, line width

dotted

numeric, how often to skip plotting points on predominance field boundaries (to gain the effect of dotted or dashed boundary lines)

spline.method

character, method used in splinefun

contour.method

character, labelling method used in contour (use NULL for no labels).

levels

numeric, levels at which to draw contour lines

col

character, color of activity lines (1D diagram) or predominance field boundaries (2D diagram)

col.names

character, colors for labels of species

fill

character, colors used to fill predominance fields

fill.NA

character, color for grid points with NA values

limit.water

logical, set NA values beyond water stability limits?

names

character, names of species for activity lines or predominance fields

format.names

logical, apply formatting to chemical formulas?

bold

logical, use bold formatting for names?

italic

logical, use italic formatting for names?

font

character, font type for names (has no effect if format.names is TRUE)

family

character, font family for names

adj

numeric, adjustment for line labels

dy

numeric, y offset for line labels

srt

numeric, rotation for line labels

main

character, a main title for the plot; NULL means to plot no title

legend.x

character, description of legend placement passed to legend

add

logical, add to current plot?

plot.it

logical, make a plot?

tplot

logical, set up plot with thermo.plot.new?

x

matrix, value of the predominant list element from diagram

...

additional arguments passed to plot or barplot

Details

This function displays diagrams representing either chemical affinities, or equilibrium chemical activities of species. The first argument is the output from affinity, equilibrate, or solubility. 0-D diagrams, at a single point, are shown as barplots. 1-D diagrams, for a single variable on the x-axis, are plotted as lines. 2-D diagrams, for two variables, are plotted as predominance fields. The allowed variables are any that affinity or the other functions accepts: temperature, pressure, or the chemical activities of the basis species.

The type argument only applies when the output from affinity is being used. For type set to auto, and 0 or 1 variables, the property computed by affinity for each species is plotted. This is usually the affinity of the formation reaction, but can be set to some other property, such as the equilibrium constant (logK). For two variables, equilibrium predominance (maximum affinity) fields are plotted. This “maximum affinity method” (Dick, 2019) uses balancing coefficients that are specified by the balance argument. If type is saturation, the function plots the line for each species where the affinity of formation equals zero (see demo("saturation") for an example). If for a given species no saturation line is possible or the range of the diagram does not include the saturation line, the function prints a message instead. If type is the name of a basis species, then the equilibrium activity of the selected basis species in each of the formation reactions is plotted (see the \CO2-acetic acid example in buffer). In the case of 2-D diagrams, both of these options use contour to draw the lines, with the method specified in contour.method.

A new plot is started unless add is TRUE. If plot.it is FALSE, no plot will be generated but all the intermediate computations will be performed and the results returned.

Line or field labels use the names of the species as provided in eout; formatting is applied to chemical formulas unless format.names is FALSE. Set names to TRUE or NULL to plot the names, or FALSE, NA, or "" to prevent plotting the names, or a character argument to replace the default species names. Alternatively, supply a numeric value to names to indicate a subset of default names that should or shouldn't be plotted (positive and negative indices, respectively). Use col.names and cex.names to change the colors and size of the labels. Use cex and cex.axis to adjust the overall character expansion factors (see par) and those of the axis labels. The x- and y-axis labels are automatically generated unless they are supplied in xlab and ylab.

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

1-D diagrams

For 1-D diagrams, the default setting for the y-axis is a logarithmic scale (unless alpha is TRUE) with limits corresponding to the range of logarithms of activities (or 0,1 if alpha is TRUE); these actions can be overridden by ylog and ylim. If legend.x is NA (the default), the lines are labeled with the names of the species near the maximum value. Otherwise, a legend is placed at the location identified by legend.x, or omitted if legend.x is NULL.

If alpha is TRUE, the fractional degrees of formation (ratios of activities to total activity) are plotted. Or, setting alpha to balance allows the activities to be multiplied by the number of the balancing component; this is useful for making “percent carbon” diagrams where the species differ in carbon number. The line type and line width can be controlled with lty and lwd, respectively. Set lty.cr to 0 to disable drawing lines between minerals (to show equal-activity lines for only aqueous species), or set lty.aq to 0 to disable drawing lines between aqueous species. To connect the points with splines instead of lines, set spline.method to one of the methods in splinefun.

2-D diagrams

On 2-D diagrams, the fields represent the species with the highest equilibrium activity. fill determines the color of the predominance fields, col that of the boundary lines. The default of NULL for fill produces transparent predominance fields. fill can be any colors, or the word rainbow, heat, terrain, topo, or cm, indicating a palette from grDevices. Starting with R version 3.6.0, fill can be the name of any available HCL color palette, matched in the same way as the palette argument of hcl.colors.

fill.NA gives the color for empty fields, i.e. points for which NA values are present, possibly by using equilibrate at extreme conditions (see test-diagram.Rd). fill.NA is also used to specify the color outside the water stability limits on Eh-pH or pe-pH diagrams, when limit.water is TRUE. Note that the default for fill.NA is automatically changed to transparent when add is TRUE.

The default line-drawing algorithm uses contourLines to obtain smooth-looking diagonal and curved lines, at the expense of not coinciding exactly with the rectangular grid that is used for drawing colors. lty, col, and lwd can be specified, but limiting the lines via xrange is not currently supported. To go back to the old behavior for drawing lines, set dotted to 0. The old behavior does not respect lty; instead, the style of the boundary lines on 2-D diagrams can be altered by supplying one or more non-zero integers in dotted, which indicates the fraction of line segments to omit; a value of 1 or NULL for dotted has the effect of not drawing the boundary lines.

normalize and as.residue apply only to the 2-D diagrams, and only when eout is the output from affinity. With 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 as.residue, the activity boundaries are calculated as between the residues of the species, and no rescaling is performed.

Activity Coefficients

The wording in this page and names of variables in functions refer exclusively to activities of aqueous species. However, if activity coefficients are calculated (using the IS argument in affinity), then these variables are effectively transformed to molalities (see tests/testthat/ test-logmolality.R). So that the labels on diagrams are adjusted accordingly, diagram sets the molality argument of axis.label to TRUE if IS was supplied as an argument to affinity. The labeling as molality takes effect even if IS is set to 0; this way, by including (or not) the IS = 0 argument to affinity, the user decides whether to label aqueous species variables as molality (or activity) for calculations at zero ionic strength (where molality = activity).

Other Functions

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 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 diagram for calculations in 2 dimensions to approximately locate the triple points on the diagram.

Value

diagram returns an invisible list containing, first, the contents of eout, i.e. the provided output of affinity or equilibrate. To this are added the name of the plotted variable in plotvar, the plotted values in plotvals, and the names used for labeling the plot in names. For 1-D diagrams, plotvals usually corresponds to the chemical activities of the species (i.e. eout$loga.equil), or, if alpha is TRUE, their mole fractions (degrees of formation). For 2-D diagrams, the output also contains predominant, giving the numbers (from the species definition) of the predominant (aka maximum-affinity) species at each grid point. The rows and columns of predominant correspond to the x- and y-variables, respectively. Finally, the output for 2-D diagrams contains a lines component, giving the x- and y-coordinates of the field boundaries computed using contourLines; the values are padded to equal length with NAs to faciliate exporting the results using write.csv.

References

Aksu, S. and Doyle, F. M. (2001) Electrochemistry of copper in aqueous glycine solutions. J. Electrochem. Soc. 148, B51–B57. https://doi.org/10.1149/1.1344532

Dick, J. M. (2019) CHNOSZ: Thermodynamic calculations and diagrams for geochemistry. Front. Earth Sci. 7:180. https://doi.org/10.3389/feart.2019.00180

Helgeson, H. C. (1970) A chemical and thermodynamic model of ore deposition in hydrothermal systems. Mineral. Soc. Amer. Spec. Pap. 3, 155–186. http://www.worldcat.org/oclc/583263

Helgeson, H. C., Delany, J. M., Nesbitt, H. W. and Bird, D. K. (1978) Summary and critique of the thermodynamic properties of rock-forming minerals. Am. J. Sci. 278-A, 1–229. http://www.worldcat.org/oclc/13594862

LaRowe, D. E. and Helgeson, H. C. (2007) Quantifying the energetics of metabolic reactions in diverse biogeochemical systems: electron flow and ATP synthesis. Geobiology 5, 153–168. https://doi.org/10.1111/j.1472-4669.2007.00099.x

Majzlan, J., Navrotsky, A., McClesky, R. B. and Alpers, C. N. (2006) Thermodynamic properties and crystal structure refinement of ferricopiapite, coquimbite, rhomboclase, and Fe\s2(SO\s4)\s3(H\s2O)\s5. Eur. J. Mineral. 18, 175–186. https://doi.org/10.1127/0935-1221/2006/0018-0175

Tagirov, B. and Schott, J. (2001) Aluminum speciation in crustal fluids revisited. Geochim. Cosmochim. Acta 65, 3965–3992. https://doi.org/10.1016/S0016-7037(01)00705-0

See Also

Other examples are present in the help for protein and buffer, and even more can be found in demos.

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
## calculate the equilibrium logarithm of activity of a 
## basis species in different reactions
basis("CHNOS")
species(c("ethanol", "lactic acid", "deoxyribose", "ribose"))
a <- affinity(T=c(0, 150))
diagram(a, type="O2", legend.x="topleft", col=rev(rainbow(4)), lwd=2)
title(main="Equilibrium logfO2 for 1e-3 mol/kg of CO2 and ... ")

### 1-D diagrams: logarithms of activities

## Degrees of formation of ionized forms of glycine
## After Fig. 1 of Aksu and Doyle, 2001 
basis("CHNOS+")
species(ispecies <- info(c("glycinium", "glycine", "glycinate")))
a <- affinity(pH=c(0, 14))
e <- equilibrate(a)
diagram(e, alpha=TRUE, lwd=1)
title(main=paste("Degrees of formation of aqueous glycine species\n",
  "after Aksu and Doyle, 2001"))

## Degrees of formation of ATP species as a function of 
## temperature, after LaRowe and Helgeson, 2007, Fig. 10b
# to make a similar diagram, activity of Mg+2 here is set to
# 10^-4, which is different from LH07, who used 10^-3 total molality
basis(c("CO2", "NH3", "H2O", "H3PO4", "O2", "H+", "Mg+2"),
  c(999, 999, 999, 999, 999, -5, -4))
species(c("HATP-3", "H2ATP-2", "MgATP-2", "MgHATP-"))
a <- affinity(T=c(0, 120, 25))
e <- equilibrate(a)
diagram(e, alpha=TRUE)  
title(main=paste("Degrees of formation of ATP species,\n",
  "pH=5, log(aMg+2)=-3. After LaRowe and Helgeson, 2007"),
  cex.main=0.9)

### 2-D diagrams: predominance diagrams
### these use the maximum affinity method

## Fe-S-O at 200 deg C, after Helgeson, 1970
basis(c("Fe", "oxygen", "S2"))
species(c("iron", "ferrous-oxide", "magnetite",
  "hematite", "pyrite", "pyrrhotite"))
# the calculations include the phase transitions of
# pyrrhotite; no additional step is needed
a <- affinity(S2=c(-50, 0), O2=c(-90, -10), T=200)
diagram(a, fill="heat")
title(main=paste("Fe-S-O, 200 degrees C, 1 bar",
  "After Helgeson, 1970", sep="\n"))

## pe-pH diagram for hydrated iron sulfides,
## goethite and pyrite, after Majzlan et al., 2006
basis(c("Fe+2", "SO4-2", "H2O", "H+", "e-"), 
  c(0, log10(3), log10(0.75), 999, 999))
species(c("rhomboclase", "ferricopiapite", "hydronium jarosite",
  "goethite", "melanterite", "pyrite"))
a <- affinity(pH=c(-1, 4, 256), pe=c(-5, 23, 256))
d <- diagram(a, main="Fe-S-O-H, after Majzlan et al., 2006")
# the first four species show up in order near pe=15
stopifnot(all.equal(unique(d$predominant[, 183]), 1:4))
water.lines(d, lwd=2)
text(3, 22, describe.basis(thermo()$basis[2:3,], digits=2, oneline=TRUE))
text(3, 21, describe.property(c("T", "P"), c(25, 1), oneline=TRUE))

## aqueous Al species, after Tagirov and Schott, 2001
basis(c("Al+3", "F-", "H+", "O2", "H2O"))
AlOH <- c("Al(OH)4-", "Al(OH)3", "Al(OH)2+", "AlOH+2")
Al <- "Al+3"
AlF <- c("AlF+2", "AlF2+", "AlF3", "AlF4-")
AlOHF <- c("Al(OH)2F2-", "Al(OH)2F", "AlOHF2")
species(c(AlOH, Al, AlF, AlOHF), "aq")
res <- 300
a <- affinity(pH = c(0.5, 6.5, res), `F-` = c(-2, -9, res), T = 200)
diagram(a, fill = "terrain")
dprop <- describe.property(c("T", "P"), c(200, "Psat"))
legend("topright", legend = dprop, bty = "n")
mtitle(c("Aqueous aluminum species",
         "After Tagirov and Schott, 2001 Fig. 4d"), cex = 0.95)

## Temperature-Pressure: kayanite-sillimanite-andalusite
# cf. Fig. 49 of Helgeson et al., 1978
# this is a system of one component (Al2SiO5), however:
# - number of basis species must be the same as of elements
# - avoid using H2O or other aqueous species because of
#     T/P limits of the water() calculations;
basis(c("corundum", "quartz", "oxygen"))
species(c("kyanite", "sillimanite", "andalusite"))
# database has transition temperatures of kyanite and andalusite
# at 1 bar only, so we permit calculation at higher temperatures
a <- affinity(T=c(200, 900, 99), P=c(0, 9000, 101), exceed.Ttr=TRUE)
d <- diagram(a, fill=NULL)
slab <- syslab(c("Al2O3", "SiO2", "H2O"))
mtitle(c(as.expression(slab), "after Helgeson et al., 1978"))
# find the approximate position of the triple point
tp <- find.tp(d$predominant)
Ttp <- a$vals[[1]][tp[1, 2]]
Ptp <- rev(a$vals[[2]])[tp[1, 1]]
points(Ttp, Ptp, pch=10, cex=5)
# some testing of the overall geometry
stopifnot(species()$name[d$predominant[1, 1]]=="andalusite")
stopifnot(species()$name[d$predominant[1, 101]]=="kyanite")
stopifnot(species()$name[d$predominant[99, 101]]=="sillimanite")

CHNOSZ documentation built on July 7, 2020, 3 p.m.