# revisit: Plots and Optima of Objective Functions In CHNOSZ: Thermodynamic Calculations and Diagrams for Geochemistry

## Description

Calculate values of an objective function from logarithms of activities of chemical species and (for some objectives) reference logarithms of activity. Make line or contour plots showing the values of the objective function and the positions of the optima (minimum or maximum).

## Usage

 ```1 2 3 4 5``` ``` revisit(eout, objective = "CV", loga2 = NULL, loga0 = NULL, ispecies = NULL, col = par("fg"), yline = 2, ylim = NULL, cex = par("cex"), lwd = par("lwd"), mar = NULL, side = 1:4, xlim = NULL, labcex = 0.6, pch = 1, main = NULL, plot.it = NULL, add = FALSE, plot.optval = TRUE, style.2D = "contour", bg = par("bg")) ```

## Arguments

 `eout` list, output from `equilibrate`, containing logarithms of activities of species `objective` character, name of `objective` function `loga2` numeric vector, reference values of logarithm of activities `loga0` numeric vector, logarithm of activities to calculate activity ratios `ispecies` numeric, which species to consider `col` character, color to use for points or lines `yline` numeric, margin line for y-axis label `ylim` numeric, limits of y axis `cex` numeric, character expansion factor `lwd` numeric, line width `mar` numeric, plot margin specifications `side` numeric, which sides of plot to draw axes `xlim` numeric, limits of x axis `labcex` numeric, character expansion factor for species labels `pch` numeric, plotting symbol(s) to use for points `main` character, main title for plot `plot.it` logical, make a plot? `add` logical, add to an existing plot? `plot.optval` logical, show the location of the optimal value(s)? `style.2D` character, type of 2-D plot `bg` character, background for `points`

## Details

`revisit` is used to calculate the variation in the equilibrium logarithms of chemical activity (supplied in `eout`) or to compare the calculated values with reference (e.g. measured) values (`loga2`). Usually, the output of `equilibrate` is used as the value for `eout`. The type of calculation is indicated by `objective`, giving the name of an `objective` function. Generally, `loga2` is expressed in base-10 logarithms. However, if `loga0` (base 10) is supplied, it is used to calculate the base-2 log ratio (log2(a1/a0)); these calculated values are then compared with values in `loga2` interpreted as base-2 logarithms.

Internally, the list of logarithms of chemical activities in `eout\$loga.equil` is passed as `loga1` to the objective function. If the objective function has an argument `a1` instead of `loga1`, the activities instead of their logarithms are passed to the function. Generally, `loga2` must be a numeric vector with length equal to that of `loga1` (i.e., number of species). However, if a single numeric value is supplied for `loga2`, it is recycled to the length of `loga1`.

For calculations at a single condition (0-D, no variation), with the qqr objective, a quantile-quantile plot (`qqnorm`) is shown. For rmsd and other objective functions having reference values (`loga2`), a scatter plot is shown with a smooth line calculated using `loess.smooth`. The line can be suppressed using `lwd=NULL`. Otherwise, no plot is made for 0-D calculations for the other objective functions.

If `plot.it` is TRUE, and `eout` is the output from `equilibrate`, and the number of variables is 1 or 2, the results are plotted — a line diagram in 1 dimension or a contour plot in 2 dimensions. `style.2D` can be set to `image` to fill the plot with colors instead of the `contour` plot that is the default.

If `plot.optval` is TRUE, the location of the optimum (or optima) is indicated by a dashed vertical line(s) on a 1-D plot or a point(s) marked by an asterisk on a 2-D plot. Also, on 2-D plots, the locations of the optima at each grid line perpendicular to the x and y axes are plotted. These points follow major ridges or valleys, and are plotted as dashed lines colored green for the x and blue for the y values.

An alternative source for the `eout` argument is any list of numeric values, each element of which corresponds to a different observation (such as a single species), all having the same dimensions (as vectors, matrices or higher-dimensional arrays) In this case, plotting is disabled, since the names of the variables are not in the input.

revisit is a partial anagram of diversity, which was the provisional name of the function but was changed in CHNOSZ-0.9. While the `diversity` function (in vegan) operates on a matrix with (biological) species on the columns, `revisit` operates on a list with (chemical) species as the elements of the list. The name of the H output value is the conventional symbol for the Shannon diversity index, which was the first target statistic to be implemented in `revisit`.

## Value

`revisit` returns a list containing at least an element named H, giving the calculated values of the objective function. For 1 or 2 dimensions of varibility of chemical conditions, the output also contains the elements `ixopt` and `iyopt` (1-D and 2-D) and `iyopt` and `yopt` (2-D) indicating the positions and values of the optimum. The optimum attribute of the `objective` function indicates whether minimal or maximal values are used. For calculations in more than two dimensions, the output contains `iopt`, a matrix.

`demo("revisit")` shows calculations for a system of proteins. `findit` is a related function implementing a gridded search of chemical activities, temperature and/or pressure that optimize the objective function.
 ``` 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``` ```## example of defining a new objective function # count the species with logarithms of activity greater than loga2 count <- function(loga1, loga2) rowSums(loga1 > loga2) # set the attribute indicating the type of optimum attr(count, "optimum") <- "maximal" # equilibrate a system of amino acids basis("CHNOS") species(aminoacids("")) a <- affinity(O2=c(-80, -60)) e <- equilibrate(a) # make a plot r <- revisit(e, "count", -5) title(main="Amino acids with metastable log activities > -5") # can also make a 2-D plot a <- affinity(O2=c(-74, -60, 25), H2O=c(-3, 3, 25)) e <- equilibrate(a) r <- revisit(e, "count", -5, style.2D="image", plot.optval=FALSE) title(main="Amino acids with metastable log activities > -5") ## 'revisit' calculations for amino acids opar <- par(mfrow=c(2, 2)) basis("CHNOS+") species(aminoacids("")) # chemical affinities as a function of logarithm of oxygen fugacity a <- affinity(O2=c(-85, -60)) # shows the equilibrium abundances of the amino acids e <- equilibrate(a) diagram(e) mtitle(c("20 amino acids", "balanced on CO2")) # show a legend with input constraints db <- describe.basis(ibasis=3) dp <- describe.property("T", 25) legend("bottomright", c(dp, db)) # default is to plot coefficient of variation r <- revisit(e) # show a title with the optimal conditions mincv <- format(r\$optimum, digits=3) t1 <- paste("minimum coeff of variation,", mincv, "at:") # the logfO2 that minimized the C.V. basis("O2", r\$x) t2 <- describe.basis(ibasis=5) mtitle(c(t1, as.expression(t2))) # chemical affinities as a function of two other variables a <- affinity(NH3=c(-10, 10, 40), T=c(0, 80, 40)) diagram(a, fill="heat") # show a legend with input constraints db <- describe.basis(ibasis=5) legend("bottomright", as.expression(db)) # contour plot of the CV e <- equilibrate(a) r <- revisit(e) # show a title with the optimal conditions mincv <- format(r\$optimum, digits=3) t1 <- paste("minimum coeff of variation,", mincv, "at:") # the logaNH3 and T that minimized the C.V. basis("NH3", r\$x) db <- describe.basis(ibasis=3) dp <- describe.property("T", r\$y) t2 <- substitute(list(dp, db), list(dp=dp[], db=db[])) mtitle(c(t1, as.expression(t2))) par(opar) ```