% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/function_PlotPerformanceByAttribute.R
\name{PlotPerformanceByAttribute}
\alias{PlotPerformanceByAttribute}
\alias{PlotJohan}
\title{Plot model performance by SUBID attributes}
\usage{
PlotPerformanceByAttribute(
  subass,
  subass.column = 2,
  groups = NULL,
  attributes,
  join.type = c("join", "cbind"),
  group.join.type = c("join", "cbind"),
  groups.color.pal = NULL,
  drop = TRUE,
  alpha = 0.4,
  trendline = TRUE,
  trendline.method = "lm",
  trendline.formula = NULL,
  trendline.alpha = 0.5,
  trendline.darken = 15,
  density.plot = FALSE,
  density.plot.type = c("density", "boxplot"),
  scale.x.log = FALSE,
  scale.y.log = FALSE,
  xsigma = 1,
  ysigma = 1,
  xlimits = c(NA, NA),
  ylimits = c(NA, NA),
  xbreaks = waiver(),
  ybreaks = waiver(),
  xlabels = waiver(),
  ylabels = waiver(),
  xlab = NULL,
  ylab = NULL,
  ncol = NULL,
  nrow = NULL,
  align = "hv",
  common.legend = TRUE,
  legend.position = "bottom",
  group.legend.title = "Group",
  common.y.axis = FALSE,
  summary.table = FALSE,
  table.margin = 0.4,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300
)

PlotJohan(
  subass,
  subass.column = 2,
  groups = NULL,
  attributes,
  join.type = c("join", "cbind"),
  group.join.type = c("join", "cbind"),
  groups.color.pal = NULL,
  drop = TRUE,
  alpha = 0.4,
  trendline = TRUE,
  trendline.method = "lm",
  trendline.formula = NULL,
  trendline.alpha = 0.5,
  trendline.darken = 15,
  density.plot = FALSE,
  density.plot.type = c("density", "boxplot"),
  scale.x.log = FALSE,
  scale.y.log = FALSE,
  xsigma = 1,
  ysigma = 1,
  xlimits = c(NA, NA),
  ylimits = c(NA, NA),
  xbreaks = waiver(),
  ybreaks = waiver(),
  xlabels = waiver(),
  ylabels = waiver(),
  xlab = NULL,
  ylab = NULL,
  ncol = NULL,
  nrow = NULL,
  align = "hv",
  common.legend = TRUE,
  legend.position = "bottom",
  group.legend.title = "Group",
  common.y.axis = FALSE,
  summary.table = FALSE,
  table.margin = 0.4,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300
)
}
\arguments{
\item{subass}{Information to plot, typically model performances from imported HYPE 'subassX.txt' files. Data frame object
with first column containing SUBIDs and additional columns containing model results to plot. See details.}

\item{subass.column}{Column index of information in \code{subass} to plot on the y-axis of the output plots.}

\item{groups}{Optional data frame object to specify groups of SUBIDs to plot separately. First column should contain SUBIDs and second column should contain group IDs.}

\item{attributes}{Data frame object containing the subbasin attribute information to plot on the x-axis of the output plots. Typically a data frame created by \code{\link{SubidAttributeSummary}}}

\item{join.type}{Specify how to join \code{subass} to \code{attributes}. Default "join" will perform a \link[dplyr:mutate-joins]{dplyr::left_join} in which the order of the SUBIDs does not need to match. Additional option "cbind"
will perform a \code{\link{cbind}} in which the order of the SUBIDs needs to match; this can be helpful if you want to create plots where \code{subass} performance data is calculated according to a
grouping variable (e.g. month).}

\item{group.join.type}{Specify how to join \code{subass} to \code{groups}. Default "join" will perform a \link[dplyr:mutate-joins]{dplyr::left_join} in which the order of the SUBIDs does not need to match. Additional option "cbind"
will perform a \code{\link{cbind}} in which the order of the SUBIDs needs to match; this can be helpful if you want to create plots where \code{subass} performance data is calculated according to a
grouping variable (e.g. month).}

\item{groups.color.pal}{Vector containing colors to use when plotting groups. Only used if groups is not \code{NULL}.}

\item{drop}{Logical, should unused factor levels be omitted from the legend. See \link[ggplot2:scale_manual]{ggplot2::scale_color_manual} and \link[ggplot2:scale_manual]{ggplot2::scale_fill_manual}.}

\item{alpha}{Numeric value to set transparency of dots in output plots. Should be in the range 0-1.}

\item{trendline}{Logical, if \code{TRUE}, then trendlines will be added to the output plots. Set to \code{FALSE} to hide trendlines. See \link[ggplot2:geom_smooth]{ggplot2::geom_smooth}.}

\item{trendline.method}{Specify method used to create trendlines. See \link[ggplot2:geom_smooth]{ggplot2::geom_smooth}.}

\item{trendline.formula}{Specify formula used to create trendlines. See \link[ggplot2:geom_smooth]{ggplot2::geom_smooth}.}

\item{trendline.alpha}{Numeric value to set transparency of trendlines in output plots. Should be in the range 0-1.}

\item{trendline.darken}{Numeric value to make the trendlines darker color shades of their corresponding scatterplot points. Should be in the range 1-100.}

\item{density.plot}{Logical, if \code{TRUE}, then density plots will be added to the output plots. Set to \code{FALSE} to hide density plots.}

\item{density.plot.type}{String, type of plot geometry to use for density plots: \code{"density"} for \link[ggplot2:geom_density]{ggplot2::geom_density} or \code{"boxplot"} for \link[ggplot2:geom_boxplot]{ggplot2::geom_boxplot}. Outliers are hidden from the boxplots.}

\item{scale.x.log}{Vector describing if output plots should use a log scale on the x-axis. A pseudo-log scale will be used if any zero or negative values are present. If length of vector == 1, then the value will be used for all output plots. Vector values should be either \code{TRUE} or \code{FALSE}. See \link[ggplot2:scale_continuous]{ggplot2::scale_x_log10}.}

\item{scale.y.log}{Vector describing if output plots should use a log scale on the y-axis. A pseudo-log scale will be used if any zero or negative values are present. If length of vector == 1, then the value will be used for all output plots. Vector values should be either \code{TRUE} or \code{FALSE}. See \link[ggplot2:scale_continuous]{ggplot2::scale_y_log10}.}

\item{xsigma}{Numeric, scaling factor for the linear part of pseudo-long transformation of x axis. Used if \code{scale.x.log} is \code{TRUE} and zero or negative values are present. See \link[scales:transform_log]{scales::pseudo_log_trans}.}

\item{ysigma}{Numeric, scaling factor for the linear part of pseudo-long transformation of y axis. Used if \code{scale.y.log} is \code{TRUE} and zero or negative values are present. See \link[scales:transform_log]{scales::pseudo_log_trans}.}

\item{xlimits}{Vector containing minimum and maximum values for the x-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_x_continuous}.}

