Package 'AMR'

Description

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.

Usage

ab_from_text(
  text,
  type = c("drug", "dose", "administration"),
  collapse = NULL,
  translate_ab = FALSE,
  thorough_search = NULL,
  info = interactive(),
  ...
)

Arguments

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. Note: the as.ab() 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() 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.

Argument 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_* functions such as ab_name() and ab_group(), or by using the translate_ab argument.

With using collapse, this function will return a character:
df %>% mutate(abx = ab_from_text(clinical_text, collapse = "|"))

Value

A list, or a character if collapse is not NULL

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

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

Description

Use these functions to return a specific property of an antibiotic from the antibiotics data set. All input values will be evaluated internally with as.ab().

Usage

ab_name(x, language = get_AMR_locale(), tolower = FALSE, ...)

ab_cid(x, ...)

ab_synonyms(x, ...)

ab_tradenames(x, ...)

ab_group(x, language = get_AMR_locale(), ...)

ab_atc(x, only_first = FALSE, ...)

ab_atc_group1(x, language = get_AMR_locale(), ...)

ab_atc_group2(x, language = get_AMR_locale(), ...)

ab_loinc(x, ...)

ab_ddd(x, administration = "oral", ...)

ab_ddd_units(x, administration = "oral", ...)

ab_info(x, language = get_AMR_locale(), ...)

ab_url(x, open = FALSE, ...)

ab_property(x, property = "name", language = get_AMR_locale(), ...)

set_ab_names(
  data,
  ...,
  property = "name",
  language = get_AMR_locale(),
  snake_case = NULL
)

Arguments

Details

All output will be translated where possible.

The function ab_url() will return the direct URL to the official WHO website. A warning will be returned if the required ATC code is not available.

The function set_ab_names() is a special column renaming function for data.frames. It renames columns names that resemble antimicrobial drugs. It always makes sure that the new column names are unique. If property = "atc" is set, preference is given to ATC codes from the J-group.

Value

• An integer in case of ab_cid()

• A named list in case of ab_info() and multiple ab_atc()/ab_synonyms()/ab_tradenames()

• A double in case of ab_ddd()

• A data.frame in case of set_ab_names()

• A character in all other cases

Source

World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: https://atcddd.fhi.no/atc_ddd_index/

European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

See Also

antibiotics

Examples

# all properties:
ab_name("AMX")
ab_atc("AMX")
ab_cid("AMX")
ab_synonyms("AMX")
ab_tradenames("AMX")
ab_group("AMX")
ab_atc_group1("AMX")
ab_atc_group2("AMX")
ab_url("AMX")

# smart lowercase transformation
ab_name(x = c("AMC", "PLB"))
ab_name(x = c("AMC", "PLB"), tolower = TRUE)

# defined daily doses (DDD)
ab_ddd("AMX", "oral")
ab_ddd_units("AMX", "oral")
ab_ddd("AMX", "iv")
ab_ddd_units("AMX", "iv")

ab_info("AMX") # all properties as a list

# all ab_* functions use as.ab() internally, so you can go from 'any' to 'any':
ab_atc("AMP")
ab_group("J01CA01")
ab_loinc("ampicillin")
ab_name("21066-6")
ab_name(6249)
ab_name("J01CA01")

# spelling from different languages and dyslexia are no problem
ab_atc("ceftriaxon")
ab_atc("cephtriaxone")
ab_atc("cephthriaxone")
ab_atc("seephthriaaksone")

# use set_ab_names() for renaming columns
colnames(example_isolates)
colnames(set_ab_names(example_isolates))
colnames(set_ab_names(example_isolates, NIT:VAN))

if (require("dplyr")) {
  example_isolates %>%
    set_ab_names()

  # this does the same:
  example_isolates %>%
    rename_with(set_ab_names)

  # set_ab_names() works with any AB property:
  example_isolates %>%
    set_ab_names(property = "atc")

  example_isolates %>%
    set_ab_names(where(is.sir)) %>%
    colnames()

  example_isolates %>%
    set_ab_names(NIT:VAN) %>%
    colnames()
}

Description

With add_custom_antimicrobials() you can add your own custom antimicrobial drug names and codes.

Usage

add_custom_antimicrobials(x)

clear_custom_antimicrobials()

Arguments

Details

Important: Due to how R works, the add_custom_antimicrobials() function has to be run in every R session - added antimicrobials are not stored between sessions and are thus lost when R is exited.

There are two ways to circumvent this and automate the process of adding antimicrobials:

Method 1: Using the package option AMR_custom_ab, which is the preferred method. To use this method:

1. Create a data set in the structure of the antibiotics data set (containing at the very least columns "ab" and "name") and save it with saveRDS() to a location of choice, e.g. "~/my_custom_ab.rds", or any remote location.

2. Set the file location to the package option AMR_custom_ab: options(AMR_custom_ab = "~/my_custom_ab.rds"). This can even be a remote file location, such as an https URL. Since options are not saved between R sessions, it is best to save this option to the .Rprofile file so that it will be loaded on start-up of R. To do this, open the .Rprofile file using e.g. utils::file.edit("~/.Rprofile"), add this text and save the file:

   # Add custom antimicrobial codes:
   options(AMR_custom_ab = "~/my_custom_ab.rds")
   

   Upon package load, this file will be loaded and run through the add_custom_antimicrobials() function.

Method 2: Loading the antimicrobial additions directly from your .Rprofile file. Note that the definitions will be stored in a user-specific R file, which is a suboptimal workflow. To use this method:

1. Edit the .Rprofile file using e.g. utils::file.edit("~/.Rprofile").

2. Add a text like below and save the file:

    # Add custom antibiotic drug codes:
    AMR::add_custom_antimicrobials(
      data.frame(ab = "TESTAB",
                 name = "Test Antibiotic",
                 group = "Test Group")
    )
   

Use clear_custom_antimicrobials() to clear the previously added antimicrobials.

See Also

add_custom_microorganisms() to add custom microorganisms.

Examples

# returns NA and throws a warning (which is suppressed here):
suppressWarnings(
  as.ab("testab")
)

# now add a custom entry - it will be considered by as.ab() and
# all ab_*() functions
add_custom_antimicrobials(
  data.frame(
    ab = "TESTAB",
    name = "Test Antibiotic",
    # you can add any property present in the
    # 'antibiotics' data set, such as 'group':
    group = "Test Group"
  )
)

# "testab" is now a new antibiotic:
as.ab("testab")
ab_name("testab")
ab_group("testab")

ab_info("testab")


# Add Co-fluampicil, which is one of the many J01CR50 codes, see
# https://atcddd.fhi.no/ddd/list_of_ddds_combined_products/
add_custom_antimicrobials(
  data.frame(
    ab = "COFLU",
    name = "Co-fluampicil",
    atc = "J01CR50",
    group = "Beta-lactams/penicillins"
  )
)
ab_atc("Co-fluampicil")
ab_name("J01CR50")

# even antibiotic selectors work
x <- data.frame(
  random_column = "some value",
  coflu = as.sir("S"),
  ampicillin = as.sir("R")
)
x
x[, betalactams()]

Description

With add_custom_microorganisms() you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis.

Usage

add_custom_microorganisms(x)

clear_custom_microorganisms()

Arguments

Details

This function will fill in missing taxonomy for you, if specific taxonomic columns are missing, see Examples.

Important: Due to how R works, the add_custom_microorganisms() function has to be run in every R session - added microorganisms are not stored between sessions and are thus lost when R is exited.

There are two ways to circumvent this and automate the process of adding microorganisms:

Method 1: Using the package option AMR_custom_mo, which is the preferred method. To use this method:

1. Create a data set in the structure of the microorganisms data set (containing at the very least column "genus") and save it with saveRDS() to a location of choice, e.g. "~/my_custom_mo.rds", or any remote location.

2. Set the file location to the package option AMR_custom_mo: options(AMR_custom_mo = "~/my_custom_mo.rds"). This can even be a remote file location, such as an https URL. Since options are not saved between R sessions, it is best to save this option to the .Rprofile file so that it will be loaded on start-up of R. To do this, open the .Rprofile file using e.g. utils::file.edit("~/.Rprofile"), add this text and save the file:

   # Add custom microorganism codes:
   options(AMR_custom_mo = "~/my_custom_mo.rds")
   

   Upon package load, this file will be loaded and run through the add_custom_microorganisms() function.

Method 2: Loading the microorganism directly from your .Rprofile file. Note that the definitions will be stored in a user-specific R file, which is a suboptimal workflow. To use this method:

1. Edit the .Rprofile file using e.g. utils::file.edit("~/.Rprofile").

2. Add a text like below and save the file:

    # Add custom antibiotic drug codes:
    AMR::add_custom_microorganisms(
      data.frame(genus = "Enterobacter",
                 species = "asburiae/cloacae")
    )
   

Use clear_custom_microorganisms() to clear the previously added microorganisms.

See Also

add_custom_antimicrobials() to add custom antimicrobials.

Examples

# a combination of species is not formal taxonomy, so
# this will result in "Enterobacter cloacae cloacae",
# since it resembles the input best:
mo_name("Enterobacter asburiae/cloacae")

# now add a custom entry - it will be considered by as.mo() and
# all mo_*() functions
add_custom_microorganisms(
  data.frame(
    genus = "Enterobacter",
    species = "asburiae/cloacae"
  )
)

# E. asburiae/cloacae is now a new microorganism:
mo_name("Enterobacter asburiae/cloacae")

# its code:
as.mo("Enterobacter asburiae/cloacae")

# all internal algorithms will work as well:
mo_name("Ent asburia cloacae")

# and even the taxonomy was added based on the genus!
mo_family("E. asburiae/cloacae")
mo_gramstain("Enterobacter asburiae/cloacae")

mo_info("Enterobacter asburiae/cloacae")


# the function tries to be forgiving:
add_custom_microorganisms(
  data.frame(
    GENUS = "BACTEROIDES / PARABACTEROIDES SLASHLINE",
    SPECIES = "SPECIES"
  )
)
mo_name("BACTEROIDES / PARABACTEROIDES")
mo_rank("BACTEROIDES / PARABACTEROIDES")

# taxonomy still works, even though a slashline genus was given as input:
mo_family("Bacteroides/Parabacteroides")


# for groups and complexes, set them as species or subspecies:
add_custom_microorganisms(
  data.frame(
    genus = "Citrobacter",
    species = c("freundii", "braakii complex"),
    subspecies = c("complex", "")
  )
)
mo_name(c("C. freundii complex", "C. braakii complex"))
mo_species(c("C. freundii complex", "C. braakii complex"))
mo_gramstain(c("C. freundii complex", "C. braakii complex"))

Description

Calculates age in years based on a reference date, which is the system date at default.

Usage

age(x, reference = Sys.Date(), exact = FALSE, na.rm = FALSE, ...)

Arguments

Details

Ages below 0 will be returned as NA with a warning. Ages above 120 will only give a warning.

This function vectorises over both x and reference, meaning that either can have a length of 1 while the other argument has a larger length.

Value

An integer (no decimals) if exact = FALSE, a double (with decimals) otherwise

See Also

To split ages into groups, use the age_groups() function.

Examples

# 10 random pre-Y2K birth dates
df <- data.frame(birth_date = as.Date("2000-01-01") - runif(10) * 25000)

# add ages
df$age <- age(df$birth_date)

# add exact ages
df$age_exact <- age(df$birth_date, exact = TRUE)

# add age at millenium switch
df$age_at_y2k <- age(df$birth_date, "2000-01-01")

df

Description

Split ages into age groups defined by the split argument. This allows for easier demographic (antimicrobial resistance) analysis.

Usage

age_groups(x, split_at = c(12, 25, 55, 75), na.rm = FALSE)

Arguments

Details

To split ages, the input for the split_at argument can be:

• A numeric vector. A value of e.g. c(10, 20) will split x on 0-9, 10-19 and 20+. A value of only 50 will split x on 0-49 and 50+. The default is to split on young children (0-11), youth (12-24), young adults (25-54), middle-aged adults (55-74) and elderly (75+).

• A character:

  • "children" or "kids", equivalent of: c(0, 1, 2, 4, 6, 13, 18). This will split on 0, 1, 2-3, 4-5, 6-12, 13-17 and 18+.

  • "elderly" or "seniors", equivalent of: c(65, 75, 85). This will split on 0-64, 65-74, 75-84, 85+.

  • "fives", equivalent of: 1:20 * 5. This will split on 0-4, 5-9, ..., 95-99, 100+.

  • "tens", equivalent of: 1:10 * 10. This will split on 0-9, 10-19, ..., 90-99, 100+.

Value

Ordered factor

See Also

To determine ages, based on one or more reference dates, use the age() function.

Examples

ages <- c(3, 8, 16, 54, 31, 76, 101, 43, 21)

# split into 0-49 and 50+
age_groups(ages, 50)

# split into 0-19, 20-49 and 50+
age_groups(ages, c(20, 50))

# split into groups of ten years
age_groups(ages, 1:10 * 10)
age_groups(ages, split_at = "tens")

# split into groups of five years
age_groups(ages, 1:20 * 5)
age_groups(ages, split_at = "fives")

# split specifically for children
age_groups(ages, c(1, 2, 4, 6, 13, 18))
age_groups(ages, "children")


# resistance of ciprofloxacin per age group
if (require("dplyr") && require("ggplot2")) {
  example_isolates %>%
    filter_first_isolate() %>%
    filter(mo == as.mo("Escherichia coli")) %>%
    group_by(age_group = age_groups(age)) %>%
    select(age_group, CIP) %>%
    ggplot_sir(
      x = "age_group",
      minimum = 0,
      x.title = "Age Group",
      title = "Ciprofloxacin resistance per age group"
    )
}

Description

Generate an antibiogram, and communicate the results in plots or tables. These functions follow the logic of Klinker et al. and Barbieri et al. (see Source), and allow reporting in e.g. R Markdown and Quarto as well.

Usage

antibiogram(
  x,
  antibiotics = where(is.sir),
  mo_transform = "shortname",
  ab_transform = NULL,
  syndromic_group = NULL,
  add_total_n = TRUE,
  only_all_tested = FALSE,
  digits = 0,
  col_mo = NULL,
  language = get_AMR_locale(),
  minimum = 30,
  combine_SI = TRUE,
  sep = " + ",
  info = interactive()
)

## S3 method for class 'antibiogram'
plot(x, ...)

## S3 method for class 'antibiogram'
autoplot(object, ...)

## S3 method for class 'antibiogram'
knit_print(
  x,
  italicise = TRUE,
  na = getOption("knitr.kable.NA", default = ""),
  ...
)

Arguments

Details

This function returns a table with values between 0 and 100 for susceptibility, not resistance.

Remember that you should filter your data to let it contain only first isolates! This is needed to exclude duplicates and to reduce selection bias. Use first_isolate() to determine them in your data set with one of the four available algorithms.

All types of antibiograms as listed below can be plotted (using ggplot2::autoplot() or base R plot()/barplot()). The antibiogram object can also be used directly in R Markdown / Quarto (i.e., knitr) for reports. In this case, knitr::kable() will be applied automatically and microorganism names will even be printed in italics at default (see argument italicise). You can also use functions from specific 'table reporting' packages to transform the output of antibiogram() to your needs, e.g. with flextable::as_flextable() or gt::gt().

Antibiogram Types

There are four antibiogram types, as proposed by Klinker et al. (2021, doi:10.1177/20499361211011373), and they are all supported by antibiogram():

1. Traditional Antibiogram

   Case example: Susceptibility of Pseudomonas aeruginosa to piperacillin/tazobactam (TZP)

   Code example:

   antibiogram(your_data,
               antibiotics = "TZP")
   

