AMR/man/resistance_predict.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resistance_predict.R
\name{resistance_predict}
\alias{resistance_predict}
\alias{sir_predict}
\alias{plot.resistance_predict}
\alias{ggplot_sir_predict}
\alias{autoplot.resistance_predict}
\title{Predict Antimicrobial Resistance}
\usage{
resistance_predict(
  x,
  col_ab,
  col_date = NULL,
  year_min = NULL,
  year_max = NULL,
  year_every = 1,
  minimum = 30,
  model = NULL,
  I_as_S = TRUE,
  preserve_measurements = TRUE,
  info = interactive(),
  ...
)

sir_predict(
  x,
  col_ab,
  col_date = NULL,
  year_min = NULL,
  year_max = NULL,
  year_every = 1,
  minimum = 30,
  model = NULL,
  I_as_S = TRUE,
  preserve_measurements = TRUE,
  info = interactive(),
  ...
)

\method{plot}{resistance_predict}(x, main = paste("Resistance Prediction of", x_name), ...)

ggplot_sir_predict(
  x,
  main = paste("Resistance Prediction of", x_name),
  ribbon = TRUE,
  ...
)

\method{autoplot}{resistance_predict}(
  object,
  main = paste("Resistance Prediction of", x_name),
  ribbon = TRUE,
  ...
)
}
\arguments{
\item{x}{A \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.}

\item{col_ab}{Column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"}).}

\item{col_date}{Column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class.}

\item{year_min}{Lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}.}

\item{year_max}{Highest year to use in the prediction model - the default is 10 years after today.}

\item{year_every}{Unit of sequence between lowest year found in the data and \code{year_max}.}

\item{minimum}{Minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.}

\item{model}{The statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.}

\item{I_as_S}{A \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.}

\item{preserve_measurements}{A \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.}

\item{info}{A \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.}

\item{...}{Arguments passed on to functions.}

\item{main}{Title of the plot.}

\item{ribbon}{A \link{logical} to indicate whether a ribbon should be shown (default) or error bars.}

\item{object}{Model data to be plotted.}
}
\value{
A \link{data.frame} with extra class \code{\link{resistance_predict}} with columns:
\itemize{
\item \code{year}
\item \code{value}, the same as \code{estimated} when \code{preserve_measurements = FALSE}, and a combination of \code{observed} and \code{estimated} otherwise
\item \code{se_min}, the lower bound of the standard error with a minimum of \code{0} (so the standard error will never go below 0\%)
\item \code{se_max} the upper bound of the standard error with a maximum of \code{1} (so the standard error will never go above 100\%)
\item \code{observations}, the total number of available observations in that year, i.e. \eqn{S + I + R}
\item \code{observed}, the original observed resistant percentages
\item \code{estimated}, the estimated resistant percentages, calculated by the model
}

Furthermore, the model itself is available as an attribute: \code{attributes(x)$model}, see \emph{Examples}.
}
\description{
Create a prediction model to predict antimicrobial resistance for the next years. Standard errors (SE) will be returned as columns \code{se_min} and \code{se_max}. See \emph{Examples} for a real live example.

\strong{NOTE:} These functions are \link[=AMR-deprecated]{deprecated} and will be removed in a future version. Use the AMR package combined with the tidymodels framework instead, for which we have written a \href{https://amr-for-r.org/articles/AMR_with_tidymodels.html}{basic and short introduction on our website}.
}
\details{
Valid options for the statistical model (argument \code{model}) are:
\itemize{
\item \code{"binomial"} or \code{"binom"} or \code{"logit"}: a generalised linear regression model with binomial distribution
\item \code{"loglin"} or \code{"poisson"}: a generalised log-linear regression model with poisson distribution
\item \code{"lin"} or \code{"linear"}: a linear regression model
}
}
\section{Interpretation of SIR}{

In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R (\url{https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}).

In aggregated analyses, such as proportions, counts, antibiograms, and plots, the 'I' category must be considered either susceptible or resistant. In epidemiological AMR data analysis, this follows the guideline: EUCAST considers 'I' susceptible, while CLSI considers 'I' resistant. The dose-dependent susceptibility of CLSI ('SDD') is always considered susceptible, as it equals what EUCAST defines as 'I'. All functions with a \code{guideline} argument for this purpose use these categories:\tabular{lll}{
   \code{guideline} \tab Susceptible \tab Resistant \cr
   \code{"EUCAST"} \tab S, SDD, I, WT \tab R, NWT, NS \cr
   \code{"CLSI"} \tab S, SDD, WT \tab I, R, NWT, NS \cr
}


The values 'WT' (wild type) and 'NWT' (non-wild type) result from epidemiological cut-off values (ECOFFs) instead of clinical breakpoints. Since they are no clinical categories, 'WT' is always considered susceptible and 'NWT' always resistant, regardless of the guideline. The value 'NS' (non-susceptible) is always considered resistant, and 'NI' (non-interpretable) is always considered a missing result.

The \code{guideline} argument can be:
\itemize{
\item \strong{Left unset}, to use the package option \code{\link[=AMR-options]{AMR_guideline}}, or \code{"EUCAST"} if this option is not set. In the latter case, a message is shown once per session (but not in R Markdown or Quarto documents); set the option to silence it.
\item \strong{\code{"EUCAST"}}, or any EUCAST version such as \code{"EUCAST 2025"}, to consider 'I' susceptible, e.g., to return \code{"SI"} vs. \code{"R"} in \code{\link[=proportion_df]{proportion_df()}}.
\item \strong{\code{"CLSI"}}, or any CLSI version such as \code{"CLSI 2025"}, to consider 'I' resistant, e.g., to return \code{"S"} vs. \code{"IR"} in \code{\link[=proportion_df]{proportion_df()}}.
\item \strong{\code{NULL} or \code{FALSE}}, to keep S, I, and R separate. This is only possible in functions that return results per category: \code{\link[=count_df]{count_df()}}, \code{\link[=proportion_df]{proportion_df()}}, \code{\link[=sir_df]{sir_df()}}, \code{\link[=ggplot_sir]{ggplot_sir()}}, \code{\link[=geom_sir]{geom_sir()}}, \code{\link[=labels_sir_count]{labels_sir_count()}}, and \code{\link[=bug_drug_combinations]{bug_drug_combinations()}}. Functions that return a single proportion or count, such as \code{\link[=susceptibility]{susceptibility()}}, \code{\link[=count_resistant]{count_resistant()}}, \code{\link[=antibiogram]{antibiogram()}}, \code{\link[=wisca]{wisca()}}, and \code{\link[=format]{format()}} on the result of \code{\link[=bug_drug_combinations]{bug_drug_combinations()}}, require 'I' to be considered either susceptible or resistant, and return an error.
}

Use \code{\link[=susceptibility]{susceptibility()}} and \code{\link[=resistance]{resistance()}} (or \code{\link[=count_susceptible]{count_susceptible()}} and \code{\link[=count_resistant]{count_resistant()}}) to follow the guideline, or e.g. \code{\link[=proportion_SI]{proportion_SI()}} and \code{\link[=proportion_R]{proportion_R()}} to be explicit regardless of the guideline.

The \code{combine_SI} argument of the functions that return results per category, \code{\link[=antibiogram]{antibiogram()}}, and \code{\link[=wisca]{wisca()}} is deprecated in favour of \code{guideline}. If set, it is followed literally and takes precedence over \code{guideline}.
}

\examples{
x <- resistance_predict(example_isolates,
  col_ab = "AMX",
  year_min = 2010,
  model = "binomial"
)
plot(x)
\donttest{
if (require("ggplot2")) {
  ggplot_sir_predict(x)
}

# using dplyr:
if (require("dplyr")) {
  x <- example_isolates \%>\%
    filter_first_isolate() \%>\%
    filter(mo_genus(mo) == "Staphylococcus") \%>\%
    resistance_predict("PEN", model = "binomial")
  print(plot(x))

  # get the model from the object
  mymodel <- attributes(x)$model
  summary(mymodel)
}

# create nice plots with ggplot2 yourself
if (require("dplyr") && require("ggplot2")) {
  data <- example_isolates \%>\%
    filter(mo == as.mo("E. coli")) \%>\%
    resistance_predict(
      col_ab = "AMX",
      col_date = "date",
      model = "binomial",
      info = FALSE,
      minimum = 15
    )
  head(data)
  autoplot(data)
}
}
}
\seealso{
The \code{\link[=proportion]{proportion()}} functions to calculate resistance

Models: \code{\link[=lm]{lm()}} \code{\link[=glm]{glm()}}
}