RFC: Configurable plot.cca - how to proceed?

[jarioksa]

cca & plot.cca were published in vegan release 1.4-0 in May, 2002. The plot function was intended as quick & dirty way of getting graph, but it was not really configurable: colours, shapes, character sizes, fonts were all hard-coded and could not be changed. This was not good. First relief was in 1.4-3 of April, 2003, which added freely configurable points and text, but this was still cumbersome. In 1.4-3 we also had first version of ordiplot which originally was intended for plotting non-vegan ordination objects (with scores function to extract their results). Later the ordiplot improved and finally we made it work in the middle of a pipe: it takes plotting from the pipe and passes the plotting data further to the next function. Support functions text and points were made more and more capable to reproduce plot.cca graphics (still improved in current development version 2.6-7), and can be used instead of text.cca and points.cca. We had to take care of using same axes, scaling etc. in all plot commands, but this is taken automatically care of within pipe. R has now pipes (and before they were in magirttr), and people are getting used to long chains of commands, partly because that is what they need to do in ggplot graphics. With the current version, we can reproduce the default plot with this pipe:

data(dune)
m <- rda(dune)
plot(m, scaling = "symmetric", type = "n") |>
  text("sites", cex = 0.7) |>
  text("species", col = 2, cex = 0.7)

It is just easy to have an arrow biplot with italic text for species names and points for sites:

plot(m, scaling = "symmetric", type = "n") |>
  points("sites", cex = 0.7, pch = 16,  col ="blue") |>
  text("species", arrows = TRUE, col = 2, cex = 0.7, font = 3, xpd = TRUE)

This feels like good enough for flexible configuration of graphics. However, I took a step forward and re-implemented plot.cca with ordiplot functions. The output is very similar (almost identical) to the old plot.cca with its default colours, shapes and sizes, but can be freely configured. The graphical parameters can be either global dot arguments which are applied for scores, or the user can supply a list of graphical parameters that replace the defaults. This adds an argument for each score element. Looks uggly, but these can be ignored if the user is satisfied with defaults or only wants to change things globally. With new plot.cca, the arrow biplot is easy:

plot(m, scaling="symmetric", spe.par = list(arrows=TRUE, font=3, xpd = TRUE))

Here we only need arguments that change defaults.

All these functions are new and need testing. All feedback is invaluable. For instance, I'm not quite sure of the user-interface. There may also be cases where these functions fail, but that needs more extensive testing.

[gavinsimpson]

Is this in a particular branch so that I can try it out?

It would be nice to turn on ordipointlabel()-like plotting in plot() or in the points() layer, something like

plot(m, scaling = "symmetric", type = "n") |>
  points("sites", cex = 0.7, optimize = TRUE) |>
  points("species", col = 2, cex = 0.7, optimize = TRUE)

where, when optimize = TRUE (default: FALSE), plotting would use ordipointlabel().

[jarioksa]

It is now in master: install in the usual way.

The function uses now points.ordiplot and text.ordiplot, and changing these functions will add the feature (and I think this should be in text). What you can do already now is:

plot(m, scaling = "symmetric", type = "n") |>
  points("species", col=2, cex = 0.7) |>
  text("species", col = 2, cex = 0.7,  pos=3)

Which will plot only species and put the species name above the point. Then you can create a position vector and manually change the pos values for text that should be positioned right, left or below the point.

For more automatic procedure, I can see now two alternatives:

1. Add this option to text.ordiplot.
2. Make ordipointlabel pipable. For this it should pass on input ordiplot object either optionally or in a compatible way. Now it is incompatible, but if it adds its new structure (coordinates of text) to an ordiplot object, it could work in both worlds (orditkplot and ordiplot).

In 2.6-7 development I made ordilabel pipable, and I've considered adding its capability to text.ordiplot similarly as in plot.envfit where the text can be over a label covering things under. There I have argument bg = <color>: if this is used, text is printed with ordilabel with that background colour. bg = "white" would be in the same colour as common background, but cover things under.

[jarioksa]

I think that making ordipointlabel pipe-compatible may be a better choice. ordiplot functions take only one kind of scores and you could optimize species and separately optimize site scores, but these optimizations can (and will) clash when overlaid. Currently ordipointlabel returns original scores stacked into one matrix and label positions with similar stacking whereas for ordiplot thru-pipes the matrices should be kept separate. What ever is done vegan3d::orditkplot should handle the result object – and naturally the ordipointlabel support functions. This can be handled either maintaining compatibility of the return object or editing these functions.

[jarioksa]

It seems that very small changes are needed for ordipointlabel pipes:

diff --git a/R/ordipointlabel.R b/R/ordipointlabel.R
index 6f780b4d..d06a8731 100644
--- a/R/ordipointlabel.R
+++ b/R/ordipointlabel.R
@@ -95,7 +95,10 @@
     ##text(lab, labels=labels, col = col, cex = cex, font = font,  ...)
     ordiArgAbsorber(lab, labels=labels, col = col, cex = cex, font = font,
                     FUN = text, ...)
-    pl <- list(points = xy)
+    if (!inherits(x, "ordiplot"))
+        pl <- list(points = xy)
+    else
+        pl <- x
     pl$labels <- lab
     attr(pl$labels, "font") <- font
     args <- list(tcex = cex, tcol = col, pch = pch, pcol = col,
@@ -104,6 +107,6 @@
     pl$par <- par(no.readonly = TRUE)
     pl$dim <- par("din")
     attr(pl, "optim") <- sol
-    class(pl) <- c("ordipointlabel", "orditkplot", class(pl))
+    class(pl) <- c("ordipointlabel", "orditkplot", "ordiplot")
     invisible(pl)
 }

With this you can do:

m <- rda(dune ~ Moisture + Management, dune.env)
plot(m, type="n", scaling="sym") |>
  ordipointlabel(pch = c("o",NA), xpd=TRUE, add=TRUE) |>
  points("species", arrow=TRUE, col=2) |>
  text("centroids", col=4, bg="white")

This will do the default ordipointlabel and optimize together species and sites, but it will only move species labels and draw no points. Instead we draw arrows for species in the next points (but species labels are optimized for points, and some will be moved over arrow, and this is not quite nice).

If ordipointlabel is used in pipe, it will add its stuff to the ordiplot object, including xy of stacked species and site scores with corresponding lab for label coordinates, plus graphic arguments. All these are extra and unknown to following plotting functions in a pipe. They are extra cargo, but we cannot use, say, calculated lab coordinates for next text.

I have not committed this github and I do not know how to proceed. It would also be very easy to implement text(..., optimize = TRUE), but this would do nothing to reduce overlap with two sets of labels. Comments?