2. Combination Antibiogram

   Case example: Additional susceptibility of Pseudomonas aeruginosa to TZP + tobramycin versus TZP alone

   Code example:

   antibiogram(your_data,
               antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"))
   

3. Syndromic Antibiogram

   Case example: Susceptibility of Pseudomonas aeruginosa to TZP among respiratory specimens (obtained among ICU patients only)

   Code example:

   antibiogram(your_data,
               antibiotics = penicillins(),
               syndromic_group = "ward")
   

4. Weighted-Incidence Syndromic Combination Antibiogram (WISCA)

   Case example: Susceptibility of Pseudomonas aeruginosa to TZP among respiratory specimens (obtained among ICU patients only) for male patients age >=65 years with heart failure

   Code example:

   library(dplyr)
   your_data %>%
     filter(ward == "ICU" & specimen_type == "Respiratory") %>%
     antibiogram(antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
                 syndromic_group = ifelse(.$age >= 65 &
                                            .$gender == "Male" &
                                            .$condition == "Heart Disease",
                                          "Study Group", "Control Group"))
   

Note that for combination antibiograms, it is important to realise that susceptibility can be calculated in two ways, which can be set with the only_all_tested argument (default is FALSE). See this example for two antibiotics, Drug A and Drug B, about how antibiogram() works to calculate the %SI:

--------------------------------------------------------------------
                    only_all_tested = FALSE  only_all_tested = TRUE
                    -----------------------  -----------------------
 Drug A    Drug B   include as  include as   include as  include as
                    numerator   denominator  numerator   denominator
--------  --------  ----------  -----------  ----------  -----------
 S or I    S or I       X            X            X            X
   R       S or I       X            X            X            X
  <NA>     S or I       X            X            -            -
 S or I      R          X            X            X            X
   R         R          -            X            -            X
  <NA>       R          -            -            -            -
 S or I     <NA>        X            X            -            -
   R        <NA>        -            -            -            -
  <NA>      <NA>        -            -            -            -
--------------------------------------------------------------------

Source

• Klinker KP et al. (2021). Antimicrobial stewardship and antibiograms: importance of moving beyond traditional antibiograms. Therapeutic Advances in Infectious Disease, May 5;8:20499361211011373; doi:10.1177/20499361211011373

• Barbieri E et al. (2021). Development of a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) to guide the choice of the empiric antibiotic treatment for urinary tract infection in paediatric patients: a Bayesian approach Antimicrobial Resistance & Infection Control May 1;10(1):74; doi:10.1186/s13756-021-00939-2

• M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 5th Edition, 2022, Clinical and Laboratory Standards Institute (CLSI). https://clsi.org/standards/products/microbiology/documents/m39/.

Examples

# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
example_isolates


# Traditional antibiogram ----------------------------------------------

antibiogram(example_isolates,
  antibiotics = c(aminoglycosides(), carbapenems())
)

antibiogram(example_isolates,
  antibiotics = aminoglycosides(),
  ab_transform = "atc",
  mo_transform = "gramstain"
)

antibiogram(example_isolates,
  antibiotics = carbapenems(),
  ab_transform = "name",
  mo_transform = "name"
)


# Combined antibiogram -------------------------------------------------

# combined antibiotics yield higher empiric coverage
antibiogram(example_isolates,
  antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
  mo_transform = "gramstain"
)

# names of antibiotics do not need to resemble columns exactly:
antibiogram(example_isolates,
  antibiotics = c("Cipro", "cipro + genta"),
  mo_transform = "gramstain",
  ab_transform = "name",
  sep = " & "
)


# Syndromic antibiogram ------------------------------------------------

# the data set could contain a filter for e.g. respiratory specimens
antibiogram(example_isolates,
  antibiotics = c(aminoglycosides(), carbapenems()),
  syndromic_group = "ward"
)

# now define a data set with only E. coli
ex1 <- example_isolates[which(mo_genus() == "Escherichia"), ]

# with a custom language, though this will be determined automatically
# (i.e., this table will be in Spanish on Spanish systems)
antibiogram(ex1,
  antibiotics = aminoglycosides(),
  ab_transform = "name",
  syndromic_group = ifelse(ex1$ward == "ICU",
    "UCI", "No UCI"
  ),
  language = "es"
)


# Weighted-incidence syndromic combination antibiogram (WISCA) ---------

# the data set could contain a filter for e.g. respiratory specimens/ICU
antibiogram(example_isolates,
  antibiotics = c("AMC", "AMC+CIP", "TZP", "TZP+TOB"),
  mo_transform = "gramstain",
  minimum = 10, # this should be >=30, but now just as example
  syndromic_group = ifelse(example_isolates$age >= 65 &
    example_isolates$gender == "M",
  "WISCA Group 1", "WISCA Group 2"
  )
)


# Print the output for R Markdown / Quarto -----------------------------

ureido <- antibiogram(example_isolates,
  antibiotics = ureidopenicillins(),
  ab_transform = "name"
)

# in an Rmd file, you would just need to return `ureido` in a chunk,
# but to be explicit here:
if (requireNamespace("knitr")) {
  cat(knitr::knit_print(ureido))
}


# Generate plots with ggplot2 or base R --------------------------------

ab1 <- antibiogram(example_isolates,
  antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
  mo_transform = "gramstain"
)
ab2 <- antibiogram(example_isolates,
  antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
  mo_transform = "gramstain",
  syndromic_group = "ward"
)

if (requireNamespace("ggplot2")) {
  ggplot2::autoplot(ab1)
}
if (requireNamespace("ggplot2")) {
  ggplot2::autoplot(ab2)
}

plot(ab1)
plot(ab2)

Description

These functions allow for filtering rows and selecting columns based on antibiotic test results that are of a specific antibiotic class or group (according to the antibiotics data set), without the need to define the columns or antibiotic abbreviations.

In short, if you have a column name that resembles an antimicrobial drug, it will be picked up by any of these functions that matches its pharmaceutical class: "cefazolin", "kefzol", "CZO" and "J01DB04" will all be picked up by cephalosporins().

Usage

ab_class(ab_class, only_sir_columns = FALSE, only_treatable = TRUE, ...)

ab_selector(filter, only_sir_columns = FALSE, only_treatable = TRUE, ...)

aminoglycosides(only_sir_columns = FALSE, only_treatable = TRUE, ...)

aminopenicillins(only_sir_columns = FALSE, ...)

antifungals(only_sir_columns = FALSE, ...)

antimycobacterials(only_sir_columns = FALSE, ...)

betalactams(only_sir_columns = FALSE, only_treatable = TRUE, ...)

carbapenems(only_sir_columns = FALSE, only_treatable = TRUE, ...)

cephalosporins(only_sir_columns = FALSE, ...)

cephalosporins_1st(only_sir_columns = FALSE, ...)

cephalosporins_2nd(only_sir_columns = FALSE, ...)

cephalosporins_3rd(only_sir_columns = FALSE, ...)

cephalosporins_4th(only_sir_columns = FALSE, ...)

cephalosporins_5th(only_sir_columns = FALSE, ...)

fluoroquinolones(only_sir_columns = FALSE, ...)

glycopeptides(only_sir_columns = FALSE, ...)

lincosamides(only_sir_columns = FALSE, only_treatable = TRUE, ...)

lipoglycopeptides(only_sir_columns = FALSE, ...)

macrolides(only_sir_columns = FALSE, ...)

nitrofurans(only_sir_columns = FALSE, ...)

oxazolidinones(only_sir_columns = FALSE, ...)

penicillins(only_sir_columns = FALSE, ...)

polymyxins(only_sir_columns = FALSE, only_treatable = TRUE, ...)

quinolones(only_sir_columns = FALSE, ...)

rifamycins(only_sir_columns = FALSE, ...)

streptogramins(only_sir_columns = FALSE, ...)

tetracyclines(only_sir_columns = FALSE, ...)

trimethoprims(only_sir_columns = FALSE, ...)

ureidopenicillins(only_sir_columns = FALSE, ...)

administrable_per_os(only_sir_columns = FALSE, ...)

administrable_iv(only_sir_columns = FALSE, ...)

not_intrinsic_resistant(
  only_sir_columns = FALSE,
  col_mo = NULL,
  version_expertrules = 3.3,
  ...
)

Arguments

Details

These functions can be used in data set calls for selecting columns and filtering rows. They work with base R, the Tidyverse, and data.table. They are heavily inspired by the Tidyverse selection helpers such as everything(), but are not limited to dplyr verbs. Nonetheless, they are very convenient to use with dplyr functions such as select(), filter() and summarise(), see Examples.

All columns in the data in which these functions are called will be searched for known antibiotic names, abbreviations, brand names, and codes (ATC, EARS-Net, WHO, etc.) according to the antibiotics data set. This means that a selector such as aminoglycosides() will pick up column names like 'gen', 'genta', 'J01GB03', 'tobra', 'Tobracin', etc.

The ab_class() function can be used to filter/select on a manually defined antibiotic class. It searches for results in the antibiotics data set within the columns group, atc_group1 and atc_group2.

The ab_selector() function can be used to internally filter the antibiotics data set on any results, see Examples. It allows for filtering on a (part of) a certain name, and/or a group name or even a minimum of DDDs for oral treatment. This function yields the highest flexibility, but is also the least user-friendly, since it requires a hard-coded filter to set.

The administrable_per_os() and administrable_iv() functions also rely on the antibiotics data set - antibiotic columns will be matched where a DDD (defined daily dose) for resp. oral and IV treatment is available in the antibiotics data set.

The not_intrinsic_resistant() function can be used to only select antibiotic columns that pose no intrinsic resistance for the microorganisms in the data set. For example, if a data set contains only microorganism codes or names of E. coli and K. pneumoniae and contains a column "vancomycin", this column will be removed (or rather, unselected) using this function. It currently applies 'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3 (2021) to determine intrinsic resistance, using the eucast_rules() function internally. Because of this determination, this function is quite slow in terms of performance.

Value

(internally) a character vector of column names, with additional class "ab_selector"

Full list of supported (antibiotic) classes

• aminoglycosides() can select:
  amikacin (AMK), amikacin/fosfomycin (AKF), apramycin (APR), arbekacin (ARB), astromicin (AST), bekanamycin (BEK), dibekacin (DKB), framycetin (FRM), gentamicin (GEN), gentamicin-high (GEH), habekacin (HAB), hygromycin (HYG), isepamicin (ISE), kanamycin (KAN), kanamycin-high (KAH), kanamycin/cephalexin (KAC), micronomicin (MCR), neomycin (NEO), netilmicin (NET), pentisomicin (PIM), plazomicin (PLZ), propikacin (PKA), ribostamycin (RST), sisomicin (SIS), streptoduocin (STR), streptomycin (STR1), streptomycin-high (STH), tobramycin (TOB), and tobramycin-high (TOH)

• aminopenicillins() can select:
  amoxicillin (AMX) and ampicillin (AMP)

• antifungals() can select:
  amorolfine (AMO), amphotericin B (AMB), amphotericin B-high (AMH), anidulafungin (ANI), butoconazole (BUT), caspofungin (CAS), ciclopirox (CIX), clotrimazole (CTR), econazole (ECO), fluconazole (FLU), flucytosine (FCT), fosfluconazole (FFL), griseofulvin (GRI), hachimycin (HCH), ibrexafungerp (IBX), isavuconazole (ISV), isoconazole (ISO), itraconazole (ITR), ketoconazole (KET), manogepix (MGX), micafungin (MIF), miconazole (MCZ), nystatin (NYS), oteseconazole (OTE), pimaricin (PMR), posaconazole (POS), rezafungin (RZF), ribociclib (RBC), sulconazole (SUC), terbinafine (TRB), terconazole (TRC), and voriconazole (VOR)

• antimycobacterials() can select:
  4-aminosalicylic acid (AMA), calcium aminosalicylate (CLA), capreomycin (CAP), clofazimine (CLF), delamanid (DLM), enviomycin (ENV), ethambutol (ETH), ethambutol/isoniazid (ETI), ethionamide (ETI1), isoniazid (INH), isoniazid/sulfamethoxazole/trimethoprim/pyridoxine (IST), morinamide (MRN), p-aminosalicylic acid (PAS), pretomanid (PMD), protionamide (PTH), pyrazinamide (PZA), rifabutin (RIB), rifampicin (RIF), rifampicin/ethambutol/isoniazid (REI), rifampicin/isoniazid (RFI), rifampicin/pyrazinamide/ethambutol/isoniazid (RPEI), rifampicin/pyrazinamide/isoniazid (RPI), rifamycin (RFM), rifapentine (RFP), simvastatin/fenofibrate (SMF), sodium aminosalicylate (SDA), streptomycin/isoniazid (STI), terizidone (TRZ), thioacetazone (TAT), thioacetazone/isoniazid (THI1), tiocarlide (TCR), and viomycin (VIO)

• betalactams() can select:
  amoxicillin (AMX), amoxicillin/clavulanic acid (AMC), amoxicillin/sulbactam (AXS), ampicillin (AMP), ampicillin/sulbactam (SAM), apalcillin (APL), aspoxicillin (APX), avibactam (AVB), azidocillin (AZD), azlocillin (AZL), aztreonam (ATM), aztreonam/avibactam (AZA), aztreonam/nacubactam (ANC), bacampicillin (BAM), benzathine benzylpenicillin (BNB), benzathine phenoxymethylpenicillin (BNP), benzylpenicillin (PEN), biapenem (BIA), carbenicillin (CRB), carindacillin (CRN), cefacetrile (CAC), cefaclor (CEC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefamandole (MAN), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/nacubactam (FNC), cefepime/tazobactam (FPT), cefetamet (CAT), cefetamet pivoxil (CPI), cefetecol (CCL), cefetrizole (CZL), cefixime (CFM), cefmenoxime (CMX), cefmetazole (CMZ), cefodizime (DIZ), cefonicid (CID), cefoperazone (CFP), cefoperazone/sulbactam (CSL), ceforanide (CND), cefoselis (CSE), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotetan (CTT), cefotiam (CTF), cefotiam hexetil (CHE), cefovecin (FOV), cefoxitin (FOX), cefoxitin screening (FOX1), cefozopran (ZOP), cefpimizole (CFZ), cefpiramide (CPM), cefpirome (CPO), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefprozil (CPR), cefquinome (CEQ), cefroxadine (CRD), cefsulodin (CFS), cefsumide (CSU), ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftezole (CTL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), ceftolozane/tazobactam (CZT), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), cefuroxime (CXM), cefuroxime axetil (CXA), cephradine (CED), ciclacillin (CIC), clometocillin (CLM), cloxacillin (CLO), dicloxacillin (DIC), doripenem (DOR), epicillin (EPC), ertapenem (ETP), flucloxacillin (FLC), hetacillin (HET), imipenem (IPM), imipenem/EDTA (IPE), imipenem/relebactam (IMR), latamoxef (LTM), lenampicillin (LEN), loracarbef (LOR), mecillinam (MEC), meropenem (MEM), meropenem/nacubactam (MNC), meropenem/vaborbactam (MEV), metampicillin (MTM), meticillin (MET), mezlocillin (MEZ), mezlocillin/sulbactam (MSU), nacubactam (NAC), nafcillin (NAF), oxacillin (OXA), panipenem (PAN), penamecillin (PNM), penicillin/novobiocin (PNO), penicillin/sulbactam (PSU), pheneticillin (PHE), phenoxymethylpenicillin (PHN), piperacillin (PIP), piperacillin/sulbactam (PIS), piperacillin/tazobactam (TZP), piridicillin (PRC), pivampicillin (PVM), pivmecillinam (PME), procaine benzylpenicillin (PRB), propicillin (PRP), razupenem (RZM), ritipenem (RIT), ritipenem acoxil (RIA), sarmoxicillin (SRX), sulbactam (SUL), sulbenicillin (SBC), sultamicillin (SLT6), talampicillin (TAL), tazobactam (TAZ), tebipenem (TBP), temocillin (TEM), ticarcillin (TIC), and ticarcillin/clavulanic acid (TCC)

