rank.affinity() now returns average group rankings as percentage values

git-svn-id: svn://scm.r-forge.r-project.org/svnroot/chnosz/pkg/CHNOSZ@822 edb9625f-4e0d-4859-8d74-9fd3b1da38cb

DESCRIPTION

@@ -1,6 +1,6 @@
-Date: 2023-12-06
+Date: 2024-01-06
 Package: CHNOSZ
-Version: 2.0.0-41
+Version: 2.0.0-42
 Title: Thermodynamic Calculations and Diagrams for Geochemistry
 Authors@R: c(
     person("Jeffrey", "Dick", , "[email protected]", role = c("aut", "cre"),

R/diagram.R

@@ -358,7 +358,7 @@ diagram <- function(
 
       ### 1-D diagram - lines for properties or chemical activities
       xvalues <- eout$vals[[1]]
-      if(missing(xlim)) xlim <- range(xvalues)  # TODO: this is backward if the vals are not increasing
+      if(missing(xlim)) xlim <- c(xvalues[1], rev(xvalues)[1])
       # Initialize the plot
       if(!add) {
         if(missing(xlab)) xlab <- axis.label(getlabel(1), basis = eout$basis, molality = molality)
@@ -401,6 +401,7 @@ diagram <- function(
           dx <- rep(dx, length.out = length(plotvals))
           dy <- rep(dy, length.out = length(plotvals))
           srt <- rep(srt, length.out = length(plotvals))
+          cex.names <- rep(cex.names, length.out = length(plotvals))
           # Don't assign to adj becuase that messes up the missing test below
           alladj <- rep(adj, length.out = length(plotvals))
           for(i in 1:length(plotvals)) {
@@ -439,7 +440,7 @@ diagram <- function(
             # Also include y-offset (dy) and y-adjustment (labels bottom-aligned with the line)
             # ... and srt (string rotation) 20171127
             text(xvalues[imax] + dx[i], plotvals[[i]][imax] + dy[i], labels = names[i], adj = c(thisadj, 0),
-              cex = cex.names, srt = srt[i], font = font, family = family)
+              cex = cex.names[i], srt = srt[i], font = font, family = family)
           }
         } else legend(x = legend.x, lty = lty, legend = names, col = col, cex = cex.names, lwd = lwd, ...)
       }

R/rank.affinity.R

@@ -1,7 +1,7 @@
 # Calculate normalized sum of ranking of affinities for species in designated groups
 # 20220416 jmd first version
 
-rank.affinity <- function(aout, groups) {
+rank.affinity <- function(aout, groups, percent = TRUE) {
   # Put the affinities into matrix form
   amat <- sapply(aout$values, as.numeric)
   # Calculate ranks
@@ -14,6 +14,8 @@ rank.affinity <- function(aout, groups) {
     if(inherits(group, "integer")) n <- length(group)
     colSums(arank[group, ]) / n
   })
+  # Calculate rank-sum percentage 20240106
+  if(percent) grank <- grank / rowSums(grank) * 100
   # Restore dims
   dims <- dim(aout$values[[1]])
   # apply() got 'simplify' argument in R 4.1.0 20230313

inst/NEWS.Rd

@@ -15,7 +15,7 @@
 \newcommand{\Cp}{\ifelse{latex}{\eqn{C_P}}{\ifelse{html}{\out{<I>C<sub>P</sub></I>}}{Cp}}}
 \newcommand{\DG0}{\ifelse{latex}{\eqn{{\Delta}G^{\circ}}}{\ifelse{html}{\out{&Delta;<I>G</I>&deg;}}{ΔG°}}}
 
-\section{Changes in CHNOSZ version 2.0.0-39 (2023-12-04)}{
+\section{Changes in CHNOSZ version 2.0.0-42 (2023-01-09)}{
 
   \subsection{NEW FEATURES}{
     \itemize{
@@ -50,6 +50,9 @@
       results in larger vignettes that are used for the CHNOSZ website; if this
       variable is unset (as on CRAN), a smaller package is built.
 
+      \item \code{rank.affinity()} now returns average group rankings as
+      percentage values.
+
     }
   }
 

man/rank.affinity.Rd

@@ -1,34 +1,35 @@
 \encoding{UTF-8}
 \name{rank.affinity}
 \alias{rank.affinity}
-\title{Normalized Sums of Ranks of Chemical Affinities}
+\title{Average Ranks of Chemical Affinities}
 \description{
-Affinity ranking for groups of species.
+Affinity rankings for groups of species.
 }
 
 \usage{
-  rank.affinity(aout, groups)
+  rank.affinity(aout, groups, percent = TRUE)
 }
 
 \arguments{
   \item{aout}{list, output of \code{\link{affinity}}}
   \item{groups}{named list of indices (integer or numeric) for species in each group}
+  \item{percent}{return average rank percentage for each group}
 }
 
 \details{
-The following calculations are applied to each set of conditions (i.e., grid point if \code{\link{affinity}} was called with two variables).
-The \code{\link{rank}}s of affinities for all species are first computed.
-Then, the ranks for the species in each group are summed and divided by the number of species in that group (this is the normalization step).
+The affinities for all species are \code{\link{rank}}ed, then the mean ranking for the species in each group is calculated.
+The mean rankings of groups are converted to a percentage, or returned as-is if \code{percent} is FALSE.
+Note that the calculations are applied to each set of conditions individually (i.e., each grid point in the affinity \code{\link{affinity}} calculation).
 }
 
 \value{
-The normalized sum of ranks are inserted into the \code{values} element of \code{aout}, and the names of the groups are inserted into the \code{species} element.
-The result can be used by \code{\link{diagram}} to show the groups with the highest normalized sum of ranks.
+The average rankings are inserted into the \code{values} element of \code{aout}, and the names of the groups are inserted into the \code{species} element.
+The result can be used by \code{\link{diagram}} to make line plots or predominance diagrams (the predominance fields correspond to the groups with highest average ranking of affinity).
 }
 
 \note{
 The reaction coefficients in the \code{species} element of the returned value of \code{aout} are not valid.
-Because balancing on a basis species (i.e., dividing by its reaction coefficient) would be incorrect, \code{diagram} enforces \code{balance = 1} so that that the normalized sums of ranks are used as-is.
+Because balancing on a basis species (i.e., dividing by its reaction coefficient) would be incorrect, \code{diagram} enforces \code{balance = 1} so that that average rankings are used without further modification.
 }
 
 \seealso{