The purpose of richness is to calculate and visualize summary statistics for logarithms of activities of chemical species. For most uses, supply the output of diagram as the value for d. Alternatively, d can be a list of logarithms of activities; the list elements each correspond to a different species and can be vectors, matrices, or higher-dimensional arrays, but they must all have the same dimensions. (This is always the case for d$logact if d is the output from diagram; the dimensionality is determined by the number of variables used in the calculations of affinity.) The type of statistic to be calculations is indicated by target, as summarized in the following table. llll{
target description extremum additional arguments
sd standard deviation min none
cv coefficient of variation min none
shannon Shannon diversity index max none
qqr correlation coefficient on q-q plot (normal distribution) max none
richness species richness max loga.ref
cvrmsd coefficient of variation of RMSD min loga.ref
spearman Spearman correlation coefficient max loga.ref
pearson Pearson correlation coefficient max loga.ref
}
sd, cv, shannon and qqrr all operate on just the sample values. richness counts the numbers of species whose logarithms of activities are above log.min. cvrmsd, spearman and pearson are comparison statistics where loga.target represents the observed values. ratio determines the correlation coefficient of a predicted change in loga ratios (d$logact vs. loga.ref) plotted agains observed changed in loga ratios (e.g., from changes in protein expression deduced from microarray experiments; given in loga.target)
If do.plot is TRUE, d is the output from diagram, 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.
The value of extremum in the table shows whether the extreme value that optimizes the system is the minimum (sd, cv, cvrmsd) or the maximum (all the others). On plots the location of the extreme value is indicated (by a dashed vertical line on a 1-D plot or a point marked by an asterisk on a 2-D plot). On 2-D plots the valleys (or ridges) leading to the location of the extremum are plotted. The ridges or valleys are plotted as dashed lines and are colored green for the $x$ values returned by extremes and blue for the $y$ values returned by extremes.
The location of the extreme value in a matrix or vector z is calculated using where.extreme. Whether the extreme is the minimum or the maximum value depends on the value of target. For matrices, if do.sat is TRUE, if the extreme value is repeated, the row and columns numbers for all instances are returned. Given a matrix of numeric values in z, extremes locates the maximum or minimum values in both dimensions. That is, the $x$ values that are returned are the column numbers where the extreme is found for each row, and the $y$ values that are returned are the row numbers where the extreme is found for each column.
If lograt.ref is provided, these values are the reference values for logarithm of abundance ratio.
The function name was changed from diversity to revisit in CHNOSZ-0.9 because there is a function named diversity in the vegan package. Note that while diversity takes a matrix with species on the columns, revisit takes a list with species as the elements of the list.