Merge pull request #79 from biometryhub/dev

Update main from dev

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 1.2.0
-Date: 2024-05-31 09:46:32 UTC
-SHA: ebce045fe222badd826f94e2d7cabb4475a5f32d
+Version: 1.2.1
+Date: 2024-06-04 09:02:24 UTC
+SHA: ec8d469ab6c9f36ffdcb8e3c7b1bab045d6ccef6

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: biometryassist
 Title: Functions to Assist Design and Analysis of Agronomic Experiments
-Version: 1.2.0
+Version: 1.2.1
 Authors@R: 
     c(person(given = "Sharon",
              family = "Nielsen",

NAMESPACE

@@ -87,6 +87,7 @@ importFrom(stats,var)
 importFrom(stringi,stri_sort)
 importFrom(stringi,stri_split_fixed)
 importFrom(utils,available.packages)
+importFrom(utils,compareVersion)
 importFrom(utils,download.file)
 importFrom(utils,install.packages)
 importFrom(utils,installed.packages)

NEWS.md

@@ -1,8 +1,14 @@
+# biometryassist 1.2.1
+
+## Bug Fixes
+
+- The new `summary_graph()` function was accidentally left out of the CRAN submission.
+
 # biometryassist 1.2.0
 
 ## Major changes
 
-- Introduced the `summary_plot()` (#75) and `heat_map()` (#19) functions 
+- Introduced the `summary_graph()` (#75) and `heat_map()` (#19) functions 
 - Enabled arbitrary `row`, `column`, `block` and `treatment` columns to be provided in the `autoplot.design()` function, to enable more general plotting of designs. (#28)
 
 ## Minor changes

R/autoplot.R

@@ -1,4 +1,4 @@
-#' Automatic plots for objects generated in biometryassist
+#' Generate automatic plots for objects generated in biometryassist
 #'
 #' @param object An object to create a plot for. Currently objects from the [multiple_comparisons()] or [design()] functions with class "mct" or "design" respectively are supported.
 #' @param label_height Height of the text labels above the upper error bar on the plot. Default is 0.1 (10%) of the difference between upper and lower error bars above the top error bar. Values > 1 are interpreted as the actual value above the upper error bar.

R/des_info.R

@@ -1,4 +1,4 @@
-#' Produces graph of design layout, skeletal ANOVA table and data frame with complete design
+#' Produce a graph of design layout, skeletal ANOVA table and data frame with complete design
 #'
 #' @param design.obj An `agricolae` design object.
 #' @param nrows The number of rows in the design.
@@ -11,7 +11,7 @@
 #' @param plot Logical (default `TRUE`). If `TRUE`, display a plot of the generated design. A plot can always be produced later using [autoplot()].
 #' @param rotation Rotate the text output as Treatments within the plot. Allows for easier reading of long treatment labels. Takes positive and negative values being number of degrees of rotation from horizontal.
 #' @param size Increase or decrease the text size within the plot for treatment labels. Numeric with default value of 4.
-#' @param margin Logical (default FALSE). Expand the plot to the edges of the plotting area i.e. remove white space between plot and axes.
+#' @param margin Logical (default FALSE). Setting to `TRUE` will add a margin (white space) between plot and axes.
 #' @param save One of `FALSE` (default)/`"none"`, `TRUE`/`"both"`, `"plot"` or `"workbook"`. Specifies which output to save.
 #' @param savename A filename for the design to be saved to. Default is the type of the design combined with "_design".
 #' @param plottype The type of file to save the plot as. Usually one of `"pdf"`, `"png"`, or `"jpg"`. See [ggplot2::ggsave()] for all possible options.

R/design.R

@@ -1,22 +1,22 @@
-#' Produces an experimental design with graph of design layout and skeletal ANOVA table
+#' Create a complete experimental design with graph of design layout and skeletal ANOVA table
 #'
-#' @param type The type of design. Supported design types are `crd`, `rcbd`, `lsd`, `crossed:<type>` where `<type>` is one of the previous types and `split`. See Details for more information.
+#' @param type The type of design. Supported design types are `crd`, `rcbd`, `lsd`, `crossed:<type>` where `<type>` is one of the previous types, and `split`. See Details for more information.
 #' @param treatments A vector containing the treatment names or labels.
-#' @param reps The number of replicates. Not required for Latin Squared Designs.
+#' @param reps The number of replicates. Ignored for Latin Square Designs.
 #' @param nrows The number of rows in the design.
 #' @param ncols The number of columns in the design.
 #' @param brows For RCBD and Split Plot designs. The number of rows in a block.
 #' @param bcols For RCBD and Split Plot designs. The number of columns in a block.
 #' @param byrow For split-plot only. Logical (default `TRUE`). Provides a way to arrange plots within whole-plots when there are multiple possible arrangements.
-#' @param sub_treatments A vector of treatments for subplots in a split plot design.
+#' @param sub_treatments A vector of treatments for sub-plots in a split plot design.
 #' @param fac.names Allows renaming of the `A` level of factorial designs (i.e. those using [agricolae::design.ab()]) by passing (optionally named) vectors of new labels to be applied to the factors within a list. See examples and details for more information.
 #' @param fac.sep The separator used by `fac.names`. Used to combine factorial design levels. If a vector of 2 levels is supplied, the first separates factor levels and label, and the second separates the different factors.
 #' @param plot Logical (default `TRUE`). If `TRUE`, display a plot of the generated design. A plot can always be produced later using [autoplot()].
 #' @param rotation Rotate the text output as Treatments within the plot. Allows for easier reading of long treatment labels. Takes positive and negative values being number of degrees of rotation from horizontal.
 #' @param size Increase or decrease the text size within the plot for treatment labels. Numeric with default value of 4.
 #' @param margin Logical (default `FALSE`). Expand the plot to the edges of the plotting area i.e. remove white space between plot and axes.
 #' @param save One of `FALSE` (default)/`"none"`, `TRUE`/`"both"`, `"plot"` or `"workbook"`. Specifies which output to save.
-#' @param savename A filename for the design to be saved to. Default is the type of the design combined with "_design".
+#' @param savename A file name for the design to be saved to. Default is the type of the design combined with "_design".
 #' @param plottype The type of file to save the plot as. Usually one of `"pdf"`, `"png"`, or `"jpg"`. See [ggplot2::ggsave()] for all possible options.
 #' @param seed Logical (default `TRUE`). If `TRUE`, return the seed used to generate the design. If a numeric value, use that value as the seed for the design.
 #' @param quiet Logical (default `FALSE`). Hide the output.
@@ -25,7 +25,7 @@
 #' @details The designs currently supported by `type` are Completely Randomised designs (`crd`), Randomised Complete Block designs (`rcbd`), Latin Square Designs (`lsd`), Factorial with crossed structure (use `crossed:<type>` where `<type>` is one of the previous types e.g. `crossed:crd`) and Split Plot designs (`split`). Nested factorial designs are supported through manual setup, see Examples.
 #' @details If `save = TRUE` (or `"both"`), both the plot and the workbook will be saved to the current working directory, with filename given by `savename`. If one of either `"plot"` or `"workbook"` is specified, only that output is saved. If `save = FALSE` (the default, or equivalently `"none"`), nothing will be output.
 #' @details `fac.names` can be supplied to provide more intuitive names for factors and their levels in factorial and split plot designs. They can be specified in a list format, for example `fac.names = list(A_names = c("a", "b", "c"), B_names = c("x", "y", "z"))`. This will result a design output with a column named `A_names` with levels `a, b, c` and another named `B_names` with levels `x, y, z`. Labels can also be supplied as a character vector (e.g. `c("A", "B")`) which will result in only the treatment column names being renamed. Only the first two elements of the list will be used, except in the case of a 3-way factorial design.
-#' @details `...` allows extra arguments to be passed to ggsave for output of the plot. The details of possible arguments can be found in  [ggplot2::ggsave()].
+#' @details `...` allows extra arguments to be passed to `ggsave()` for output of the plot. The details of possible arguments can be found in  [ggplot2::ggsave()].
 #'
 #' @importFrom graphics plot
 #' @importFrom ggplot2 ggsave

R/heatmap.R

@@ -1,15 +1,16 @@
-#' Heatmap
+#' Produce a heatmap of variables in a grid layout.
 #'
-#' Function to plot heatmaps of variables in a grid layout.
+#' This function plots a heatmap of variables in a grid layout, optionally grouping them.
 #'
-#' @param data A data frame containing the data to be plotted
-#' @param value A column of `data`, containing the values that vary over the space which produces the colours
+#' @param data A data frame containing the data to be plotted.
+#' @param value A column of `data`, containing the values that vary over the space which produces the colours.
 #' @param x_axis The column of `data` to use as the x axis data.
 #' @param y_axis The column of `data` to use as the y axis data.
 #' @param grouping An optional grouping variable to facet the plot by.
 #' @param raster Logical (default: `TRUE`). If `TRUE` uses [ggplot2::geom_raster()] for speed. Will not work if the grid is irregular.
-#' @param smooth Logical (default: `TRUE`). If `raster` is `TRUE`, interpolation can be applied across the grid to obtain a smoothed grid. Ignored if `raster` is `FALSE`.
-#' @param palette Colour palatte to use. By default it will use the `viridis` (colour-blind friendly) palette. Other palettes available can be seen with [grDevices::hcl.pals()].
+#' @param smooth Logical (default: `FALSE`). If `raster` is `TRUE`, interpolation can be applied across the grid to obtain a smoothed grid. Ignored if `raster` is `FALSE`.
+#' @param palette Colour palette to use. By default it will use the `viridis` (colour-blind friendly) palette. Other palettes available can be seen with [grDevices::hcl.pals()].
+#' @param ... Other arguments passed to [`facet_wrap()`]
 #'
 #' @importFrom ggplot2 ggplot aes geom_tile geom_raster scale_fill_gradientn scale_x_continuous scale_y_continuous facet_wrap vars theme_bw
 #' @importFrom rlang ensym enquo quo_is_null
@@ -25,11 +26,26 @@
 #' dat$groups <- sample(rep(LETTERS[1:6], times = 5))
 #'
 #' heat_map(dat, value, x, y)
+#'
+#' # Column names can be quoted, but don't need to be.
 #' heat_map(dat, "value", "x", "y", "groups")
-heat_map <- function(data, value, x_axis, y_axis, grouping = NULL, raster = TRUE, smooth = FALSE, palette = "default") {
+#'
+#' # Different palettes are available
+#' heat_map(dat, value, x, y, palette = "Spectral")
+#'
+#' # Arguments in ... are passed through to facet_wrap
+#' heat_map(dat, value, x, y, groups, labeller = ggplot2:::label_both)
+#' heat_map(dat, value, x, y, groups, scales = "free_y")
+#' heat_map(dat, value, x, y, groups, nrow = 1)
+heat_map <- function(data, value, x_axis, y_axis, grouping = NULL, raster = TRUE, smooth = FALSE, palette = "default", ...) {
 
     # TODO:
     # - Error and sanity checking
+    if(!is.data.frame(data)) {
+        stop(data, " is not a data frame.", call. = FALSE)
+    }
+
+    rlang::check_dots_used()
 
     value <- rlang::ensym(value)
     x_axis <- rlang::ensym(x_axis)
@@ -58,7 +74,7 @@ heat_map <- function(data, value, x_axis, y_axis, grouping = NULL, raster = TRUE
 
     if(!rlang::quo_is_null(grouping)) {
         grouping <- rlang::ensym(grouping)
-        plt <- plt + ggplot2::facet_wrap(ggplot2::vars({{ grouping }}))
+        plt <- plt + ggplot2::facet_wrap(ggplot2::vars({{ grouping }}), ...)
     }
 
     plt <- plt+ggplot2::theme_bw()

R/install_asreml.R

@@ -1,4 +1,4 @@
-#' Install or Update the ASReml-R package
+#' Install or update the ASReml-R package
 #'
 #' @description Helper functions for installing or updating the ASReml-R package, intended to reduce the difficulty of finding the correct version for your operating system and R version.
 #'

R/logltest.R

@@ -1,4 +1,4 @@
-#' Log-likelihood test for comparing terms in ASReml-R models
+#' Conduct a log-likelihood test for comparing terms in ASReml-R models
 #'
 #' @param model.obj An ASReml-R model object
 #' @param rand.terms Random terms from the model. Default is NULL.

R/mct.R

@@ -1,4 +1,4 @@
-#' Multiple Comparison Tests
+#' Perform Multiple Comparison Tests on a statistical model
 #'
 #' A function for comparing and ranking predicted means with Tukey's Honest Significant Difference (HSD) Test.
 #'
@@ -484,7 +484,7 @@ multiple_comparisons <- function(model.obj,
 }
 
 
-#' Print method for multiple_comparisons
+#' Print output of multiple_comparisons
 #'
 #' @param x An mct object to print to the console.
 #' @param ... Other arguments

R/resplot.R

@@ -1,4 +1,4 @@
-#' Residual plots of linear models.
+#' Produce residual plots of linear models
 #'
 #' Produces plots of residuals for assumption checking of linear (mixed) models.
 #'
@@ -10,7 +10,7 @@
 #' @param call.size A numeric value for the size of the model displayed on the plot.
 #' @param mod.obj Deprecated to be consistent with other functions. Please use `model.obj` instead.
 #'
-#' @return A list containing ggplot2 objects which are diagnostic plots.
+#' @return A ggplot2 object containing the diagnostic plots.
 #'
 #' @importFrom ggplot2 ggplot geom_histogram aes theme_bw stat_qq labs geom_qq_line geom_point
 #' @importFrom stats fitted qnorm quantile residuals sd shapiro.test

R/summary_graph.R

@@ -1,26 +1,37 @@
-#' Summary Graph
+#' Visualise a graphical summary of variables from a data frame
 #'
-#' Produce a graphical summary of variables from a data frame. Variables are plotted
-#' as box plots, grouped and, if enough variables are provided, coloured and facetted.
+#' Variables are plotted in different ways according to the number of explanatory
+#' variables provided as input.
 #'
 #' @param data A data frame containing the variables to be plotted.
 #' @param response The response variable to plot.
-#' @param exp_var The explanatory (or grouping) variable to plot.
-#' @param resp_units A string providing units to display on the response variable axis.
+#' @param exp_var The explanatory (or grouping) variable(s) to plot. Up to three can be provided.
+#' @param resp_units A string providing units to display on the response variable (y) axis. Will use the empty string by default so axes will have no units by default.
 #'
 #' @importFrom ggplot2 ggplot aes geom_boxplot stat_summary facet_wrap geom_point labs theme_bw
 #' @importFrom rlang ensym ensyms as_string
 #'
 #' @return A ggplot2 plot object
 #' @export
 #'
+#' @details
+#' With a single explanatory variable, a boxplot grouped by `exp_var` is produced.
+#' With two explanatory variables, a dot-plot with lines connecting the mean of each
+#' group is produced, with the first element of `exp_var` used as the x axis variable,
+#' and the second is used to colour the points. Three explanatory variables produces
+#' the same as two, but with the third used to facet the plot.
+#'
 #' @examples
 #'
 #' summary_graph(iris, "Petal.Length", "Species", "mm")
-#' summary_graph(iris, Petal.Length, "Species", "mm")
+#'
+#' # Multiple
+#' summary_graph(npk, "yield", c("N", "P"), "lb/plot")
+#'
+#  # Three way interaction
 #' summary_graph(npk, "yield", c("N", "P", "K"), "lb/plot")
 #'
-summary_graph <- function(data, response, exp_var, resp_units) {
+summary_graph <- function(data, response, exp_var, resp_units = "") {
 
     # TODO: NSE
 
@@ -33,10 +44,10 @@ summary_graph <- function(data, response, exp_var, resp_units) {
         stop(rlang::as_string(response), " does not appear to be a column of data. Please check input.", call. = FALSE)
     }
     if(!is.numeric(data[[rlang::as_string(response)]])) {
-        warning(rlang::as_string(response), " is not a numeric variable.")
+        stop(rlang::as_string(response), " is not a numeric variable.")
     }
     if(!is.character(resp_units)) {
-        stop("resp_units must be provided as a string.")
+        stop("resp_units must be provided as a string with quotes.")
     }
 
 
@@ -60,12 +71,17 @@ summary_graph <- function(data, response, exp_var, resp_units) {
             ggplot2::facet_wrap(~ .data[[exp_var[3]]])
     }
     else {
-        stop("Additional explanatory variables are not currently handled.")
+        stop("Additional explanatory variables are not currently supported.")
     }
 
+    if(resp_units!="") {
+        gg <- gg + ggplot2::labs(y = paste({{ response }}, " (", resp_units, ")", sep = ""))
+
+    }
     gg <- gg + ggplot2::geom_point(alpha = 0.3) +
-        ggplot2::labs(y = paste({{ response }}, " (", resp_units, ")", sep = "")) +
         ggplot2::theme_bw()
 
     return(gg)
 }
+
+

R/utility_functions.R

@@ -21,15 +21,15 @@ quiet <- function(x) {
 # this function is executed once the package is loaded
 ######################################################
 
-#' @importFrom utils available.packages packageVersion
+#' @importFrom utils available.packages packageVersion compareVersion
 #' @importFrom rlang is_interactive is_installed
 .onAttach <- function(library, pkg)
 {
-    installed_version <- utils::packageVersion('biometryassist')
+    local_version <- utils::packageVersion('biometryassist')
 
     if(rlang::is_interactive() && !isFALSE(rlang::peek_option("biometryassist.check"))) {
         output <- paste(paste0("    ", paste0(rep("~", times = 69), collapse = "")),
-                        paste("    |  ", pkg, " version ", installed_version, "                                     |",sep=""),
+                        paste("    |  ", pkg, " version ", local_version, "                                     |",sep=""),
                         "    |  Authors: Sharon Nielsen, Sam Rogers, Annie Conway                |",
                         "    |  Developed at the University of Adelaide with funding provided    |",
                         "    |  by the Australian Grains Research and Development Corporation.   |",
@@ -47,7 +47,7 @@ quiet <- function(x) {
         }
 
         # check which version is more recent
-        current_version <- tryCatch(
+        cran_version <- tryCatch(
             {
                 packages <- utils::available.packages()
                 ver <- packages["biometryassist","Version"]
@@ -57,11 +57,22 @@ quiet <- function(x) {
             }
         )
 
-        if(!is.na(current_version) && current_version > installed_version) { # current version on CRAN newer than installed
-            warning("    biometryassist version ", current_version, " is now available.\n",
+        if(compare_version(cran_version, as.character(local_version)) == 1) { # current version on CRAN newer than installed
+            warning("    biometryassist version ", cran_version, " is now available.\n",
                     "    Please update biometryassist by running\n",
                     "    install.packages('biometryassist')", call. = FALSE)
         }
     }
     invisible()
 }
+
+#' Function to compare package version for mocking
+#'
+#' @param a One package version
+#' @param b Another package version
+#'
+#' @return
+#' @keywords internal
+compare_version <- function(a, b) {
+    return(utils::compareVersion(as.character(a), as.character(b)))
+}

R/variogram.r

@@ -1,4 +1,4 @@
-#' Variogram plots for spatial models.
+#' Display variogram plots for spatial models
 #'
 #' Produces variogram plots for checking spatial trends.
 #'

_pkgdown.yml

@@ -9,18 +9,18 @@ template:
 
 reference:
 - title: Design
-  desc: Functions to help with the design of experiments
+  desc: Functions to help with the design of experiments.
 - contents:
   - starts_with("des")
 - title: Analysis
-  desc: Functions to help with the analysis of experiments
+  desc: Functions to help with the analysis of experiments.
 - contents:
   - resplot
   - multiple_comparisons
   - variogram
   - logl_test
 - title: Utilities
-  desc: Other helper functions
+  desc: Other helper functions.
 - contents:
   - autoplot
   - heat_map