AMR/man/mean_amr_distance.Rd

93 lines
3.6 KiB
Plaintext
Raw Normal View History

2022-08-30 21:48:02 +02:00
% 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}
2023-01-21 23:47:20 +01:00
\alias{mean_amr_distance.sir}
2022-08-30 21:48:02 +02:00
\alias{mean_amr_distance.data.frame}
2022-10-21 16:02:14 +02:00
\alias{amr_distance_from_row}
2022-12-30 13:02:37 +01:00
\title{Calculate the Mean AMR Distance}
2022-08-30 21:48:02 +02:00
\usage{
mean_amr_distance(x, ...)
2023-01-21 23:47:20 +01:00
\method{mean_amr_distance}{sir}(x, ..., combine_SI = TRUE)
2022-08-30 21:48:02 +02:00
\method{mean_amr_distance}{data.frame}(x, ..., combine_SI = TRUE)
2022-10-21 16:02:14 +02:00
amr_distance_from_row(amr_distance, row)
2022-08-30 21:48:02 +02:00
}
\arguments{
2023-01-21 23:47:20 +01:00
\item{x}{a vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes}
2022-08-30 21:48:02 +02:00
2022-12-30 13:02:37 +01:00
\item{...}{variables to select (supports \link[tidyselect:language]{tidyselect language} such as \code{column1:column4} and \code{where(is.mic)}, and can thus also be \link[=ab_selector]{antibiotic selectors}}
2022-08-30 21:48:02 +02:00
\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) - the default is \code{TRUE}}
2022-08-30 21:48:02 +02:00
2022-10-21 16:02:14 +02:00
\item{amr_distance}{the outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}}
2022-08-30 21:48:02 +02:00
\item{row}{an index, such as a row number}
}
\description{
2022-12-30 13:02:37 +01:00
Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand.
2022-08-30 21:48:02 +02:00
}
\details{
2023-01-05 14:46:44 +01:00
The mean AMR distance is effectively \href{https://en.wikipedia.org/wiki/Standard_score}{the Z-score}; a normalised numeric value to compare AMR test results which can help to identify similar isolates, without comparing antibiograms by hand.
2022-08-30 21:48:02 +02:00
2023-01-05 14:46:44 +01:00
MIC values (see \code{\link[=as.mic]{as.mic()}}) are transformed with \code{\link[=log2]{log2()}} first; their distance is thus calculated as \code{(log2(x) - mean(log2(x))) / sd(log2(x))}.
2022-08-30 21:48:02 +02:00
2023-01-21 23:47:20 +01:00
SIR values (see \code{\link[=as.sir]{as.sir()}}) 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.
2022-08-30 21:48:02 +02:00
2023-01-05 14:46:44 +01:00
For data sets, the mean AMR distance will be calculated per column, after which the mean per row will be returned, see \emph{Examples}.
2022-08-30 21:48:02 +02:00
2022-10-21 16:02:14 +02:00
Use \code{\link[=amr_distance_from_row]{amr_distance_from_row()}} to subtract distances from the distance of one row, see \emph{Examples}.
2022-08-30 21:48:02 +02:00
}
\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{
2023-01-21 23:47:20 +01:00
sir <- random_sir(10)
sir
mean_amr_distance(sir)
2023-01-05 14:46:44 +01:00
mic <- random_mic(10)
mic
mean_amr_distance(mic)
# equal to the Z-score of their log2:
(log2(mic) - mean(log2(mic))) / sd(log2(mic))
disk <- random_disk(10)
disk
mean_amr_distance(disk)
2022-08-30 21:48:02 +02:00
2022-09-01 15:20:57 +02:00
y <- data.frame(
id = LETTERS[1:10],
2023-01-21 23:47:20 +01:00
amox = random_sir(10, ab = "amox", mo = "Escherichia coli"),
2023-01-05 14:46:44 +01:00
cipr = random_disk(10, ab = "cipr", mo = "Escherichia coli"),
2022-09-01 15:20:57 +02:00
gent = random_mic(10, ab = "gent", mo = "Escherichia coli"),
tobr = random_mic(10, ab = "tobr", mo = "Escherichia coli")
)
2022-08-30 21:48:02 +02:00
y
mean_amr_distance(y)
y$amr_distance <- mean_amr_distance(y, where(is.mic))
y[order(y$amr_distance), ]
if (require("dplyr")) {
2022-09-01 15:20:57 +02:00
y \%>\%
mutate(
2023-01-05 14:46:44 +01:00
amr_distance = mean_amr_distance(y),
2022-10-21 16:02:14 +02:00
check_id_C = amr_distance_from_row(amr_distance, id == "C")
2022-09-01 15:20:57 +02:00
) \%>\%
2022-08-30 21:48:02 +02:00
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) \%>\%
2023-01-05 14:46:44 +01:00
mutate(dist = mean_amr_distance(.)) \%>\%
arrange(mo, dist)
2022-08-30 21:48:02 +02:00
}
}