AMR (for R)?(To find out how to conduct AMR analysis, please continue reading here to get started.)
+(To find out how to conduct AMR data analysis, please continue reading here to get started.)
AMR is a free, open-source and independent R package to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. Our aim is to provide a standard for clean and reproducible antimicrobial resistance data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting.
After installing this package, R knows ~70,000 distinct microbial species and all ~550 antibiotic, antimycotic and antiviral drugs by name and code (including ATC, EARS-NET, LOINC and SNOMED CT), and knows all about valid R/SI and MIC values. It supports any data format, including WHONET/EARS-Net data.
This package is fully independent of any other R package and works on Windows, macOS and Linux with all versions of R since R-3.0.0 (April 2013). It was designed to work in any setting, including those with very limited resources. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the University of Groningen, in collaboration with non-profit organisations Certe Medical Diagnostics and Advice and University Medical Center Groningen. This R package is actively maintained and is free software (see Copyright).
@@ -361,7 +361,7 @@ Since you are one of our users, we would like to know how you use the package anTo find out how to conduct AMR analysis, please continue reading here to get started or click the links in the ‘How to’ menu.
+To find out how to conduct AMR data analysis, please continue reading here to get started or click the links in the ‘How to’ menu.
example_isolates data set. This data set contains 2,000 microbial isolates with their full antibiograms. It reflects reality and can be used to practice AMR analysis.example_isolates data set. This data set contains 2,000 microbial isolates with their full antibiograms. It reflects reality and can be used to practice AMR data analysis.WHONET data set. This data set only contains fake data, but with the exact same structure as files exported by WHONET. Read more about WHONET on its tutorial page.NEWS.md
Functions that are applied to a data set containing antibiotic columns gained the argument only_rsi_columns, which defaults to TRUE if any of the columns are of class <rsi> (i.e., transformed with as.rsi()). This increases reliability of automatic determination of antibiotic columns (so only columns that are defined to be <rsi> will be affected).
This change might invalidate existing code. But since the new argument always returns FALSE when no <rsi> column can be found in the data, this chance is low.
Affected functions are:
+ab_class() and its wrappers, such as aminoglocysides(), carbapenems(), penicillins())filter_ab_class() and its wrappers, such as filter_aminoglocysides(), filter_carbapenems(), filter_penicillins())eucast_rules()mdro() (including wrappers such as brmo(), mrgn and eucast_exceptional_phenotypes())guess_ab_col()You can quickly transform all your eligible columns using either:
+ +Function isolate_identifier(), which will paste a microorganism code with all antimicrobial results of a data set into one string for each row. This is useful to compare isolates, e.g. between institutions or regions, when there is no genotyping available.
Function mo_is_yeast(), which determines whether a microorganism is a member of the taxonomic class Saccharomycetes or the taxonomic order Saccharomycetales:
+mo_kingdom(c("Aspergillus", "Candida")) #> [1] "Fungi" "Fungi" @@ -267,7 +292,7 @@ example_isolates[which(mo_is_yeast()), ] # base R example_isolates %>% filter(mo_is_yeast()) # dplyrThe
-mo_type()function has also been updated to reflect this change:@@ -315,7 +344,7 @@+mo_type(c("Aspergillus", "Candida")) # [1] "Fungi" "Yeasts" @@ -280,6 +305,8 @@Changed
+
- +
is.rsi()now returns a vector ofTRUE/FALSEwhen the input is a data set, in case it will iterate over all columns- Using functions without setting a data set (e.g.,
mo_is_gram_negative(),mo_is_gram_positive(),mo_is_intrinsic_resistant(),first_isolate(),mdro()) now work withdplyrsgroup_by()again- Updated the data set
@@ -287,12 +314,14 @@microorganisms.codes(which contains popular LIS and WHONET codes for microorganisms) for some species of Mycobacterium that previously incorrectly returned M. africanum- WHONET code
"PNV"will now correctly be interpreted asPHN, the antibiotic code for phenoxymethylpenicillin (‘peni V’)- Fix for verbose output of
mdro(..., verbose = TRUE)for German guideline (3MGRN and 4MGRN) and Dutch guideline (BRMO, only P. aeruginosa)- -
+is.rsi.eligible()now returnsFALSEimmediately if the input does not contain any of the values “R”, “S” or “I”. This drastically improves speed, also for a lot of other functions that rely on automatic determination of antibiotic columns.is.rsi.eligible()now detects if the column name resembles an antibiotic name or code and now returnsTRUEimmediately if the input contains any of the values “R”, “S” or “I”. This drastically improves speed, also for a lot of other functions that rely on automatic determination of antibiotic columns.- Functions
get_episode()andis_new_episode()now support less than a day as value for argumentepisode_days(e.g., to include one patient/test per hour)- Argument
ampc_cephalosporin_resistanceineucast_rules()now also applies to value “I” (not only “S”)- Updated colours of values R, S and I in tibble printing
- Functions
+print()andsummary()on a Principal Components Analysis object (pca()) now print additional group info if the original data was grouped usingdplyr::group_by()- Improved speed of
guess_ab_col()+@@ -300,7 +329,7 @@ Other
- Big documentation updates
-- Loading the package (i.e.,
+library(AMR)) now is ~50 times faster than before, in costs of package size (increased with ~3 MB)- Loading the package (i.e.,
library(AMR)) now is ~50 times faster than before, in costs of package size (which increased by ~3 MB)
Functions get_episode() and is_new_episode() to determine (patient) episodes which are not necessarily based on microorganisms. The get_episode() function returns the index number of the episode per group, while the is_new_episode() function returns values TRUE/FALSE to indicate whether an item in a vector is the start of a new episode. They also support dplyrs grouping (i.e. using group_by()):
+library(dplyr) example_isolates %>% @@ -369,7 +398,7 @@mdr_cmi2012(),- -
eucast_exceptional_phenotypes()+# to select first isolates that are Gram-negative # and view results of cephalosporins and aminoglycosides: @@ -381,7 +410,7 @@For antibiotic selection functions (such as
-cephalosporins(),aminoglycosides()) to select columns based on a certain antibiotic group, the dependency on thetidyselectpackage was removed, meaning that they can now also be used without the need to have this package installed and now also work in base R function calls (they rely on R 3.2 or later):+# above example in base R: example_isolates[which(first_isolate() & mo_is_gram_negative()), @@ -432,7 +461,7 @@Data set
intrinsic_resistant. This data set contains all bug-drug combinations where the ‘bug’ is intrinsic resistant to the ‘drug’ according to the latest EUCAST insights. It contains just two columns:microorganismandantibiotic.Curious about which enterococci are actually intrinsic resistant to vancomycin?
-+library(AMR) library(dplyr) @@ -455,7 +484,7 @@
Support for using
-dplyr’sacross()to interpret MIC values or disk zone diameters, which also automatically determines the column with microorganism names or codes.+# until dplyr 1.0.0 your_data %>% mutate_if(is.mic, as.rsi) @@ -473,7 +502,7 @@Added intelligent data cleaning to
-as.disk(), so numbers can also be extracted from text and decimal numbers will always be rounded up:+as.disk(c("disk zone: 23.4 mm", 23.4)) #> Class <disk> @@ -534,7 +563,7 @@Function
ab_from_text()to retrieve antimicrobial drug names, doses and forms of administration from clinical texts in e.g. health care records, which also corrects for misspelling since it usesas.ab()internallyTidyverse selection helpers for antibiotic classes, that help to select the columns of antibiotics that are of a specific antibiotic class, without the need to define the columns or antibiotic abbreviations. They can be used in any function that allows selection helpers, like
-dplyr::select()andtidyr::pivot_longer():+library(dplyr) @@ -610,9 +639,9 @@AMR 1.2.0 2020-05-28
-+-Breaking
+Breaking
Removed code dependency on all other R packages, making this package fully independent of the development process of others. This is a major code change, but will probably not be noticeable by most users.
@@ -723,7 +752,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Fixed important floating point error for some MIC comparisons in EUCAST 2020 guideline
Interpretation from MIC values (and disk zones) to R/SI can now be used with
-mutate_at()of thedplyrpackage:+yourdata %>% mutate_at(vars(antibiotic1:antibiotic25), as.rsi, mo = "E. coli") @@ -752,7 +781,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Support for LOINC codes in the
-antibioticsdata set. Useab_loinc()to retrieve LOINC codes, or use a LOINC code for input in anyab_*function:+ab_loinc("ampicillin") #> [1] "21066-6" "3355-5" "33562-0" "33919-2" "43883-8" "43884-6" "87604-5" @@ -763,7 +792,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Support for SNOMED CT codes in the
-microorganismsdata set. Usemo_snomed()to retrieve SNOMED codes, or use a SNOMED code for input in anymo_*function:+mo_snomed("S. aureus") #> [1] 115329001 3092008 113961008 @@ -820,19 +849,19 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/AMR 0.9.0 2019-11-29
-+-Breaking
+Breaking
- Adopted Adeolu et al. (2016), PMID 27620848 for the
microorganismsdata set, which means that the new order Enterobacterales now consists of a part of the existing family Enterobacteriaceae, but that this family has been split into other families as well (like Morganellaceae and Yersiniaceae). Although published in 2016, this information is not yet in the Catalogue of Life version of 2019. All MDRO determinations withmdro()will now use the Enterobacterales order for all guidelines before 2016 that were dependent on the Enterobacteriaceae family.
If you were dependent on the old Enterobacteriaceae family e.g. by using in your code:
-+if (mo_family(somebugs) == "Enterobacteriaceae") ...then please adjust this to:
-+@@ -846,7 +875,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/if (mo_order(somebugs) == "Enterobacterales") ...
Functions
-susceptibility()andresistance()as aliases ofproportion_SI()andproportion_R(), respectively. These functions were added to make it more clear that “I” should be considered susceptible and not resistant.+library(dplyr) example_isolates %>% @@ -875,7 +904,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/More intelligent way of coping with some consonants like “l” and “r”
Added a score (a certainty percentage) to
-mo_uncertainties(), that is calculated using the Levenshtein distance:+as.mo(c("Stafylococcus aureus", "staphylokok aureuz")) @@ -928,20 +957,20 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/AMR 0.8.0 2019-10-15
-+-Breaking
+Breaking
Determination of first isolates now excludes all ‘unknown’ microorganisms at default, i.e. microbial code
-"UNKNOWN". They can be included with the new argumentinclude_unknown:+first_isolate(..., include_unknown = TRUE)For WHONET users, this means that all records/isolates with organism code
"con"(contamination) will be excluded at default, sinceas.mo("con") = "UNKNOWN". The function always shows a note with the number of ‘unknown’ microorganisms that were included or excluded.For code consistency, classes
-abandmowill now be preserved in any subsetting or assignment. For the sake of data integrity, this means that invalid assignments will now result inNA:+# how it works in base R: x <- factor("A") @@ -966,7 +995,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Function
-bug_drug_combinations()to quickly get adata.framewith the results of all bug-drug combinations in a data set. The column containing microorganism codes is guessed automatically and its input is transformed withmo_shortname()at default:+x <- bug_drug_combinations(example_isolates) #> NOTE: Using column `mo` as input for `col_mo`. @@ -989,13 +1018,13 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/ #> 4 Gram-negative AMX 227 0 405 632 #> NOTE: Use 'format()' on this result to get a publicable/printable format.You can format this to a printable format, ready for reporting or exporting to e.g. Excel with the base R
-format()function:+format(x, combine_IR = FALSE)Additional way to calculate co-resistance, i.e. when using multiple antimicrobials as input for
-portion_*functions orcount_*functions. This can be used to determine the empiric susceptibility of a combination therapy. A new argumentonly_all_tested(which defaults toFALSE) replaces the oldalso_single_testedand can be used to select one of the two methods to count isolates and calculate portions. The difference can be seen in this example table (which is also on theportionandcounthelp pages), where the %SI is being determined:+# -------------------------------------------------------------------- # only_all_tested = FALSE only_all_tested = TRUE @@ -1017,7 +1046,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/-
tibbleprinting support for classesrsi,mic,disk,abmo. When usingtibbles containing antimicrobial columns, valuesSwill print in green, valuesIwill print in yellow and valuesRwill print in red. Microbial IDs (classmo) will emphasise on the genus and species, not on the kingdom.+# (run this on your own console, as this page does not support colour printing) library(dplyr) @@ -1100,7 +1129,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Function
-rsi_df()to transform adata.frameto a data set containing only the microbial interpretation (S, I, R), the antibiotic, the percentage of S/I/R and the number of available isolates. This is a convenient combination of the existing functionscount_df()andportion_df()to immediately show resistance percentages and number of available isolates:+septic_patients %>% select(AMX, CIP) %>% @@ -1127,7 +1156,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/- UPEC (Uropathogenic E. coli)
All these lead to the microbial ID of E. coli:
-+as.mo("UPEC") # B_ESCHR_COL @@ -1232,7 +1261,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/when all values are unique it now shows a message instead of a warning
support for boxplots:
-+septic_patients %>% freq(age) %>% @@ -1294,7 +1323,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/We’ve got a new website: https://msberends.gitlab.io/AMR (built with the great
pkgdown)
- Contains the complete manual of this package and all of its functions with an explanation of their arguments
-- Contains a comprehensive tutorial about how to conduct antimicrobial resistance analysis, import data from WHONET or SPSS and many more.
+- Contains a comprehensive tutorial about how to conduct AMR data analysis, import data from WHONET or SPSS and many more.
@@ -1327,7 +1356,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
New filters for antimicrobial classes. Use these functions to filter isolates on results in one of more antibiotics from a specific class:
-+filter_aminoglycosides() filter_carbapenems() @@ -1341,7 +1370,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/ filter_macrolides() filter_tetracyclines()The
-antibioticsdata set will be searched, after which the input data will be checked for column names with a value in any abbreviations, codes or official names found in theantibioticsdata set. For example:+septic_patients %>% filter_glycopeptides(result = "R") # Filtering on glycopeptide antibacterials: any of `vanc` or `teic` is R @@ -1350,7 +1379,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/All
-ab_*functions are deprecated and replaced byatc_*functions:+ab_property -> atc_property() ab_name -> atc_name() @@ -1368,10 +1397,10 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/New function
mo_uncertainties()to review values that could be coerced to a valid MO code usingas.mo(), but with uncertainty.New function
mo_renamed()to get a list of all returned values fromas.mo()that have had taxonomic renaming- -
New function
age()to calculate the (patients) age in years- +
New function
age_groups()to split ages into custom or predefined groups (like children or elderly). This allows for easier demographic antimicrobial resistance analysis per age group.New function
age_groups()to split ages into custom or predefined groups (like children or elderly). This allows for easier demographic AMR data analysis per age group.New function
-ggplot_rsi_predict()as well as the base Rplot()function can now be used for resistance prediction calculated withresistance_predict():+x <- resistance_predict(septic_patients, col_ab = "amox") plot(x) @@ -1379,13 +1408,13 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Functions
-filter_first_isolate()andfilter_first_weighted_isolate()to shorten and fasten filtering on data sets with antimicrobial results, e.g.:+septic_patients %>% filter_first_isolate(...) # or filter_first_isolate(septic_patients, ...)is equal to:
-+septic_patients %>% mutate(only_firsts = first_isolate(septic_patients, ...)) %>% @@ -1418,7 +1447,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Now handles incorrect spelling, like
-iinstead ofyandfinstead ofph:+# mo_fullname() uses as.mo() internally @@ -1430,7 +1459,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Uncertainty of the algorithm is now divided into four levels, 0 to 3, where the default
-allow_uncertain = TRUEis equal to uncertainty level 2. Run?as.mofor more info about these levels.+# equal: as.mo(..., allow_uncertain = TRUE) @@ -1445,7 +1474,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/All microbial IDs that found are now saved to a local file
~/.Rhistory_mo. Use the new functionclean_mo_history()to delete this file, which resets the algorithms.Incoercible results will now be considered ‘unknown’, MO code
-UNKNOWN. On foreign systems, properties of these will be translated to all languages already previously supported: German, Dutch, French, Italian, Spanish and Portuguese:+mo_genus("qwerty", language = "es") # Warning: @@ -1495,7 +1524,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Support for tidyverse quasiquotation! Now you can create frequency tables of function outcomes:
-+# Determine genus of microorganisms (mo) in `septic_patients` data set: # OLD WAY @@ -1579,7 +1608,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Fewer than 3 characters as input for
as.mowill return NAFunction
-as.mo(and allmo_*wrappers) now supports genus abbreviations with “species” attached+as.mo("E. species") # B_ESCHR mo_fullname("E. spp.") # "Escherichia species" @@ -1596,7 +1625,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
Support for grouping variables, test with:
-+septic_patients %>% group_by(hospital_id) %>% @@ -1604,7 +1633,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Support for (un)selecting columns:
-+septic_patients %>% freq(hospital_id) %>% @@ -1684,7 +1713,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/They also come with support for German, Dutch, French, Italian, Spanish and Portuguese:
-+mo_gramstain("E. coli") # [1] "Gram negative" @@ -1695,7 +1724,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/ mo_fullname("S. group A", language = "pt") # Portuguese # [1] "Streptococcus grupo A"Furthermore, former taxonomic names will give a note about the current taxonomic name:
-+mo_gramstain("Esc blattae") # Note: 'Escherichia blattae' (Burgess et al., 1973) was renamed 'Shimwellia blattae' (Priest and Barker, 2010) @@ -1710,7 +1739,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Function
is.rsi.eligibleto check for columns that have valid antimicrobial results, but do not have thersiclass yet. Transform the columns of your raw data with:data %>% mutate_if(is.rsi.eligible, as.rsi)Functions
-as.moandis.moas replacements foras.bactidandis.bactid(since themicrooganismsdata set not only contains bacteria). These last two functions are deprecated and will be removed in a future release. Theas.mofunction determines microbial IDs using intelligent rules:+as.mo("E. coli") # [1] B_ESCHR_COL @@ -1719,7 +1748,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/ as.mo("S group A") # [1] B_STRPTC_GRAAnd with great speed too - on a quite regular Linux server from 2007 it takes us less than 0.02 seconds to transform 25,000 items:
-+thousands_of_E_colis <- rep("E. coli", 25000) microbenchmark::microbenchmark(as.mo(thousands_of_E_colis), unit = "s") @@ -1753,7 +1782,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Added three antimicrobial agents to the
antibioticsdata set: Terbinafine (D01BA02), Rifaximin (A07AA11) and Isoconazole (D01AC05)Added 163 trade names to the
-antibioticsdata set, it now contains 298 different trade names in total, e.g.:+ab_official("Bactroban") # [1] "Mupirocin" @@ -1770,7 +1799,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/Added arguments
minimumandas_percenttoportion_dfSupport for quasiquotation in the functions series
-count_*andportions_*, andn_rsi. This allows to check for more than 2 vectors or columns.+