diagram {CHNOSZ} | R Documentation |
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.
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, ...) strip(affinity, ispecies = NULL, col = NULL, ns = NULL, xticks = NULL, ymin = -0.2, xpad = 1, cex.names = 0.7) find.tp(x)
eout |
list, object returned by |
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 |
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 |
contour.method |
character, labelling method used in |
levels |
numeric, levels at which to draw contour lines |
col |
character, color of activity lines (1D diagram) or predominance field boundaries (2D diagram), or colors of bars in a strip 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 |
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 |
legend.x |
character, description of legend placement passed to |
add |
logical, add to current plot? |
plot.it |
logical, make a plot? |
tplot |
logical, set up plot with |
affinity |
list, object returned by |
ispecies |
numeric, which species to consider (default of |
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 |
... |
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 barplot
s.
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.
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
.
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.
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).
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.
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.
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
.
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 Fe2(SO4)3(H2O)5. 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
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.
## 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 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")