• carbapenems() can select:
  biapenem (BIA), doripenem (DOR), ertapenem (ETP), imipenem (IPM), imipenem/EDTA (IPE), imipenem/relebactam (IMR), meropenem (MEM), meropenem/nacubactam (MNC), meropenem/vaborbactam (MEV), panipenem (PAN), razupenem (RZM), ritipenem (RIT), ritipenem acoxil (RIA), and tebipenem (TBP)

• cephalosporins() can select:
  cefacetrile (CAC), cefaclor (CEC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefamandole (MAN), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/tazobactam (FPT), cefetamet (CAT), cefetamet pivoxil (CPI), cefetecol (CCL), cefetrizole (CZL), cefixime (CFM), cefmenoxime (CMX), cefmetazole (CMZ), cefodizime (DIZ), cefonicid (CID), cefoperazone (CFP), cefoperazone/sulbactam (CSL), ceforanide (CND), cefoselis (CSE), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotetan (CTT), cefotiam (CTF), cefotiam hexetil (CHE), cefovecin (FOV), cefoxitin (FOX), cefoxitin screening (FOX1), cefozopran (ZOP), cefpimizole (CFZ), cefpiramide (CPM), cefpirome (CPO), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefprozil (CPR), cefquinome (CEQ), cefroxadine (CRD), cefsulodin (CFS), cefsumide (CSU), ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftezole (CTL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), ceftolozane/tazobactam (CZT), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), cefuroxime (CXM), cefuroxime axetil (CXA), cephradine (CED), latamoxef (LTM), and loracarbef (LOR)

• cephalosporins_1st() can select:
  cefacetrile (CAC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefroxadine (CRD), ceftezole (CTL), and cephradine (CED)

• cephalosporins_2nd() can select:
  cefaclor (CEC), cefamandole (MAN), cefmetazole (CMZ), cefonicid (CID), ceforanide (CND), cefotetan (CTT), cefotiam (CTF), cefoxitin (FOX), cefoxitin screening (FOX1), cefprozil (CPR), cefuroxime (CXM), cefuroxime axetil (CXA), and loracarbef (LOR)

• cephalosporins_3rd() can select:
  cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefetamet (CAT), cefetamet pivoxil (CPI), cefixime (CFM), cefmenoxime (CMX), cefodizime (DIZ), cefoperazone (CFP), cefoperazone/sulbactam (CSL), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotiam hexetil (CHE), cefovecin (FOV), cefpimizole (CFZ), cefpiramide (CPM), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefsulodin (CFS), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), and latamoxef (LTM)

• cephalosporins_4th() can select:
  cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/tazobactam (FPT), cefetecol (CCL), cefoselis (CSE), cefozopran (ZOP), cefpirome (CPO), and cefquinome (CEQ)

• cephalosporins_5th() can select:
  ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), and ceftolozane/tazobactam (CZT)

• fluoroquinolones() can select:
  besifloxacin (BES), ciprofloxacin (CIP), clinafloxacin (CLX), danofloxacin (DAN), delafloxacin (DFX), difloxacin (DIF), enoxacin (ENX), enrofloxacin (ENR), finafloxacin (FIN), fleroxacin (FLE), garenoxacin (GRN), gatifloxacin (GAT), gemifloxacin (GEM), grepafloxacin (GRX), lascufloxacin (LSC), levofloxacin (LVX), levonadifloxacin (LND), lomefloxacin (LOM), marbofloxacin (MAR), metioxate (MXT), miloxacin (MIL), moxifloxacin (MFX), nadifloxacin (NAD), nifuroquine (NIF), norfloxacin (NOR), ofloxacin (OFX), orbifloxacin (ORB), pazufloxacin (PAZ), pefloxacin (PEF), pradofloxacin (PRA), premafloxacin (PRX), prulifloxacin (PRU), rufloxacin (RFL), sarafloxacin (SAR), sitafloxacin (SIT), sparfloxacin (SPX), temafloxacin (TMX), tilbroquinol (TBQ), tioxacin (TXC), tosufloxacin (TFX), and trovafloxacin (TVA)

• glycopeptides() can select:
  avoparcin (AVO), dalbavancin (DAL), norvancomycin (NVA), oritavancin (ORI), ramoplanin (RAM), teicoplanin (TEC), teicoplanin-macromethod (TCM), telavancin (TLV), vancomycin (VAN), and vancomycin-macromethod (VAM)

• lincosamides() can select:
  acetylmidecamycin (ACM), acetylspiramycin (ASP), clindamycin (CLI), clindamycin inducible screening (CLI1), gamithromycin (GAM), kitasamycin (KIT), lincomycin (LIN), meleumycin (MEL), nafithromycin (ZWK), pirlimycin (PRL), primycin (PRM), solithromycin (SOL), tildipirosin (TIP), tilmicosin (TIL), tulathromycin (TUL), tylosin (TYL), and tylvalosin (TYL1)

• lipoglycopeptides() can select:
  dalbavancin (DAL), oritavancin (ORI), and telavancin (TLV)

• macrolides() can select:
  acetylmidecamycin (ACM), acetylspiramycin (ASP), azithromycin (AZM), clarithromycin (CLR), dirithromycin (DIR), erythromycin (ERY), flurithromycin (FLR1), gamithromycin (GAM), josamycin (JOS), kitasamycin (KIT), meleumycin (MEL), midecamycin (MID), miocamycin (MCM), nafithromycin (ZWK), oleandomycin (OLE), pirlimycin (PRL), primycin (PRM), rokitamycin (ROK), roxithromycin (RXT), solithromycin (SOL), spiramycin (SPI), telithromycin (TLT), tildipirosin (TIP), tilmicosin (TIL), troleandomycin (TRL), tulathromycin (TUL), tylosin (TYL), and tylvalosin (TYL1)

• nitrofurans() can select:
  furazidin (FUR), furazolidone (FRZ), nifurtoinol (NFR), nitrofurantoin (NIT), and nitrofurazone (NIZ)

• oxazolidinones() can select:
  cadazolid (CDZ), cycloserine (CYC), linezolid (LNZ), tedizolid (TZD), and thiacetazone (THA)

• penicillins() can select:
  amoxicillin (AMX), amoxicillin/clavulanic acid (AMC), amoxicillin/sulbactam (AXS), ampicillin (AMP), ampicillin/sulbactam (SAM), apalcillin (APL), aspoxicillin (APX), avibactam (AVB), azidocillin (AZD), azlocillin (AZL), aztreonam (ATM), aztreonam/avibactam (AZA), aztreonam/nacubactam (ANC), bacampicillin (BAM), benzathine benzylpenicillin (BNB), benzathine phenoxymethylpenicillin (BNP), benzylpenicillin (PEN), carbenicillin (CRB), carindacillin (CRN), cefepime/nacubactam (FNC), ciclacillin (CIC), clometocillin (CLM), cloxacillin (CLO), dicloxacillin (DIC), epicillin (EPC), flucloxacillin (FLC), hetacillin (HET), lenampicillin (LEN), mecillinam (MEC), metampicillin (MTM), meticillin (MET), mezlocillin (MEZ), mezlocillin/sulbactam (MSU), nacubactam (NAC), nafcillin (NAF), oxacillin (OXA), penamecillin (PNM), penicillin/novobiocin (PNO), penicillin/sulbactam (PSU), pheneticillin (PHE), phenoxymethylpenicillin (PHN), piperacillin (PIP), piperacillin/sulbactam (PIS), piperacillin/tazobactam (TZP), piridicillin (PRC), pivampicillin (PVM), pivmecillinam (PME), procaine benzylpenicillin (PRB), propicillin (PRP), sarmoxicillin (SRX), sulbactam (SUL), sulbenicillin (SBC), sultamicillin (SLT6), talampicillin (TAL), tazobactam (TAZ), temocillin (TEM), ticarcillin (TIC), and ticarcillin/clavulanic acid (TCC)

• polymyxins() can select:
  colistin (COL), polymyxin B (PLB), and polymyxin B/polysorbate 80 (POP)

• quinolones() can select:
  besifloxacin (BES), cinoxacin (CIN), ciprofloxacin (CIP), ciprofloxacin/metronidazole (CIM), ciprofloxacin/ornidazole (CIO), ciprofloxacin/tinidazole (CIT), clinafloxacin (CLX), danofloxacin (DAN), delafloxacin (DFX), difloxacin (DIF), enoxacin (ENX), enrofloxacin (ENR), finafloxacin (FIN), fleroxacin (FLE), flumequine (FLM), garenoxacin (GRN), gatifloxacin (GAT), gemifloxacin (GEM), grepafloxacin (GRX), lascufloxacin (LSC), levofloxacin (LVX), levonadifloxacin (LND), lomefloxacin (LOM), marbofloxacin (MAR), metioxate (MXT), miloxacin (MIL), moxifloxacin (MFX), nadifloxacin (NAD), nalidixic acid (NAL), nemonoxacin (NEM), nifuroquine (NIF), nitroxoline (NTR), norfloxacin (NOR), ofloxacin (OFX), orbifloxacin (ORB), oxolinic acid (OXO), pazufloxacin (PAZ), pefloxacin (PEF), pipemidic acid (PPA), piromidic acid (PIR), pradofloxacin (PRA), premafloxacin (PRX), prulifloxacin (PRU), rosoxacin (ROS), rufloxacin (RFL), sarafloxacin (SAR), sitafloxacin (SIT), sparfloxacin (SPX), temafloxacin (TMX), tilbroquinol (TBQ), tioxacin (TXC), tosufloxacin (TFX), and trovafloxacin (TVA)

• rifamycins() can select:
  rifabutin (RIB), rifampicin (RIF), rifampicin/ethambutol/isoniazid (REI), rifampicin/isoniazid (RFI), rifampicin/pyrazinamide/ethambutol/isoniazid (RPEI), rifampicin/pyrazinamide/isoniazid (RPI), rifamycin (RFM), and rifapentine (RFP)

• streptogramins() can select:
  pristinamycin (PRI) and quinupristin/dalfopristin (QDA)

• tetracyclines() can select:
  cetocycline (CTO), chlortetracycline (CTE), clomocycline (CLM1), demeclocycline (DEM), doxycycline (DOX), eravacycline (ERV), lymecycline (LYM), metacycline (MTC), minocycline (MNO), omadacycline (OMC), oxytetracycline (OXY), penimepicycline (PNM1), rolitetracycline (RLT), sarecycline (SRC), tetracycline (TCY), and tigecycline (TGC)

• trimethoprims() can select:
  brodimoprim (BDP), sulfadiazine (SDI), sulfadiazine/tetroxoprim (SLT), sulfadiazine/trimethoprim (SLT1), sulfadimethoxine (SUD), sulfadimidine (SDM), sulfadimidine/trimethoprim (SLT2), sulfafurazole (SLF), sulfaisodimidine (SLF1), sulfalene (SLF2), sulfamazone (SZO), sulfamerazine (SLF3), sulfamerazine/trimethoprim (SLT3), sulfamethizole (SLF4), sulfamethoxazole (SMX), sulfamethoxypyridazine (SLF5), sulfametomidine (SLF6), sulfametoxydiazine (SLF7), sulfametrole/trimethoprim (SLT4), sulfamoxole (SLF8), sulfamoxole/trimethoprim (SLT5), sulfanilamide (SLF9), sulfaperin (SLF10), sulfaphenazole (SLF11), sulfapyridine (SLF12), sulfathiazole (SUT), sulfathiourea (SLF13), trimethoprim (TMP), and trimethoprim/sulfamethoxazole (SXT)

• ureidopenicillins() can select:
  azlocillin (AZL), mezlocillin (MEZ), piperacillin (PIP), and piperacillin/tazobactam (TZP)

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

Examples

# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
example_isolates


# Examples sections below are split into 'dplyr', 'base R', and 'data.table':


# dplyr -------------------------------------------------------------------

if (require("dplyr")) {
  example_isolates %>% select(carbapenems())
}

if (require("dplyr")) {
  # select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB'
  example_isolates %>% select(mo, aminoglycosides())
}

if (require("dplyr")) {
  # select only antibiotic columns with DDDs for oral treatment
  example_isolates %>% select(administrable_per_os())
}

if (require("dplyr")) {
  # get AMR for all aminoglycosides e.g., per ward:
  example_isolates %>%
    group_by(ward) %>%
    summarise(across(aminoglycosides(),
                     resistance))
}
if (require("dplyr")) {
  # You can combine selectors with '&' to be more specific:
  example_isolates %>%
    select(penicillins() & administrable_per_os())
}
if (require("dplyr")) {
  # get AMR for only drugs that matter - no intrinsic resistance:
  example_isolates %>%
    filter(mo_genus() %in% c("Escherichia", "Klebsiella")) %>%
    group_by(ward) %>%
    summarise_at(not_intrinsic_resistant(),
                 resistance)
}
if (require("dplyr")) {
  # get susceptibility for antibiotics whose name contains "trim":
  example_isolates %>%
    filter(first_isolate()) %>%
    group_by(ward) %>%
    summarise(across(ab_selector(name %like% "trim"), susceptibility))
}
if (require("dplyr")) {
  # this will select columns 'IPM' (imipenem) and 'MEM' (meropenem):
  example_isolates %>%
    select(carbapenems())
}
if (require("dplyr")) {
  # this will select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB':
  example_isolates %>%
    select(mo, aminoglycosides())
}
if (require("dplyr")) {
  # any() and all() work in dplyr's filter() too:
  example_isolates %>%
    filter(
      any(aminoglycosides() == "R"),
      all(cephalosporins_2nd() == "R")
    )
}
if (require("dplyr")) {
  # also works with c():
  example_isolates %>%
    filter(any(c(carbapenems(), aminoglycosides()) == "R"))
}
if (require("dplyr")) {
  # not setting any/all will automatically apply all():
  example_isolates %>%
    filter(aminoglycosides() == "R")
}
if (require("dplyr")) {
  # this will select columns 'mo' and all antimycobacterial drugs ('RIF'):
  example_isolates %>%
    select(mo, ab_class("mycobact"))
}
if (require("dplyr")) {
  # get bug/drug combinations for only glycopeptides in Gram-positives:
  example_isolates %>%
    filter(mo_is_gram_positive()) %>%
    select(mo, glycopeptides()) %>%
    bug_drug_combinations() %>%
    format()
}
if (require("dplyr")) {
  data.frame(
    some_column = "some_value",
    J01CA01 = "S"
  ) %>% # ATC code of ampicillin
    select(penicillins()) # only the 'J01CA01' column will be selected
}
if (require("dplyr")) {
  # with recent versions of dplyr, this is all equal:
  x <- example_isolates[carbapenems() == "R", ]
  y <- example_isolates %>% filter(carbapenems() == "R")
  z <- example_isolates %>% filter(if_all(carbapenems(), ~ .x == "R"))
  identical(x, y) && identical(y, z)
}


# base R ------------------------------------------------------------------

# select columns 'IPM' (imipenem) and 'MEM' (meropenem)
example_isolates[, carbapenems()]

# select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB'
example_isolates[, c("mo", aminoglycosides())]

# select only antibiotic columns with DDDs for oral treatment
example_isolates[, administrable_per_os()]

# filter using any() or all()
example_isolates[any(carbapenems() == "R"), ]
subset(example_isolates, any(carbapenems() == "R"))

# filter on any or all results in the carbapenem columns (i.e., IPM, MEM):
example_isolates[any(carbapenems()), ]
example_isolates[all(carbapenems()), ]

