r/Various documentation improvements.

Author: MLopez-Ibanez

r/DESCRIPTION

@@ -11,12 +11,12 @@ Authors@R: c(person("Manuel", "López-Ibáñez", role = c("aut", "cre"),
 Description: Visualization of multi-dimensional data arising in multi-objective optimization, including plots of the empirical attainment function (EAF), M. López-Ibáñez, L. Paquete, and T. Stützle (2010) <doi:10.1007/978-3-642-02538-9_9>, and symmetric Vorob'ev expectation and deviation, M. Binois, D. Ginsbourger, O. Roustant (2015) <doi:10.1016/j.ejor.2014.07.032>, among others.
 Depends: R (>= 4.0)
 Imports:
-        moocore,
-        graphics,
+        Rdpack,
+        collapse (>= 2.0.8),
         grDevices,
+        graphics,
         matrixStats,
-        collapse (>= 2.0.8),
-        Rdpack
+        moocore
 Suggests:
     extrafont,
     viridisLite,

r/R/eafdiffplot.R

@@ -15,14 +15,14 @@
 #' @param col A character vector of three colors for the magnitude of the
 #'   differences of 0, 0.5, and 1. Intermediate colors are computed
 #'   automatically given the value of `intervals`. Alternatively, a function
-#'   such as [viridisLite::viridis()] that generates a colormap given an integer
-#'   argument.
+#'   such as [viridisLite::viridis()] that generates a colormap given an
+#'   integer argument.
 #'
-#' @param intervals (`integer(1)`|`character()`) \cr The
-#'   absolute range of the differences \eqn{[0, 1]} is partitioned into the number
-#'   of intervals provided. If an integer is provided, then labels for each
-#'   interval are  computed automatically. If a character vector is
-#'   provided, its length is taken as the number of intervals.
+#' @param intervals (`integer(1)`|`character()`)\cr The absolute range of the
+#'   differences \eqn{[0, 1]} is partitioned into the number of intervals
+#'   provided. If an integer is provided, then labels for each interval are
+#'   computed automatically. If a character vector is provided, its length is
+#'   taken as the number of intervals.
 #'
 #' @param percentiles The percentiles of the EAF of each side that will be
 #'   plotted as attainment surfaces. `NA` does not plot any. See
@@ -31,12 +31,12 @@
 #' @param full.eaf Whether to plot the EAF of each side instead of the
 #'   differences between the EAFs.
 #'
-#' @param type Whether the EAF differences are plotted as points
-#'   (`"points"`) or whether to color the areas that have at least a
+#' @param type (`"points"`|`"area"`)\cr Whether the EAF differences are plotted
+#'   as points (`"points"`) or whether to color the areas that have at least a
 #'   certain value (`"area"`).
 #'
-#' @param legend.pos The position of the legend. See [legend()].  A value of
-#'   `"none"` hides the legend.
+#' @param legend.pos (`character(1)`)\cr The position of the legend. See
+#'   [legend()].  A value of `"none"` hides the legend.
 #'
 #' @param title_left,title_right Title for left and right panels, respectively.
 #'
@@ -58,28 +58,27 @@
 #'   [plot.default()].
 #'
 #' @details
-#'   This function calculates the differences between the EAFs of two
-#'   data sets, and plots on the left the differences in favour
-#'   of the left data set, and on the right the differences in favour of
-#'   the right data set. By default, it also plots the grand best and worst
-#'   attainment surfaces, that is, the 0%- and 100%-attainment surfaces
-#'   over all data. These two surfaces delimit the area where differences
-#'   may exist. In addition, it also plots the 50%-attainment surface of
-#'   each data set.
 #'
-#'   With `type = "point"`, only the points where there is a change in
-#'   the value of the EAF difference are plotted. This means that for areas
-#'   where the EAF differences stays constant, the region will appear in
-#'   white even if the value of the differences in that region is
-#'   large. This explains "white holes" surrounded by black
-#'   points.
+#'   This function calculates the differences between the EAFs of two data
+#'   sets, and plots on the left the differences in favour of the left data
+#'   set, and on the right the differences in favour of the right data set. By
+#'   default, it also plots the grand best and worst attainment surfaces, that
+#'   is, the 0%- and 100%-attainment surfaces over all data. These two surfaces
+#'   delimit the area where differences may exist. In addition, it also plots
+#'   the 50%-attainment surface of each data set.
 #'
-#'   With `type = "area"`, the area where the EAF differences has a
-#'   certain value is plotted.  The idea for the algorithm to compute the
-#'   areas was provided by Carlos M. Fonseca.  The implementation uses R
-#'   polygons, which some PDF viewers may have trouble rendering correctly
-#'   (See
-#'   \url{https://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-are-there-unwanted-borders}). Plots (should) look correct when printed.
+#'   With `type = "point"`, only the points where there is a change in the
+#'   value of the EAF difference are plotted. This means that for areas where
+#'   the EAF differences stays constant, the region will appear in white even
+#'   if the value of the differences in that region is large. This explains
+#'   "white holes" surrounded by black points.
+#'
+#'   With `type = "area"`, the area where the EAF differences has a certain
+#'   value is plotted.  The idea for the algorithm to compute the areas was
+#'   provided by Carlos M. Fonseca.  The implementation uses R polygons, which
+#'   some PDF viewers may have trouble rendering correctly (See
+#'   \url{https://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-are-there-unwanted-borders}).
+#'   Plots (should) look correct when printed.
 #'
 #'   Large differences that appear when using `type = "point"` may
 #'   seem to disappear when using `type = "area"`. The explanation is
@@ -160,7 +159,7 @@ eafdiffplot <-
   # FIXME: check that it is either an integer or a character vector.
   if (length(intervals) == 1L) {
     intervals <- seq_intervals_labels(
-      round(seq(0, 1 , length.out = 1 + intervals), 4L), digits = 1L)
+      round(seq(0, 1, length.out = 1 + intervals), 4L), digits = 1L)
   }
   if (is.function(col)) { # It is a color-map, like viridis()
     col <- col(length(intervals))

r/R/eafplot.R

@@ -4,13 +4,13 @@
 #' attainment surfaces for certain percentiles or as points.
 #'
 #' This function can be used to plot random sets of points like those obtained
-#' by different runs of biobjective stochastic optimisation algorithms.  An EAF
+#' by different runs of biobjective stochastic optimisation algorithms \citep{LopPaqStu09emaa}.  An EAF
 #' curve represents the boundary separating points that are known to be
 #' attainable (that is, dominated in Pareto sense) in at least a fraction
-#' (quantile) of the runs from those that are not. The median EAF represents
+#' (quantile) of the runs from those that are not \citep{Grunert01}. The median EAF represents
 #' the curve where the fraction of attainable points is 50%.  In single
 #' objective optimisation the function can be used to plot the profile of
-#' solution quality over time of a collection of runs of a stochastic optimizer.
+#' solution quality over time of a collection of runs of a stochastic optimizer. \citep{LopVerDreDoe2025}.
 #'
 #' @param x Either a matrix of data values, or a data frame, or a list of
 #'     data frames of exactly three columns.
@@ -20,18 +20,29 @@ eafplot <- function(x, ...) UseMethod("eafplot")
 
 #' @describeIn eafplot Main function
 #'
-#' @param groups This may be used to plot profiles of different algorithms on the same plot.
-#' @param sets (`numeric()`)\cr Vector indicating which set each point belongs to.
-#' @param percentiles (`numeric()`) Vector indicating which percentile should be plot. The
-#'   default is to plot only the median attainment curve.
-#' @param attsurfs   TODO
-#' @param type (`character(1)`)\cr string giving the type of plot desired.  The following values
-#'   are possible, \samp{points} and \samp{area}.
+#' @param sets Vector indicating which set each point belongs to. Will be coerced to a factor.
+#'
+#' @param groups This may be used to plot data for different algorithms on
+#'   the same plot. Will be coerced to a factor.
+#'
+#' @param percentiles (`numeric()`)\cr Vector indicating which percentile
+#'   should be plot. The default is to plot only the median attainment curve.
+#'
+#' @param attsurfs TODO
+#'
+#' @param type (`"point"`|`"area"`)\cr Type of plot.
+#'
 #' @param xlab,ylab,xlim,ylim,log,col,lty,lwd,pch,cex.pch,las Graphical
 #'   parameters, see [plot.default()].
-#' @param legend.pos the position of the legend, see [legend()].  A value of `"none"` hides the legend.
-#' @param legend.txt a character or expression vector to appear in the
-#'   legend. If `NULL`, appropriate labels will be generated.
+#'
+#' @param legend.pos (`character(1)`|`list()`|`data.frame()`)\cr Position of
+#'   the legend.  This may be xy coordinates or a keyword ("bottomright",
+#'   "bottom", "bottomleft", "left", "topleft", "top", "topright", "right",
+#'   "center"). See Details in [legend()].  A value of "none" hides the legend.
+#'
+#' @param legend.txt (`expression()`|`character()`)\cr Character or expression
+#'   vector to appear in the legend. If `NULL`, appropriate labels will be
+#'   generated.
 #'
 #' @param extra.points A list of matrices or data.frames with
 #'   two-columns. Each element of the list defines a set of points, or
@@ -43,18 +54,16 @@ eafplot <- function(x, ...) UseMethod("eafplot")
 #' @param extra.legend A character vector providing labels for the
 #'   groups of points.
 #'
-#' @param maximise `logical()`|`logical(1)`\cr Whether the objectives must be
+#' @param maximise (`logical()`|`logical(1)`)\cr Whether the objectives must be
 #'   maximised instead of minimised. Either a single logical value that applies
 #'   to all objectives or a vector of logical values, with one value per
 #'   objective.
 #'
-#' @param xaxis.side On which side the x-axis is drawn. Valid values are
-#'   `"below"` and `"above"`. See [axis()].
+#' @param xaxis.side (`"below"`|`"above"`)\cr On which side the x-axis is drawn.  See [axis()].
 #'
-#' @param yaxis.side On which side the y-axis is drawn. Valid values are
-#'   `"left"` and `"right"`. See [axis()].
+#' @param yaxis.side (`"left"`|`"right"`)\cr On which side the y-axis is drawn. See [axis()].
 #'
-#' @param axes A logical value indicating whether both axes should be drawn
+#' @param axes (`logical(1)`)\cr A logical value indicating whether both axes should be drawn
 #'   on the plot.
 #'
 #' @param sci.notation Generate prettier labels
@@ -106,11 +115,13 @@ eafplot <- function(x, ...) UseMethod("eafplot")
 #'          ylab = "Minimum idle time (minutes)", maximise = c(FALSE, TRUE),
 #'          las = 1, log = "y", main = "SPEA2 (Richmond)",
 #'          legend.pos = "bottomright")
+#'
+#' data(tpls50x20_1_MWT, package="moocore")
+#' eafplot(tpls50x20_1_MWT[, c(2,3)], sets = tpls50x20_1_MWT[,4L],
+#'         groups = tpls50x20_1_MWT[["algorithm"]])
 #' }
 #' @references
-#' \insertRef{Grunert01}{moocore}
-#'
-#' \insertRef{LopPaqStu09emaa}{moocore}
+#' \insertAllCited{}
 #' @concept eaf
 #' @export
 eafplot.default <-
@@ -165,13 +176,13 @@ eafplot.default <-
   if (is.null(ylab))
     ylab <- if (!is.null(colnames(x)[2L])) colnames(x)[2L] else "objective 2"
 
-  if (!is.null (attsurfs)) {
-    # Don't we need to apply maximise?
-    attsurfs <- lapply(attsurfs, function(x) as.matrix(x[, c(1L,2L), drop=FALSE]))
-  } else {
+  if (is.null (attsurfs)) {
     attsurfs <- eaf(x, sets, percentiles = percentiles, maximise = maximise, groups = groups)
     attsurfs <- eaf_as_list(attsurfs)
     #    attsurfs <- lapply(attsurfs, matrix_maximise, maximise = maximise)
+  } else {
+    # Don't we need to apply maximise?
+    attsurfs <- lapply(attsurfs, function(x) as.matrix(x[, c(1L,2L), drop=FALSE]))
   }
 
   # FIXME: We should take the range from the attsurfs to not make x mandatory.
@@ -415,17 +426,17 @@ plot_eaf_full_area <- function(attsurfs, extreme, maximise, col)
 # seq_intervals_labels(seq(0,1, length.out=5), digits = 1)
 # "[0.0, 0.2)" "[0.2, 0.4)" "[0.4, 0.6)" "[0.6, 0.8)" "[0.8, 1.0]"
 # FIXME: Add examples and tests
-seq_intervals_labels <- function(s, first.open = FALSE, last.open = FALSE,
+seq_intervals_labels <- function(s, first_open = FALSE, last_open = FALSE,
                                  digits = NULL)
 {
   # FIXME:  This should use:
   # levels(cut(0, s, dig.lab=digits, include.lowest=TRUE, right=FALSE))
   s <- formatC(s, digits = digits, format = if (is.null(digits)) "g" else "f")
   if (length(s) < 2) stop ("sequence must have at least 2 values")
   intervals <- paste0("[", s[-length(s)], ", ", s[-1], ")")
-  if (first.open)
+  if (first_open)
     substr(intervals[1], 0, 1) <- "("
-  if (!last.open) {
+  if (!last_open) {
     len <- nchar(intervals[length(intervals)])
     substr(intervals[length(intervals)], len, len+1) <- "]"
   }

r/R/interactive.R

@@ -7,26 +7,15 @@
 #' [moocore::choose_eafdiff()] may be used in a non-interactive context.
 #'
 #' @inheritParams eafdiffplot
-# @param data.left,data.right Data frames corresponding to the input data of
-#   left and right sides, respectively. Each data frame has at least three
-#   columns, the third one being the set of each point. See also
-#   [read_datasets()].
-#
-# @param intervals (`integer(1)`|`character()`) \cr The absolute range of the
-#   differences \eqn{[0, 1]} is partitioned into the number of intervals
-#   provided. If an integer is provided, then labels for each interval are
-#   computed automatically. If a character vector is provided, its length is
-#   taken as the number of intervals.
 #'
 #' @param ... Other graphical parameters are passed down to
 #'   [eafdiffplot()].
 #'
-#'
-#' @return `matrix` where the first 4 columns give the coordinates of two
+#' @return `matrix()` where the first 4 columns give the coordinates of two
 #'   corners of each rectangle and the last column. In both cases, the last
 #'   column gives the positive differences in favor of the chosen side.
 #'
-#' @seealso    [moocore::read_datasets()], [eafdiffplot()], [moocore::whv_rect()]
+#' @seealso  [moocore::read_datasets()], [eafdiffplot()], [moocore::whv_rect()]
 #'
 #' @examples
 #'
@@ -56,7 +45,7 @@
 #' boxplot(list(A1=whv_A1, A2=whv_A2), main = "Weighted hypervolume")
 #' }
 #'
-#'@references
+#' @references
 #' \insertAllCited{}
 #' @concept eaf
 #' @export

r/R/pdf_crop.R

@@ -18,31 +18,35 @@
 #' As an alternative, saving the PDF with [grDevices::cairo_pdf()] should
 #' already embed the fonts.
 #'
-#' @param filename Filename of a PDF file to crop. The file will be overwritten.
-#' @param mustWork If `TRUE`, then give an error if the file cannot be cropped.
-#' @param pdfcrop Path to the `pdfcrop` utility.
-#' @param embed_fonts (`logical(1)`) If `TRUE`, use [grDevices::embedFonts()] to embed fonts.
-#' @return Nothing
+#' @param filename (`character(1)`)\cr Filename of a PDF file to crop. The file will be overwritten.
+#'
+#' @param mustWork (`logical1`)\cr If `TRUE`, then give an error if the file cannot be cropped.
+#'
+#' @param pdfcrop (`character(1)`)\cr Path to the `pdfcrop` utility.
+#'
+#' @param embed_fonts (`logical(1)`)\cr If `TRUE`, use [grDevices::embedFonts()] to embed fonts.
+#'
+#' @return No return value, called for side effects
 #'
 #' @seealso [grDevices::embedFonts()] [extrafont::embed_fonts()] [grDevices::cairo_pdf()]
 #'
 #' @examples
-#' \dontrun{
 #' extdata_path <- system.file(package = "moocore", "extdata")
 #' A1 <- read_datasets(file.path(extdata_path, "wrots_l100w10_dat"))
 #' A2 <- read_datasets(file.path(extdata_path, "wrots_l10w100_dat"))
-#' pdf(file = "eaf.pdf", onefile = TRUE, width = 5, height = 4)
-#' eafplot(list(A1 = A1, A2 = A2), percentiles = 50, sci.notation=TRUE)
+#' filename <- tempfile("eafplot", fileext=".pdf")
+#' pdf(file = filename, onefile = TRUE, width = 5, height = 4)
+#' eafplot(list(A1 = A1, A2 = A2), percentiles = 50, sci.notation = TRUE)
 #' dev.off()
-#' pdf_crop("eaf.pdf")
-#' }
+#' try(pdf_crop(filename)) # This may fail if pdfcrop is not installed.
+#'
 #' @export
 pdf_crop <- function(filename, mustWork = FALSE, pdfcrop = Sys.which("pdfcrop"),
                      embed_fonts = FALSE)
 {
   if (!file.exists(filename)) {
     stop("PDF file", shQuote(filename), "not found")
-  } else if(!has_file_extension(filename, "pdf")){
+  } else if (!has_file_extension(filename, "pdf")) {
     stop(shQuote(filename), "is not a PDF file")
   } else if (is.null(pdfcrop) || pdfcrop == "") {
       if (mustWork) {
@@ -52,12 +56,8 @@ pdf_crop <- function(filename, mustWork = FALSE, pdfcrop = Sys.which("pdfcrop"),
       }
   } else {
     system2(pdfcrop, c("--pdfversion 1.5", shQuote(filename), shQuote(filename)),
-            timeout = 60, stdout = FALSE, stderr = FALSE)
-    if (embed_fonts) embedFonts(filename)
+      timeout = 60, stdout = FALSE, stderr = FALSE)
+    if (embed_fonts)
+      embedFonts(filename)
   }
 }
-
-has_file_extension <- function(filename, extension)
-{
-  grepl(paste0('[.]', extension, '$'), filename, ignore.case = TRUE)
-}