Merge pull request #184 from hugomflavio/issue_183

closes 183

Author: hugomflavio

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: actel
 Title: Acoustic Telemetry Data Analysis
-Version: 1.3.0.9023
+Version: 1.3.0.9024
 Authors@R: c(
     person("Hugo", "Flávio", role = c("aut", "cre"),
            email = "hflavio@dal.ca", comment = c(ORCID = "0000-0002-5174-1197")),

NEWS.md

@@ -40,6 +40,7 @@ Enhancements:
   * Improved the inner mechanics of `extractSignals()` and `extractCodeSpaces()` so they're much faster now.
   * New arguments `back.warning` and `back.error` included to `migration()` to give users more control over warnings and user interaction prompts.
   * New column "Last.section" in `status.df`.
+  * New argument `y.order` for function `plotDetections()` following user request (issue [#183](https://github.com/hugomflavio/actel/issues/183)).
 
 ## actel 1.3.0
 

R/helper.R

@@ -542,9 +542,9 @@ event <- function(..., type, tag) {
   }
   type <- tolower(type)
 
-  if ("warning" %in% type & "error" %in% type) { # nocov start
+  if ("warning" %in% type & "stop" %in% type) { # nocov start
     # this should never happen, this is a dev error
-    stop("event() was called with both warning and error flags.",
+    stop("event() was called with both warning and stop flags.",
          call. = FALSE)
   } # nocov end
 

R/plot.R

@@ -776,6 +776,7 @@ plotMoves <- function(input, tags, title, xlab, ylab, col, array.alias, show.rel
 #' @param tag The transmitter to be plotted.
 #' @param type DEPRECATED. Please use the argument y.axis instead.
 #' @param y.axis The type of y axis desired. One of "stations" (default) or "arrays".
+#' @param y.order A vector with the desired order for the y-axis values.
 #' @param title An optional title for the plot. If left empty, a default title will be added.
 #' @param xlab,ylab Optional axis names for the plot. If left empty, default axis names will be added.
 #' @param col An optional colour scheme for the detections. If left empty, default colours will be added.
@@ -810,8 +811,8 @@ plotMoves <- function(input, tags, title, xlab, ylab, col, array.alias, show.rel
 #' @export
 #'
 plotDetections <- function(input, tag, type,
-                           y.axis = c("auto", "stations", "arrays"), title,
-                           xlab, ylab, col, array.alias, section.alias,
+                           y.axis = c("auto", "stations", "arrays"), y.order,
+                           title, xlab, ylab, col, array.alias, section.alias,
                            frame.warning = TRUE, x.label.format,
                            only.valid = FALSE, like.migration = TRUE) {
   # NOTE: The NULL variables below are actually column names used by ggplot.
@@ -975,12 +976,30 @@ plotDetections <- function(input, tag, type,
     names(link) <- 1:length(link)
     link <- sort(link)
     link <- as.numeric(names(link))
-    y.order <- spatial$stations$Standard.name[link]
+    tmp.y.order <- spatial$stations$Standard.name[link]
   } else {
     if (any(detections$Array == "Unknown")) {
-      y.order <- c(array.order$Array, "Unknown")
+      tmp.y.order <- c(array.order$Array, "Unknown")
     } else {
-      y.order <- array.order$Array
+      tmp.y.order <- array.order$Array
+    }
+  }
+
+  if (missing("y.order")) {
+    y.order <- tmp.y.order
+  } else {
+    check <- !tmp.y.order %in% y.order
+    if (any(check)) {
+      stop("y.order argument is missing the following required values: ",
+           paste(tmp.y.order[check], collapse = ", "),
+           call. = FALSE)
+    }
+    check <- !y.order %in% tmp.y.order
+    if (any(check)) {
+      warning("y.order argument has values that will not be used: ",
+           paste(y.order[check], collapse = ", "),
+           call. = FALSE, immediate. = TRUE)
+      y.order <- y.order[!check]
     }
   }