# filter with multiple antibiotic selectors using c()
example_isolates[all(c(carbapenems(), aminoglycosides()) == "R"), ]

# filter + select in one go: get penicillins in carbapenem-resistant strains
example_isolates[any(carbapenems() == "R"), penicillins()]

# You can combine selectors with '&' to be more specific. For example,
# penicillins() would select benzylpenicillin ('peni G') and
# administrable_per_os() would select erythromycin. Yet, when combined these
# drugs are both omitted since benzylpenicillin is not administrable per os
# and erythromycin is not a penicillin:
example_isolates[, penicillins() & administrable_per_os()]

# ab_selector() applies a filter in the `antibiotics` data set and is thus
# very flexible. For instance, to select antibiotic columns with an oral DDD
# of at least 1 gram:
example_isolates[, ab_selector(oral_ddd > 1 & oral_units == "g")]


# data.table --------------------------------------------------------------

# data.table is supported as well, just use it in the same way as with
# base R, but add `with = FALSE` if using a single AB selector.

if (require("data.table")) {
  dt <- as.data.table(example_isolates)

  # this does not work, it returns column *names*
  dt[, carbapenems()]
}
if (require("data.table")) {
  # so `with = FALSE` is required
  dt[, carbapenems(), with = FALSE]
}

# for multiple selections or AB selectors, `with = FALSE` is not needed:
if (require("data.table")) {
  dt[, c("mo", aminoglycosides())]
}
if (require("data.table")) {
  dt[, c(carbapenems(), aminoglycosides())]
}

# row filters are also supported:
if (require("data.table")) {
  dt[any(carbapenems() == "S"), ]
}
if (require("data.table")) {
  dt[any(carbapenems() == "S"), penicillins(), with = FALSE]
}

Description

Two data sets containing all antibiotics/antimycotics and antivirals. Use as.ab() or one of the ab_* functions to retrieve values from the antibiotics data set. Three identifiers are included in this data set: an antibiotic ID (ab, primarily used in this package) as defined by WHONET/EARS-Net, an ATC code (atc) as defined by the WHO, and a Compound ID (cid) as found in PubChem. Other properties in this data set are derived from one or more of these codes. Note that some drugs have multiple ATC codes.

Usage

antibiotics

antivirals

Format

For the antibiotics data set: a tibble with 485 observations and 14 variables:

• ab
  Antibiotic ID as used in this package (such as AMC), using the official EARS-Net (European Antimicrobial Resistance Surveillance Network) codes where available. This is a unique identifier.

• cid
  Compound ID as found in PubChem. This is a unique identifier.

• name
  Official name as used by WHONET/EARS-Net or the WHO. This is a unique identifier.

• group
  A short and concise group name, based on WHONET and WHOCC definitions

• atc
  ATC codes (Anatomical Therapeutic Chemical) as defined by the WHOCC, like J01CR02

• atc_group1
  Official pharmacological subgroup (3rd level ATC code) as defined by the WHOCC, like "Macrolides, lincosamides and streptogramins"

• atc_group2
  Official chemical subgroup (4th level ATC code) as defined by the WHOCC, like "Macrolides"

• abbr
  List of abbreviations as used in many countries, also for antibiotic susceptibility testing (AST)

• synonyms
  Synonyms (often trade names) of a drug, as found in PubChem based on their compound ID

• oral_ddd
  Defined Daily Dose (DDD), oral treatment, currently available for 179 drugs

• oral_units
  Units of oral_ddd

• iv_ddd
  Defined Daily Dose (DDD), parenteral (intravenous) treatment, currently available for 153 drugs

• iv_units
  Units of iv_ddd

• loinc
  All codes associated with the name of the antimicrobial drug from Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Use ab_loinc() to retrieve them quickly, see ab_property().

For the antivirals data set: a tibble with 120 observations and 11 variables:

• av
  Antiviral ID as used in this package (such as ACI), using the official EARS-Net (European Antimicrobial Resistance Surveillance Network) codes where available. This is a unique identifier. Combinations are codes that contain a + to indicate this, such as ATA+COBI for atazanavir/cobicistat.

• name
  Official name as used by WHONET/EARS-Net or the WHO. This is a unique identifier.

• atc
  ATC codes (Anatomical Therapeutic Chemical) as defined by the WHOCC

• cid
  Compound ID as found in PubChem. This is a unique identifier.

• atc_group
  Official pharmacological subgroup (3rd level ATC code) as defined by the WHOCC

• synonyms
  Synonyms (often trade names) of a drug, as found in PubChem based on their compound ID

• oral_ddd
  Defined Daily Dose (DDD), oral treatment

• oral_units
  Units of oral_ddd

• iv_ddd
  Defined Daily Dose (DDD), parenteral treatment

• iv_units
  Units of iv_ddd

• loinc
  All codes associated with the name of the antiviral drug from Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Use av_loinc() to retrieve them quickly, see av_property().

An object of class tbl_df (inherits from tbl, data.frame) with 120 rows and 11 columns.

Details

Properties that are based on an ATC code are only available when an ATC is available. These properties are: atc_group1, atc_group2, oral_ddd, oral_units, iv_ddd and iv_units.

Synonyms (i.e. trade names) were derived from the PubChem Compound ID (column cid) and consequently only available where a CID is available.

Direct download

Like all data sets in this package, these data sets are publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

WHOCC

This package contains all ~550 antibiotic, antimycotic and antiviral drugs and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, https://atcddd.fhi.no) and the Pharmaceuticals Community Register of the European Commission (https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm).

These have become the gold standard for international drug utilisation monitoring and research.

The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.

NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package. See https://atcddd.fhi.no/copyright_disclaimer/.

Source

• World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology (WHOCC): https://atcddd.fhi.no/atc_ddd_index/

• Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Accessed from https://loinc.org on October 19th, 2023.

• European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm

See Also

microorganisms, intrinsic_resistant

Examples

antibiotics
antivirals

Description

Use this function to determine the antibiotic drug code of one or more antibiotics. The data set antibiotics will be searched for abbreviations, official names and synonyms (brand names).

Usage

as.ab(x, flag_multiple_results = TRUE, info = interactive(), ...)

is.ab(x)

Arguments

Details

All entries in the antibiotics data set have three different identifiers: a human readable EARS-Net code (column ab, used by ECDC and WHONET), an ATC code (column atc, used by WHO), and a CID code (column cid, Compound ID, used by PubChem). The data set contains more than 5,000 official brand names from many different countries, as found in PubChem. Not that some drugs contain multiple ATC codes.

All these properties will be searched for the user input. The as.ab() can correct for different forms of misspelling:

• Wrong spelling of drug names (such as "tobramicin" or "gentamycin"), which corrects for most audible similarities such as f/ph, x/ks, c/z/s, t/th, etc.

• Too few or too many vowels or consonants

• Switching two characters (such as "mreopenem", often the case in clinical data, when doctors typed too fast)

• Digitalised paper records, leaving artefacts like 0/o/O (zero and O's), B/8, n/r, etc.

Use the ab_* functions to get properties based on the returned antibiotic ID, see Examples.

Note: the as.ab() and ab_* functions may use very long regular expression to match brand names of antimicrobial drugs. This may fail on some systems.

You can add your own manual codes to be considered by as.ab() and all ab_* functions, see add_custom_antimicrobials().

Value

A character vector with additional class ab

Source

World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: https://atcddd.fhi.no/atc_ddd_index/

European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm

WHOCC

This package contains all ~550 antibiotic, antimycotic and antiviral drugs and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, https://atcddd.fhi.no) and the Pharmaceuticals Community Register of the European Commission (https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm).

These have become the gold standard for international drug utilisation monitoring and research.

The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.

NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package. See https://atcddd.fhi.no/copyright_disclaimer/.

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

See Also

• antibiotics for the data.frame that is being used to determine ATCs

• ab_from_text() for a function to retrieve antimicrobial drugs from clinical text (from health care records)

Examples

# these examples all return "ERY", the ID of erythromycin:
as.ab("J01FA01")
as.ab("J 01 FA 01")
as.ab("Erythromycin")
as.ab("eryt")
as.ab("   eryt 123")
as.ab("ERYT")
as.ab("ERY")
as.ab("eritromicine") # spelled wrong, yet works
as.ab("Erythrocin") # trade name
as.ab("Romycin") # trade name

# spelling from different languages and dyslexia are no problem
ab_atc("ceftriaxon")
ab_atc("cephtriaxone") # small spelling error
ab_atc("cephthriaxone") # or a bit more severe
ab_atc("seephthriaaksone") # and even this works

# use ab_* functions to get a specific properties (see ?ab_property);
# they use as.ab() internally:
ab_name("J01FA01")
ab_name("eryt")


if (require("dplyr")) {
  # you can quickly rename 'sir' columns using set_ab_names() with dplyr:
  example_isolates %>%
    set_ab_names(where(is.sir), property = "atc")
}

Description

Use this function to determine the antiviral drug code of one or more antiviral drugs. The data set antivirals will be searched for abbreviations, official names and synonyms (brand names).

Usage

as.av(x, flag_multiple_results = TRUE, info = interactive(), ...)

is.av(x)

Arguments

Details

All entries in the antivirals data set have three different identifiers: a human readable EARS-Net code (column ab, used by ECDC and WHONET), an ATC code (column atc, used by WHO), and a CID code (column cid, Compound ID, used by PubChem). The data set contains more than 5,000 official brand names from many different countries, as found in PubChem. Not that some drugs contain multiple ATC codes.

All these properties will be searched for the user input. The as.av() can correct for different forms of misspelling:

• Wrong spelling of drug names (such as "acyclovir"), which corrects for most audible similarities such as f/ph, x/ks, c/z/s, t/th, etc.

• Too few or too many vowels or consonants

• Switching two characters (such as "aycclovir", often the case in clinical data, when doctors typed too fast)

• Digitalised paper records, leaving artefacts like 0/o/O (zero and O's), B/8, n/r, etc.

Use the av_* functions to get properties based on the returned antiviral drug ID, see Examples.

Note: the as.av() and av_* functions may use very long regular expression to match brand names of antimicrobial drugs. This may fail on some systems.

Value

A character vector with additional class ab

Source

World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: https://atcddd.fhi.no/atc_ddd_index/

European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm

WHOCC

This package contains all ~550 antibiotic, antimycotic and antiviral drugs and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, https://atcddd.fhi.no) and the Pharmaceuticals Community Register of the European Commission (https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm).

These have become the gold standard for international drug utilisation monitoring and research.

The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.

NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package. See https://atcddd.fhi.no/copyright_disclaimer/.

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

See Also

• antivirals for the data.frame that is being used to determine ATCs

• av_from_text() for a function to retrieve antimicrobial drugs from clinical text (from health care records)

Examples

# these examples all return "ACI", the ID of aciclovir:
as.av("J05AB01")
as.av("J 05 AB 01")
as.av("Aciclovir")
as.av("aciclo")
as.av("   aciclo 123")
as.av("ACICL")
as.av("ACI")
as.av("Virorax") # trade name
as.av("Zovirax") # trade name

as.av("acyklofir") # severe spelling error, yet works

# use av_* functions to get a specific properties (see ?av_property);
# they use as.av() internally:
av_name("J05AB01")
av_name("acicl")

Description

This transforms a vector to a new class disk, which is a disk diffusion growth zone size (around an antibiotic disk) in millimetres between 6 and 50.

Usage

as.disk(x, na.rm = FALSE)

NA_disk_

is.disk(x)

Arguments

Format

An object of class disk (inherits from integer) of length 1.

Details

Interpret disk values as SIR values with as.sir(). It supports guidelines from EUCAST and CLSI.

Disk diffusion growth zone sizes must be between 6 and 50 millimetres. Values higher than 50 but lower than 100 will be maximised to 50. All others input values outside the 6-50 range will return NA.

NA_disk_ is a missing value of the new disk class.

Value

An integer with additional class disk

See Also

as.sir()

Examples

# transform existing disk zones to the `disk` class (using base R)
df <- data.frame(
  microorganism = "Escherichia coli",
  AMP = 20,
  CIP = 14,
  GEN = 18,
  TOB = 16
)
df[, 2:5] <- lapply(df[, 2:5], as.disk)
str(df)


# transforming is easier with dplyr:
if (require("dplyr")) {
  df %>% mutate(across(AMP:TOB, as.disk))
}


# interpret disk values, see ?as.sir
as.sir(
  x = as.disk(18),
  mo = "Strep pneu", # `mo` will be coerced with as.mo()
  ab = "ampicillin", # and `ab` with as.ab()
  guideline = "EUCAST"
)

# interpret whole data set, pretend to be all from urinary tract infections:
as.sir(df, uti = TRUE)

Description

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

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)

## S3 method for class 'mic'
droplevels(x, as.mic = FALSE, ...)

Arguments

Details

To interpret MIC values as SIR values, use 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 factor with valid MIC values as factor 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 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 are implemented for the MIC class (such as !, !=, <, >=, exp(), log2()). Some functions of the stats package are also implemented (such as quantile(), median(), fivenum()). Since sd() and var() are non-generic functions, these could not be extended. Use mad() as an alternative, or use e.g. sd(as.numeric(x)) where x is your vector of MIC values.

Using as.double() or as.numeric() on MIC values will remove the operators and return a numeric vector. Do not use as.integer() on MIC values as by the R convention on factors, it will return the index of the factor levels (which is often useless for regular users).

Use droplevels() 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() 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_.

Value

Ordered factor with additional class mic, that in mathematical operations acts as a numeric vector. Bear in mind that the outcome of any mathematical operation on MICs will return a numeric value.

See Also

as.sir()

Examples

mic_data <- as.mic(c(">=32", "1.0", "1", "1.00", 8, "<=0.128", "8", "16", "16"))
mic_data
is.mic(mic_data)

# this can also coerce combined MIC/SIR values:
as.mic("<=0.002; S")

# mathematical processing treats MICs as numeric values
fivenum(mic_data)
quantile(mic_data)
all(mic_data < 512)

# rescale MICs using rescale_mic()
rescale_mic(mic_data, mic_range = c(4, 16))

# interpret MIC values
as.sir(
  x = as.mic(2),
  mo = as.mo("Streptococcus pneumoniae"),
  ab = "AMX",
  guideline = "EUCAST"
)
as.sir(
  x = as.mic(c(0.01, 2, 4, 8)),
  mo = as.mo("Streptococcus pneumoniae"),
  ab = "AMX",
  guideline = "EUCAST"
)

# 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
}

Description

Use this function to get a valid microorganism code (mo) based on arbitrary user input. Determination is done using intelligent rules and the complete taxonomic tree of the kingdoms Animalia, Archaea, Bacteria, Chromista, and Protozoa, and most microbial species from the kingdom Fungi (see Source). The input can be almost anything: a full name (like "Staphylococcus aureus"), an abbreviated name (such as "S. aureus"), an abbreviation known in the field (such as "MRSA"), or just a genus. See Examples.

Usage

as.mo(
  x,
  Becker = FALSE,
  Lancefield = FALSE,
  minimum_matching_score = NULL,
  keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
  reference_df = get_mo_source(),
  ignore_pattern = getOption("AMR_ignore_pattern", NULL),
  cleaning_regex = getOption("AMR_cleaning_regex", mo_cleaning_regex()),
  only_fungi = getOption("AMR_only_fungi", FALSE),
  language = get_AMR_locale(),
  info = interactive(),
  ...
)

is.mo(x)

mo_uncertainties()

mo_renamed()

mo_failures()

mo_reset_session()

mo_cleaning_regex()

Arguments

Details

