Built site for AMR@3.0.1.9003: ba30b08

reference/ab_from_text.md

@@ -0,0 +1,192 @@
+# Retrieve Antimicrobial Drug Names and Doses from Clinical Text
+
+Use this function on e.g. clinical texts from health care records. It
+returns a [list](https://rdrr.io/r/base/list.html) with all
+antimicrobial drugs, doses and forms of administration found in the
+texts.
+
+## Usage
+
+``` r
+ab_from_text(text, type = c("drug", "dose", "administration"),
+  collapse = NULL, translate_ab = FALSE, thorough_search = NULL,
+  info = interactive(), ...)
+```
+
+## Arguments
+
+- text:
+
+  Text to analyse.
+
+- type:
+
+  Type of property to search for, either `"drug"`, `"dose"` or
+  `"administration"`, see *Examples*.
+
+- collapse:
+
+  A [character](https://rdrr.io/r/base/character.html) to pass on to
+  `paste(, collapse = ...)` to only return one
+  [character](https://rdrr.io/r/base/character.html) per element of
+  `text`, see *Examples*.
+
+- translate_ab:
+
+  If `type = "drug"`: a column name of the
+  [antimicrobials](https://amr-for-r.org/reference/antimicrobials.md)
+  data set to translate the antibiotic abbreviations to, using
+  [`ab_property()`](https://amr-for-r.org/reference/ab_property.md). The
+  default is `FALSE`. Using `TRUE` is equal to using "name".
+
+- thorough_search:
+
+  A [logical](https://rdrr.io/r/base/logical.html) to indicate whether
+  the input must be extensively searched for misspelling and other
+  faulty input values. Setting this to `TRUE` will take considerably
+  more time than when using `FALSE`. At default, it will turn `TRUE`
+  when all input elements contain a maximum of three words.
+
+- info:
+
+  A [logical](https://rdrr.io/r/base/logical.html) to indicate whether a
+  progress bar should be printed - the default is `TRUE` only in
+  interactive mode.
+
+- ...:
+
+  Arguments passed on to
+  [`as.ab()`](https://amr-for-r.org/reference/as.ab.md).
+
+## Value
+
+A [list](https://rdrr.io/r/base/list.html), or a
+[character](https://rdrr.io/r/base/character.html) if `collapse` is not
+`NULL`
+
+## Details
+
+This function is also internally used by
+[`as.ab()`](https://amr-for-r.org/reference/as.ab.md), although it then
+only searches for the first drug name and will throw a note if more drug
+names could have been returned. Note: the
+[`as.ab()`](https://amr-for-r.org/reference/as.ab.md) function may use
+very long regular expression to match brand names of antimicrobial
+drugs. This may fail on some systems.
+
+### Argument `type`
+
+At default, the function will search for antimicrobial drug names. All
+text elements will be searched for official names, ATC codes and brand
+names. As it uses [`as.ab()`](https://amr-for-r.org/reference/as.ab.md)
+internally, it will correct for misspelling.
+
+With `type = "dose"` (or similar, like "dosing", "doses"), all text
+elements will be searched for
+[numeric](https://rdrr.io/r/base/numeric.html) values that are higher
+than 100 and do not resemble years. The output will be
+[numeric](https://rdrr.io/r/base/numeric.html). It supports any unit (g,
+mg, IE, etc.) and multiple values in one clinical text, see *Examples*.
+
+With `type = "administration"` (or abbreviations, like "admin", "adm"),
+all text elements will be searched for a form of drug administration. It
+supports the following forms (including common abbreviations): buccal,
+implant, inhalation, instillation, intravenous, nasal, oral, parenteral,
+rectal, sublingual, transdermal and vaginal. Abbreviations for oral
+(such as 'po', 'per os') will become "oral", all values for intravenous
+(such as 'iv', 'intraven') will become "iv". It supports multiple values
+in one clinical text, see *Examples*.
+
+### Argument `collapse`
+
+Without using `collapse`, this function will return a
+[list](https://rdrr.io/r/base/list.html). This can be convenient to use
+e.g. inside a
+[`mutate()`](https://dplyr.tidyverse.org/reference/mutate.html)):  
+`df %>% mutate(abx = ab_from_text(clinical_text))`
+
+The returned AB codes can be transformed to official names, groups, etc.
+with all [`ab_*`](https://amr-for-r.org/reference/ab_property.md)
+functions such as
+[`ab_name()`](https://amr-for-r.org/reference/ab_property.md) and
+[`ab_group()`](https://amr-for-r.org/reference/ab_property.md), or by
+using the `translate_ab` argument.
+
+With using `collapse`, this function will return a
+[character](https://rdrr.io/r/base/character.html):  
+`df %>% mutate(abx = ab_from_text(clinical_text, collapse = "|"))`
+
+## Examples
+
+``` r
+# mind the bad spelling of amoxicillin in this line,
+# straight from a true health care record:
+ab_from_text("28/03/2020 regular amoxicilliin 500mg po tid")
+#> [[1]]
+#> Class 'ab'
+#> [1] AMX
+#> 
+
+ab_from_text("500 mg amoxi po and 400mg cipro iv")
+#> [[1]]
+#> Class 'ab'
+#> [1] AMX CIP
+#> 
+ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "dose")
+#> [[1]]
+#> [1] 500 400
+#> 
+ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "admin")
+#> [[1]]
+#> [1] "oral" "iv"  
+#> 
+
+ab_from_text("500 mg amoxi po and 400mg cipro iv", collapse = ", ")
+#> [1] "AMX, CIP"
+# \donttest{
+# if you want to know which antibiotic groups were administered, do e.g.:
+abx <- ab_from_text("500 mg amoxi po and 400mg cipro iv")
+ab_group(abx[[1]])
+#> [1] "Beta-lactams/penicillins" "Fluoroquinolones"        
+
+if (require("dplyr")) {
+  tibble(clinical_text = c(
+    "given 400mg cipro and 500 mg amox",
+    "started on doxy iv today"
+  )) %>%
+    mutate(
+      abx_codes = ab_from_text(clinical_text),
+      abx_doses = ab_from_text(clinical_text, type = "doses"),
+      abx_admin = ab_from_text(clinical_text, type = "admin"),
+      abx_coll = ab_from_text(clinical_text, collapse = "|"),
+      abx_coll_names = ab_from_text(clinical_text,
+        collapse = "|",
+        translate_ab = "name"
+      ),
+      abx_coll_doses = ab_from_text(clinical_text,
+        type = "doses",
+        collapse = "|"
+      ),
+      abx_coll_admin = ab_from_text(clinical_text,
+        type = "admin",
+        collapse = "|"
+      )
+    )
+}
+#> Loading required package: dplyr
+#> 
+#> Attaching package: ‘dplyr’
+#> The following objects are masked from ‘package:stats’:
+#> 
+#>     filter, lag
+#> The following objects are masked from ‘package:base’:
+#> 
+#>     intersect, setdiff, setequal, union
+#> # A tibble: 2 × 8
+#>   clinical_text            abx_codes abx_doses abx_admin abx_coll abx_coll_names
+#>   <chr>                    <list>    <list>    <list>    <chr>    <chr>         
+#> 1 given 400mg cipro and 5… <ab [2]>  <dbl [2]> <chr [1]> CIP|AMX  Ciprofloxacin…
+#> 2 started on doxy iv today <ab [1]>  <dbl [1]> <chr [1]> DOX      Doxycycline   
+#> # ℹ 2 more variables: abx_coll_doses <chr>, abx_coll_admin <chr>
+# }
+```