CHNOSZ (version 1.3.2)

diagram: Chemical Activity Diagrams

Description

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

Usage

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, lwd = par("lwd"), dotted = NULL, spline.method = NULL,
    contour.method = "edge",
    # 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, ...)
  strip(affinity, ispecies = NULL, col = NULL, ns = NULL, 
    xticks = NULL, ymin = -0.2, xpad = 1, cex.names = 0.7)
  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

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

col

character, color of activity lines (1D diagram) or predominance field boundaries (2D diagram), or colors of bars in a strip diagram (strip)

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?

affinity

list, object returned by affinity

ispecies

numeric, which species to consider (default of NULL is to consider all species)

ns

numeric, numbers of species, used to make inset plots for strip diagrams

xticks

numeric, location of supplemental tick marks on x-axis

ymin

numeric, lower limit of y-axis

xpad

numeric, amount to extend x-axis on each side

x

matrix, value of the predominant list element from diagram

...

additional arguments passed to plot or barplot

Value

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

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

Affinity Diagrams

The function behaves differently when the output from affinity is being used instead of the equilibrium activities from equilibrate. If type is auto, and the number of dimensions is 0 or 1, 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). If type is auto, and the number of dimensions is 2, then equilibrium predominance (maximum affinity) fields are plotted. This algorithm is based on a comparison of the affinities of the formation reactions scaled by the balancing coefficients that are determined 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 is beyond the saturation line, the function prints a message instead. If type is the name of a basis species, the equilibrium activity of the selected basis species in each of the formation reactions is plotted (see the -acetic acid example in buffer). In the case of 2-D diagrams, both of these options use contour to draw the lines, using the method specified in contour.method. The saturation diagram can handle multiple species, but if type is the name a basis species, then only the first species of interest is used in the calculation, and a warning is produced if there is more than one.

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

Strip Diagrams

A different incarnation of 1-D speciation diagrams is provided by strip. This function generates any number of strip diagrams in a single plot. The diagrams are made up of colors bars whose heights represent the relative abundances of species; the color bars are arranged in order of abundance and the total height of the stack of colors bars is constant. If ispecies is a list, the number of strip diagrams is equal to the number of elements of the list, and the elements of this list are numeric vectors that identify the species to consider for each diagram. The strips are labeled with the names of ispecies. If col is NULL, the colors of the bars are generated using rainbow. Supplemental ticks can be added to the x-axis at the locations specified in xtick; they are larger than the standard ticks and have colors corresponding to those of the color bars. ymin can be decreased in order to add more space at the bottom of the plot, and xpad can be changed in order to increase or decrease the size of the x-axis relative to the width of the strips. An inset dot-and-line plot is created below each strip if ns is given. This argument has the same format as ispecies, and can be used e.g. to display the relative numbers of species for comparison with the stability calculations.

Details

diagram takes as its primary input the results from equilibrate and displays diagrams representing the equilibrium chemical activities of the species. 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 accepts: temperature, pressure, or the chemical activities of the basis species

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 formuls unless format.names is FALSE. Use the names argument to override the default species names. Alternatively, supply a numeric value to names to indicate the 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.

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.

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

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(SO)(HO). 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. See the vignette Hot-spring proteins in CHNOSZ for an example of the strip charts.

Examples

Run this code
# NOT RUN {
## 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", "O2", "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
# this uses a HCL palette for the fill colors
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")
# }

Run the code above in your browser using DataCamp Workspace