Built site for AMR@3.0.1.9003: ba30b08

reference/as.mic.md

@@ -0,0 +1,232 @@
+# Transform Input to Minimum Inhibitory Concentrations (MIC)
+
+This transforms vectors to a new class `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.
+
+## Usage
+
+``` r
+as.mic(x, na.rm = FALSE, keep_operators = "all")
+
+is.mic(x)
+
+NA_mic_
+
+rescale_mic(x, mic_range, keep_operators = "edges", as.mic = TRUE)
+
+mic_p50(x, na.rm = FALSE, ...)
+
+mic_p90(x, na.rm = FALSE, ...)
+
+# S3 method for class 'mic'
+droplevels(x, as.mic = FALSE, ...)
+```
+
+## Arguments
+
+- x:
+
+  A [character](https://rdrr.io/r/base/character.html) or
+  [numeric](https://rdrr.io/r/base/numeric.html) vector.
+
+- na.rm:
+
+  A [logical](https://rdrr.io/r/base/logical.html) indicating whether
+  missing values should be removed.
+
+- keep_operators:
+
+  A [character](https://rdrr.io/r/base/character.html) specifying how to
+  handle operators (such as `>` and `<=`) in the input. Accepts one of
+  three values: `"all"` (or `TRUE`) to keep all operators, `"none"` (or
+  `FALSE`) to remove all operators, or `"edges"` to keep operators only
+  at both ends of the range.
+
+- mic_range:
+
+  A manual range to rescale the MIC values, e.g.,
+  `mic_range = c(0.001, 32)`. Use `NA` to prevent rescaling on one side,
+  e.g., `mic_range = c(NA, 32)`.
+
+- as.mic:
+
+  A [logical](https://rdrr.io/r/base/logical.html) to indicate whether
+  the `mic` class should be kept - the default is `TRUE` for
+  `rescale_mic()` and `FALSE` for
+  [`droplevels()`](https://rdatatable.gitlab.io/data.table/reference/fdroplevels.html).
+  When setting this to `FALSE` in `rescale_mic()`, the output will have
+  factor levels that acknowledge `mic_range`.
+
+- ...:
+
+  Arguments passed on to methods.
+
+## Value
+
+Ordered [factor](https://rdrr.io/r/base/factor.html) with additional
+class `mic`, that in mathematical operations acts as a
+[numeric](https://rdrr.io/r/base/numeric.html) vector. Bear in mind that
+the outcome of any mathematical operation on MICs will return a
+[numeric](https://rdrr.io/r/base/numeric.html) value.
+
+## Details
+
+To interpret MIC values as SIR values, use
+[`as.sir()`](https://amr-for-r.org/reference/as.sir.md) on MIC values.
+It supports guidelines from EUCAST (2011-2025) and CLSI (2011-2025).
+
+This class for MIC values is a quite a special data type: formally it is
+an ordered [factor](https://rdrr.io/r/base/factor.html) with valid MIC
+values as [factor](https://rdrr.io/r/base/factor.html) levels (to make
+sure only valid MIC values are retained), but for any mathematical
+operation it acts as decimal numbers:
+
+    x <- random_mic(10)
+    x
+    #> 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
+
+This makes it possible to maintain operators that often come with MIC
+values, such "\>=" and "\<=", even when filtering using
+[numeric](https://rdrr.io/r/base/numeric.html) values in data analysis,
+e.g.:
+
+    x[x > 4]
+    #> 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
+
+All so-called [group generic
+functions](https://rdrr.io/r/base/groupGeneric.html) are implemented for
+the MIC class (such as `!`, `!=`, `<`, `>=`,
+[`exp()`](https://rdrr.io/r/base/Log.html),
+[`log2()`](https://rdrr.io/r/base/Log.html)). Some mathematical
+functions are also implemented (such as
+[`quantile()`](https://rdrr.io/r/stats/quantile.html),
+[`median()`](https://rdrr.io/r/stats/median.html),
+[`fivenum()`](https://rdrr.io/r/stats/fivenum.html)). Since
+[`sd()`](https://rdrr.io/r/stats/sd.html) and
+[`var()`](https://rdrr.io/r/stats/cor.html) are non-generic functions,
+these could not be extended. Use
+[`mad()`](https://rdrr.io/r/stats/mad.html) as an alternative, or use
+e.g. `sd(as.numeric(x))` where `x` is your vector of MIC values.
+
+Using [`as.double()`](https://rdrr.io/r/base/double.html) or
+[`as.numeric()`](https://rdrr.io/r/base/numeric.html) on MIC values will
+remove the operators and return a numeric vector. Do **not** use
+[`as.integer()`](https://rdrr.io/r/base/integer.html) on MIC values as
+by the R convention on [factor](https://rdrr.io/r/base/factor.html)s, it
+will return the index of the factor levels (which is often useless for
+regular users).
+
+The function `is.mic()` detects if the input contains class `mic`. If
+the input is a [data.frame](https://rdrr.io/r/base/data.frame.html) or
+[list](https://rdrr.io/r/base/list.html), it iterates over all
+columns/items and returns a
+[logical](https://rdrr.io/r/base/logical.html) vector.
+
+Use
+[`droplevels()`](https://rdatatable.gitlab.io/data.table/reference/fdroplevels.html)
+to drop unused levels. At default, it will return a plain factor. Use
+`droplevels(..., as.mic = TRUE)` to maintain the `mic` class.
+
+With `rescale_mic()`, existing MIC ranges can be limited to a defined
+range of MIC values. This can be useful to better compare MIC
+distributions.
+
+For `ggplot2`, use one of the
+[`scale_*_mic()`](https://amr-for-r.org/reference/plot.md) functions to
+plot MIC values. They allows custom MIC ranges and to plot intermediate
+log2 levels for missing MIC values.
+
+`NA_mic_` is a missing value of the new `mic` class, analogous to e.g.
+base R's [`NA_character_`](https://rdrr.io/r/base/NA.html).
+
+Use `mic_p50()` and `mic_p90()` to get the 50th and 90th percentile of
+MIC values. They return 'normal'
+[numeric](https://rdrr.io/r/base/numeric.html) values.
+
+## See also
+
+[`as.sir()`](https://amr-for-r.org/reference/as.sir.md)
+
+## Examples
+
+``` r
+mic_data <- as.mic(c(">=32", "1.0", "1", "1.00", 8, "<=0.128", "8", "16", "16"))
+mic_data
+#> Class 'mic'
+#> [1] >=32    1       1       1       8       <=0.128 8       16      16     
+is.mic(mic_data)
+#> [1] TRUE
+
+# this can also coerce combined MIC/SIR values:
+as.mic("<=0.002; S")
+#> Class 'mic'
+#> [1] <=0.002
+
+# mathematical processing treats MICs as numeric values
+fivenum(mic_data)
+#> [1]  0.128  1.000  8.000 16.000 32.000
+quantile(mic_data)
+#>     0%    25%    50%    75%   100% 
+#>  0.128  1.000  8.000 16.000 32.000 
+all(mic_data < 512)
+#> [1] TRUE
+
+# rescale MICs using rescale_mic()
+rescale_mic(mic_data, mic_range = c(4, 16))
+#> Class 'mic'
+#> [1] >=16 <=4  <=4  <=4  8    <=4  8    >=16 >=16
+
+# interpret MIC values
+as.sir(
+  x = as.mic(2),
+  mo = as.mo("Streptococcus pneumoniae"),
+  ab = "AMX",
+  guideline = "EUCAST"
+)
+#> Class 'sir'
+#> [1] R
+as.sir(
+  x = as.mic(c(0.01, 2, 4, 8)),
+  mo = as.mo("Streptococcus pneumoniae"),
+  ab = "AMX",
+  guideline = "EUCAST"
+)
+#> Class 'sir'
+#> [1] S R R R
+
+# plot MIC values, see ?plot
+plot(mic_data)
+
+plot(mic_data, mo = "E. coli", ab = "cipro")
+
+
+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
+}
+```