* 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.
@ -20,7 +20,8 @@
@@ -20,7 +20,8 @@
* Improvements for algorithm in `as.ab()`, so that e.g. `as.ab("ampi sul")` and `ab_name("ampi sul")` work
* Functions `ab_atc()` and `ab_group()` now return `NA` if no antimicrobial agent could be found
* Small fix for some text input that could not be coerced as valid MIC values
* Fixed interpretation of generic CLSI interpretation rules (thanks to Anthony Underwood)
* Fix for interpretation of generic CLSI interpretation rules (thanks to Anthony Underwood)
* Fix for `set_mo_source()` to make sure that column `mo` will always be the second column
### Other
* Removed previously deprecated function `p.symbol()` - it was replaced with `p_symbol()`
#' 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()].
#' @inheritSection lifecycle Maturing lifecycle
#' @inheritSection lifecycle Stable lifecycle
#' @param x any (vector of) text that can be coerced to a valid microorganism code with [as.ab()]
#' @param tolower logical to indicate whether the first character of every output should be transformed to a lower case character. This will lead to e.g. "polymyxin B" and not "polymyxin b".
#' @param property one of the column names of one of the [antibiotics] data set
@ -33,7 +33,7 @@
@@ -33,7 +33,7 @@
#' @param ... other parameters passed on to [as.ab()]
#' @details All output will be [translate]d where possible.
#'
#' The function [ab_url()] will return the direct URL to the official WHO website. A warning will be returned if the reauired ATC code is not available.
#' 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.
#' Use these functions to return a specific property of a microorganism. All input values will be evaluated internally with [as.mo()], which makes it possible to use microbial abbreviations, codes and names as input. Please see *Examples*.
#' @inheritSection lifecycle Stable lifecycle
#' @param x any (vector of) text that can be coerced to a valid microorganism code with [as.mo()]
#' @param property one of the column names of the [microorganisms] data set or `"shortname"`
#' @param language language of the returned text, defaults to system language (see [get_locale()]) and can also be set with `getOption("AMR_locale")`. Use `language = NULL` or `language = ""` to prevent translation.
#' User-defined reference data set for microorganisms
#'
#' @description These functions can be used to predefine your own reference to be used in [as.mo()] and consequently all `mo_*` functions like [mo_genus()] and [mo_gramstain()].
#'
#' This is **the fastest way** to have your organisation (or analysis) specific codes picked up and translated by this package.
#' @inheritSection lifecycle Stable lifecycle
#' @param path location of your reference file, see Details
#' @param path location of your reference file, see Details. Can be `""`, `NULL` or `FALSE` to delete the reference file.
#' @rdname mo_source
#' @name mo_source
#' @aliases set_mo_source get_mo_source
@ -35,11 +35,12 @@
@@ -35,11 +35,12 @@
#'
#' [get_mo_source()] will return the data set by reading `"~/.mo_source.rds"` with [readRDS()]. If the original file has changed (the file defined with `path`), it will call [set_mo_source()] to update the data file automatically.
#'
#' Reading an Excel file (`.xlsx`) with only one row has a size of 8-9 kB. The compressed file used by this package will have a size of 0.1 kB and can be read by [get_mo_source()] in only a couple of microseconds (a millionth of a second).
#' Reading an Excel file (`.xlsx`) with only one row has a size of 8-9 kB. The compressed file created with [set_mo_source()] will then have a size of 0.1 kB and can be read by [get_mo_source()] in only a couple of microseconds (millionths of a second).
#'
#' ## How it works
#' @section How to setup:
#'
#' Imagine this data on a sheet of an Excel file (mo codes were looked up in the [microorganisms] data set). The first column contains the organisation specific codes, the second column contains an MO code from this package:
#'
#' Imagine this data on a sheet of an Excel file (mo codes were looked up in the `microorganisms` data set). The first column contains the organisation specific codes, the second column contains an MO code from this package:
#' ```
#' | A | B |
#' --|--------------------|--------------|
@ -50,27 +51,31 @@
@@ -50,27 +51,31 @@
#' ```
#'
#' We save it as `"home/me/ourcodes.xlsx"`. Now we have to set it as a source:
#'
#' ```
#' set_mo_source("home/me/ourcodes.xlsx")
#' # Created mo_source file '~/.mo_source.rds' from 'home/me/ourcodes.xlsx'.
#' #> NOTE: Created mo_source file '~/.mo_source.rds' from 'home/me/ourcodes.xlsx'
#' #> (columns "Organisation XYZ" and "mo")
#' ```
#'
#' It has now created a file `"~/.mo_source.rds"` with the contents of our Excel file, but only the first column with foreign values and the 'mo' column will be kept.
#' It has now created a file `"~/.mo_source.rds"` with the contents of our Excel file. Only the first column with foreign values and the 'mo' column will be kept when creating the RDS file.
#' If we edit the Excel file to, let's say, by adding row 4 like this:
#' If we edit the Excel file by, let's say, adding row 4 like this:
#'
#' ```
#' | A | B |
#' --|--------------------|--------------|
@ -82,36 +87,41 @@
@@ -82,36 +87,41 @@
#' ```
#'
#' ...any new usage of an MO function in this package will update your data file:
#'
#' ```
#' as.mo("lab_mo_ecoli")
#' # Updated mo_source file '~/.mo_source.rds' from 'home/me/ourcodes.xlsx'.
#' [1] B_ESCHR_COLI
#' #> NOTE: Updated mo_source file '~/.mo_source.rds' from 'home/me/ourcodes.xlsx'
#' #> (columns "Organisation XYZ" and "mo")
#' #> [1] B_ESCHR_COLI
#'
#' mo_genus("lab_Staph_aureus")
#' [1] "Staphylococcus"
#' #> [1] "Staphylococcus"
#' ```
#'
#' To remove the reference data file completely, just use `""` or `NULL` as input for `[set_mo_source()]`:
#' To delete the reference data file, just use `""`, `NULL` or `FALSE` as input for [set_mo_source()]:
#'
#' ```
#' set_mo_source(NULL)
#' # Removed mo_source file '~/.mo_source.rds'.
#' ```
#'
#' If the original Excel file is moved or deleted, the mo_source file will be removed upon the next use of [as.mo()]. If the mo_source file is manually deleted (i.e. without using [set_mo_source()]), the references to the mo_source file will be removed upon the next use of [as.mo()].
<p><strong>Note:</strong> values on this page will change with every website update since they are based on randomly created values and the page was written in <ahref="https://rmarkdown.rstudio.com/">R Markdown</a>. However, the methodology remains unchanged. This page was generated on 20 May 2020.</p>
<p><strong>Note:</strong> values on this page will change with every website update since they are based on randomly created values and the page was written in <ahref="https://rmarkdown.rstudio.com/">R Markdown</a>. However, the methodology remains unchanged. This page was generated on 25 May 2020.</p>
<p>Finally, we will apply <ahref="http://www.eucast.org/expert_rules_and_intrinsic_resistance/">EUCAST rules</a> on our antimicrobial results. In Europe, most medical microbiological laboratories already apply these rules. Our package features their latest insights on intrinsic resistance and exceptional phenotypes. Moreover, the <code><ahref="../reference/eucast_rules.html">eucast_rules()</a></code> function can also apply additional rules, like forcing <helptitle="ATC: J01CA01">ampicillin</help> = R when <helptitle="ATC: J01CR02">amoxicillin/clavulanic acid</help> = R.</p>
<p>Because the amoxicillin (column <code>AMX</code>) and amoxicillin/clavulanic acid (column <code>AMC</code>) in our data were generated randomly, some rows will undoubtedly contain AMX = S and AMC = R, which is technically impossible. The <code><ahref="../reference/eucast_rules.html">eucast_rules()</a></code> fixes this:</p>
<spanclass="co"># Skipping inheritance rules defined by this package, such as setting trimethoprim (TMP) = R where trimethoprim/sulfamethoxazole (SXT) = R.</span>
<spanclass="co"># Use eucast_rules(..., rules = "all") to also apply those rules.</span>
<p>This <code>AMR</code> package includes this methodology with the <code><ahref="../reference/first_isolate.html">first_isolate()</a></code> function. It adopts the episode of a year (can be changed by user) and it starts counting days after every selected isolate. This new variable can easily be added to our data:</p>
<spanclass="co"># [34mNOTE: Using column `[1mbacteria[22m` as input for `col_mo`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mdate[22m` as input for `col_date`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mpatient_id[22m` as input for `col_patient_id`.[39m</span></pre></body></html></div>
<p>So only 28.5% is suitable for resistance analysis! We can now filter on it with the <code><ahref="https://dplyr.tidyverse.org/reference/filter.html">filter()</a></code> function, also from the <code>dplyr</code> package:</p>
<spanclass="co"># NOTE: Using column `bacteria` as input for `col_mo`.</span>
<spanclass="co"># NOTE: Using column `date` as input for `col_date`.</span>
<spanclass="co"># NOTE: Using column `patient_id` as input for `col_patient_id`.</span></pre></body></html></div>
<p>So only 28.2% is suitable for resistance analysis! We can now filter on it with the <code><ahref="https://dplyr.tidyverse.org/reference/filter.html">filter()</a></code> function, also from the <code>dplyr</code> package:</p>
<p>For future use, the above two syntaxes can be shortened with the <code><ahref="../reference/first_isolate.html">filter_first_isolate()</a></code> function:</p>
<p>We made a slight twist to the CLSI algorithm, to take into account the antimicrobial susceptibility profile. Have a look at all isolates of patient S1, sorted on date:</p>
<p>We made a slight twist to the CLSI algorithm, to take into account the antimicrobial susceptibility profile. Have a look at all isolates of patient K4, sorted on date:</p>
<p>Only 1 isolates are marked as ‘first’ according to CLSI guideline. But when reviewing the antibiogram, it is obvious that some isolates are absolutely different strains and should be included too. This is why we weigh isolates, based on their antibiogram. The <code><ahref="../reference/key_antibiotics.html">key_antibiotics()</a></code> function adds a vector with 18 key antibiotics: 6 broad spectrum ones, 6 small spectrum for Gram negatives and 6 small spectrum for Gram positives. These can be defined by the user.</p>
<p>Only 2 isolates are marked as ‘first’ according to CLSI guideline. But when reviewing the antibiogram, it is obvious that some isolates are absolutely different strains and should be included too. This is why we weigh isolates, based on their antibiogram. The <code><ahref="../reference/key_antibiotics.html">key_antibiotics()</a></code> function adds a vector with 18 key antibiotics: 6 broad spectrum ones, 6 small spectrum for Gram negatives and 6 small spectrum for Gram positives. These can be defined by the user.</p>
<p>If a column exists with a name like ‘key(…)ab’ the <code><ahref="../reference/first_isolate.html">first_isolate()</a></code> function will automatically use it and determine the first weighted isolates. Mind the NOTEs in below output:</p>
<spanclass="co"># [34mNOTE: Using column `[1mbacteria[22m` as input for `col_mo`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mbacteria[22m` as input for `col_mo`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mdate[22m` as input for `col_date`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mpatient_id[22m` as input for `col_patient_id`.[39m</span>
<spanclass="co"># [34mNOTE: Using column `[1mkeyab[22m` as input for `col_keyantibiotics`. Use [1mcol_keyantibiotics = FALSE[22m to prevent this.[39m</span></pre></body></html></div>
<spanclass="co"># NOTE: Using column `bacteria` as input for `col_mo`.</span>
<spanclass="co"># NOTE: Using column `bacteria` as input for `col_mo`.</span>
<spanclass="co"># NOTE: Using column `date` as input for `col_date`.</span>
<spanclass="co"># NOTE: Using column `patient_id` as input for `col_patient_id`.</span>
<spanclass="co"># NOTE: Using column `keyab` as input for `col_keyantibiotics`. Use col_keyantibiotics = FALSE to prevent this.</span></pre></body></html></div>
<p>Instead of 1, now 10 isolates are flagged. In total, 78.4% of all isolates are marked ‘first weighted’ - 49.9% more than when using the CLSI guideline. In real life, this novel algorithm will yield 5-10% more isolates than the classic CLSI guideline.</p>
<p>Instead of 2, now 7 isolates are flagged. In total, 78.4% of all isolates are marked ‘first weighted’ - 50.1% more than when using the CLSI guideline. In real life, this novel algorithm will yield 5-10% more isolates than the classic CLSI guideline.</p>
<p>As with <code><ahref="../reference/first_isolate.html">filter_first_isolate()</a></code>, there’s a shortcut for this new algorithm too:</p>
<p>The functions <code><ahref="../reference/proportion.html">resistance()</a></code> and <code><ahref="../reference/proportion.html">susceptibility()</a></code> can be used to calculate antimicrobial resistance or susceptibility. For more specific analyses, the functions <code><ahref="../reference/proportion.html">proportion_S()</a></code>, <code><ahref="../reference/proportion.html">proportion_SI()</a></code>, <code><ahref="../reference/proportion.html">proportion_I()</a></code>, <code><ahref="../reference/proportion.html">proportion_IR()</a></code> and <code><ahref="../reference/proportion.html">proportion_R()</a></code> can be used to determine the proportion of a specific antimicrobial outcome.</p>
<p>As per the EUCAST guideline of 2019, we calculate resistance as the proportion of R (<code><ahref="../reference/proportion.html">proportion_R()</a></code>, equal to <code><ahref="../reference/proportion.html">resistance()</a></code>) and susceptibility as the proportion of S and I (<code><ahref="../reference/proportion.html">proportion_SI()</a></code>, equal to <code><ahref="../reference/proportion.html">susceptibility()</a></code>). These functions can be used on their own:</p>
<p>Or can be used in conjuction with <code><ahref="https://dplyr.tidyverse.org/reference/group_by.html">group_by()</a></code> and <code><ahref="https://dplyr.tidyverse.org/reference/summarise.html">summarise()</a></code>, both from the <code>dplyr</code> package:</p>