A microorganism (MO) code from this package (class: mo) is human-readable and typically looks like these examples:

  Code               Full name
  ---------------    --------------------------------------
  B_KLBSL            Klebsiella
  B_KLBSL_PNMN       Klebsiella pneumoniae
  B_KLBSL_PNMN_RHNS  Klebsiella pneumoniae rhinoscleromatis
  |   |    |    |
  |   |    |    |
  |   |    |    \---> subspecies, a 3-5 letter acronym
  |   |    \----> species, a 3-6 letter acronym
  |   \----> genus, a 4-8 letter acronym
  \----> kingdom: A (Archaea), AN (Animalia), B (Bacteria),
                  C (Chromista), F (Fungi), PL (Plantae),
                  P (Protozoa)

Values that cannot be coerced will be considered 'unknown' and will return the MO code UNKNOWN with a warning.

Use the mo_* functions to get properties based on the returned code, see Examples.

The as.mo() function uses a novel and scientifically validated (doi:10.18637/jss.v104.i03) matching score algorithm (see Matching Score for Microorganisms below) to match input against the available microbial taxonomy in this package. This implicates that e.g. "E. coli" (a microorganism highly prevalent in humans) will return the microbial ID of Escherichia coli and not Entamoeba coli (a microorganism less prevalent in humans), although the latter would alphabetically come first.

Coping with Uncertain Results

Results of non-exact taxonomic input are based on their matching score. The lowest allowed score can be set with the minimum_matching_score argument. At default this will be determined based on the character length of the input, the taxonomic kingdom, and the human pathogenicity of the taxonomic outcome. If values are matched with uncertainty, a message will be shown to suggest the user to inspect the results with mo_uncertainties(), which returns a data.frame with all specifications.

To increase the quality of matching, the cleaning_regex argument is used to clean the input. This must be a regular expression that matches parts of the input that should be removed before the input is matched against the available microbial taxonomy. It will be matched Perl-compatible and case-insensitive. The default value of cleaning_regex is the outcome of the helper function mo_cleaning_regex().

There are three helper functions that can be run after using the as.mo() function:

• Use mo_uncertainties() to get a data.frame that prints in a pretty format with all taxonomic names that were guessed. The output contains the matching score for all matches (see Matching Score for Microorganisms below).

• Use mo_failures() to get a character vector with all values that could not be coerced to a valid value.

• Use mo_renamed() to get a data.frame with all values that could be coerced based on old, previously accepted taxonomic names.

For Mycologists

The matching score algorithm gives precedence to bacteria over fungi. If you are only analysing fungi, be sure to use only_fungi = TRUE, or better yet, add this to your code and run it once every session:

options(AMR_only_fungi = TRUE)

This will make sure that no bacteria or other 'non-fungi' will be returned by as.mo(), or any of the mo_* functions.

Coagulase-negative and Coagulase-positive Staphylococci

With Becker = TRUE, the following staphylococci will be converted to their corresponding coagulase group:

• Coagulase-negative: S. americanisciuri, S. argensis, S. arlettae, S. auricularis, S. borealis, S. brunensis, S. caeli, S. caledonicus, S. canis, S. capitis, S. capitis capitis, S. capitis urealyticus, S. capitis ureolyticus, S. caprae, S. carnosus, S. carnosus carnosus, S. carnosus utilis, S. casei, S. caseolyticus, S. chromogenes, S. cohnii, S. cohnii cohnii, S. cohnii urealyticum, S. cohnii urealyticus, S. condimenti, S. croceilyticus, S. debuckii, S. devriesei, S. durrellii, S. edaphicus, S. epidermidis, S. equorum, S. equorum equorum, S. equorum linens, S. felis, S. fleurettii, S. gallinarum, S. haemolyticus, S. hominis, S. hominis hominis, S. hominis novobiosepticus, S. jettensis, S. kloosii, S. lentus, S. lloydii, S. lugdunensis, S. marylandisciuri, S. massiliensis, S. microti, S. muscae, S. nepalensis, S. pasteuri, S. petrasii, S. petrasii croceilyticus, S. petrasii jettensis, S. petrasii petrasii, S. petrasii pragensis, S. pettenkoferi, S. piscifermentans, S. pragensis, S. pseudoxylosus, S. pulvereri, S. ratti, S. rostri, S. saccharolyticus, S. saprophyticus, S. saprophyticus bovis, S. saprophyticus saprophyticus, S. schleiferi, S. schleiferi schleiferi, S. sciuri, S. sciuri carnaticus, S. sciuri lentus, S. sciuri rodentium, S. sciuri sciuri, S. shinii, S. simulans, S. stepanovicii, S. succinus, S. succinus casei, S. succinus succinus, S. taiwanensis, S. urealyticus, S. ureilyticus, S. veratri, S. vitulinus, S. vitulus, S. warneri, and S. xylosus

• Coagulase-positive: S. agnetis, S. argenteus, S. coagulans, S. cornubiensis, S. delphini, S. hyicus, S. hyicus chromogenes, S. hyicus hyicus, S. intermedius, S. lutrae, S. pseudintermedius, S. roterodami, S. schleiferi coagulans, S. schweitzeri, S. simiae, and S. singaporensis

This is based on:

• Becker K et al. (2014). Coagulase-Negative Staphylococci. Clin Microbiol Rev. 27(4): 870-926; doi:10.1128/CMR.00109-13

• Becker K et al. (2019). Implications of identifying the recently defined members of the S. aureus complex, S. argenteus and S. schweitzeri: A position paper of members of the ESCMID Study Group for staphylococci and Staphylococcal Diseases (ESGS). Clin Microbiol Infect; doi:10.1016/j.cmi.2019.02.028

• Becker K et al. (2020). Emergence of coagulase-negative staphylococci. Expert Rev Anti Infect Ther. 18(4):349-366; doi:10.1080/14787210.2020.1730813

For newly named staphylococcal species, such as S. brunensis (2024) and S. shinii (2023), we looked up the scientific reference to make sure the species are considered for the correct coagulase group.

Lancefield Groups in Streptococci

With Lancefield = TRUE, the following streptococci will be converted to their corresponding Lancefield group:

• Streptococcus Group A: S. pyogenes

• Streptococcus Group B: S. agalactiae

• Streptococcus Group C: S. dysgalactiae, S. dysgalactiae dysgalactiae, S. dysgalactiae equisimilis, S. equi, S. equi equi, S. equi ruminatorum, and S. equi zooepidemicus

• Streptococcus Group F: S. anginosus, S. anginosus anginosus, S. anginosus whileyi, S. constellatus, S. constellatus constellatus, S. constellatus pharyngis, S. constellatus viborgensis, and S. intermedius

• Streptococcus Group G: S. canis, S. dysgalactiae, S. dysgalactiae dysgalactiae, and S. dysgalactiae equisimilis

• Streptococcus Group H: S. sanguinis

• Streptococcus Group K: S. salivarius, S. salivarius salivarius, and S. salivarius thermophilus

• Streptococcus Group L: S. dysgalactiae, S. dysgalactiae dysgalactiae, and S. dysgalactiae equisimilis

This is based on:

• Lancefield RC (1933). A serological differentiation of human and other groups of hemolytic streptococci. J Exp Med. 57(4): 571-95; doi:10.1084/jem.57.4.571

Value

A character vector with additional class mo

Source

• Berends MS et al. (2022). AMR: An R Package for Working with Antimicrobial Resistance Data. Journal of Statistical Software, 104(3), 1-31; doi:10.18637/jss.v104.i03

• Parte, AC et al. (2020). List of Prokaryotic names with Standing in Nomenclature (LPSN) moves to the DSMZ. International Journal of Systematic and Evolutionary Microbiology, 70, 5607-5612; doi:10.1099/ijsem.0.004332. Accessed from https://lpsn.dsmz.de on June 24th, 2024.

• Vincent, R et al (2013). MycoBank gearing up for new horizons. IMA Fungus, 4(2), 371-9; doi:10.5598/imafungus.2013.04.02.16. Accessed from https://www.mycobank.org on June 24th, 2024.

• GBIF Secretariat (2023). GBIF Backbone Taxonomy. Checklist dataset doi:10.15468/39omei. Accessed from https://www.gbif.org on June 24th, 2024.

• Reimer, LC et al. (2022). BacDive in 2022: the knowledge base for standardized bacterial and archaeal data. Nucleic Acids Res., 50(D1):D741-D74; doi:10.1093/nar/gkab961. Accessed from https://bacdive.dsmz.de on July 16th, 2024.

• Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS). US Edition of SNOMED CT from 1 September 2020. Value Set Name 'Microorganism', OID 2.16.840.1.114222.4.11.1009 (v12). URL: https://phinvads.cdc.gov

• Bartlett A et al. (2022). A comprehensive list of bacterial pathogens infecting humans Microbiology 168:001269; doi:10.1099/mic.0.001269

Matching Score for Microorganisms

With ambiguous user input in as.mo() and all the mo_* functions, the returned results are chosen based on their matching score using mo_matching_score(). This matching score $m$, is calculated as:

where:

• $x$ is the user input;

• $n$ is a taxonomic name (genus, species, and subspecies);

• $l_n$ is the length of $n$;

• $lev$ is the Levenshtein distance function (counting any insertion as 1, and any deletion or substitution as 2) that is needed to change $x$ into $n$;

• $p_n$ is the human pathogenic prevalence group of $n$, as described below;

• $k_n$ is the taxonomic kingdom of $n$, set as Bacteria = 1, Fungi = 1.25, Protozoa = 1.5, Archaea = 2, others = 3.

The grouping into human pathogenic prevalence $p$ is based on recent work from Bartlett et al. (2022, doi:10.1099/mic.0.001269) who extensively studied medical-scientific literature to categorise all bacterial species into these groups:

• Established, if a taxonomic species has infected at least three persons in three or more references. These records have prevalence = 1.0 in the microorganisms data set;

• Putative, if a taxonomic species has fewer than three known cases. These records have prevalence = 1.25 in the microorganisms data set.

Furthermore,

• Any genus present in the established list also has prevalence = 1.0 in the microorganisms data set;

• Any other genus present in the putative list has prevalence = 1.25 in the microorganisms data set;

• Any other species or subspecies of which the genus is present in the two aforementioned groups, has prevalence = 1.5 in the microorganisms data set;

• Any non-bacterial genus, species or subspecies of which the genus is present in the following list, has prevalence = 1.25 in the microorganisms data set: Absidia, Acanthamoeba, Acremonium, Aedes, Alternaria, Amoeba, Ancylostoma, Angiostrongylus, Anisakis, Anopheles, Apophysomyces, Arthroderma, Aspergillus, Aureobasidium, Basidiobolus, Beauveria, Blastocystis, Blastomyces, Candida, Capillaria, Chaetomium, Chrysonilia, Chrysosporium, Cladophialophora, Cladosporium, Conidiobolus, Contracaecum, Cordylobia, Cryptococcus, Curvularia, Demodex, Dermatobia, Dientamoeba, Diphyllobothrium, Dirofilaria, Echinostoma, Entamoeba, Enterobius, Exophiala, Exserohilum, Fasciola, Fonsecaea, Fusarium, Geotrichum, Giardia, Haloarcula, Halobacterium, Halococcus, Hansenula, Hendersonula, Heterophyes, Histomonas, Histoplasma, Hymenolepis, Hypomyces, Hysterothylacium, Kloeckera, Kluyveromyces, Kodamaea, Leishmania, Lichtheimia, Lodderomyces, Lomentospora, Malassezia, Malbranchea, Metagonimus, Meyerozyma, Microsporidium, Microsporum, Millerozyma, Mortierella, Mucor, Mycocentrospora, Necator, Nectria, Ochroconis, Oesophagostomum, Oidiodendron, Opisthorchis, Paecilomyces, Pediculus, Penicillium, Phlebotomus, Phoma, Pichia, Piedraia, Pithomyces, Pityrosporum, Pneumocystis, Pseudallescheria, Pseudoscopulariopsis, Pseudoterranova, Pulex, Rhizomucor, Rhizopus, Rhodotorula, Saccharomyces, Saprochaete, Sarcoptes, Scedosporium, Scolecobasidium, Scopulariopsis, Scytalidium, Spirometra, Sporobolomyces, Sporotrichum, Stachybotrys, Strongyloides, Syngamus, Taenia, Talaromyces, Toxocara, Trichinella, Trichobilharzia, Trichoderma, Trichomonas, Trichophyton, Trichosporon, Trichostrongylus, Trichuris, Tritirachium, Trombicula, Trypanosoma, Tunga, Verticillium, or Wuchereria;

• All other records have prevalence = 2.0 in the microorganisms data set.

When calculating the matching score, all characters in $x$ and $n$ are ignored that are other than A-Z, a-z, 0-9, spaces and parentheses.

All matches are sorted descending on their matching score and for all user input values, the top match will be returned. This will lead to the effect that e.g., "E. coli" will return the microbial ID of Escherichia coli ($m = 0.688$, a highly prevalent microorganism found in humans) and not Entamoeba coli ($m = 0.381$, a less prevalent microorganism in humans), although the latter would alphabetically come first.

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

See Also

microorganisms for the data.frame that is being used to determine ID's.

The mo_* functions (such as mo_genus(), mo_gramstain()) to get properties based on the returned code.

Examples

# These examples all return "B_STPHY_AURS", the ID of S. aureus:
as.mo(c(
  "sau", # WHONET code
  "stau",
  "STAU",
  "staaur",
  "S. aureus",
  "S aureus",
  "Sthafilokkockus aureus", # handles incorrect spelling
  "Staphylococcus aureus (MRSA)",
  "MRSA", # Methicillin Resistant S. aureus
  "VISA", # Vancomycin Intermediate S. aureus
  "VRSA", # Vancomycin Resistant S. aureus
  115329001 # SNOMED CT code
))

# Dyslexia is no problem - these all work:
as.mo(c(
  "Ureaplasma urealyticum",
  "Ureaplasma urealyticus",
  "Ureaplasmium urealytica",
  "Ureaplazma urealitycium"
))

# input will get cleaned up with the input given in the `cleaning_regex` argument,
# which defaults to `mo_cleaning_regex()`:
cat(mo_cleaning_regex(), "\n")

as.mo("Streptococcus group A")

as.mo("S. epidermidis") # will remain species: B_STPHY_EPDR
as.mo("S. epidermidis", Becker = TRUE) # will not remain species: B_STPHY_CONS

as.mo("S. pyogenes") # will remain species: B_STRPT_PYGN
as.mo("S. pyogenes", Lancefield = TRUE) # will not remain species: B_STRPT_GRPA

# All mo_* functions use as.mo() internally too (see ?mo_property):
mo_genus("E. coli")
mo_gramstain("ESCO")
mo_is_intrinsic_resistant("ESCCOL", ab = "vanco")

Description

Clean up existing SIR values, or interpret minimum inhibitory concentration (MIC) values and disk diffusion diameters according to EUCAST or CLSI. as.sir() transforms the input to a new class sir, which is an ordered factor containing the levels S, SDD, I, R, NI.

These breakpoints are currently implemented:

• For clinical microbiology: EUCAST 2011-2024 and CLSI 2011-2024;

• For veterinary microbiology: EUCAST 2021-2024 and CLSI 2019-2024;

• For ECOFFs (Epidemiological Cut-off Values): EUCAST 2020-2024 and CLSI 2022-2024.

All breakpoints used for interpretation are available in our clinical_breakpoints data set.

Usage

as.sir(x, ...)

NA_sir_

is.sir(x)

is_sir_eligible(x, threshold = 0.05)

## Default S3 method:
as.sir(
  x,
  S = "^(S|U)+$",
  I = "^(I)+$",
  R = "^(R)+$",
  NI = "^(N|NI|V)+$",
  SDD = "^(SDD|D|H)+$",
  ...
)

