Use this function on e.g. clinical texts from health care records. It returns a list with all antimicrobial drugs, doses and forms of administration found in the texts.

ab_from_text(
text,
collapse = NULL,
translate_ab = FALSE,
thorough_search = NULL,
...
)

## Arguments

text text to analyse type of property to search for, either "drug", "dose" or "administration", see Examples character to pass on to paste(..., collapse = ...) to only return one character per element of text, see Examples if type = "drug": a column name of the antibiotics data set to translate the antibiotic abbreviations to, using ab_property(). Defaults to FALSE. Using TRUE is equal to using "name". logical 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. parameters passed on to as.ab()

## Value

A list, or a character if collapse is not NULL

## Details

This function is also internally used by as.ab(), although it then only searches for the first drug name and will throw a note if more drug names could have been returned.

### Parameter 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() internally, it will correct for misspelling.

With type = "dose" (or similar, like "dosing", "doses"), all text elements will be searched for numeric values that are higher than 100 and do not resemble years. The output will be numeric. 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.

### Parameter collapse

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 = "|"))

## Maturing lifecycle

The lifecycle of this function is maturing. The unlying code of a maturing function has been roughed out, but finer details might still change. Since this function needs wider usage and more extensive testing, you are very welcome to suggest changes at our repository or write us an email (see section 'Contact Us').

## Read more on our website!

On our website https://msberends.github.io/AMR/ you can find a comprehensive tutorial about how to conduct AMR analysis, the complete documentation of all functions and an example analysis using WHONET data. As we would like to better understand the backgrounds and needs of our users, please participate in our survey!

## Examples

# 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 tds")

ab_from_text("500 mg amoxi po and 400mg cipro iv")
ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "dose")
ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "admin")

ab_from_text("500 mg amoxi po and 400mg cipro iv", collapse = ", ")

# 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]])

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"),