AMR/man/as.mic.Rd

136 lines
5.6 KiB
Plaintext
Raw Normal View History

2018-02-21 11:52:31 +01:00
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mic.R
\docType{data}
2018-02-21 11:52:31 +01:00
\name{as.mic}
\alias{as.mic}
\alias{mic}
2018-02-21 11:52:31 +01:00
\alias{is.mic}
\alias{NA_mic_}
\alias{rescale_mic}
2022-05-09 21:33:27 +02:00
\alias{droplevels.mic}
\title{Transform Input to Minimum Inhibitory Concentrations (MIC)}
2018-02-21 11:52:31 +01:00
\usage{
2023-12-03 01:06:00 +01:00
as.mic(x, na.rm = FALSE, keep_operators = "all")
2018-02-21 11:52:31 +01:00
is.mic(x)
NA_mic_
rescale_mic(x, mic_range, keep_operators = "edges", as.mic = TRUE)
2022-05-09 21:33:27 +02:00
\method{droplevels}{mic}(x, as.mic = FALSE, ...)
2018-02-21 11:52:31 +01:00
}
\arguments{
2021-05-12 18:15:03 +02:00
\item{x}{a \link{character} or \link{numeric} vector}
2018-02-21 11:52:31 +01:00
2021-05-12 18:15:03 +02:00
\item{na.rm}{a \link{logical} indicating whether missing values should be removed}
2022-05-09 21:33:27 +02:00
2023-12-03 01:06:00 +01:00
\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.}
\item{mic_range}{a manual range to limit the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to set no limit on one side, e.g., \code{mic_range = c(NA, 32)}.}
\item{as.mic}{a \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{FALSE}}
\item{...}{arguments passed on to methods}
2018-02-21 11:52:31 +01:00
}
\value{
Ordered \link{factor} with additional class \code{\link{mic}}, that in mathematical operations acts as a \link{numeric} vector. Bear in mind that the outcome of any mathematical operation on MICs will return a \link{numeric} value.
2018-02-21 11:52:31 +01:00
}
\description{
This transforms vectors to a new class \code{\link{mic}}, which treats the input as decimal numbers, while maintaining operators (such as ">=") and only allowing valid MIC values known to the field of (medical) microbiology.
2018-02-21 11:52:31 +01:00
}
2019-05-10 16:44:59 +02:00
\details{
To interpret MIC values as SIR values, use \code{\link[=as.sir]{as.sir()}} on MIC values. It supports guidelines from EUCAST (2011-2024) and CLSI (2011-2024).
This class for MIC values is a quite a special data type: formally it is an ordered \link{factor} with valid MIC values as \link{factor} levels (to make sure only valid MIC values are retained), but for any mathematical operation it acts as decimal numbers:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x <- random_mic(10)
x
2022-10-19 11:47:57 +02:00
#> Class 'mic'
#> [1] 16 1 8 8 64 >=128 0.0625 32 32 16
is.factor(x)
#> [1] TRUE
x[1] * 2
#> [1] 32
median(x)
#> [1] 26
}\if{html}{\out{</div>}}
This makes it possible to maintain operators that often come with MIC values, such ">=" and "<=", even when filtering using \link{numeric} values in data analysis, e.g.:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x[x > 4]
2022-10-19 11:47:57 +02:00
#> Class 'mic'
#> [1] 16 8 8 64 >=128 32 32 16
df <- data.frame(x, hospital = "A")
subset(df, x > 4) # or with dplyr: df \%>\% filter(x > 4)
#> x hospital
#> 1 16 A
#> 5 64 A
#> 6 >=128 A
#> 8 32 A
#> 9 32 A
#> 10 16 A
}\if{html}{\out{</div>}}
All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some functions of the \code{stats} package are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values.
2022-05-09 21:33:27 +02:00
Using \code{\link[=as.double]{as.double()}} or \code{\link[=as.numeric]{as.numeric()}} on MIC values will remove the operators and return a numeric vector. Do \strong{not} use \code{\link[=as.integer]{as.integer()}} on MIC values as by the \R convention on \link{factor}s, it will return the index of the factor levels (which is often useless for regular users).
2022-10-19 11:47:57 +02:00
Use \code{\link[=droplevels]{droplevels()}} to drop unused levels. At default, it will return a plain factor. Use \code{droplevels(..., as.mic = TRUE)} to maintain the \code{mic} class.
2022-05-09 21:33:27 +02:00
With \code{\link[=rescale_mic]{rescale_mic()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions.
2023-12-04 08:19:02 +01:00
For \code{ggplot2}, use one of the \code{\link[=scale_x_mic]{scale_*_mic()}} functions to plot MIC values. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values.
2022-10-19 11:47:57 +02:00
\code{NA_mic_} is a missing value of the new \code{mic} class, analogous to e.g. base \R's \code{\link[base:NA]{NA_character_}}.
2019-05-10 16:44:59 +02:00
}
2018-02-22 20:48:48 +01:00
\examples{
mic_data <- as.mic(c(">=32", "1.0", "1", "1.00", 8, "<=0.128", "8", "16", "16"))
2022-08-21 16:37:20 +02:00
mic_data
2018-02-22 20:48:48 +01:00
is.mic(mic_data)
2018-03-14 09:58:58 +01:00
2023-01-21 23:47:20 +01:00
# this can also coerce combined MIC/SIR values:
2022-08-21 16:37:20 +02:00
as.mic("<=0.002; S")
2018-06-19 10:05:38 +02:00
2022-08-21 16:37:20 +02:00
# mathematical processing treats MICs as numeric values
2021-03-05 15:36:39 +01:00
fivenum(mic_data)
quantile(mic_data)
all(mic_data < 512)
# rescale MICs using rescale_mic()
rescale_mic(mic_data, mic_range = c(4, 16))
2019-05-10 16:44:59 +02:00
# interpret MIC values
2023-01-21 23:47:20 +01:00
as.sir(
2022-08-28 10:31:50 +02:00
x = as.mic(2),
mo = as.mo("Streptococcus pneumoniae"),
ab = "AMX",
guideline = "EUCAST"
)
2023-01-21 23:47:20 +01:00
as.sir(
2022-08-28 10:31:50 +02:00
x = as.mic(c(0.01, 2, 4, 8)),
mo = as.mo("Streptococcus pneumoniae"),
ab = "AMX",
guideline = "EUCAST"
)
2019-05-10 16:44:59 +02:00
# plot MIC values, see ?plot
2018-02-22 20:48:48 +01:00
plot(mic_data)
plot(mic_data, mo = "E. coli", ab = "cipro")
2022-08-27 20:49:37 +02:00
if (require("ggplot2")) {
autoplot(mic_data, mo = "E. coli", ab = "cipro")
}
if (require("ggplot2")) {
autoplot(mic_data, mo = "E. coli", ab = "cipro", language = "nl") # Dutch
}
2018-02-22 20:48:48 +01:00
}
\seealso{
2023-01-21 23:47:20 +01:00
\code{\link[=as.sir]{as.sir()}}
}
\keyword{datasets}