## S3 method for class 'mic'
as.sir(
  x,
  mo = NULL,
  ab = deparse(substitute(x)),
  guideline = getOption("AMR_guideline", "EUCAST"),
  uti = NULL,
  conserve_capped_values = FALSE,
  add_intrinsic_resistance = FALSE,
  reference_data = AMR::clinical_breakpoints,
  include_screening = getOption("AMR_include_screening", FALSE),
  include_PKPD = getOption("AMR_include_PKPD", TRUE),
  breakpoint_type = getOption("AMR_breakpoint_type", "human"),
  host = NULL,
  verbose = FALSE,
  ...
)

## S3 method for class 'disk'
as.sir(
  x,
  mo = NULL,
  ab = deparse(substitute(x)),
  guideline = getOption("AMR_guideline", "EUCAST"),
  uti = NULL,
  add_intrinsic_resistance = FALSE,
  reference_data = AMR::clinical_breakpoints,
  include_screening = getOption("AMR_include_screening", FALSE),
  include_PKPD = getOption("AMR_include_PKPD", TRUE),
  breakpoint_type = getOption("AMR_breakpoint_type", "human"),
  host = NULL,
  verbose = FALSE,
  ...
)

## S3 method for class 'data.frame'
as.sir(
  x,
  ...,
  col_mo = NULL,
  guideline = getOption("AMR_guideline", "EUCAST"),
  uti = NULL,
  conserve_capped_values = FALSE,
  add_intrinsic_resistance = FALSE,
  reference_data = AMR::clinical_breakpoints,
  include_screening = getOption("AMR_include_screening", FALSE),
  include_PKPD = getOption("AMR_include_PKPD", TRUE),
  breakpoint_type = getOption("AMR_breakpoint_type", "human"),
  host = NULL,
  verbose = FALSE
)

sir_interpretation_history(clean = FALSE)

Arguments

Details

Note: The clinical breakpoints in this package were validated through, and imported from, WHONET. The public use of this AMR package has been endorsed by both CLSI and EUCAST. See clinical_breakpoints for more information.

How it Works

The as.sir() function can work in four ways:

1. For cleaning raw / untransformed data. The data will be cleaned to only contain valid values, namely: S for susceptible, I for intermediate or 'susceptible, increased exposure', R for resistant, NI for non-interpretable, and SDD for susceptible dose-dependent. Each of these can be set using a regular expression. Furthermore, as.sir() will try its best to clean with some intelligence. For example, mixed values with SIR interpretations and MIC values such as "<0.25; S" will be coerced to "S". Combined interpretations for multiple test methods (as seen in laboratory records) such as "S; S" will be coerced to "S", but a value like "S; I" will return NA with a warning that the input is invalid.

2. For interpreting minimum inhibitory concentration (MIC) values according to EUCAST or CLSI. You must clean your MIC values first using as.mic(), that also gives your columns the new data class mic. Also, be sure to have a column with microorganism names or codes. It will be found automatically, but can be set manually using the mo argument.

   • Using dplyr, SIR interpretation can be done very easily with either:

     your_data %>% mutate_if(is.mic, as.sir)
     your_data %>% mutate(across(where(is.mic), as.sir))
     your_data %>% mutate_if(is.mic, as.sir, ab = "column_with_antibiotics", mo = "column_with_microorganisms")
     your_data %>% mutate_if(is.mic, as.sir, ab = c("cipro", "ampicillin", ...), mo = c("E. coli", "K. pneumoniae", ...))
     
     # for veterinary breakpoints, also set `host`:
     your_data %>% mutate_if(is.mic, as.sir, host = "column_with_animal_species", guideline = "CLSI")
     

   • Operators like "<=" will be stripped before interpretation. When using conserve_capped_values = TRUE, an MIC value of e.g. ">2" will always return "R", even if the breakpoint according to the chosen guideline is ">=4". This is to prevent that capped values from raw laboratory data would not be treated conservatively. The default behaviour (conserve_capped_values = FALSE) considers ">2" to be lower than ">=4" and might in this case return "S" or "I".

3. For interpreting disk diffusion diameters according to EUCAST or CLSI. You must clean your disk zones first using as.disk(), that also gives your columns the new data class disk. Also, be sure to have a column with microorganism names or codes. It will be found automatically, but can be set manually using the mo argument.

   • Using dplyr, SIR interpretation can be done very easily with either:

     your_data %>% mutate_if(is.disk, as.sir)
     your_data %>% mutate(across(where(is.disk), as.sir))
     your_data %>% mutate_if(is.disk, as.sir, ab = "column_with_antibiotics", mo = "column_with_microorganisms")
     your_data %>% mutate_if(is.disk, as.sir, ab = c("cipro", "ampicillin", ...), mo = c("E. coli", "K. pneumoniae", ...))
     
     # for veterinary breakpoints, also set `host`:
     your_data %>% mutate_if(is.disk, as.sir, host = "column_with_animal_species", guideline = "CLSI")
     

4. For interpreting a complete data set, with automatic determination of MIC values, disk diffusion diameters, microorganism names or codes, and antimicrobial test results. This is done very simply by running as.sir(your_data).

For points 2, 3 and 4: Use sir_interpretation_history() to retrieve a data.frame (or tibble if the tibble package is installed) with all results of the last as.sir() call.

Supported Guidelines

For interpreting MIC values as well as disk diffusion diameters, currently implemented guidelines are for clinical microbiology: EUCAST 2011-2024 and CLSI 2011-2024, and for veterinary microbiology: EUCAST 2021-2024 and CLSI 2019-2024.

Thus, the guideline argument must be set to e.g., "EUCAST 2024" or "CLSI 2024". By simply using "EUCAST" (the default) or "CLSI" as input, the latest included version of that guideline will automatically be selected. You can set your own data set using the reference_data argument. The guideline argument will then be ignored.

You can set the default guideline with the package option AMR_guideline (e.g. in your .Rprofile file), such as:

  options(AMR_guideline = "CLSI")
  options(AMR_guideline = "CLSI 2018")
  options(AMR_guideline = "EUCAST 2020")
  # or to reset:
  options(AMR_guideline = NULL)

For veterinary guidelines, these might be the best options:

  options(AMR_guideline = "CLSI")
  options(AMR_breakpoint_type = "animal")

When applying veterinary breakpoints (by setting host or by setting breakpoint_type = "animal"), the CLSI VET09 guideline will be applied to cope with missing animal species-specific breakpoints.

After Interpretation

After using as.sir(), you can use the eucast_rules() defined by EUCAST to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism.

To determine which isolates are multi-drug resistant, be sure to run mdro() (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about interpreting multidrug-resistant organisms here.

Machine-Readable Clinical Breakpoints

The repository of this package contains a machine-readable version of all guidelines. This is a CSV file consisting of 34 063 rows and 14 columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. This allows for easy implementation of these rules in laboratory information systems (LIS). Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed.

Other

The function is.sir() detects if the input contains class sir. If the input is a data.frame, it iterates over all columns and returns a logical vector.

The base R function as.double() can be used to retrieve quantitative values from a sir object: "S" = 1, "I"/"SDD" = 2, "R" = 3. All other values are rendered NA . Note: Do not use as.integer(), since that (because of how R works internally) will return the factor level indices, and not these aforementioned quantitative values.

The function is_sir_eligible() returns TRUE when a column contains at most 5% invalid antimicrobial interpretations (not S and/or I and/or R and/or NI and/or SDD), and FALSE otherwise. The threshold of 5% can be set with the threshold argument. If the input is a data.frame, it iterates over all columns and returns a logical vector.

NA_sir_ is a missing value of the new sir class, analogous to e.g. base R's NA_character_.

Value

Ordered factor with new class sir

Interpretation of SIR

In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (https://www.eucast.org/newsiandr):

• S - Susceptible, standard dosing regimen
  A microorganism is categorised as "Susceptible, standard dosing regimen", when there is a high likelihood of therapeutic success using a standard dosing regimen of the agent.

• I - Susceptible, increased exposure
  A microorganism is categorised as "Susceptible, Increased exposure" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.

• R = Resistant
  A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.

  • Exposure is a function of how the mode of administration, dose, dosing interval, infusion time, as well as distribution and excretion of the antimicrobial agent will influence the infecting organism at the site of infection.

This AMR package honours this insight. Use susceptibility() (equal to proportion_SI()) to determine antimicrobial susceptibility and count_susceptible() (equal to count_SI()) to count susceptible isolates.

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

Source

For interpretations of minimum inhibitory concentration (MIC) values and disk diffusion diameters:

• CLSI M39: Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 2011-2024, Clinical and Laboratory Standards Institute (CLSI). https://clsi.org/standards/products/microbiology/documents/m39/.

• CLSI M100: Performance Standard for Antimicrobial Susceptibility Testing, 2011-2024, Clinical and Laboratory Standards Institute (CLSI). https://clsi.org/standards/products/microbiology/documents/m100/.

• CLSI VET01: Performance Standards for Antimicrobial Disk and Dilution Susceptibility Tests for Bacteria Isolated From Animals, 2019-2024, Clinical and Laboratory Standards Institute (CLSI). https://clsi.org/standards/products/veterinary-medicine/documents/vet01/.

• CLSI VET09: Understanding Susceptibility Test Data as a Component of Antimicrobial Stewardship in Veterinary Settings, 2019-2024, Clinical and Laboratory Standards Institute (CLSI). https://clsi.org/standards/products/veterinary-medicine/documents/vet09/.

• EUCAST Breakpoint tables for interpretation of MICs and zone diameters, 2011-2024, European Committee on Antimicrobial Susceptibility Testing (EUCAST). https://www.eucast.org/clinical_breakpoints.

• WHONET as a source for machine-reading the clinical breakpoints (read more here), 1989-2024, WHO Collaborating Centre for Surveillance of Antimicrobial Resistance. https://whonet.org/.

See Also

as.mic(), as.disk(), as.mo()

Examples

example_isolates
summary(example_isolates) # see all SIR results at a glance

# For INTERPRETING disk diffusion and MIC values -----------------------

# example data sets, with combined MIC values and disk zones
df_wide <- data.frame(
  microorganism = "Escherichia coli",
  amoxicillin = as.mic(8),
  cipro = as.mic(0.256),
  tobra = as.disk(16),
  genta = as.disk(18),
  ERY = "R"
)
df_long <- data.frame(
  bacteria = rep("Escherichia coli", 4),
  antibiotic = c("amoxicillin", "cipro", "tobra", "genta"),
  mics = as.mic(c(0.01, 1, 4, 8)),
  disks = as.disk(c(6, 10, 14, 18))
)


## Using dplyr -------------------------------------------------
if (require("dplyr")) {
  # approaches that all work without additional arguments:
  df_wide %>% mutate_if(is.mic, as.sir)
  df_wide %>% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir)
  df_wide %>% mutate(across(where(is.mic), as.sir))
  df_wide %>% mutate_at(vars(amoxicillin:tobra), as.sir)
  df_wide %>% mutate(across(amoxicillin:tobra, as.sir))
  
  # approaches that all work with additional arguments:
  df_long %>%
    # given a certain data type, e.g. MIC values
    mutate_if(is.mic, as.sir,
              mo = "bacteria",
              ab = "antibiotic",
              guideline = "CLSI")
  df_long %>%
    mutate(across(where(is.mic),
                  function(x) as.sir(x,
                                     mo = "bacteria",
                                     ab = "antibiotic",
                                     guideline = "CLSI")))
  df_wide %>%
    # given certain columns, e.g. from 'cipro' to 'genta'
    mutate_at(vars(cipro:genta), as.sir,
              mo = "bacteria",
              guideline = "CLSI")
  df_wide %>%
    mutate(across(cipro:genta,
                       function(x) as.sir(x,
                                          mo = "bacteria",
                                          guideline = "CLSI")))
                       
  # for veterinary breakpoints, add 'host':
  df_long$animal_species <- c("cats", "dogs", "horses", "cattle")
  df_long %>%
    # given a certain data type, e.g. MIC values
    mutate_if(is.mic, as.sir,
              mo = "bacteria",
              ab = "antibiotic",
              host = "animal_species",
              guideline = "CLSI")
  df_long %>%
    mutate(across(where(is.mic),
                  function(x) as.sir(x,
                                     mo = "bacteria",
                                     ab = "antibiotic",
                                     host = "animal_species",
                                     guideline = "CLSI")))
  df_wide %>%
    mutate_at(vars(cipro:genta), as.sir,
              mo = "bacteria",
              ab = "antibiotic",
              host = "animal_species",
              guideline = "CLSI")
  df_wide %>%
    mutate(across(cipro:genta,
                       function(x) as.sir(x,
                                          mo = "bacteria",
                                          host = "animal_species",
                                          guideline = "CLSI")))
  
  # to include information about urinary tract infections (UTI)
  data.frame(mo = "E. coli",
             nitrofuratoin = c("<= 2", 32),
             from_the_bladder = c(TRUE, FALSE)) %>%
    as.sir(uti = "from_the_bladder")

  data.frame(mo = "E. coli",
             nitrofuratoin = c("<= 2", 32),
             specimen = c("urine", "blood")) %>%
    as.sir() # automatically determines urine isolates

  df_wide %>%
    mutate_at(vars(cipro:genta), as.sir, mo = "E. coli", uti = TRUE)
}


## Using base R ------------------------------------------------

as.sir(df_wide)

# return a 'logbook' about the results:
sir_interpretation_history()

# for single values
as.sir(
  x = as.mic(2),
  mo = as.mo("S. pneumoniae"),
  ab = "AMP",
  guideline = "EUCAST"
)

as.sir(
  x = as.disk(18),
  mo = "Strep pneu", # `mo` will be coerced with as.mo()
  ab = "ampicillin", # and `ab` with as.ab()
  guideline = "EUCAST"
)


# For CLEANING existing SIR values ------------------------------------

as.sir(c("S", "SDD", "I", "R", "NI", "A", "B", "C"))
as.sir("<= 0.002; S") # will return "S"
sir_data <- as.sir(c(rep("S", 474), rep("I", 36), rep("R", 370)))
is.sir(sir_data)
plot(sir_data) # for percentages
barplot(sir_data) # for frequencies

# as common in R, you can use as.integer() to return factor indices:
as.integer(as.sir(c("S", "SDD", "I", "R", "NI", NA)))
# but for computational use, as.double() will return 1 for S, 2 for I/SDD, and 3 for R:
as.double(as.sir(c("S", "SDD", "I", "R", "NI", NA)))

# the dplyr way
if (require("dplyr")) {
  example_isolates %>%
    mutate_at(vars(PEN:RIF), as.sir)
  # same:
  example_isolates %>%
    as.sir(PEN:RIF)

  # fastest way to transform all columns with already valid AMR results to class `sir`:
  example_isolates %>%
    mutate_if(is_sir_eligible, as.sir)

  # since dplyr 1.0.0, this can also be:
  # example_isolates %>%
  #   mutate(across(where(is_sir_eligible), as.sir))
}

Description

Gets data from the WHOCC website to determine properties of an Anatomical Therapeutic Chemical (ATC) (e.g. an antibiotic), such as the name, defined daily dose (DDD) or standard unit.

Usage

atc_online_property(
  atc_code,
  property,
  administration = "O",
  url = "https://atcddd.fhi.no/atc_ddd_index/?code=%s&showdescription=no",
  url_vet = "https://atcddd.fhi.no/atcvet/atcvet_index/?code=%s&showdescription=no"
)

atc_online_groups(atc_code, ...)

atc_online_ddd(atc_code, ...)

atc_online_ddd_units(atc_code, ...)

Arguments

Details

Options for argument administration:

• "Implant" = Implant

• "Inhal" = Inhalation

• "Instill" = Instillation

• "N" = nasal

• "O" = oral

• "P" = parenteral

• "R" = rectal

• "SL" = sublingual/buccal

• "TD" = transdermal

• "V" = vaginal

Abbreviations of return values when using property = "U" (unit):

• "g" = gram

• "mg" = milligram

• "mcg" = microgram

• "U" = unit

• "TU" = thousand units

• "MU" = million units

• "mmol" = millimole

• "ml" = millilitre (e.g. eyedrops)

N.B. This function requires an internet connection and only works if the following packages are installed: curl, rvest, xml2.

Source

https://atcddd.fhi.no/atc_ddd_alterations__cumulative/ddd_alterations/abbrevations/

Examples

if (requireNamespace("curl") && requireNamespace("rvest") && requireNamespace("xml2")) {
  # oral DDD (Defined Daily Dose) of amoxicillin
  atc_online_property("J01CA04", "DDD", "O")
  atc_online_ddd(ab_atc("amox"))

  # parenteral DDD (Defined Daily Dose) of amoxicillin
  atc_online_property("J01CA04", "DDD", "P")

  atc_online_property("J01CA04", property = "groups") # search hierarchical groups of amoxicillin
}

Description

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

Usage

av_from_text(
  text,
  type = c("drug", "dose", "administration"),
  collapse = NULL,
  translate_av = FALSE,
  thorough_search = NULL,
  info = interactive(),
  ...
)

Arguments

Details

This function is also internally used by as.av(), 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.av() function may use very long regular expression to match brand names of antiviral drugs. This may fail on some systems.

Argument type

At default, the function will search for antiviral drug names. All text elements will be searched for official names, ATC codes and brand names. As it uses as.av() 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.

Argument collapse

Without using collapse, this function will return a list. This can be convenient to use e.g. inside a mutate()):
df %>% mutate(avx = av_from_text(clinical_text))

