NEWS.md
- Function ab_from_text() to retrieve antimicrobial drugs from clinical texts in e.g. health care records, which also corrects for misspelling since it uses as.ab() internally:
ab_from_text("28/03/2020 regular amoxiciliin 500mg po tds") -#> [1] "Amoxicillin"
ab_from_text(c("28/03/2020 regular amoxiciliin 500mg po tds", + "15/04/2020 started on ciprofloxi-thingy and tobra today")) +#> [[1]] +#> Class <ab> +#> [1] AMX +#> +#> [[2]] +#> Class <ab> +#> [1] CIP TOB
Tidyverse selections for antibiotic classes, that help to select the columns of antibiotics that are of a specific antibiotic class, without the need to define the columns or antibiotic abbreviations. They can be used in any function that allows Tidyverse selections, like dplyr::select() and tidyr::pivot_longer():
Added function filter_penicillins() to filter isolates on a specific result in any column with a name in the antimicrobial ‘penicillins’ class (more specific: ATC subgroup Beta-lactam antibacterials, penicillins)
Added official antimicrobial names to all filter_ab_class() functions, such as filter_aminoglycosides()
Added antibiotics code “FOX1” for cefoxitin screening (abbreviation “cfsc”) to the antibiotics data set
Added Monuril as trade name for fosfomycin
bug_drug_combinations() for when only one antibiotic was in the input data<mo>, to highlight the %SI vs. %Ras.ab(), many more misspellings are now translatableas.ab(), many more misspellings are now translatable. The as.ab() function will now throw a note if more than 1 antimicrobial drug could be retrieved from a single input value.as.ab()
+R/ab_from_text.R
ab_from_text.RdUse this function on e.g. clinical texts from health care records. It returns a vector of antimicrobial drugs found in the texts.
+Use this function on e.g. clinical texts from health care records. It returns a list with all antimicrobial drugs found in the texts.
ab_from_text(text, collapse = NULL, translate_ab = "name", ...)+
ab_from_text(text, collapse = NULL, translate_ab = FALSE, ...)
| translate_ab | -a column name of the antibiotics data set to translate the antibiotic abbreviations to, using |
+ a column name of the antibiotics data set to translate the antibiotic abbreviations to, using |
|---|---|---|
| ... | @@ -258,11 +258,17 @@
A list, or a character if collapse is not NULL
To use this for creating a new variable in a data set (e.g. with mutate()), it could be convenient to paste the outcome together with the collapse parameter so every value in your new variable will be a character of length 1:
+
Without using collapse, this function will return a list. This can be convenient to use e.g. inside a mutate()):
+df %>% mutate(abx = ab_from_text(clinical_text))
The returned AB codes can be transformed to official names, groups, etc. with all ab_property() functions like ab_name() and ab_group(), or by using the translate_ab parameter.
With using collapse, this function will return a character:
df %>% mutate(abx = ab_from_text(clinical_text, collapse = "|"))
This function is also internally used by as.ab(), although it then only returns the first hit.
This function is also internally used by as.ab(), although it then only returns the first hit and will throw a note if more results could have been returned.
# mind the bad spelling of amoxicillin in this line, @@ -274,7 +280,19 @@ # if you want to know which antibiotic groups were administered, check it: abx <- ab_from_text("administered amoxi/clav and cipro") -ab_group(abx)+ab_group(abx[[1]]) + +if (require(dplyr)) { + tibble(clinical_text = c("given cipro and mero", + "started on doxy today")) %>% + mutate(abx = ab_from_text(clinical_text), + abx2 = ab_from_text(clinical_text, + collapse = "|"), + abx3 = ab_from_text(clinical_text, + collapse = "|", + translate_ab = "name")) + +}
Use this function to determine the antibiotic code of one or more antibiotics. The data set antibiotics will be searched for abbreviations, official names and synonyms (brand names).
as.ab(x, ...) +as.ab(x, flag_multiple_results = TRUE, ...) is.ab(x)@@ -246,6 +246,10 @@x + character vector to determine to antibiotic ID
+ flag_multiple_results ++ logical to indicate whether a note should be printed to the console that probably more than one antibiotic code or name can be retrieved from a single input value.
... diff --git a/docs/reference/index.html b/docs/reference/index.html index e1d2603d..6fed9854 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -81,7 +81,7 @@ @@ -289,7 +289,7 @@ arguments passed on to internal functions
- + Retrieve antimicrobial drugs from text
Retrieve antimicrobial drugs from clinical text
diff --git a/man/ab_from_text.Rd b/man/ab_from_text.Rd index be1bdcb8..78ae6120 100644 --- a/man/ab_from_text.Rd +++ b/man/ab_from_text.Rd @@ -2,27 +2,35 @@ % Please edit documentation in R/ab_from_text.R \name{ab_from_text} \alias{ab_from_text} -\title{Retrieve antimicrobial drugs from text} +\title{Retrieve antimicrobial drugs from clinical text} \usage{ -ab_from_text(text, collapse = NULL, translate_ab = "name", ...) +ab_from_text(text, collapse = NULL, translate_ab = FALSE, ...) } \arguments{ \item{text}{text to analyse} \item{collapse}{character to pass on to \code{paste(..., collapse = ...)} to only return one character per element of \code{text}, see Examples} -\item{translate_ab}{a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. Defaults to "name", which is equal to using \code{TRUE}. Use a value \code{FALSE}, \code{NULL} or \code{NA} to prevent translation of the \verb{ } code.} +\item{translate_ab}{a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. Defaults to \code{FALSE}. Using \code{TRUE} is equal to using "name".} \item{...}{parameters passed on to \code{\link[=as.ab]{as.ab()}}} } +\value{ +A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL} +} \description{ -Use this function on e.g. clinical texts from health care records. It returns a vector of antimicrobial drugs found in the texts. +Use this function on e.g. clinical texts from health care records. It returns a \link{list} with all antimicrobial drugs found in the texts. } \details{ -To use this for creating a new variable in a data set (e.g. with \code{mutate()}), it could be convenient to paste the outcome together with the \code{collapse} parameter so every value in your new variable will be a character of length 1:\cr +Without using \code{collapse}, this function will return a \link{list}. This can be convenient to use e.g. inside a \code{mutate()}):\cr +\code{df \%>\% mutate(abx = ab_from_text(clinical_text))} + +The returned AB codes can be transformed to official names, groups, etc. with all \code{\link[=ab_property]{ab_property()}} functions like \code{\link[=ab_name]{ab_name()}} and \code{\link[=ab_group]{ab_group()}}, or by using the \code{translate_ab} parameter. + +With using \code{collapse}, this function will return a \link{character}:\cr \code{df \%>\% mutate(abx = ab_from_text(clinical_text, collapse = "|"))} -This function is also internally used by \code{\link[=as.ab]{as.ab()}}, although it then only returns the first hit. +This function is also internally used by \code{\link[=as.ab]{as.ab()}}, although it then only returns the first hit and will throw a note if more results could have been returned. } \examples{ # mind the bad spelling of amoxicillin in this line, @@ -34,5 +42,17 @@ ab_from_text("administered amoxi/clav and cipro", collapse = ", ") # if you want to know which antibiotic groups were administered, check it: abx <- ab_from_text("administered amoxi/clav and cipro") -ab_group(abx) +ab_group(abx[[1]]) + +if (require(dplyr)) { + tibble(clinical_text = c("given cipro and mero", + "started on doxy today")) \%>\% + mutate(abx = ab_from_text(clinical_text), + abx2 = ab_from_text(clinical_text, + collapse = "|"), + abx3 = ab_from_text(clinical_text, + collapse = "|", + translate_ab = "name")) + +} } diff --git a/man/as.ab.Rd b/man/as.ab.Rd index e2a9d9d3..6f464bb9 100644 --- a/man/as.ab.Rd +++ b/man/as.ab.Rd @@ -6,13 +6,15 @@ \alias{is.ab} \title{Transform to antibiotic ID} \usage{ -as.ab(x, ...) +as.ab(x, flag_multiple_results = TRUE, ...) is.ab(x) } \arguments{ \item{x}{character vector to determine to antibiotic ID} +\item{flag_multiple_results}{logical to indicate whether a note should be printed to the console that probably more than one antibiotic code or name can be retrieved from a single input value.} + \item{...}{arguments passed on to internal functions} } \value{ diff --git a/tests/testthat/test-ab.R b/tests/testthat/test-ab.R index 14b9bb09..05000130 100755 --- a/tests/testthat/test-ab.R +++ b/tests/testthat/test-ab.R @@ -54,6 +54,8 @@ test_that("as.ab works", { expect_equal(as.character(as.ab("Amoxy + clavulaanzuur")), "AMC") + + expect_message(as.ab("cipro mero")) # assigning and subsetting x <- antibiotics$ab diff --git a/tests/testthat/test-ab_from_text.R b/tests/testthat/test-ab_from_text.R index ce9be46e..a5a52548 100644 --- a/tests/testthat/test-ab_from_text.R +++ b/tests/testthat/test-ab_from_text.R @@ -23,10 +23,10 @@ context("ab_from_text.R") test_that("ab_from_text works", { - expect_identical(ab_from_text("28/03/2020 regular amoxicilliin 500mg po tds"), + expect_identical(ab_from_text("28/03/2020 regular amoxicilliin 500mg po tds")[[1]], + as.ab("Amoxicillin")) + expect_identical(ab_from_text("28/03/2020 regular amoxicilliin 500mg po tds", translate_ab = TRUE)[[1]], "Amoxicillin") - expect_identical(ab_from_text("28/03/2020 regular amoxicilliin 500mg po tds", translate_ab = FALSE), - as.ab("AMX")) - expect_identical(ab_from_text("administered amoxi/clav and cipro", collapse = ", "), - "Amoxicillin, Ciprofloxacin") + expect_identical(ab_from_text("administered amoxi/clav and cipro", collapse = ", ")[[1]], + "AMX, CIP") })