AMR/man/mean_amr_distance.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mean_amr_distance.R
\name{mean_amr_distance}
\alias{mean_amr_distance}
\alias{mean_amr_distance.default}
\alias{mean_amr_distance.mic}
\alias{mean_amr_distance.disk}
\alias{mean_amr_distance.rsi}
\alias{mean_amr_distance.data.frame}
\alias{distance_from_row}
\title{Mean AMR Distance}
\usage{
mean_amr_distance(x, ...)

\method{mean_amr_distance}{default}(x, ...)

\method{mean_amr_distance}{mic}(x, ...)

\method{mean_amr_distance}{disk}(x, ...)

\method{mean_amr_distance}{rsi}(x, combine_SI = TRUE, ...)

\method{mean_amr_distance}{data.frame}(x, ..., combine_SI = TRUE)

distance_from_row(mean_distance, row)
}
\arguments{
\item{x}{a vector of class \link[=as.rsi]{rsi}, \link[=as.rsi]{rsi} or \link[=as.rsi]{rsi}, or a \link{data.frame} containing columns of any of these classes}

\item{...}{variables to select (supports tidy selection such as \code{column1:column4} and \code{\link[tidyselect:language]{where(is.mic)}}), and can thus also be \link[=ab_selector]{antibiotic selectors}}

\item{combine_SI}{a \link{logical} to indicate whether all values of S and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant), defaults to \code{TRUE}}

\item{mean_distance}{the outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}}

\item{row}{an index, such as a row number}
}
\description{
This function calculates a normalised mean for antimicrobial resistance between multiple observations.
}
\details{
The mean AMR distance is a normalised numeric value to compare AMR test results and can help to identify similar isolates, without comparing antibiograms by hand. For common numeric data this distance is equal to \href{https://en.wikipedia.org/wiki/Standard_score}{Z scores} (the number of standard deviations from the mean).

MIC values (see \code{\link[=as.mic]{as.mic()}}) are transformed with \code{\link[=log2]{log2()}} first; their distance is calculated as \code{(log2(x) - mean(log2(x))) / sd(log2(x))}.

R/SI values (see \code{\link[=as.rsi]{as.rsi()}}) are transformed using \code{"S"} = 1, \code{"I"} = 2, and \code{"R"} = 3. If \code{combine_SI} is \code{TRUE} (default), the \code{"I"} will be considered to be 1.

For data sets, the mean AMR distance will be calculated per variable, after which the mean of all columns will returned per row (using \code{\link[=rowMeans]{rowMeans()}}), see \emph{Examples}.

Use \code{\link[=distance_from_row]{distance_from_row()}} to subtract distances from the distance of one row, see \emph{Examples}.
}
\section{Interpretation}{

Isolates with distances less than 0.01 difference from each other should be considered similar. Differences lower than 0.025 should be considered suspicious.
}

\examples{
x <- random_mic(10)
x
mean_amr_distance(x)

y <- data.frame(
  id = LETTERS[1:10],
  amox = random_mic(10, ab = "amox", mo = "Escherichia coli"),
  cipr = random_mic(10, ab = "cipr", mo = "Escherichia coli"),
  gent = random_mic(10, ab = "gent", mo = "Escherichia coli"),
  tobr = random_mic(10, ab = "tobr", mo = "Escherichia coli")
)
y
mean_amr_distance(y)
y$amr_distance <- mean_amr_distance(y, where(is.mic))
y[order(y$amr_distance), ]

if (require("dplyr")) {
  y \%>\%
    mutate(
      amr_distance = mean_amr_distance(., where(is.mic)),
      check_id_C = distance_from_row(amr_distance, id == "C")
    ) \%>\%
    arrange(check_id_C)
}
if (require("dplyr")) {
  # support for groups
  example_isolates \%>\%
    filter(mo_genus() == "Enterococcus" & mo_species() != "") \%>\%
    select(mo, TCY, carbapenems()) \%>\%
    group_by(mo) \%>\%
    mutate(d = mean_amr_distance(., where(is.rsi))) \%>\%
    arrange(mo, d)
}
}