The returned AV codes can be transformed to official names, groups, etc. with all av_* functions such as av_name() and av_group(), or by using the translate_av argument.

With using collapse, this function will return a character:
df %>% mutate(avx = av_from_text(clinical_text, collapse = "|"))

Value

A list, or a character if collapse is not NULL

Examples

av_from_text("28/03/2020 valaciclovir po tid")
av_from_text("28/03/2020 valaciclovir po tid", type = "admin")

Description

Use these functions to return a specific property of an antiviral drug from the antivirals data set. All input values will be evaluated internally with as.av().

Usage

av_name(x, language = get_AMR_locale(), tolower = FALSE, ...)

av_cid(x, ...)

av_synonyms(x, ...)

av_tradenames(x, ...)

av_group(x, language = get_AMR_locale(), ...)

av_atc(x, ...)

av_loinc(x, ...)

av_ddd(x, administration = "oral", ...)

av_ddd_units(x, administration = "oral", ...)

av_info(x, language = get_AMR_locale(), ...)

av_url(x, open = FALSE, ...)

av_property(x, property = "name", language = get_AMR_locale(), ...)

Arguments

Details

All output will be translated where possible.

The function av_url() will return the direct URL to the official WHO website. A warning will be returned if the required ATC code is not available.

Value

• An integer in case of av_cid()

• A named list in case of av_info() and multiple av_atc()/av_synonyms()/av_tradenames()

• A double in case of av_ddd()

• A character in all other cases

Source

World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: https://atcddd.fhi.no/atc_ddd_index/

European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm

Reference Data Publicly Available

All data sets in this AMR package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit our website for the download links. The actual files are of course available on our GitHub repository.

See Also

antivirals

Examples

# all properties:
av_name("ACI")
av_atc("ACI")
av_cid("ACI")
av_synonyms("ACI")
av_tradenames("ACI")
av_group("ACI")
av_url("ACI")

# lowercase transformation
av_name(x = c("ACI", "VALA"))
av_name(x = c("ACI", "VALA"), tolower = TRUE)

# defined daily doses (DDD)
av_ddd("ACI", "oral")
av_ddd_units("ACI", "oral")
av_ddd("ACI", "iv")
av_ddd_units("ACI", "iv")

av_info("ACI") # all properties as a list

# all av_* functions use as.av() internally, so you can go from 'any' to 'any':
av_atc("ACI")
av_group("J05AB01")
av_loinc("abacavir")
av_name("29113-8")
av_name(135398513)
av_name("J05AB01")

Description

Easy check for data availability of all columns in a data set. This makes it easy to get an idea of which antimicrobial combinations can be used for calculation with e.g. susceptibility() and resistance().

Usage

availability(tbl, width = NULL)

Arguments

Details

The function returns a data.frame with columns "resistant" and "visual_resistance". The values in that columns are calculated with resistance().

Value

data.frame with column names of tbl as row names

Examples

availability(example_isolates)

if (require("dplyr")) {
  example_isolates %>%
    filter(mo == as.mo("Escherichia coli")) %>%
    select_if(is.sir) %>%
    availability()
}

Description

Determine antimicrobial resistance (AMR) of all bug-drug combinations in your data set where at least 30 (default) isolates are available per species. Use format() on the result to prettify it to a publishable/printable format, see Examples.

Usage

bug_drug_combinations(x, col_mo = NULL, FUN = mo_shortname, ...)

## S3 method for class 'bug_drug_combinations'
format(
  x,
  translate_ab = "name (ab, atc)",
  language = get_AMR_locale(),
  minimum = 30,
  combine_SI = TRUE,
  add_ab_group = TRUE,
  remove_intrinsic_resistant = FALSE,
  decimal.mark = getOption("OutDec"),
  big.mark = ifelse(decimal.mark == ",", ".", ","),
  ...
)

Arguments

Details

The function format() calculates the resistance per bug-drug combination and returns a table ready for reporting/publishing. Use combine_SI = TRUE (default) to test R vs. S+I and combine_SI = FALSE to test R+I vs. S. This table can also directly be used in R Markdown / Quarto without the need for e.g. knitr::kable().

Value

The function bug_drug_combinations() returns a data.frame with columns "mo", "ab", "S", "SDD", "I", "R", and "total".

Examples

# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
example_isolates


x <- bug_drug_combinations(example_isolates)
head(x)
format(x, translate_ab = "name (atc)")

# Use FUN to change to transformation of microorganism codes
bug_drug_combinations(example_isolates,
  FUN = mo_gramstain
)

bug_drug_combinations(example_isolates,
  FUN = function(x) {
    ifelse(x == as.mo("Escherichia coli"),
      "E. coli",
      "Others"
    )
  }
)

Description

Data set containing clinical breakpoints to interpret MIC and disk diffusion to SIR values, according to international guidelines. This dataset contain breakpoints for humans, 7 different animal groups, and ECOFFs.

Currently available breakpoint guidelines for clinical microbiology are EUCAST 2011-2024 and CLSI 2011-2024.

Currently available breakpoint guidelines for veterinary microbiology are EUCAST 2021-2024 and CLSI 2019-2024.

Use as.sir() to transform MICs or disks measurements to SIR values.

Usage

clinical_breakpoints

Format

A tibble with 34 063 observations and 14 variables:

• guideline
  Name of the guideline

• type
  Breakpoint type, either "ECOFF", "animal", or "human"

• host
  Host of infectious agent. This is mostly useful for veterinary breakpoints and is either "ECOFF", "aquatic", "cats", "cattle", "dogs", "horse", "human", "poultry", or "swine"

• method
  Testing method, either "DISK" or "MIC"

• site
  Body site for which the breakpoint must be applied, e.g. "Oral" or "Respiratory"

• mo
  Microbial ID, see as.mo()

• rank_index
  Taxonomic rank index of mo from 1 (subspecies/infraspecies) to 5 (unknown microorganism)

• ab
  Antibiotic code as used by this package, EARS-Net and WHONET, see as.ab()

• ref_tbl
  Info about where the guideline rule can be found

• disk_dose
  Dose of the used disk diffusion method

• breakpoint_S
  Lowest MIC value or highest number of millimetres that leads to "S"

• breakpoint_R
  Highest MIC value or lowest number of millimetres that leads to "R"

• uti
  A logical value (TRUE/FALSE) to indicate whether the rule applies to a urinary tract infection (UTI)

• is_SDD
  A logical value (TRUE/FALSE) to indicate whether the intermediate range between "S" and "R" should be interpreted as "SDD", instead of "I". This currently applies to 24 breakpoints.

Details

Different types of breakpoints

Supported types of breakpoints are ECOFF, animal, and human. ECOFF (Epidemiological cut-off) values are used in antimicrobial susceptibility testing to differentiate between wild-type and non-wild-type strains of bacteria or fungi.

The default is "human", which can also be set with the package option AMR_breakpoint_type. Use as.sir(..., breakpoint_type = ...) to interpret raw data using a specific breakpoint type, e.g. as.sir(..., breakpoint_type = "ECOFF") to use ECOFFs.

Imported from WHONET

Clinical breakpoints in this package were validated through and imported from WHONET, a free desktop Windows application developed and supported by the WHO Collaborating Centre for Surveillance of Antimicrobial Resistance. More can be read on their website. The developers of WHONET and this AMR package have been in contact about sharing their work. We highly appreciate their great development on the WHONET software.

Response from CLSI and EUCAST

The CEO of CLSI and the chairman of EUCAST have endorsed the work and public use of this AMR package (and consequently the use of their breakpoints) in June 2023, when future development of distributing clinical breakpoints was discussed in a meeting between CLSI, EUCAST, WHO, developers of WHONET software, and developers of this AMR package.

Download

Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. Please visit our website for the download links. The actual files are of course available on our GitHub repository. They allow for machine reading EUCAST and CLSI guidelines, which is almost impossible with the MS Excel and PDF files distributed by EUCAST and CLSI, though initiatives have started to overcome these burdens.

NOTE: this AMR package (and the WHONET software as well) contains rather complex internal methods to apply the guidelines. For example, some breakpoints must be applied on certain species groups (which are in case of this package available through the microorganisms.groups data set). It is important that this is considered when using the breakpoints for own use.

See Also

intrinsic_resistant

Examples

clinical_breakpoints

Description

These functions can be used to count resistant/susceptible microbial isolates. All functions support quasiquotation with pipes, can be used in summarise() from the dplyr package and also support grouped variables, see Examples.

count_resistant() should be used to count resistant isolates, count_susceptible() should be used to count susceptible isolates.

Usage

count_resistant(..., only_all_tested = FALSE)

count_susceptible(..., only_all_tested = FALSE)

count_S(..., only_all_tested = FALSE)

count_SI(..., only_all_tested = FALSE)

count_I(..., only_all_tested = FALSE)

count_IR(..., only_all_tested = FALSE)

count_R(..., only_all_tested = FALSE)

count_all(..., only_all_tested = FALSE)

n_sir(..., only_all_tested = FALSE)

count_df(
  data,
  translate_ab = "name",
  language = get_AMR_locale(),
  combine_SI = TRUE
)

Arguments

Details

These functions are meant to count isolates. Use the resistance()/susceptibility() functions to calculate microbial resistance/susceptibility.

The function count_resistant() is equal to the function count_R(). The function count_susceptible() is equal to the function count_SI().

The function n_sir() is an alias of count_all(). They can be used to count all available isolates, i.e. where all input antibiotics have an available result (S, I or R). Their use is equal to n_distinct(). Their function is equal to count_susceptible(...) + count_resistant(...).

The function count_df() takes any variable from data that has an sir class (created with as.sir()) and counts the number of S's, I's and R's. It also supports grouped variables. The function sir_df() works exactly like count_df(), but adds the percentage of S, I and R.

Value

An integer

Interpretation of SIR

