(v1.5.0.9025) big plot and ggplot generics update

2025-07-12 22:21:52 +02:00 · 2021-02-25 10:33:08 +01:00
parent 31ceba5441
commit a673407904
42 changed files with 1058 additions and 842 deletions
--- a/man/plot.Rd
+++ b/man/plot.Rd
@ -1,102 +1,107 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/amr.R, R/disk.R, R/mic.R, R/rsi.R
+% Please edit documentation in R/plot.R
 \name{plot}
 \alias{plot}
-\alias{plot.disk}
 \alias{plot.mic}
-\alias{barplot.mic}
+\alias{ggplot.mic}
+\alias{plot.disk}
+\alias{ggplot.disk}
 \alias{plot.rsi}
-\alias{barplot.rsi}
 \title{Plotting for Classes \code{rsi}, \code{mic} and \code{disk}}
 \usage{
-\method{plot}{disk}(
-  x,
-  main = paste("Disk zones values of", deparse(substitute(x))),
-  ylab = "Frequency",
-  xlab = "Disk diffusion (mm)",
-  axes = FALSE,
-  ...
-)
-
 \method{plot}{mic}(
  x,
  main = paste("MIC values of", deparse(substitute(x))),
  ylab = "Frequency",
-  xlab = "MIC value",
-  axes = FALSE,
+  xlab = "Minimum Inhibitory Concentration (mg/L)",
+  mo = NULL,
+  ab = NULL,
+  guideline = "EUCAST",
+  colours_RSI = c("#ED553B", "#3CAEA3", "#F6D55C"),
+  expand = TRUE,
  ...
 )

-\method{barplot}{mic}(
-  height,
-  main = paste("MIC values of", deparse(substitute(height))),
+\method{ggplot}{mic}(
+  data,
+  mapping = NULL,
+  title = paste("MIC values of", deparse(substitute(data))),
  ylab = "Frequency",
-  xlab = "MIC value",
-  axes = FALSE,
+  xlab = "Minimum Inhibitory Concentration (mg/L)",
+  mo = NULL,
+  ab = NULL,
+  guideline = "EUCAST",
+  colours_RSI = c("#ED553B", "#3CAEA3", "#F6D55C"),
+  expand = TRUE,
+  ...
+)
+
+\method{plot}{disk}(
+  x,
+  main = paste("Disk zones values of", deparse(substitute(x))),
+  ylab = "Frequency",
+  xlab = "Disk diffusion diameter (mm)",
+  mo = NULL,
+  ab = NULL,
+  guideline = "EUCAST",
+  colours_RSI = c("#ED553B", "#3CAEA3", "#F6D55C"),
+  expand = TRUE,
+  ...
+)
+
+\method{ggplot}{disk}(
+  data,
+  mapping = NULL,
+  title = paste("Disk zones values of", deparse(substitute(data))),
+  ylab = "Frequency",
+  xlab = "Disk diffusion diameter (mm)",
+  mo = NULL,
+  ab = NULL,
+  guideline = "EUCAST",
+  colours_RSI = c("#ED553B", "#3CAEA3", "#F6D55C"),
+  expand = TRUE,
  ...
 )

 \method{plot}{rsi}(
  x,
-  lwd = 2,
-  ylim = NULL,
  ylab = "Percentage",
  xlab = "Antimicrobial Interpretation",
  main = paste("Resistance Overview of", deparse(substitute(x))),
-  axes = FALSE,
-  ...
-)
-
-\method{barplot}{rsi}(
-  height,
-  col = c("chartreuse4", "chartreuse3", "brown3"),
-  xlab = ifelse(beside, "Antimicrobial Interpretation", ""),
-  main = paste("Resistance Overview of", deparse(substitute(height))),
-  ylab = "Frequency",
-  beside = TRUE,
-  axes = beside,
  ...
 )
 }
 \arguments{
-\item{x}{the coordinates of points in the plot. Alternatively, a
-      single plotting structure, function or \emph{any \R object with a
-        \code{plot} method} can be provided.}
+\item{x}{MIC values created with \code{\link[=as.mic]{as.mic()}} or disk diffusion values created with \code{\link[=as.disk]{as.disk()}}}

-\item{main}{overall and sub title for the plot.}
+\item{main, title}{title of the plot}

-\item{ylab}{a label for the y axis.}
+\item{xlab, ylab}{axis title}

-\item{xlab}{a label for the x axis.}
+\item{mo}{any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}}

-\item{axes}{logical.  If \code{TRUE}, a vertical (or horizontal, if
-    \code{horiz} is true) axis is drawn.}
+\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial code with \code{\link[=as.ab]{as.ab()}}}

