iz_plot_alluvial.R

#' iNZight Helper Function to generate Alluvial plots
#'
#' Will, (if required) recode the data to Alluvial or Lasagna format using \code{\link{recode_long_alluvial}} or
#' \code{\link{recode_long_lasagna}} as required,
#' and provide a complete ready-to-output plot for iNZight or other purposes.
#'
#' @param .data A longZight object generated by \code{\link{load_long_data}}
#' @param response The response variable to be plotted as an Alluvial plot
#' @param xlab  Optional x-axis label
#' @param title Optional title
#' @param completecases Logical variable to exclude incomplete cases
#' @param highlight Response level to be highlighted
#(only for \code{plot.mode = 1} or if \code{.data} inherits the \code{longZightAlluv} class)
#' @param plot.mode Integer between 1 and 3. \code{1} for "Colour by Origin" mode, \code{2} for "Transitional" mode and \code{3} for "Trace Flow" mode.
#' @param focus Time period to use as focus/origin point (only for \code{plot.mode = 1} or if \code{.data} inherits the \code{longZightAlluv} class)
#'
#' @return \code{\link[ggplot2:ggplot2-package]{ggplot2}} plot with the data represented as an Alluvial diagram
#' @examples
#' \dontrun{
#' mydata %>%
#'   load_long_data(IDind, WAVE) %>%
#'   refactor_wave %>%
#'   iz_plot_alluvial(A5E, completecases = TRUE)
#' }
#' @export
iz_plot_alluvial <- function(...) {
  UseMethod("iz_plot_alluvial")
}

#' iNZight Helper Function to generate Alluvial plots from \code{longZightAlluv} objects
#' @rdname iz_plot_alluvial
#' @method iz_plot_alluvial longZightAlluv
#' @export
#' @export
iz_plot_alluvial.longZightAlluv <- function(.data, response, xlab = "Wave", title = paste0("Plot of ", response), completecases = FALSE, highlight = NULL, plot.mode = 1, focus = NULL, ...) {
  print(.data %>%
        plot_long_alluvial(highlight = highlight, focus = focus) +
          ggtitle(response))
}

#' iNZight Helper Function to generate Alluvial plots from \code{longZightLasagna} objects
#' @rdname iz_plot_alluvial
#' @method iz_plot_alluvial longZightLasagna
#' @export
#' @export
iz_plot_alluvial.longZightLasagna <- function(.data, response, xlab = "Wave", title = paste0("Plot of ", response), completecases = FALSE, highlight = NULL, plot.mode = 1, ...) {
  print(.data %>%
        plot_long_alluvial(highlight = highlight, alluvium = (plot.mode == 3)) +
          ggplot2::ggtitle(response))
}

#' iNZight Helper Function to generate Alluvial plots from \code{longZight} objects
#' @rdname iz_plot_alluvial
#' @method iz_plot_alluvial longZight
#' @export
#' @export
iz_plot_alluvial.longZight <- function(.data, response, xlab = "Wave", title = paste0("Plot of ", response), completecases = FALSE, highlight = NULL, plot.mode = 1, focus = NULL, ...) {
  if (plot.mode == 1) {
  print(.data %>% recode_long_alluvial(response, completecases = completecases, ts.args = FALSE) %>%
    plot_long_alluvial(highlight = highlight, focus = NULL) +
      ggtitle(response))
  } else {
    print(.data %>% recode_long_lasagna(response, completecases = completecases, ts.args = FALSE) %>%
            plot_long_alluvial(highlight = highlight, alluvium = (plot.mode == 3)) +
            ggplot2::ggtitle(response))
  }
}