In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (https://www.eucast.org/newsiandr):

• S - Susceptible, standard dosing regimen
  A microorganism is categorised as "Susceptible, standard dosing regimen", when there is a high likelihood of therapeutic success using a standard dosing regimen of the agent.

• I - Susceptible, increased exposure
  A microorganism is categorised as "Susceptible, Increased exposure" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.

• R = Resistant
  A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.

  • Exposure is a function of how the mode of administration, dose, dosing interval, infusion time, as well as distribution and excretion of the antimicrobial agent will influence the infecting organism at the site of infection.

This AMR package honours this insight. Use susceptibility() (equal to proportion_SI()) to determine antimicrobial susceptibility and count_susceptible() (equal to count_SI()) to count susceptible isolates.

Combination Therapy

When using more than one variable for ... (= combination therapy), use only_all_tested to only count isolates that are tested for all antibiotics/variables that you test them for. See this example for two antibiotics, Drug A and Drug B, about how susceptibility() works to calculate the %SI:

--------------------------------------------------------------------
                    only_all_tested = FALSE  only_all_tested = TRUE
                    -----------------------  -----------------------
 Drug A    Drug B   include as  include as   include as  include as
                    numerator   denominator  numerator   denominator
--------  --------  ----------  -----------  ----------  -----------
 S or I    S or I       X            X            X            X
   R       S or I       X            X            X            X
  <NA>     S or I       X            X            -            -
 S or I      R          X            X            X            X
   R         R          -            X            -            X
  <NA>       R          -            -            -            -
 S or I     <NA>        X            X            -            -
   R        <NA>        -            -            -            -
  <NA>      <NA>        -            -            -            -
--------------------------------------------------------------------

Please note that, in combination therapies, for only_all_tested = TRUE applies that:

    count_S()    +   count_I()    +   count_R()    = count_all()
  proportion_S() + proportion_I() + proportion_R() = 1

and that, in combination therapies, for only_all_tested = FALSE applies that:

    count_S()    +   count_I()    +   count_R()    >= count_all()
  proportion_S() + proportion_I() + proportion_R() >= 1

Using only_all_tested has no impact when only using one antibiotic as input.

See Also

proportion_* to calculate microbial resistance and susceptibility.

Examples

# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.

# base R ------------------------------------------------------------
count_resistant(example_isolates$AMX) # counts "R"
count_susceptible(example_isolates$AMX) # counts "S" and "I"
count_all(example_isolates$AMX) # counts "S", "I" and "R"

# be more specific
count_S(example_isolates$AMX)
count_SI(example_isolates$AMX)
count_I(example_isolates$AMX)
count_IR(example_isolates$AMX)
count_R(example_isolates$AMX)

# Count all available isolates
count_all(example_isolates$AMX)
n_sir(example_isolates$AMX)

# n_sir() is an alias of count_all().
# Since it counts all available isolates, you can
# calculate back to count e.g. susceptible isolates.
# These results are the same:
count_susceptible(example_isolates$AMX)
susceptibility(example_isolates$AMX) * n_sir(example_isolates$AMX)

# dplyr -------------------------------------------------------------

if (require("dplyr")) {
  example_isolates %>%
    group_by(ward) %>%
    summarise(
      R = count_R(CIP),
      I = count_I(CIP),
      S = count_S(CIP),
      n1 = count_all(CIP), # the actual total; sum of all three
      n2 = n_sir(CIP), # same - analogous to n_distinct
      total = n()
    ) # NOT the number of tested isolates!

  # Number of available isolates for a whole antibiotic class
  # (i.e., in this data set columns GEN, TOB, AMK, KAN)
  example_isolates %>%
    group_by(ward) %>%
    summarise(across(aminoglycosides(), n_sir))

  # Count co-resistance between amoxicillin/clav acid and gentamicin,
  # so we can see that combination therapy does a lot more than mono therapy.
  # Please mind that `susceptibility()` calculates percentages right away instead.
  example_isolates %>% count_susceptible(AMC) # 1433
  example_isolates %>% count_all(AMC) # 1879

  example_isolates %>% count_susceptible(GEN) # 1399
  example_isolates %>% count_all(GEN) # 1855

  example_isolates %>% count_susceptible(AMC, GEN) # 1764
  example_isolates %>% count_all(AMC, GEN) # 1936

  # Get number of S+I vs. R immediately of selected columns
  example_isolates %>%
    select(AMX, CIP) %>%
    count_df(translate = FALSE)

  # It also supports grouping variables
  example_isolates %>%
    select(ward, AMX, CIP) %>%
    group_by(ward) %>%
    count_df(translate = FALSE)
}

Description

Define custom EUCAST rules for your organisation or specific analysis and use the output of this function in eucast_rules().

Usage

custom_eucast_rules(...)

Arguments

Details

Some organisations have their own adoption of EUCAST rules. This function can be used to define custom EUCAST rules to be used in the eucast_rules() function.

Value

A list containing the custom rules

How it works

Basics

If you are familiar with the case_when() function of the dplyr package, you will recognise the input method to set your own rules. Rules must be set using what R considers to be the 'formula notation'. The rule itself is written before the tilde (~) and the consequence of the rule is written after the tilde:

x <- custom_eucast_rules(TZP == "S" ~ aminopenicillins == "S",
                         TZP == "R" ~ aminopenicillins == "R")

These are two custom EUCAST rules: if TZP (piperacillin/tazobactam) is "S", all aminopenicillins (ampicillin and amoxicillin) must be made "S", and if TZP is "R", aminopenicillins must be made "R". These rules can also be printed to the console, so it is immediately clear how they work:

x
#> A set of custom EUCAST rules:
#>
#>   1. If TZP is "S" then set to  S :
#>      amoxicillin (AMX), ampicillin (AMP)
#>
#>   2. If TZP is "R" then set to  R :
#>      amoxicillin (AMX), ampicillin (AMP)

The rules (the part before the tilde, in above example TZP == "S" and TZP == "R") must be evaluable in your data set: it should be able to run as a filter in your data set without errors. This means for the above example that the column TZP must exist. We will create a sample data set and test the rules set:

df <- data.frame(mo = c("Escherichia coli", "Klebsiella pneumoniae"),
                 TZP = as.sir("R"),
                 ampi = as.sir("S"),
                 cipro = as.sir("S"))
df
#>                      mo TZP ampi cipro
#> 1      Escherichia coli   R    S     S
#> 2 Klebsiella pneumoniae   R    S     S

eucast_rules(df, rules = "custom", custom_rules = x, info = FALSE)
#>                      mo TZP ampi cipro
#> 1      Escherichia coli   R    R     S
#> 2 Klebsiella pneumoniae   R    R     S

Using taxonomic properties in rules

There is one exception in columns used for the rules: all column names of the microorganisms data set can also be used, but do not have to exist in the data set. These column names are: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "oxygen_tolerance", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "mycobank", "mycobank_parent", "mycobank_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence", and "snomed". Thus, this next example will work as well, despite the fact that the df data set does not contain a column genus:

y <- custom_eucast_rules(TZP == "S" & genus == "Klebsiella" ~ aminopenicillins == "S",
                         TZP == "R" & genus == "Klebsiella" ~ aminopenicillins == "R")

eucast_rules(df, rules = "custom", custom_rules = y, info = FALSE)
#>                      mo TZP ampi cipro
#> 1      Escherichia coli   R    S     S
#> 2 Klebsiella pneumoniae   R    R     S

Usage of multiple antibiotics and antibiotic group names

You can define antibiotic groups instead of single antibiotics for the rule consequence, which is the part after the tilde (~). In the examples above, the antibiotic group aminopenicillins includes both ampicillin and amoxicillin.

Rules can also be applied to multiple antibiotics and antibiotic groups simultaneously. Use the c() function to combine multiple antibiotics. For instance, the following example sets all aminopenicillins and ureidopenicillins to "R" if column TZP (piperacillin/tazobactam) is "R":

x <- custom_eucast_rules(TZP == "R" ~ c(aminopenicillins, ureidopenicillins) == "R")
x
#> A set of custom EUCAST rules:
#> 
#>   1. If TZP is "R" then set to "R":
#>      amoxicillin (AMX), ampicillin (AMP), azlocillin (AZL), mezlocillin (MEZ), piperacillin (PIP), piperacillin/tazobactam (TZP)

These 30 antibiotic groups are allowed in the rules (case-insensitive) and can be used in any combination:

• aminoglycosides
  (amikacin, amikacin/fosfomycin, apramycin, arbekacin, astromicin, bekanamycin, dibekacin, framycetin, gentamicin, gentamicin-high, habekacin, hygromycin, isepamicin, kanamycin, kanamycin-high, kanamycin/cephalexin, micronomicin, neomycin, netilmicin, pentisomicin, plazomicin, propikacin, ribostamycin, sisomicin, streptoduocin, streptomycin, streptomycin-high, tobramycin, and tobramycin-high)

• aminopenicillins
  (amoxicillin and ampicillin)

• antifungals
  (amorolfine, amphotericin B, amphotericin B-high, anidulafungin, butoconazole, caspofungin, ciclopirox, clotrimazole, econazole, fluconazole, flucytosine, fosfluconazole, griseofulvin, hachimycin, ibrexafungerp, isavuconazole, isoconazole, itraconazole, ketoconazole, manogepix, micafungin, miconazole, nystatin, oteseconazole, pimaricin, posaconazole, rezafungin, ribociclib, sulconazole, terbinafine, terconazole, and voriconazole)

• antimycobacterials
  (4-aminosalicylic acid, calcium aminosalicylate, capreomycin, clofazimine, delamanid, enviomycin, ethambutol, ethambutol/isoniazid, ethionamide, isoniazid, isoniazid/sulfamethoxazole/trimethoprim/pyridoxine, morinamide, p-aminosalicylic acid, pretomanid, protionamide, pyrazinamide, rifabutin, rifampicin, rifampicin/ethambutol/isoniazid, rifampicin/isoniazid, rifampicin/pyrazinamide/ethambutol/isoniazid, rifampicin/pyrazinamide/isoniazid, rifamycin, rifapentine, simvastatin/fenofibrate, sodium aminosalicylate, streptomycin/isoniazid, terizidone, thioacetazone, thioacetazone/isoniazid, tiocarlide, and viomycin)

• betalactams
  (amoxicillin, amoxicillin/clavulanic acid, amoxicillin/sulbactam, ampicillin, ampicillin/sulbactam, apalcillin, aspoxicillin, avibactam, azidocillin, azlocillin, aztreonam, aztreonam/avibactam, aztreonam/nacubactam, bacampicillin, benzathine benzylpenicillin, benzathine phenoxymethylpenicillin, benzylpenicillin, biapenem, carbenicillin, carindacillin, cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/nacubactam, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, ciclacillin, clometocillin, cloxacillin, dicloxacillin, doripenem, epicillin, ertapenem, flucloxacillin, hetacillin, imipenem, imipenem/EDTA, imipenem/relebactam, latamoxef, lenampicillin, loracarbef, mecillinam, meropenem, meropenem/nacubactam, meropenem/vaborbactam, metampicillin, meticillin, mezlocillin, mezlocillin/sulbactam, nacubactam, nafcillin, oxacillin, panipenem, penamecillin, penicillin/novobiocin, penicillin/sulbactam, pheneticillin, phenoxymethylpenicillin, piperacillin, piperacillin/sulbactam, piperacillin/tazobactam, piridicillin, pivampicillin, pivmecillinam, procaine benzylpenicillin, propicillin, razupenem, ritipenem, ritipenem acoxil, sarmoxicillin, sulbactam, sulbenicillin, sultamicillin, talampicillin, tazobactam, tebipenem, temocillin, ticarcillin, and ticarcillin/clavulanic acid)

• carbapenems
  (biapenem, doripenem, ertapenem, imipenem, imipenem/EDTA, imipenem/relebactam, meropenem, meropenem/nacubactam, meropenem/vaborbactam, panipenem, razupenem, ritipenem, ritipenem acoxil, and tebipenem)

• cephalosporins
  (cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, latamoxef, and loracarbef)

• cephalosporins_1st
  (cefacetrile, cefadroxil, cefalexin, cefaloridine, cefalotin, cefapirin, cefatrizine, cefazedone, cefazolin, cefroxadine, ceftezole, and cephradine)

• cephalosporins_2nd
  (cefaclor, cefamandole, cefmetazole, cefonicid, ceforanide, cefotetan, cefotiam, cefoxitin, cefoxitin screening, cefprozil, cefuroxime, cefuroxime axetil, and loracarbef)

• cephalosporins_3rd
  (cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefetamet, cefetamet pivoxil, cefixime, cefmenoxime, cefodizime, cefoperazone, cefoperazone/sulbactam, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotiam hexetil, cefovecin, cefpimizole, cefpiramide, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefsulodin, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, and latamoxef)

• cephalosporins_4th
  (cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetecol, cefoselis, cefozopran, cefpirome, and cefquinome)

• cephalosporins_5th
  (ceftaroline, ceftaroline/avibactam, ceftobiprole, ceftobiprole medocaril, and ceftolozane/tazobactam)

• cephalosporins_except_caz
  (cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, latamoxef, and loracarbef)

• fluoroquinolones
  (besifloxacin, ciprofloxacin, clinafloxacin, danofloxacin, delafloxacin, difloxacin, enoxacin, enrofloxacin, finafloxacin, fleroxacin, garenoxacin, gatifloxacin, gemifloxacin, grepafloxacin, lascufloxacin, levofloxacin, levonadifloxacin, lomefloxacin, marbofloxacin, metioxate, miloxacin, moxifloxacin, nadifloxacin, nifuroquine, norfloxacin, ofloxacin, orbifloxacin, pazufloxacin, pefloxacin, pradofloxacin, premafloxacin, prulifloxacin, rufloxacin, sarafloxacin, sitafloxacin, sparfloxacin, temafloxacin, tilbroquinol, tioxacin, tosufloxacin, and trovafloxacin)

• glycopeptides
  (avoparcin, dalbavancin, norvancomycin, oritavancin, ramoplanin, teicoplanin, teicoplanin-macromethod, telavancin, vancomycin, and vancomycin-macromethod)

• glycopeptides_except_lipo
  (avoparcin, norvancomycin, ramoplanin, teicoplanin, teicoplanin-macromethod, vancomycin, and vancomycin-macromethod)

• lincosamides
  (acetylmidecamycin, acetylspiramycin, clindamycin, clindamycin inducible screening, gamithromycin, kitasamycin, lincomycin, meleumycin, nafithromycin, pirlimycin, primycin, solithromycin, tildipirosin, tilmicosin, tulathromycin, tylosin, and tylvalosin)

• lipoglycopeptides
  (dalbavancin, oritavancin, and telavancin)

• macrolides
  (acetylmidecamycin, acetylspiramycin, azithromycin, clarithromycin, dirithromycin, erythromycin, flurithromycin, gamithromycin, josamycin, kitasamycin, meleumycin, midecamycin, miocamycin, nafithromycin, oleandomycin, pirlimycin, primycin, rokitamycin, roxithromycin, solithromycin, spiramycin, telithromycin, tildipirosin, tilmicosin, troleandomycin, tulathromycin, tylosin, and tylvalosin)

• nitrofurans
  (furazidin, furazolidone, nifurtoinol, nitrofurantoin, and nitrofurazone)

• oxazolidinones
  (cadazolid, cycloserine, linezolid, tedizolid, and thiacetazone)

• penicillins
  (amoxicillin, amoxicillin/clavulanic acid, amoxicillin/sulbactam, ampicillin, ampicillin/sulbactam, apalcillin, aspoxicillin, avibactam, azidocillin, azlocillin, aztreonam, aztreonam/avibactam, aztreonam/nacubactam, bacampicillin, benzathine benzylpenicillin, benzathine phenoxymethylpenicillin, benzylpenicillin, carbenicillin, carindacillin, cefepime/nacubactam, ciclacillin, clometocillin, cloxacillin, dicloxacillin, epicillin, flucloxacillin, hetacillin, lenampicillin, mecillinam, metampicillin, meticillin, mezlocillin, mezlocillin/sulbactam, nacubactam, nafcillin, oxacillin, penamecillin, penicillin/novobiocin, penicillin/sulbactam, pheneticillin, phenoxymethylpenicillin, piperacillin, piperacillin/sulbactam, piperacillin/tazobactam, piridicillin, pivampicillin, pivmecillinam, procaine benzylpenicillin, propicillin, sarmoxicillin, sulbactam, sulbenicillin, sultamicillin, talampicillin, tazobactam, temocillin, ticarcillin, and ticarcillin/clavulanic acid)

• polymyxins
  (colistin, polymyxin B, and polymyxin B/polysorbate 80)

• quinolones
  (besifloxacin, cinoxacin, ciprofloxacin, ciprofloxacin/metronidazole, ciprofloxacin/ornidazole, ciprofloxacin/tinidazole, clinafloxacin, danofloxacin, delafloxacin, difloxacin, enoxacin, enrofloxacin, finafloxacin, fleroxacin, flumequine, garenoxacin, gatifloxacin, gemifloxacin, grepafloxacin, lascufloxacin, levofloxacin, levonadifloxacin, lomefloxacin, marbofloxacin, metioxate, miloxacin, moxifloxacin, nadifloxacin, nalidixic acid, nemonoxacin, nifuroquine, nitroxoline, norfloxacin, ofloxacin, orbifloxacin, oxolinic acid, pazufloxacin, pefloxacin, pipemidic acid, piromidic acid, pradofloxacin, premafloxacin, prulifloxacin, rosoxacin, rufloxacin, sarafloxacin, sitafloxacin, sparfloxacin, temafloxacin, tilbroquinol, tioxacin, tosufloxacin, and trovafloxacin)

• rifamycins
  (rifabutin, rifampicin, rifampicin/ethambutol/isoniazid, rifampicin/isoniazid, rifampicin/pyrazinamide/ethambutol/isoniazid, rifampicin/pyrazinamide/isoniazid, rifamycin, and rifapentine)

• streptogramins
  (pristinamycin and quinupristin/dalfopristin)

• tetracyclines
  (cetocycline, chlortetracycline, clomocycline, demeclocycline, doxycycline, eravacycline, lymecycline, metacycline, minocycline, omadacycline, oxytetracycline, penimepicycline, rolitetracycline, sarecycline, tetracycline, and tigecycline)

• tetracyclines_except_tgc
  (cetocycline, chlortetracycline, clomocycline, demeclocycline, doxycycline, eravacycline, lymecycline, metacycline, minocycline, omadacycline, oxytetracycline, penimepicycline, rolitetracycline, sarecycline, and tetracycline)

• trimethoprims
  (brodimoprim, sulfadiazine, sulfadiazine/tetroxoprim, sulfadiazine/trimethoprim, sulfadimethoxine, sulfadimidine, sulfadimidine/trimethoprim, sulfafurazole, sulfaisodimidine, sulfalene, sulfamazone, sulfamerazine, sulfamerazine/trimethoprim, sulfamethizole, sulfamethoxazole, sulfamethoxypyridazine, sulfametomidine, sulfametoxydiazine, sulfametrole/trimethoprim, sulfamoxole, sulfamoxole/trimethoprim, sulfanilamide, sulfaperin, sulfaphenazole, sulfapyridine, sulfathiazole, sulfathiourea, trimethoprim, and trimethoprim/sulfamethoxazole)

• ureidopenicillins
  (azlocillin, mezlocillin, piperacillin, and piperacillin/tazobactam)

Examples

x <- custom_eucast_rules(
  AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
  AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I"
)
x

# run the custom rule set (verbose = TRUE will return a logbook instead of the data set):
eucast_rules(example_isolates,
  rules = "custom",
  custom_rules = x,
  info = FALSE,
  verbose = TRUE
)

# combine rule sets
x2 <- c(
  x,
  custom_eucast_rules(TZP == "R" ~ carbapenems == "R")
)
x2