-\item{...}{Arguments passed on to functions}
+\item{guideline}{interpretation guideline to use, defaults to the latest included EUCAST guideline, see \emph{Details}}

-\item{height}{either a vector or matrix of values describing the
-    bars which make up the plot.  If \code{height} is a vector, the
-    plot consists of a sequence of rectangular bars with heights
-    given by the values in the vector.  If \code{height} is a matrix
-    and \code{beside} is \code{FALSE} then each bar of the plot
-    corresponds to a column of \code{height}, with the values in the
-    column giving the heights of stacked sub-bars making up the
-    bar.  If \code{height} is a matrix and \code{beside} is
-    \code{TRUE}, then the values in each column are juxtaposed
-    rather than stacked.}
+\item{colours_RSI}{colours to use for filling in the bars, must be a vector of three values (in the order R, S and I). The default colours are colour-blind friendly.}

-\item{ylim}{limits for the y axis.}
+\item{expand}{logical to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.}

-\item{col}{a vector of colors for the bars or bar components.
-    By default, grey is used if \code{height} is a vector, and a
-    gamma-corrected grey palette if \code{height} is a matrix.}
+\item{...}{arguments passed on to \code{\link[=as.rsi]{as.rsi()}}}

-\item{beside}{a logical value.  If \code{FALSE}, the columns of
-    \code{height} are portrayed as stacked bars, and if \code{TRUE}
-    the columns are portrayed as juxtaposed bars.}
+\item{mapping}{aesthetic mappings to use for \code{\link[ggplot2:ggplot]{ggplot()}}}
+}
+\value{
+The \code{ggplot} functions return a \code{\link[ggplot2:ggplot]{ggplot}} model that is extendible with any \code{ggplot2} function.
 }
 \description{
-Functions to print classes of the \code{AMR} package.
+Functions to plot classes \code{rsi}, \code{mic} and \code{disk}, with support for base R and \code{ggplot2}.
+}
+\details{
+For interpreting MIC values as well as disk diffusion diameters, supported guidelines to be used as input for the \code{guideline} argument are: "EUCAST 2021", "EUCAST 2020", "EUCAST 2019", "EUCAST 2018", "EUCAST 2017", "EUCAST 2016", "EUCAST 2015", "EUCAST 2014", "EUCAST 2013", "EUCAST 2012", "EUCAST 2011", "CLSI 2019", "CLSI 2018", "CLSI 2017", "CLSI 2016", "CLSI 2015", "CLSI 2014", "CLSI 2013", "CLSI 2012", "CLSI 2011" and "CLSI 2010".
+
+Simply using \code{"CLSI"} or \code{"EUCAST"} as input will automatically select the latest version of that guideline.
 }
 \section{Stable Lifecycle}{

@ -111,4 +116,19 @@ If the unlying code needs breaking changes, they will occur gradually. For examp
 On our website \url{https://msberends.github.io/AMR/} you can find \href{https://msberends.github.io/AMR/articles/AMR.html}{a comprehensive tutorial} about how to conduct AMR data analysis, the \href{https://msberends.github.io/AMR/reference/}{complete documentation of all functions} and \href{https://msberends.github.io/AMR/articles/WHONET.html}{an example analysis using WHONET data}. As we would like to better understand the backgrounds and needs of our users, please \href{https://msberends.github.io/AMR/survey.html}{participate in our survey}!
 }

-\keyword{internal}
+\examples{
+some_mic_values <- random_mic(size = 100)
+some_disk_values <- random_disk(size = 100, mo = "Escherichia coli", ab = "cipro")
+
+plot(some_mic_values)
+plot(some_disk_values)
+
+# when providing the microorganism and antibiotic, colours will show interpretations:
+plot(some_mic_values, mo = "S. aureus", ab = "ampicillin")
+plot(some_disk_values, mo = "Escherichia coli", ab = "cipro")
+
+if (require("ggplot2")) {
+  ggplot(some_mic_values)
+  ggplot(some_disk_values, mo = "Escherichia coli", ab = "cipro")
+}
+}