new AMR distance function

man/mean_amr_distance.Rd

@@ -0,0 +1,87 @@
+% 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)
+}
+}