revisit: Plots and Optima of Objective Functions

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

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.

See Also

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.