\item{ylimits}{Vector containing minimum and maximum values for the y-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous}.}

\item{xbreaks}{Vector containing the break values used for the x-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_x_continuous}.}

\item{ybreaks}{Vector containing the break values used for the y-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous}.}

\item{xlabels}{Vector containing the labels for each break value used for the x-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_x_continuous}.}

\item{ylabels}{Vector containing the labels for each break value used for the y-axis of the output plots. See \link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous}.}

\item{xlab}{String containing the text to use for the x-axis title of the output plots. See \link[ggplot2:labs]{ggplot2::xlab}.}

\item{ylab}{String containing the text to use for the y-axis title of the output plots. See \link[ggplot2:labs]{ggplot2::ylab}.}

\item{ncol}{Integer, number of columns to use in the output arranged plot. See \link[ggpubr:ggarrange]{ggpubr::ggarrange}.}

\item{nrow}{Integer, number of rows to use in the output arranged plot. See \link[ggpubr:ggarrange]{ggpubr::ggarrange}.}

\item{align}{Specify how output plots should be arranged. See \link[ggpubr:ggarrange]{ggpubr::ggarrange}.}

\item{common.legend}{Specify if arranged plot should use a common legend. See \link[ggpubr:ggarrange]{ggpubr::ggarrange}.}

\item{legend.position}{Specify position of common legend for arranged plot. See \link[ggpubr:ggarrange]{ggpubr::ggarrange}. Use \code{"none"} to hide legend.}

\item{group.legend.title}{String, title for plot legend when generating plots with \code{groups}.}

\item{common.y.axis}{Logical, if \code{TRUE}, then only one y-axis label and marginal density plot will be provided. If \code{FALSE}, then separate y-axis labels and marginal density plots will be included for each subplot.}

\item{summary.table}{Logical, if \code{TRUE}, then a table providing summary statistics will be included at the bottom of the output plot.}

\item{table.margin}{Numeric, controls spacing between plots and summary table.}

\item{filename}{String, filename used to save plot. File extension must be specified. See \link[ggplot2:ggsave]{ggplot2::ggsave}.}

\item{width}{Numeric, specify width of output plot. See \link[ggplot2:ggsave]{ggplot2::ggsave}.}

\item{height}{Numeric, specify height of output plot. See \link[ggplot2:ggsave]{ggplot2::ggsave}.}

\item{units}{Specify units of \code{width} and \code{height}. See \link[ggplot2:ggsave]{ggplot2::ggsave}.}

\item{dpi}{Specify resolution of output plot. See \link[ggplot2:ggsave]{ggplot2::ggsave}.}
}
\value{
\code{PlotPerformanceByAttribute} returns a plot to the currently active plot device.
}
\description{
Create scatterplots of model performance by SUBID attributes.
}
\details{
\code{PlotPerformanceByAttribute} can be used to analyze model performance according to subbasin attributes. The function requires two primary inputs; Model performance
information is contained in the \code{subass} input, and subbasin attribute information is contained in the \code{attributes} input. The \code{subass.column} argument controls
which column of the \code{subass} data frame will be used as the y-coordinate of points. Plots will be generated for each column in the \code{attributes} data frame
(except for the column named "SUBID") using the column values as the x-coordinate of the points.

A subbasin attribute summary table can be generated using \code{\link{SubidAttributeSummary}}, and additional columns can be joined to the data frame to add additional output plots.
}
\examples{
\donttest{
subass <- ReadSubass(filename = system.file("demo_model", "results",
  "subass1.txt",
  package = "HYPEtools"
), check.names = TRUE)
gd <- ReadGeoData(filename = system.file("demo_model",
  "GeoData.txt",
  package = "HYPEtools"
))
gc <- ReadGeoClass(filename = system.file("demo_model",
  "GeoClass.txt",
  package = "HYPEtools"
))

attributes <- SubidAttributeSummary(subids <- subass$SUBID,
  gd = gd, gc = gc,
  mapoutputs = c(system.file("demo_model", "results", "mapCOUT.txt", package = "HYPEtools")),
  upstream.gd.cols = c("SLOPE_MEAN")
)

PlotPerformanceByAttribute(
  subass = subass,
  attributes = attributes[, c("SUBID", "landuse_1", "landuse_2", "landuse_3")],
  xlimits = c(0, 1)
)
}

}
\seealso{
\code{\link{ReadSubass}} for HYPE result import; \code{\link{SubidAttributeSummary}} for subbasin attribute summary
}
