From 63099cd81ea30493d010c115805d1b6269176a88 Mon Sep 17 00:00:00 2001 From: Matthijs Berends Date: Mon, 31 Mar 2025 10:51:31 +0200 Subject: [PATCH] (v2.1.1.9232) is.mic() iteration, documentation cleanup --- DESCRIPTION | 4 +- NEWS.md | 3 +- R/aa_helper_functions.R | 6 +- R/ab.R | 10 +- R/ab_from_text.R | 14 +- R/ab_property.R | 20 +- R/age.R | 16 +- R/amr_selectors.R | 12 +- R/antibiogram.R | 44 +- R/atc_online.R | 12 +- R/av.R | 8 +- R/av_from_text.R | 14 +- R/av_property.R | 14 +- R/availability.R | 4 +- R/bug_drug_combinations.R | 12 +- R/count.R | 2 +- R/custom_antimicrobials.R | 2 +- R/custom_eucast_rules.R | 2 +- R/custom_microorganisms.R | 2 +- R/disk.R | 4 +- R/eucast_rules.R | 24 +- R/export_biosample.R | 6 +- R/first_isolate.R | 36 +- R/get_episode.R | 6 +- R/ggplot_pca.R | 40 +- R/ggplot_sir.R | 36 +- R/guess_ab_col.R | 8 +- R/italicise_taxonomy.R | 4 +- R/join_microorganisms.R | 8 +- R/key_antimicrobials.R | 14 +- R/kurtosis.R | 6 +- R/like.R | 6 +- R/mdro.R | 14 +- R/mean_amr_distance.R | 12 +- R/mic.R | 22 +- R/mo.R | 24 +- R/mo_property.R | 10 +- R/mo_source.R | 4 +- R/pca.R | 4 +- R/plotting.R | 26 +- R/proportion.R | 20 +- R/random.R | 10 +- R/resistance_predict.R | 28 +- R/sir.R | 40 +- R/skewness.R | 4 +- R/top_n_microorganisms.R | 8 +- R/translate.R | 4 +- ....txt => gpt_training_text_v2.1.1.9232.txt} | 682 +++++++++--------- man/ab_from_text.Rd | 14 +- man/ab_property.Rd | 20 +- man/add_custom_antimicrobials.Rd | 2 +- man/add_custom_microorganisms.Rd | 2 +- man/age.Rd | 10 +- man/age_groups.Rd | 6 +- man/antibiogram.Rd | 44 +- man/antimicrobial_selectors.Rd | 16 +- man/as.ab.Rd | 10 +- man/as.av.Rd | 8 +- man/as.disk.Rd | 4 +- man/as.mic.Rd | 16 +- man/as.mo.Rd | 24 +- man/as.sir.Rd | 38 +- man/atc_online.Rd | 12 +- man/av_from_text.Rd | 14 +- man/av_property.Rd | 14 +- man/availability.Rd | 4 +- man/bug_drug_combinations.Rd | 20 +- man/count.Rd | 10 +- man/custom_eucast_rules.Rd | 2 +- man/eucast_rules.Rd | 26 +- man/export_ncbi_biosample.Rd | 6 +- man/first_isolate.Rd | 36 +- man/get_episode.Rd | 6 +- man/ggplot_pca.Rd | 38 +- man/ggplot_sir.Rd | 44 +- man/guess_ab_col.Rd | 8 +- man/italicise_taxonomy.Rd | 4 +- man/join.Rd | 8 +- man/key_antimicrobials.Rd | 20 +- man/kurtosis.Rd | 6 +- man/like.Rd | 6 +- man/mdro.Rd | 20 +- man/mean_amr_distance.Rd | 12 +- man/mo_property.Rd | 14 +- man/mo_source.Rd | 4 +- man/pca.Rd | 4 +- man/plot.Rd | 50 +- man/proportion.Rd | 22 +- man/random.Rd | 10 +- man/resistance_predict.Rd | 30 +- man/skewness.Rd | 4 +- man/top_n_microorganisms.Rd | 8 +- man/translate.Rd | 4 +- 93 files changed, 1001 insertions(+), 990 deletions(-) rename data-raw/{gpt_training_text_v2.1.1.9231.txt => gpt_training_text_v2.1.1.9232.txt} (96%) diff --git a/DESCRIPTION b/DESCRIPTION index a9c7ba23f..eaf2f2aa1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 2.1.1.9231 -Date: 2025-03-29 +Version: 2.1.1.9232 +Date: 2025-03-31 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) data analysis and to work with microbial and antimicrobial properties by diff --git a/NEWS.md b/NEWS.md index ed703d661..d4fd91105 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 2.1.1.9231 +# AMR 2.1.1.9232 *(this beta version will eventually become v3.0. We're happy to reach a new major milestone soon, which will be all about the new One Health support! Install this beta using [the instructions here](https://msberends.github.io/AMR/#latest-development-version).)* @@ -80,6 +80,7 @@ This package now supports not only tools for AMR data analysis in clinical setti * Comparisons of MIC values are now more strict. For example, `>32` is higher than (and never equal to) `32`. Thus, `as.mic(">32") == as.mic(32)` now returns `FALSE`, and `as.mic(">32") > as.mic(32)` now returns `TRUE`. * Sorting of MIC values (using `sort()`) was fixed in the same manner; `<0.001` now gets sorted before `0.001`, and `>0.001` gets sorted after `0.001`. * Intermediate log2 levels used for MIC plotting are now more common values instead of following a strict dilution range + * `is.mic()` now returns a vector of `TRUE`/`FALSE` if the input is a `data.frame`, just like `as.sir()` * `eucast_rules()` now has an argument `overwrite` (default: `FALSE`) to indicate whether non-`NA` values should be overwritten * Disks of 0 to 5 mm are now allowed, the newly allowed range for disk diffusion (`as.disk()`) is now between 0 and 50 mm * Updated `italicise_taxonomy()` to support HTML output diff --git a/R/aa_helper_functions.R b/R/aa_helper_functions.R index 98fa8842d..b43af1f58 100644 --- a/R/aa_helper_functions.R +++ b/R/aa_helper_functions.R @@ -1164,9 +1164,9 @@ unique_call_id <- function(entire_session = FALSE, match_fn = NULL) { } #' @noRd -#' @param fn name of the function as a character -#' @param ... character elements to be pasted together as a 'salt' -#' @param entire_session show message once per session +#' @param fn Name of the function as a character +#' @param ... Character elements to be pasted together as a 'salt' +#' @param entire_session Show message once per session message_not_thrown_before <- function(fn, ..., entire_session = FALSE) { # this is to prevent that messages/notes will be printed for every dplyr group or more than once per session # e.g. this would show a msg 4 times: example_isolates %>% group_by(ward) %>% filter(mo_is_gram_negative()) diff --git a/R/ab.R b/R/ab.R index e2e98ff9d..d2e540945 100755 --- a/R/ab.R +++ b/R/ab.R @@ -30,11 +30,11 @@ #' Transform Input to an Antibiotic ID #' #' Use this function to determine the antimicrobial drug code of one or more antimicrobials. The data set [antimicrobials] will be searched for abbreviations, official names and synonyms (brand names). -#' @param x a [character] vector to determine to antibiotic ID -#' @param flag_multiple_results a [logical] to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value. -#' @param language language to coerce input values from any of the `r length(LANGUAGES_SUPPORTED)` supported languages - default to the system language if supported (see [get_AMR_locale()]) -#' @param info a [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode -#' @param ... arguments passed on to internal functions +#' @param x A [character] vector to determine to antibiotic ID +#' @param flag_multiple_results A [logical] to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value. +#' @param language Language to coerce input values from any of the `r length(LANGUAGES_SUPPORTED)` supported languages - default to the system language if supported (see [get_AMR_locale()]) +#' @param info A [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode +#' @param ... Arguments passed on to internal functions #' @rdname as.ab #' @inheritSection WHOCC WHOCC #' @details All entries in the [antimicrobials] 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. diff --git a/R/ab_from_text.R b/R/ab_from_text.R index 7444bb510..a38fab675 100755 --- a/R/ab_from_text.R +++ b/R/ab_from_text.R @@ -30,13 +30,13 @@ #' Retrieve Antimicrobial Drug Names and Doses from Clinical Text #' #' 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. -#' @param text text to analyse -#' @param type type of property to search for, either `"drug"`, `"dose"` or `"administration"`, see *Examples* -#' @param collapse a [character] to pass on to `paste(, collapse = ...)` to only return one [character] per element of `text`, see *Examples* -#' @param translate_ab if `type = "drug"`: a column name of the [antimicrobials] data set to translate the antibiotic abbreviations to, using [ab_property()]. The default is `FALSE`. Using `TRUE` is equal to using "name". -#' @param thorough_search a [logical] to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to `TRUE` will take considerably more time than when using `FALSE`. At default, it will turn `TRUE` when all input elements contain a maximum of three words. -#' @param info a [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode -#' @param ... arguments passed on to [as.ab()] +#' @param text Text to analyse +#' @param type Type of property to search for, either `"drug"`, `"dose"` or `"administration"`, see *Examples* +#' @param collapse A [character] to pass on to `paste(, collapse = ...)` to only return one [character] per element of `text`, see *Examples* +#' @param translate_ab If `type = "drug"`: a column name of the [antimicrobials] data set to translate the antibiotic abbreviations to, using [ab_property()]. The default is `FALSE`. Using `TRUE` is equal to using "name". +#' @param thorough_search A [logical] to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to `TRUE` will take considerably more time than when using `FALSE`. At default, it will turn `TRUE` when all input elements contain a maximum of three words. +#' @param info A [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode +#' @param ... Arguments passed on to [as.ab()] #' @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` diff --git a/R/ab_property.R b/R/ab_property.R index d816f5047..823e3484b 100755 --- a/R/ab_property.R +++ b/R/ab_property.R @@ -30,16 +30,16 @@ #' Get Properties of an Antibiotic #' #' Use these functions to return a specific property of an antibiotic from the [antimicrobials] data set. All input values will be evaluated internally with [as.ab()]. -#' @param x any (vector of) text that can be coerced to a valid antibiotic drug code with [as.ab()] -#' @param tolower a [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 [antimicrobials] data set: `vector_or(colnames(antimicrobials), sort = FALSE)`. -#' @param language language of the returned text - the default is the current system language (see [get_AMR_locale()]) and can also be set with the package option [`AMR_locale`][AMR-options]. Use `language = NULL` or `language = ""` to prevent translation. -#' @param administration way of administration, either `"oral"` or `"iv"` -#' @param open browse the URL using [utils::browseURL()] -#' @param ... in case of [set_ab_names()] and `data` is a [data.frame]: columns to select (supports tidy selection such as `column1:column4`), otherwise other arguments passed on to [as.ab()] -#' @param data a [data.frame] of which the columns need to be renamed, or a [character] vector of column names -#' @param snake_case a [logical] to indicate whether the names should be in so-called [snake case](https://en.wikipedia.org/wiki/Snake_case): in lower case and all spaces/slashes replaced with an underscore (`_`) -#' @param only_first a [logical] to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group) +#' @param x Any (vector of) text that can be coerced to a valid antibiotic drug code with [as.ab()] +#' @param tolower A [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 [antimicrobials] data set: `vector_or(colnames(antimicrobials), sort = FALSE)`. +#' @param language Language of the returned text - the default is the current system language (see [get_AMR_locale()]) and can also be set with the package option [`AMR_locale`][AMR-options]. Use `language = NULL` or `language = ""` to prevent translation. +#' @param administration Way of administration, either `"oral"` or `"iv"` +#' @param open Browse the URL using [utils::browseURL()] +#' @param ... In case of [set_ab_names()] and `data` is a [data.frame]: columns to select (supports tidy selection such as `column1:column4`), otherwise other arguments passed on to [as.ab()] +#' @param data A [data.frame] of which the columns need to be renamed, or a [character] vector of column names +#' @param snake_case A [logical] to indicate whether the names should be in so-called [snake case](https://en.wikipedia.org/wiki/Snake_case): in lower case and all spaces/slashes replaced with an underscore (`_`) +#' @param only_first A [logical] to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group) #' @details All output [will be translated][translate] 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. diff --git a/R/age.R b/R/age.R index c987da0a2..51fe23d5d 100755 --- a/R/age.R +++ b/R/age.R @@ -30,11 +30,11 @@ #' Age in Years of Individuals #' #' Calculates age in years based on a reference date, which is the system date at default. -#' @param x date(s), [character] (vectors) will be coerced with [as.POSIXlt()] -#' @param reference reference date(s) (default is today), [character] (vectors) will be coerced with [as.POSIXlt()] -#' @param exact a [logical] to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of [year-to-date](https://en.wikipedia.org/wiki/Year-to-date) (YTD) of `x` by the number of days in the year of `reference` (either 365 or 366). -#' @param na.rm a [logical] to indicate whether missing values should be removed -#' @param ... arguments passed on to [as.POSIXlt()], such as `origin` +#' @param x Date(s), [character] (vectors) will be coerced with [as.POSIXlt()] +#' @param reference Reference date(s) (default is today), [character] (vectors) will be coerced with [as.POSIXlt()] +#' @param exact A [logical] to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of [year-to-date](https://en.wikipedia.org/wiki/Year-to-date) (YTD) of `x` by the number of days in the year of `reference` (either 365 or 366). +#' @param na.rm A [logical] to indicate whether missing values should be removed +#' @param ... Arguments passed on to [as.POSIXlt()], such as `origin` #' @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. @@ -129,9 +129,9 @@ age <- function(x, reference = Sys.Date(), exact = FALSE, na.rm = FALSE, ...) { #' Split Ages into Age Groups #' #' Split ages into age groups defined by the `split` argument. This allows for easier demographic (antimicrobial resistance) analysis. -#' @param x age, e.g. calculated with [age()] -#' @param split_at values to split `x` at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See *Details*. -#' @param na.rm a [logical] to indicate whether missing values should be removed +#' @param x Age, e.g. calculated with [age()] +#' @param split_at Values to split `x` at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See *Details*. +#' @param na.rm A [logical] to indicate whether missing values should be removed #' @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+. diff --git a/R/amr_selectors.R b/R/amr_selectors.R index 4c0345bd5..5cfc33353 100755 --- a/R/amr_selectors.R +++ b/R/amr_selectors.R @@ -38,12 +38,12 @@ #' my_data_with_all_these_columns %>% #' select(cephalosporins()) #' ``` -#' @param amr_class an antimicrobial class or a part of it, such as `"carba"` and `"carbapenems"`. The columns `group`, `atc_group1` and `atc_group2` of the [antimicrobials] data set will be searched (case-insensitive) for this value. -#' @param filter an [expression] to be evaluated in the [antimicrobials] data set, such as `name %like% "trim"` -#' @param only_sir_columns a [logical] to indicate whether only columns of class `sir` must be selected (default is `FALSE`), see [as.sir()] -#' @param only_treatable a [logical] to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is `TRUE`), such as gentamicin-high (`GEH`) and imipenem/EDTA (`IPE`) -#' @param return_all a [logical] to indicate whether all matched columns must be returned (default is `TRUE`). With `FALSE`, only the first of each unique antimicrobial will be returned, e.g. if both columns `"genta"` and `"gentamicin"` exist in the data, only the first hit for gentamicin will be returned. -#' @param ... ignored, only in place to allow future extensions +#' @param amr_class An antimicrobial class or a part of it, such as `"carba"` and `"carbapenems"`. The columns `group`, `atc_group1` and `atc_group2` of the [antimicrobials] data set will be searched (case-insensitive) for this value. +#' @param filter An [expression] to be evaluated in the [antimicrobials] data set, such as `name %like% "trim"` +#' @param only_sir_columns A [logical] to indicate whether only columns of class `sir` must be selected (default is `FALSE`), see [as.sir()] +#' @param only_treatable A [logical] to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is `TRUE`), such as gentamicin-high (`GEH`) and imipenem/EDTA (`IPE`) +#' @param return_all A [logical] to indicate whether all matched columns must be returned (default is `TRUE`). With `FALSE`, only the first of each unique antimicrobial will be returned, e.g. if both columns `"genta"` and `"gentamicin"` exist in the data, only the first hit for gentamicin will be returned. +#' @param ... Ignored, only in place to allow future extensions #' @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][tidyselect::language] such as [`everything()`][tidyselect::everything()], but are not limited to `dplyr` verbs. Nonetheless, they are very convenient to use with `dplyr` functions such as [`select()`][dplyr::select()], [`filter()`][dplyr::filter()] and [`summarise()`][dplyr::summarise()], see *Examples*. #' diff --git a/R/antibiogram.R b/R/antibiogram.R index 383f0420c..b43172961 100755 --- a/R/antibiogram.R +++ b/R/antibiogram.R @@ -33,8 +33,8 @@ #' Create detailed antibiograms with options for traditional, combination, syndromic, and Bayesian WISCA methods. #' #' Adhering to previously described approaches (see *Source*) and especially the Bayesian WISCA model (Weighted-Incidence Syndromic Combination Antibiogram) by Bielicki *et al.*, these functions provide flexible output formats including plots and tables, ideal for integration with R Markdown and Quarto reports. -#' @param x a [data.frame] containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see [as.sir()]) -#' @param antimicrobials a vector specifying the antimicrobials to include in the antibiogram (see *Examples*). Will be evaluated using [guess_ab_col()]. This can be: +#' @param x A [data.frame] containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see [as.sir()]) +#' @param antimicrobials A vector specifying the antimicrobials to include in the antibiogram (see *Examples*). Will be evaluated using [guess_ab_col()]. This can be: #' - Any antimicrobial name or code #' - A column name in `x` that contains SIR values #' - Any [antimicrobial selector][antimicrobial_selectors], such as [aminoglycosides()] or [carbapenems()] @@ -48,25 +48,25 @@ #' - `carbapenems() + "GEN"` #' - `carbapenems() + c("", "GEN")` #' - `carbapenems() + c("", aminoglycosides())` -#' @param mo_transform a character to transform microorganism input - must be `"name"`, `"shortname"` (default), `"gramstain"`, or one of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`. Can also be `NULL` to not transform the input or `NA` to consider all microorganisms 'unknown'. -#' @param ab_transform a character to transform antimicrobial input - must be one of the column names of the [antimicrobials] data set (defaults to `"name"`): `r vector_or(colnames(antimicrobials), sort = FALSE, quotes = TRUE)`. Can also be `NULL` to not transform the input. -#' @param syndromic_group a column name of `x`, or values calculated to split rows of `x`, e.g. by using [ifelse()] or [`case_when()`][dplyr::case_when()]. See *Examples*. -#' @param add_total_n a [logical] to indicate whether `n_tested` available numbers per pathogen should be added to the table (default is `TRUE`). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for *E. coli* 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when `wisca = TRUE`; in that case, use [retrieve_wisca_parameters()] to get the parameters used for WISCA. +#' @param mo_transform A character to transform microorganism input - must be `"name"`, `"shortname"` (default), `"gramstain"`, or one of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`. Can also be `NULL` to not transform the input or `NA` to consider all microorganisms 'unknown'. +#' @param ab_transform A character to transform antimicrobial input - must be one of the column names of the [antimicrobials] data set (defaults to `"name"`): `r vector_or(colnames(antimicrobials), sort = FALSE, quotes = TRUE)`. Can also be `NULL` to not transform the input. +#' @param syndromic_group A column name of `x`, or values calculated to split rows of `x`, e.g. by using [ifelse()] or [`case_when()`][dplyr::case_when()]. See *Examples*. +#' @param add_total_n A [logical] to indicate whether `n_tested` available numbers per pathogen should be added to the table (default is `TRUE`). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for *E. coli* 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when `wisca = TRUE`; in that case, use [retrieve_wisca_parameters()] to get the parameters used for WISCA. #' @param only_all_tested (for combination antibiograms): a [logical] to indicate that isolates must be tested for all antimicrobials, see *Details* -#' @param digits number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise -#' @param formatting_type numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See *Details* > *Formatting Type* for a list of options. -#' @param col_mo column name of the names or codes of the microorganisms (see [as.mo()]) - the default is the first column of class [`mo`]. Values will be coerced using [as.mo()]. -#' @param language language to translate text, which defaults to the system language (see [get_AMR_locale()]) -#' @param minimum the minimum allowed number of available (tested) isolates. Any isolate count lower than `minimum` will return `NA` with a warning. The default number of `30` isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see *Source*. -#' @param combine_SI a [logical] to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is `TRUE`) -#' @param sep a separating character for antimicrobial columns in combination antibiograms -#' @param wisca a [logical] to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is `FALSE`). This will use a Bayesian decision model to estimate regimen coverage probabilities using [Monte Carlo simulations](https://en.wikipedia.org/wiki/Monte_Carlo_method). Set `simulations`, `conf_interval`, and `interval_side` to adjust. +#' @param digits Number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise +#' @param formatting_type Numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See *Details* > *Formatting Type* for a list of options. +#' @param col_mo Column name of the names or codes of the microorganisms (see [as.mo()]) - the default is the first column of class [`mo`]. Values will be coerced using [as.mo()]. +#' @param language Language to translate text, which defaults to the system language (see [get_AMR_locale()]) +#' @param minimum The minimum allowed number of available (tested) isolates. Any isolate count lower than `minimum` will return `NA` with a warning. The default number of `30` isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see *Source*. +#' @param combine_SI A [logical] to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is `TRUE`) +#' @param sep A separating character for antimicrobial columns in combination antibiograms +#' @param wisca A [logical] to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is `FALSE`). This will use a Bayesian decision model to estimate regimen coverage probabilities using [Monte Carlo simulations](https://en.wikipedia.org/wiki/Monte_Carlo_method). Set `simulations`, `conf_interval`, and `interval_side` to adjust. #' @param simulations (for WISCA) a numerical value to set the number of Monte Carlo simulations -#' @param conf_interval a numerical value to set confidence interval (default is `0.95`) -#' @param interval_side the side of the confidence interval, either `"two-tailed"` (default), `"left"` or `"right"` -#' @param info a [logical] to indicate info should be printed - the default is `TRUE` only in interactive mode -#' @param object an [antibiogram()] object -#' @param ... when used in [R Markdown or Quarto][knitr::kable()]: arguments passed on to [knitr::kable()] (otherwise, has no use) +#' @param conf_interval A numerical value to set confidence interval (default is `0.95`) +#' @param interval_side The side of the confidence interval, either `"two-tailed"` (default), `"left"` or `"right"` +#' @param info A [logical] to indicate info should be printed - the default is `TRUE` only in interactive mode +#' @param object An [antibiogram()] object +#' @param ... When used in [R Markdown or Quarto][knitr::kable()]: arguments passed on to [knitr::kable()] (otherwise, has no use) #' @details These functions return 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 with one of the four available algorithms: isolate-based, patient-based, episode-based, or phenotype-based. @@ -1183,7 +1183,7 @@ wisca <- function(x, } #' @export -#' @param wisca_model the outcome of [wisca()] or [`antibiogram(..., wisca = TRUE)`][antibiogram()] +#' @param wisca_model The outcome of [wisca()] or [`antibiogram(..., wisca = TRUE)`][antibiogram()] #' @rdname antibiogram retrieve_wisca_parameters <- function(wisca_model, ...) { stop_ifnot(isTRUE(attributes(wisca_model)$wisca), "This function only applies to WISCA models. Use `wisca()` or `antibiogram(..., wisca = TRUE)` to create a WISCA model.") @@ -1320,8 +1320,8 @@ autoplot.antibiogram <- function(object, ...) { # will be exported in zzz.R #' @method knit_print antibiogram -#' @param italicise a [logical] to indicate whether the microorganism names in the [knitr][knitr::kable()] table should be made italic, using [italicise_taxonomy()]. -#' @param na character to use for showing `NA` values +#' @param italicise A [logical] to indicate whether the microorganism names in the [knitr][knitr::kable()] table should be made italic, using [italicise_taxonomy()]. +#' @param na Character to use for showing `NA` values #' @rdname antibiogram knit_print.antibiogram <- function(x, italicise = TRUE, na = getOption("knitr.kable.NA", default = ""), ...) { stop_ifnot_installed("knitr") diff --git a/R/atc_online.R b/R/atc_online.R index 55cd0b1e1..e735e26c7 100755 --- a/R/atc_online.R +++ b/R/atc_online.R @@ -30,12 +30,12 @@ #' Get ATC Properties from WHOCC Website #' #' Gets data from the WHOCC website to determine properties of an Anatomical Therapeutic Chemical (ATC) (e.g. an antimicrobial), such as the name, defined daily dose (DDD) or standard unit. -#' @param atc_code a [character] (vector) with ATC code(s) of antimicrobials, will be coerced with [as.ab()] and [ab_atc()] internally if not a valid ATC code -#' @param property property of an ATC code. Valid values are `"ATC"`, `"Name"`, `"DDD"`, `"U"` (`"unit"`), `"Adm.R"`, `"Note"` and `groups`. For this last option, all hierarchical groups of an ATC code will be returned, see *Examples*. -#' @param administration type of administration when using `property = "Adm.R"`, see *Details* -#' @param url url of website of the WHOCC. The sign `%s` can be used as a placeholder for ATC codes. -#' @param url_vet url of website of the WHOCC for veterinary medicine. The sign `%s` can be used as a placeholder for ATC_vet codes (that all start with "Q"). -#' @param ... arguments to pass on to `atc_property` +#' @param atc_code A [character] (vector) with ATC code(s) of antimicrobials, will be coerced with [as.ab()] and [ab_atc()] internally if not a valid ATC code +#' @param property Property of an ATC code. Valid values are `"ATC"`, `"Name"`, `"DDD"`, `"U"` (`"unit"`), `"Adm.R"`, `"Note"` and `groups`. For this last option, all hierarchical groups of an ATC code will be returned, see *Examples*. +#' @param administration Type of administration when using `property = "Adm.R"`, see *Details* +#' @param url URL of website of the WHOCC. The sign `%s` can be used as a placeholder for ATC codes. +#' @param url_vet URL of website of the WHOCC for veterinary medicine. The sign `%s` can be used as a placeholder for ATC_vet codes (that all start with "Q"). +#' @param ... Arguments to pass on to `atc_property` #' @details #' Options for argument `administration`: #' diff --git a/R/av.R b/R/av.R index 8b06a9f74..889681f1e 100755 --- a/R/av.R +++ b/R/av.R @@ -30,10 +30,10 @@ #' Transform Input to an Antiviral Drug ID #' #' 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). -#' @param x a [character] vector to determine to antiviral drug ID -#' @param flag_multiple_results a [logical] to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value. -#' @param info a [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode -#' @param ... arguments passed on to internal functions +#' @param x A [character] vector to determine to antiviral drug ID +#' @param flag_multiple_results A [logical] to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value. +#' @param info A [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode +#' @param ... Arguments passed on to internal functions #' @rdname as.av #' @inheritSection WHOCC WHOCC #' @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. diff --git a/R/av_from_text.R b/R/av_from_text.R index 2ab26bc45..62b00772f 100755 --- a/R/av_from_text.R +++ b/R/av_from_text.R @@ -30,13 +30,13 @@ #' Retrieve Antiviral Drug Names and Doses from Clinical Text #' #' 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. -#' @param text text to analyse -#' @param type type of property to search for, either `"drug"`, `"dose"` or `"administration"`, see *Examples* -#' @param collapse a [character] to pass on to `paste(, collapse = ...)` to only return one [character] per element of `text`, see *Examples* -#' @param translate_av if `type = "drug"`: a column name of the [antivirals] data set to translate the antibiotic abbreviations to, using [av_property()]. The default is `FALSE`. Using `TRUE` is equal to using "name". -#' @param thorough_search a [logical] to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to `TRUE` will take considerably more time than when using `FALSE`. At default, it will turn `TRUE` when all input elements contain a maximum of three words. -#' @param info a [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode -#' @param ... arguments passed on to [as.av()] +#' @param text Text to analyse +#' @param type Type of property to search for, either `"drug"`, `"dose"` or `"administration"`, see *Examples* +#' @param collapse A [character] to pass on to `paste(, collapse = ...)` to only return one [character] per element of `text`, see *Examples* +#' @param translate_av If `type = "drug"`: a column name of the [antivirals] data set to translate the antibiotic abbreviations to, using [av_property()]. The default is `FALSE`. Using `TRUE` is equal to using "name". +#' @param thorough_search A [logical] to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to `TRUE` will take considerably more time than when using `FALSE`. At default, it will turn `TRUE` when all input elements contain a maximum of three words. +#' @param info A [logical] to indicate whether a progress bar should be printed - the default is `TRUE` only in interactive mode +#' @param ... Arguments passed on to [as.av()] #' @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` diff --git a/R/av_property.R b/R/av_property.R index cb75f3bec..c49b3cc9f 100755 --- a/R/av_property.R +++ b/R/av_property.R @@ -30,13 +30,13 @@ #' Get Properties of an Antiviral Drug #' #' 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()]. -#' @param x any (vector of) text that can be coerced to a valid antiviral drug code with [as.av()] -#' @param tolower a [logical] to indicate whether the first [character] of every output should be transformed to a lower case [character]. -#' @param property one of the column names of one of the [antivirals] data set: `vector_or(colnames(antivirals), sort = FALSE)`. -#' @param language language of the returned text - the default is system language (see [get_AMR_locale()]) and can also be set with the package option [`AMR_locale`][AMR-options]. Use `language = NULL` or `language = ""` to prevent translation. -#' @param administration way of administration, either `"oral"` or `"iv"` -#' @param open browse the URL using [utils::browseURL()] -#' @param ... other arguments passed on to [as.av()] +#' @param x Any (vector of) text that can be coerced to a valid antiviral drug code with [as.av()] +#' @param tolower A [logical] to indicate whether the first [character] of every output should be transformed to a lower case [character]. +#' @param property One of the column names of one of the [antivirals] data set: `vector_or(colnames(antivirals), sort = FALSE)`. +#' @param language Language of the returned text - the default is system language (see [get_AMR_locale()]) and can also be set with the package option [`AMR_locale`][AMR-options]. Use `language = NULL` or `language = ""` to prevent translation. +#' @param administration Way of administration, either `"oral"` or `"iv"` +#' @param open Browse the URL using [utils::browseURL()] +#' @param ... Other arguments passed on to [as.av()] #' @details All output [will be translated][translate] 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. diff --git a/R/availability.R b/R/availability.R index ec7d960e4..b0962a12d 100755 --- a/R/availability.R +++ b/R/availability.R @@ -30,8 +30,8 @@ #' Check Availability of Columns #' #' 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()]. -#' @param tbl a [data.frame] or [list] -#' @param width number of characters to present the visual availability - the default is filling the width of the console +#' @param tbl A [data.frame] or [list] +#' @param width Number of characters to present the visual availability - the default is filling the width of the console #' @details The function returns a [data.frame] with columns `"resistant"` and `"visual_resistance"`. The values in that columns are calculated with [resistance()]. #' @return [data.frame] with column names of `tbl` as row names #' @export diff --git a/R/bug_drug_combinations.R b/R/bug_drug_combinations.R index 021786420..c064d255b 100755 --- a/R/bug_drug_combinations.R +++ b/R/bug_drug_combinations.R @@ -31,13 +31,13 @@ #' #' 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*. #' @inheritParams eucast_rules -#' @param combine_SI a [logical] to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is `TRUE` -#' @param add_ab_group a [logical] to indicate where the group of the antimicrobials must be included as a first column +#' @param combine_SI A [logical] to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is `TRUE` +#' @param add_ab_group A [logical] to indicate where the group of the antimicrobials must be included as a first column #' @param remove_intrinsic_resistant [logical] to indicate that rows and columns with 100% resistance for all tested antimicrobials must be removed from the table -#' @param FUN the function to call on the `mo` column to transform the microorganism codes - the default is [mo_shortname()] -#' @param translate_ab a [character] of length 1 containing column names of the [antimicrobials] data set -#' @param include_n_rows a [logical] to indicate if the total number of rows must be included in the output -#' @param ... arguments passed on to `FUN` +#' @param FUN The function to call on the `mo` column to transform the microorganism codes - the default is [mo_shortname()] +#' @param translate_ab A [character] of length 1 containing column names of the [antimicrobials] data set +#' @param include_n_rows A [logical] to indicate if the total number of rows must be included in the output +#' @param ... Arguments passed on to `FUN` #' @inheritParams sir_df #' @inheritParams base::formatC #' @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()]. diff --git a/R/count.R b/R/count.R index 074e7f861..c095832ba 100755 --- a/R/count.R +++ b/R/count.R @@ -32,7 +32,7 @@ #' @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. -#' @param ... one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with [as.sir()] if needed. +#' @param ... One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with [as.sir()] if needed. #' @inheritParams proportion #' @inheritSection as.sir Interpretation of SIR #' @details These functions are meant to count isolates. Use the [resistance()]/[susceptibility()] functions to calculate microbial resistance/susceptibility. diff --git a/R/custom_antimicrobials.R b/R/custom_antimicrobials.R index 55cbccc25..7c98ebe6b 100755 --- a/R/custom_antimicrobials.R +++ b/R/custom_antimicrobials.R @@ -30,7 +30,7 @@ #' Add Custom Antimicrobials #' #' With [add_custom_antimicrobials()] you can add your own custom antimicrobial drug names and codes. -#' @param x a [data.frame] resembling the [antimicrobials] data set, at least containing columns "ab" and "name" +#' @param x A [data.frame] resembling the [antimicrobials] data set, at least containing columns "ab" and "name" #' @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: diff --git a/R/custom_eucast_rules.R b/R/custom_eucast_rules.R index ff6e558ed..b738f7aa0 100755 --- a/R/custom_eucast_rules.R +++ b/R/custom_eucast_rules.R @@ -30,7 +30,7 @@ #' Define Custom EUCAST Rules #' #' Define custom EUCAST rules for your organisation or specific analysis and use the output of this function in [eucast_rules()]. -#' @param ... rules in [formula][base::tilde] notation, see below for instructions, and in *Examples* +#' @param ... Rules in [formula][base::tilde] notation, see below for instructions, and in *Examples* #' @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. #' @section How it works: diff --git a/R/custom_microorganisms.R b/R/custom_microorganisms.R index 2e4c04662..955d9e9df 100755 --- a/R/custom_microorganisms.R +++ b/R/custom_microorganisms.R @@ -30,7 +30,7 @@ #' Add Custom Microorganisms #' #' With [add_custom_microorganisms()] you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis. -#' @param x a [data.frame] resembling the [microorganisms] data set, at least containing column "genus" (case-insensitive) +#' @param x A [data.frame] resembling the [microorganisms] data set, at least containing column "genus" (case-insensitive) #' @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. diff --git a/R/disk.R b/R/disk.R index 13a6f386b..929c6ee4d 100755 --- a/R/disk.R +++ b/R/disk.R @@ -31,8 +31,8 @@ #' #' This transforms a vector to a new class [`disk`], which is a disk diffusion growth zone size (around an antibiotic disk) in millimetres between 0 and 50. #' @rdname as.disk -#' @param x vector -#' @param na.rm a [logical] indicating whether missing values should be removed +#' @param x Vector +#' @param na.rm A [logical] indicating whether missing values should be removed #' @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 0 and 50 millimetres. Values higher than 50 but lower than 100 will be maximised to 50. All others input values outside the 0-50 range will return `NA`. diff --git a/R/eucast_rules.R b/R/eucast_rules.R index 845f241cc..1dffe8f26 100755 --- a/R/eucast_rules.R +++ b/R/eucast_rules.R @@ -59,19 +59,19 @@ format_eucast_version_nr <- function(version, markdown = TRUE) { #' Apply rules from clinical breakpoints notes and expected resistant phenotypes as defined by the European Committee on Antimicrobial Susceptibility Testing (EUCAST, ), see *Source*. Use [eucast_dosage()] to get a [data.frame] with advised dosages of a certain bug-drug combination, which is based on the [dosage] data set. #' #' To improve the interpretation of the antibiogram before EUCAST rules are applied, some non-EUCAST rules can applied at default, see *Details*. -#' @param x a data set with antimicrobials columns, such as `amox`, `AMX` and `AMC` -#' @param info a [logical] to indicate whether progress should be printed to the console - the default is only print while in interactive sessions -#' @param rules a [character] vector that specifies which rules should be applied. Must be one or more of `"breakpoints"`, `"expected_phenotypes"`, `"expert"`, `"other"`, `"custom"`, `"all"`, and defaults to `c("breakpoints", "expected_phenotypes")`. The default value can be set to another value using the package option [`AMR_eucastrules`][AMR-options]: `options(AMR_eucastrules = "all")`. If using `"custom"`, be sure to fill in argument `custom_rules` too. Custom rules can be created with [custom_eucast_rules()]. -#' @param verbose a [logical] to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time. -#' @param version_breakpoints the version number to use for the EUCAST Clinical Breakpoints guideline. Can be `r vector_or(names(EUCAST_VERSION_BREAKPOINTS), reverse = TRUE)`. -#' @param version_expected_phenotypes the version number to use for the EUCAST Expected Phenotypes. Can be `r vector_or(names(EUCAST_VERSION_EXPECTED_PHENOTYPES), reverse = TRUE)`. -#' @param version_expertrules the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be `r vector_or(names(EUCAST_VERSION_EXPERT_RULES), reverse = TRUE)`. +#' @param x A data set with antimicrobials columns, such as `amox`, `AMX` and `AMC` +#' @param info A [logical] to indicate whether progress should be printed to the console - the default is only print while in interactive sessions +#' @param rules A [character] vector that specifies which rules should be applied. Must be one or more of `"breakpoints"`, `"expected_phenotypes"`, `"expert"`, `"other"`, `"custom"`, `"all"`, and defaults to `c("breakpoints", "expected_phenotypes")`. The default value can be set to another value using the package option [`AMR_eucastrules`][AMR-options]: `options(AMR_eucastrules = "all")`. If using `"custom"`, be sure to fill in argument `custom_rules` too. Custom rules can be created with [custom_eucast_rules()]. +#' @param verbose A [logical] to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time. +#' @param version_breakpoints The version number to use for the EUCAST Clinical Breakpoints guideline. Can be `r vector_or(names(EUCAST_VERSION_BREAKPOINTS), reverse = TRUE)`. +#' @param version_expected_phenotypes The version number to use for the EUCAST Expected Phenotypes. Can be `r vector_or(names(EUCAST_VERSION_EXPECTED_PHENOTYPES), reverse = TRUE)`. +#' @param version_expertrules The version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be `r vector_or(names(EUCAST_VERSION_EXPERT_RULES), reverse = TRUE)`. #' @param ampc_cephalosporin_resistance (only applies when `rules` contains `"expert"` or `"all"`) a [character] value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants - the default is `NA`. Currently only works when `version_expertrules` is `3.2` and higher; these versions of '*EUCAST Expert Rules on Enterobacterales*' state that results of cefotaxime, ceftriaxone and ceftazidime should be reported with a note, or results should be suppressed (emptied) for these three drugs. A value of `NA` (the default) for this argument will remove results for these three drugs, while e.g. a value of `"R"` will make the results for these drugs resistant. Use `NULL` or `FALSE` to not alter results for these three drugs of AmpC de-repressed cephalosporin-resistant mutants. Using `TRUE` is equal to using `"R"`. \cr For *EUCAST Expert Rules* v3.2, this rule applies to: `r vector_and(gsub("[^a-zA-Z ]+", "", unlist(strsplit(EUCAST_RULES_DF[which(EUCAST_RULES_DF$reference.version %in% c(3.2, 3.3) & EUCAST_RULES_DF$reference.rule %like% "ampc"), "this_value"][1], "|", fixed = TRUE))), quotes = "*")`. -#' @param ... column name of an antimicrobial, see section *Antimicrobials* below -#' @param ab any (vector of) text that can be coerced to a valid antimicrobial drug code with [as.ab()] -#' @param administration route of administration, either `r vector_or(dosage$administration)` -#' @param only_sir_columns a [logical] to indicate whether only antimicrobial columns must be detected that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) -#' @param custom_rules custom rules to apply, created with [custom_eucast_rules()] +#' @param ... Column name of an antimicrobial, see section *Antimicrobials* below +#' @param ab Any (vector of) text that can be coerced to a valid antimicrobial drug code with [as.ab()] +#' @param administration Route of administration, either `r vector_or(dosage$administration)` +#' @param only_sir_columns A [logical] to indicate whether only antimicrobial columns must be detected that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) +#' @param custom_rules Custom rules to apply, created with [custom_eucast_rules()] #' @param overwrite A [logical] indicating whether to overwrite non-`NA` values (default: `FALSE`). When `FALSE`, only `NA` values are modified. To ensure compliance with EUCAST guidelines, **this should remain** `FALSE`, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant." #' @inheritParams first_isolate #' @details diff --git a/R/export_biosample.R b/R/export_biosample.R index 738a63ab7..a19fc5b7e 100755 --- a/R/export_biosample.R +++ b/R/export_biosample.R @@ -30,9 +30,9 @@ #' Export Data Set as NCBI BioSample Antibiogram #' #' -#' @param x a data set -#' @param filename a character string specifying the file name -#' @param type a character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see +#' @param x A data set +#' @param filename A character string specifying the file name +#' @param type A character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see #' @keywords internal export_ncbi_biosample <- function(x, filename = paste0("biosample_", format(Sys.time(), "%Y-%m-%d-%H%M%S"), ".xlsx"), diff --git a/R/first_isolate.R b/R/first_isolate.R index c76da8826..639f5985c 100644 --- a/R/first_isolate.R +++ b/R/first_isolate.R @@ -30,26 +30,26 @@ #' Determine First Isolates #' #' Determine first isolates of all microorganisms of every patient per episode and (if needed) per specimen type. These functions support all four methods as summarised by Hindler *et al.* in 2007 (\doi{10.1086/511864}). To determine patient episodes not necessarily based on microorganisms, use [is_new_episode()] that also supports grouping with the `dplyr` package. -#' @param x a [data.frame] containing isolates. Can be left blank for automatic determination, see *Examples*. -#' @param col_date column name of the result date (or date that is was received on the lab) - the default is the first column with a date class -#' @param col_patient_id column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive) -#' @param col_mo column name of the names or codes of the microorganisms (see [as.mo()]) - the default is the first column of class [`mo`]. Values will be coerced using [as.mo()]. -#' @param col_testcode column name of the test codes. Use `col_testcode = NULL` to **not** exclude certain test codes (such as test codes for screening). In that case `testcodes_exclude` will be ignored. -#' @param col_specimen column name of the specimen type or group -#' @param col_icu column name of the logicals (`TRUE`/`FALSE`) whether a ward or department is an Intensive Care Unit (ICU). This can also be a [logical] vector with the same length as rows in `x`. +#' @param x A [data.frame] containing isolates. Can be left blank for automatic determination, see *Examples*. +#' @param col_date Column name of the result date (or date that is was received on the lab) - the default is the first column with a date class +#' @param col_patient_id Column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive) +#' @param col_mo Column name of the names or codes of the microorganisms (see [as.mo()]) - the default is the first column of class [`mo`]. Values will be coerced using [as.mo()]. +#' @param col_testcode Column name of the test codes. Use `col_testcode = NULL` to **not** exclude certain test codes (such as test codes for screening). In that case `testcodes_exclude` will be ignored. +#' @param col_specimen Column name of the specimen type or group +#' @param col_icu Column name of the logicals (`TRUE`/`FALSE`) whether a ward or department is an Intensive Care Unit (ICU). This can also be a [logical] vector with the same length as rows in `x`. #' @param col_keyantimicrobials (only useful when `method = "phenotype-based"`) column name of the key antimicrobials to determine first isolates, see [key_antimicrobials()]. The default is the first column that starts with 'key' followed by 'ab' or 'antibiotics' or 'antimicrobials' (case insensitive). Use `col_keyantimicrobials = FALSE` to prevent this. Can also be the output of [key_antimicrobials()]. -#' @param episode_days episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see *Source*. -#' @param testcodes_exclude a [character] vector with test codes that should be excluded (case-insensitive) -#' @param icu_exclude a [logical] to indicate whether ICU isolates should be excluded (rows with value `TRUE` in the column set with `col_icu`) -#' @param specimen_group value in the column set with `col_specimen` to filter on -#' @param type type to determine weighed isolates; can be `"keyantimicrobials"` or `"points"`, see *Details* -#' @param method the method to apply, either `"phenotype-based"`, `"episode-based"`, `"patient-based"` or `"isolate-based"` (can be abbreviated), see *Details*. The default is `"phenotype-based"` if antimicrobial test results are present in the data, and `"episode-based"` otherwise. +#' @param episode_days Episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see *Source*. +#' @param testcodes_exclude A [character] vector with test codes that should be excluded (case-insensitive) +#' @param icu_exclude A [logical] to indicate whether ICU isolates should be excluded (rows with value `TRUE` in the column set with `col_icu`) +#' @param specimen_group Value in the column set with `col_specimen` to filter on +#' @param type Type to determine weighed isolates; can be `"keyantimicrobials"` or `"points"`, see *Details* +#' @param method The method to apply, either `"phenotype-based"`, `"episode-based"`, `"patient-based"` or `"isolate-based"` (can be abbreviated), see *Details*. The default is `"phenotype-based"` if antimicrobial test results are present in the data, and `"episode-based"` otherwise. #' @param ignore_I [logical] to indicate whether antibiotic interpretations with `"I"` will be ignored when `type = "keyantimicrobials"`, see *Details* -#' @param points_threshold minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when `type = "points"`, see *Details* -#' @param info a [logical] to indicate info should be printed - the default is `TRUE` only in interactive mode -#' @param include_unknown a [logical] to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code `"UNKNOWN"`, which defaults to `FALSE`. For WHONET users, this means that all records with organism code `"con"` (*contamination*) will be excluded at default. Isolates with a microbial ID of `NA` will always be excluded as first isolate. -#' @param include_untested_sir a [logical] to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use `include_untested_sir = FALSE` to always return `FALSE` for such rows. This checks the data set for columns of class `sir` and consequently requires transforming columns with antibiotic results using [as.sir()] first. -#' @param ... arguments passed on to [first_isolate()] when using [filter_first_isolate()], otherwise arguments passed on to [key_antimicrobials()] (such as `universal`, `gram_negative`, `gram_positive`) +#' @param points_threshold Minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when `type = "points"`, see *Details* +#' @param info A [logical] to indicate info should be printed - the default is `TRUE` only in interactive mode +#' @param include_unknown A [logical] to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code `"UNKNOWN"`, which defaults to `FALSE`. For WHONET users, this means that all records with organism code `"con"` (*contamination*) will be excluded at default. Isolates with a microbial ID of `NA` will always be excluded as first isolate. +#' @param include_untested_sir A [logical] to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use `include_untested_sir = FALSE` to always return `FALSE` for such rows. This checks the data set for columns of class `sir` and consequently requires transforming columns with antibiotic results using [as.sir()] first. +#' @param ... Arguments passed on to [first_isolate()] when using [filter_first_isolate()], otherwise arguments passed on to [key_antimicrobials()] (such as `universal`, `gram_negative`, `gram_positive`) #' @details #' The methodology implemented in these functions is strictly based on the recommendations outlined in [CLSI Guideline M39](https://clsi.org/standards/products/microbiology/documents/m39) and the research overview by Hindler *et al.* (2007, \doi{10.1086/511864}). #' diff --git a/R/get_episode.R b/R/get_episode.R index 3deab1b10..9dda45066 100644 --- a/R/get_episode.R +++ b/R/get_episode.R @@ -30,10 +30,10 @@ #' Determine Clinical or Epidemic Episodes #' #' These functions determine which items in a vector can be considered (the start of) a new episode. This can be used to determine clinical episodes for any epidemiological analysis. The [get_episode()] function returns the index number of the episode per group, while the [is_new_episode()] function returns `TRUE` for every new [get_episode()] index. Both absolute and relative episode determination are supported. -#' @param x vector of dates (class `Date` or `POSIXt`), will be sorted internally to determine episodes -#' @param episode_days episode length in days to specify the time period after which a new episode begins, can also be less than a day or `Inf`, see *Details* +#' @param x Vector of dates (class `Date` or `POSIXt`), will be sorted internally to determine episodes +#' @param episode_days Episode length in days to specify the time period after which a new episode begins, can also be less than a day or `Inf`, see *Details* #' @param case_free_days (inter-epidemic) interval length in days after which a new episode will start, can also be less than a day or `Inf`, see *Details* -#' @param ... ignored, only in place to allow future extensions +#' @param ... Ignored, only in place to allow future extensions #' @details Episodes can be determined in two ways: absolute and relative. #' #' 1. Absolute diff --git a/R/ggplot_pca.R b/R/ggplot_pca.R index 0b1d3b95f..f18c451f5 100755 --- a/R/ggplot_pca.R +++ b/R/ggplot_pca.R @@ -30,27 +30,27 @@ #' PCA Biplot with `ggplot2` #' #' Produces a `ggplot2` variant of a so-called [biplot](https://en.wikipedia.org/wiki/Biplot) for PCA (principal component analysis), but is more flexible and more appealing than the base \R [biplot()] function. -#' @param x an object returned by [pca()], [prcomp()] or [princomp()] +#' @param x An object returned by [pca()], [prcomp()] or [princomp()] #' @inheritParams stats::biplot.prcomp -#' @param labels an optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the [pca()] function as input for `x`, this will be determined automatically based on the attribute `non_numeric_cols`, see [pca()]. -#' @param labels_textsize the size of the text used for the labels -#' @param labels_text_placement adjustment factor the placement of the variable names (`>=1` means further away from the arrow head) -#' @param groups an optional vector of groups for the labels, with the same length as `labels`. If set, the points and labels will be coloured according to these groups. When using the [pca()] function as input for `x`, this will be determined automatically based on the attribute `non_numeric_cols`, see [pca()]. -#' @param ellipse a [logical] to indicate whether a normal data ellipse should be drawn for each group (set with `groups`) -#' @param ellipse_prob statistical size of the ellipse in normal probability -#' @param ellipse_size the size of the ellipse line -#' @param ellipse_alpha the alpha (transparency) of the ellipse line -#' @param points_size the size of the points -#' @param points_alpha the alpha (transparency) of the points -#' @param arrows a [logical] to indicate whether arrows should be drawn -#' @param arrows_textsize the size of the text for variable names -#' @param arrows_colour the colour of the arrow and their text -#' @param arrows_size the size (thickness) of the arrow lines -#' @param arrows_textsize the size of the text at the end of the arrows -#' @param arrows_textangled a [logical] whether the text at the end of the arrows should be angled -#' @param arrows_alpha the alpha (transparency) of the arrows and their text -#' @param base_textsize the text size for all plot elements except the labels and arrows -#' @param ... arguments passed on to functions +#' @param labels An optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the [pca()] function as input for `x`, this will be determined automatically based on the attribute `non_numeric_cols`, see [pca()]. +#' @param labels_textsize The size of the text used for the labels +#' @param labels_text_placement Adjustment factor the placement of the variable names (`>=1` means further away from the arrow head) +#' @param groups An optional vector of groups for the labels, with the same length as `labels`. If set, the points and labels will be coloured according to these groups. When using the [pca()] function as input for `x`, this will be determined automatically based on the attribute `non_numeric_cols`, see [pca()]. +#' @param ellipse A [logical] to indicate whether a normal data ellipse should be drawn for each group (set with `groups`) +#' @param ellipse_prob Statistical size of the ellipse in normal probability +#' @param ellipse_size The size of the ellipse line +#' @param ellipse_alpha The alpha (transparency) of the ellipse line +#' @param points_size The size of the points +#' @param points_alpha The alpha (transparency) of the points +#' @param arrows A [logical] to indicate whether arrows should be drawn +#' @param arrows_textsize The size of the text for variable names +#' @param arrows_colour The colour of the arrow and their text +#' @param arrows_size The size (thickness) of the arrow lines +#' @param arrows_textsize The size of the text at the end of the arrows +#' @param arrows_textangled A [logical] whether the text at the end of the arrows should be angled +#' @param arrows_alpha The alpha (transparency) of the arrows and their text +#' @param base_textsize The text size for all plot elements except the labels and arrows +#' @param ... Arguments passed on to functions #' @source The [ggplot_pca()] function is based on the `ggbiplot()` function from the `ggbiplot` package by Vince Vu, as found on GitHub: (retrieved: 2 March 2020, their latest commit: [`7325e88`](https://github.com/vqv/ggbiplot/commit/7325e880485bea4c07465a0304c470608fffb5d9); 12 February 2015). #' #' As per their GPL-2 licence that demands documentation of code changes, the changes made based on the source code were: diff --git a/R/ggplot_sir.R b/R/ggplot_sir.R index 7334f9f91..2741316fa 100755 --- a/R/ggplot_sir.R +++ b/R/ggplot_sir.R @@ -30,25 +30,25 @@ #' AMR Plots with `ggplot2` #' #' Use these functions to create bar plots for AMR data analysis. All functions rely on [ggplot2][ggplot2::ggplot()] functions. -#' @param data a [data.frame] with column(s) of class [`sir`] (see [as.sir()]) -#' @param position position adjustment of bars, either `"fill"`, `"stack"` or `"dodge"` -#' @param x variable to show on x axis, either `"antibiotic"` (default) or `"interpretation"` or a grouping variable -#' @param fill variable to categorise using the plots legend, either `"antibiotic"` (default) or `"interpretation"` or a grouping variable -#' @param breaks a [numeric] vector of positions -#' @param limits a [numeric] vector of length two providing limits of the scale, use `NA` to refer to the existing minimum or maximum -#' @param facet variable to split plots by, either `"interpretation"` (default) or `"antibiotic"` or a grouping variable +#' @param data A [data.frame] with column(s) of class [`sir`] (see [as.sir()]) +#' @param position Position adjustment of bars, either `"fill"`, `"stack"` or `"dodge"` +#' @param x Variable to show on x axis, either `"antibiotic"` (default) or `"interpretation"` or a grouping variable +#' @param fill Variable to categorise using the plots legend, either `"antibiotic"` (default) or `"interpretation"` or a grouping variable +#' @param breaks A [numeric] vector of positions +#' @param limits A [numeric] vector of length two providing limits of the scale, use `NA` to refer to the existing minimum or maximum +#' @param facet Variable to split plots by, either `"interpretation"` (default) or `"antibiotic"` or a grouping variable #' @inheritParams proportion #' @param nrow (when using `facet`) number of rows -#' @param colours a named vactor with colour to be used for filling. The default colours are colour-blind friendly. -#' @param datalabels show datalabels using [labels_sir_count()] -#' @param datalabels.size size of the datalabels -#' @param datalabels.colour colour of the datalabels -#' @param title text to show as title of the plot -#' @param subtitle text to show as subtitle of the plot -#' @param caption text to show as caption of the plot -#' @param x.title text to show as x axis description -#' @param y.title text to show as y axis description -#' @param ... other arguments passed on to [geom_sir()] or, in case of [scale_sir_colours()], named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See *Examples*. +#' @param colours A named vactor with colour to be used for filling. The default colours are colour-blind friendly. +#' @param datalabels Show datalabels using [labels_sir_count()] +#' @param datalabels.size Size of the datalabels +#' @param datalabels.colour Colour of the datalabels +#' @param title Text to show as title of the plot +#' @param subtitle Text to show as subtitle of the plot +#' @param caption Text to show as caption of the plot +#' @param x.title Text to show as x axis description +#' @param y.title Text to show as y axis description +#' @param ... Other arguments passed on to [geom_sir()] or, in case of [scale_sir_colours()], named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See *Examples*. #' @details At default, the names of antimicrobials will be shown on the plots using [ab_name()]. This can be set with the `translate_ab` argument. See [count_df()]. #' #' [geom_sir()] will take any variable from the data that has an [`sir`] class (created with [as.sir()]) using [sir_df()] and will plot bars with the percentage S, I, and R. The default behaviour is to have the bars stacked and to have the different antimicrobials on the x axis. @@ -58,7 +58,7 @@ #' * [facet_sir()] creates 2d plots (at default based on S/I/R) using [ggplot2::facet_wrap()]. #' * [scale_y_percent()] transforms the y axis to a 0 to 100% range using [ggplot2::scale_y_continuous()]. #' * [scale_sir_colours()] sets colours to the bars (green for S, yellow for I, and red for R). with multilingual support. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. -#' * [theme_sir()] is a [ggplot2 theme][[ggplot2::theme()] with minimal distraction. +#' * [theme_sir()] is a [ggplot2 theme][ggplot2::theme()] with minimal distraction. #' * [labels_sir_count()] print datalabels on the bars with percentage and amount of isolates using [ggplot2::geom_text()]. #' #' [ggplot_sir()] is a wrapper around all above functions that uses data as first input. This makes it possible to use this function after a pipe (`%>%`). See *Examples*. diff --git a/R/guess_ab_col.R b/R/guess_ab_col.R index b6584f5b0..228e7ab22 100755 --- a/R/guess_ab_col.R +++ b/R/guess_ab_col.R @@ -30,10 +30,10 @@ #' Guess Antibiotic Column #' #' This tries to find a column name in a data set based on information from the [antimicrobials] data set. Also supports WHONET abbreviations. -#' @param x a [data.frame] -#' @param search_string a text to search `x` for, will be checked with [as.ab()] if this value is not a column in `x` -#' @param verbose a [logical] to indicate whether additional info should be printed -#' @param only_sir_columns a [logical] to indicate whether only antibiotic columns must be detected that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) +#' @param x A [data.frame] +#' @param search_string A text to search `x` for, will be checked with [as.ab()] if this value is not a column in `x` +#' @param verbose A [logical] to indicate whether additional info should be printed +#' @param only_sir_columns A [logical] to indicate whether only antibiotic columns must be detected that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) #' @details You can look for an antibiotic (trade) name or abbreviation and it will search `x` and the [antimicrobials] data set for any column containing a name or code of that antibiotic. #' @return A column name of `x`, or `NULL` when no result is found. #' @export diff --git a/R/italicise_taxonomy.R b/R/italicise_taxonomy.R index 9c7bded87..ddc38fc25 100755 --- a/R/italicise_taxonomy.R +++ b/R/italicise_taxonomy.R @@ -30,8 +30,8 @@ #' Italicise Taxonomic Families, Genera, Species, Subspecies #' #' According to the binomial nomenclature, the lowest four taxonomic levels (family, genus, species, subspecies) should be printed in italics. This function finds taxonomic names within strings and makes them italic. -#' @param string a [character] (vector) -#' @param type type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see *Details* +#' @param string A [character] (vector) +#' @param type Type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see *Details* #' @details #' This function finds the taxonomic names and makes them italic based on the [microorganisms] data set. #' diff --git a/R/join_microorganisms.R b/R/join_microorganisms.R index 6b1848c44..fadb2feb1 100755 --- a/R/join_microorganisms.R +++ b/R/join_microorganisms.R @@ -33,10 +33,10 @@ #' @rdname join #' @name join #' @aliases join inner_join -#' @param x existing data set to join, or [character] vector. In case of a [character] vector, the resulting [data.frame] will contain a column 'x' with these values. -#' @param by a variable to join by - if left empty will search for a column with class [`mo`] (created with [as.mo()]) or will be `"mo"` if that column name exists in `x`, could otherwise be a column name of `x` with values that exist in `microorganisms$mo` (such as `by = "bacteria_id"`), or another column in [microorganisms] (but then it should be named, like `by = c("bacteria_id" = "fullname")`) -#' @param suffix if there are non-joined duplicate variables in `x` and `y`, these suffixes will be added to the output to disambiguate them. Should be a [character] vector of length 2. -#' @param ... ignored, only in place to allow future extensions +#' @param x Existing data set to join, or [character] vector. In case of a [character] vector, the resulting [data.frame] will contain a column 'x' with these values. +#' @param by A variable to join by - if left empty will search for a column with class [`mo`] (created with [as.mo()]) or will be `"mo"` if that column name exists in `x`, could otherwise be a column name of `x` with values that exist in `microorganisms$mo` (such as `by = "bacteria_id"`), or another column in [microorganisms] (but then it should be named, like `by = c("bacteria_id" = "fullname")`) +#' @param suffix If there are non-joined duplicate variables in `x` and `y`, these suffixes will be added to the output to disambiguate them. Should be a [character] vector of length 2. +#' @param ... Ignored, only in place to allow future extensions #' @details **Note:** As opposed to the `join()` functions of `dplyr`, [character] vectors are supported and at default existing columns will get a suffix `"2"` and the newly joined columns will not get a suffix. #' #' If the `dplyr` package is installed, their join functions will be used. Otherwise, the much slower [merge()] and [interaction()] functions from base \R will be used. diff --git a/R/key_antimicrobials.R b/R/key_antimicrobials.R index 9423f33d5..4d2f833c3 100755 --- a/R/key_antimicrobials.R +++ b/R/key_antimicrobials.R @@ -30,15 +30,15 @@ #' (Key) Antimicrobials for First Weighted Isolates #' #' These functions can be used to determine first weighted isolates by considering the phenotype for isolate selection (see [first_isolate()]). Using a phenotype-based method to determine first isolates is more reliable than methods that disregard phenotypes. -#' @param x a [data.frame] with antimicrobials columns, like `AMX` or `amox`. Can be left blank to determine automatically. +#' @param x A [data.frame] with antimicrobials columns, like `AMX` or `amox`. Can be left blank to determine automatically. #' @param y,z [character] vectors to compare #' @inheritParams first_isolate -#' @param universal names of **broad-spectrum** antimicrobial drugs, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antimicrobial drugs -#' @param gram_negative names of antibiotic drugs for **Gram-positives**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antibiotic drugs -#' @param gram_positive names of antibiotic drugs for **Gram-negatives**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antibiotic drugs -#' @param antifungal names of antifungal drugs for **fungi**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antifungal drugs -#' @param only_sir_columns a [logical] to indicate whether only columns must be included that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) -#' @param ... ignored, only in place to allow future extensions +#' @param universal Names of **broad-spectrum** antimicrobial drugs, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antimicrobial drugs +#' @param gram_negative Names of antibiotic drugs for **Gram-positives**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antibiotic drugs +#' @param gram_positive Names of antibiotic drugs for **Gram-negatives**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antibiotic drugs +#' @param antifungal Names of antifungal drugs for **fungi**, case-insensitive. Set to `NULL` to ignore. See *Details* for the default antifungal drugs +#' @param only_sir_columns A [logical] to indicate whether only columns must be included that were transformed to class `sir` (see [as.sir()]) on beforehand (default is `FALSE`) +#' @param ... Ignored, only in place to allow future extensions #' @details #' The [key_antimicrobials()] and [all_antimicrobials()] functions are context-aware. This means that the `x` argument can be left blank if used inside a [data.frame] call, see *Examples*. #' diff --git a/R/kurtosis.R b/R/kurtosis.R index ad38adae3..236a5d2e3 100755 --- a/R/kurtosis.R +++ b/R/kurtosis.R @@ -30,9 +30,9 @@ #' Kurtosis of the Sample #' #' @description Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. A normal distribution has a kurtosis of 3 and a excess kurtosis of 0. -#' @param x a vector of values, a [matrix] or a [data.frame] -#' @param na.rm a [logical] to indicate whether `NA` values should be stripped before the computation proceeds -#' @param excess a [logical] to indicate whether the *excess kurtosis* should be returned, defined as the kurtosis minus 3. +#' @param x A vector of values, a [matrix] or a [data.frame] +#' @param na.rm A [logical] to indicate whether `NA` values should be stripped before the computation proceeds +#' @param excess A [logical] to indicate whether the *excess kurtosis* should be returned, defined as the kurtosis minus 3. #' @seealso [skewness()] #' @rdname kurtosis #' @export diff --git a/R/like.R b/R/like.R index f5ff23146..9429b5b1e 100755 --- a/R/like.R +++ b/R/like.R @@ -30,9 +30,9 @@ #' Vectorised Pattern Matching with Keyboard Shortcut #' #' Convenient wrapper around [grepl()] to match a pattern: `x %like% pattern`. It always returns a [`logical`] vector and is always case-insensitive (use `x %like_case% pattern` for case-sensitive matching). Also, `pattern` can be as long as `x` to compare items of each index in both vectors, or they both can have the same length to iterate over all cases. -#' @param x a [character] vector where matches are sought, or an object which can be coerced by [as.character()] to a [character] vector. -#' @param pattern a [character] vector containing regular expressions (or a [character] string for `fixed = TRUE`) to be matched in the given [character] vector. Coerced by [as.character()] to a [character] string if possible. -#' @param ignore.case if `FALSE`, the pattern matching is *case sensitive* and if `TRUE`, case is ignored during matching. +#' @param x A [character] vector where matches are sought, or an object which can be coerced by [as.character()] to a [character] vector. +#' @param pattern A [character] vector containing regular expressions (or a [character] string for `fixed = TRUE`) to be matched in the given [character] vector. Coerced by [as.character()] to a [character] string if possible. +#' @param ignore.case If `FALSE`, the pattern matching is *case sensitive* and if `TRUE`, case is ignored during matching. #' @return A [logical] vector #' @name like #' @rdname like diff --git a/R/mdro.R b/R/mdro.R index b2742d7e9..00f6ca375 100755 --- a/R/mdro.R +++ b/R/mdro.R @@ -30,20 +30,20 @@ #' Determine Multidrug-Resistant Organisms (MDRO) #' #' Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national, or custom guidelines. -#' @param x a [data.frame] with antimicrobials columns, like `AMX` or `amox`. Can be left blank for automatic determination. -#' @param guideline a specific guideline to follow, see sections *Supported international / national guidelines* and *Using Custom Guidelines* below. When left empty, the publication by Magiorakos *et al.* (see below) will be followed. +#' @param x A [data.frame] with antimicrobials columns, like `AMX` or `amox`. Can be left blank for automatic determination. +#' @param guideline A specific guideline to follow, see sections *Supported international / national guidelines* and *Using Custom Guidelines* below. When left empty, the publication by Magiorakos *et al.* (see below) will be followed. #' @param esbl [logical] values, or a column name containing logical values, indicating the presence of an ESBL gene (or production of its proteins) #' @param carbapenemase [logical] values, or a column name containing logical values, indicating the presence of a carbapenemase gene (or production of its proteins) #' @param mecA [logical] values, or a column name containing logical values, indicating the presence of a *mecA* gene (or production of its proteins) #' @param mecC [logical] values, or a column name containing logical values, indicating the presence of a *mecC* gene (or production of its proteins) #' @param vanA [logical] values, or a column name containing logical values, indicating the presence of a *vanA* gene (or production of its proteins) #' @param vanB [logical] values, or a column name containing logical values, indicating the presence of a *vanB* gene (or production of its proteins) -#' @param ... in case of [custom_mdro_guideline()]: a set of rules, see section *Using Custom Guidelines* below. Otherwise: column name of an antibiotic, see section *Antimicrobials* below. -#' @param as_factor a [logical] to indicate whether the returned value should be an ordered [factor] (`TRUE`, default), or otherwise a [character] vector +#' @param ... In case of [custom_mdro_guideline()]: a set of rules, see section *Using Custom Guidelines* below. Otherwise: column name of an antibiotic, see section *Antimicrobials* below. +#' @param as_factor A [logical] to indicate whether the returned value should be an ordered [factor] (`TRUE`, default), or otherwise a [character] vector #' @inheritParams eucast_rules -#' @param pct_required_classes minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for *S. aureus*. Setting this `pct_required_classes` argument to `0.5` (default) means that for every *S. aureus* isolate at least 8 different classes must be available. Any lower number of available classes will return `NA` for that isolate. -#' @param combine_SI a [logical] to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the [mdro()] function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using `combine_SI = FALSE`, resistance is considered when isolates are R or I. -#' @param verbose a [logical] to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not. +#' @param pct_required_classes Minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for *S. aureus*. Setting this `pct_required_classes` argument to `0.5` (default) means that for every *S. aureus* isolate at least 8 different classes must be available. Any lower number of available classes will return `NA` for that isolate. +#' @param combine_SI A [logical] to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the [mdro()] function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using `combine_SI = FALSE`, resistance is considered when isolates are R or I. +#' @param verbose A [logical] to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not. #' @inheritSection eucast_rules Antimicrobials #' @details #' These functions are context-aware. This means that the `x` argument can be left blank if used inside a [data.frame] call, see *Examples*. diff --git a/R/mean_amr_distance.R b/R/mean_amr_distance.R index 1cbba0f5f..cf492b56d 100755 --- a/R/mean_amr_distance.R +++ b/R/mean_amr_distance.R @@ -30,9 +30,9 @@ #' Calculate the Mean AMR Distance #' #' Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand. -#' @param x a vector of class [sir][as.sir()], [mic][as.mic()] or [disk][as.disk()], or a [data.frame] containing columns of any of these classes -#' @param ... variables to select (supports [tidyselect language][tidyselect::language] such as `column1:column4` and `where(is.mic)`, and can thus also be [antimicrobial selectors][amr_selector()] -#' @param combine_SI a [logical] to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is `TRUE` +#' @param x A vector of class [sir][as.sir()], [mic][as.mic()] or [disk][as.disk()], or a [data.frame] containing columns of any of these classes +#' @param ... Variables to select. Supports [tidyselect language][tidyselect::language] (such as `column1:column4` and `where(is.mic)`), and can thus also be [antimicrobial selectors][amr_selector()] +#' @param combine_SI A [logical] to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is `TRUE` #' @details The mean AMR distance is effectively [the Z-score](https://en.wikipedia.org/wiki/Standard_score); a normalised numeric value to compare AMR test results which can help to identify similar isolates, without comparing antibiograms by hand. #' #' MIC values (see [as.mic()]) are transformed with [log2()] first; their distance is thus calculated as `(log2(x) - mean(log2(x))) / sd(log2(x))`. @@ -69,7 +69,7 @@ #' ) #' y #' mean_amr_distance(y) -#' y$amr_distance <- mean_amr_distance(y, where(is.mic)) +#' y$amr_distance <- mean_amr_distance(y, is.mic(y)) #' y[order(y$amr_distance), ] #' #' if (require("dplyr")) { @@ -171,8 +171,8 @@ mean_amr_distance.data.frame <- function(x, ..., combine_SI = TRUE) { } #' @rdname mean_amr_distance -#' @param amr_distance the outcome of [mean_amr_distance()] -#' @param row an index, such as a row number +#' @param amr_distance The outcome of [mean_amr_distance()] +#' @param row An index, such as a row number #' @export amr_distance_from_row <- function(amr_distance, row) { meet_criteria(amr_distance, allow_class = "numeric", is_finite = TRUE) diff --git a/R/mic.R b/R/mic.R index 457e1d244..3c8f9568e 100644 --- a/R/mic.R +++ b/R/mic.R @@ -60,10 +60,10 @@ COMMON_MIC_VALUES <- c( #' #' 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. #' @rdname as.mic -#' @param x a [character] or [numeric] vector -#' @param na.rm a [logical] indicating whether missing values should be removed -#' @param keep_operators a [character] specifying how to handle operators (such as `>` and `<=`) in the input. Accepts one of three values: `"all"` (or `TRUE`) to keep all operators, `"none"` (or `FALSE`) to remove all operators, or `"edges"` to keep operators only at both ends of the range. -#' @param ... arguments passed on to methods +#' @param x A [character] or [numeric] vector +#' @param na.rm A [logical] indicating whether missing values should be removed +#' @param keep_operators A [character] specifying how to handle operators (such as `>` and `<=`) in the input. Accepts one of three values: `"all"` (or `TRUE`) to keep all operators, `"none"` (or `FALSE`) to remove all operators, or `"edges"` to keep operators only at both ends of the range. +#' @param ... Arguments passed on to methods #' @details To interpret MIC values as SIR values, use [as.sir()] on MIC values. It supports guidelines from EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`) and CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`). #' #' 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: @@ -102,10 +102,12 @@ COMMON_MIC_VALUES <- c( #' #> 10 16 A #' ``` #' -#' All so-called [group generic functions][groupGeneric()] 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. +#' All so-called [group generic functions][groupGeneric()] are implemented for the MIC class (such as `!`, `!=`, `<`, `>=`, [exp()], [log2()]). Some mathematical functions 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 [factor]s, it will return the index of the factor levels (which is often useless for regular users). #' +#' The function [is.mic()] detects if the input contains class `mic`. If the input is a [data.frame] or [list], it iterates over all columns/items and returns a [logical] vector. +#' #' 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. @@ -285,7 +287,11 @@ as.mic <- function(x, na.rm = FALSE, keep_operators = "all") { #' @rdname as.mic #' @export is.mic <- function(x) { - inherits(x, "mic") + if (identical(typeof(x), "list")) { + unname(vapply(FUN.VALUE = logical(1), x, is.mic)) + } else { + isTRUE(inherits(x, "mic")) + } } #' @rdname as.mic @@ -297,7 +303,7 @@ NA_mic_ <- set_clean_class(factor(NA, levels = VALID_MIC_LEVELS, ordered = TRUE) ) #' @rdname as.mic -#' @param mic_range a manual range to rescale the MIC values, e.g., `mic_range = c(0.001, 32)`. Use `NA` to prevent rescaling on one side, e.g., `mic_range = c(NA, 32)`. +#' @param mic_range A manual range to rescale the MIC values, e.g., `mic_range = c(0.001, 32)`. Use `NA` to prevent rescaling on one side, e.g., `mic_range = c(NA, 32)`. #' @export rescale_mic <- function(x, mic_range, keep_operators = "edges", as.mic = TRUE) { meet_criteria(mic_range, allow_class = c("numeric", "integer", "logical", "mic"), has_length = 2, allow_NA = TRUE, allow_NULL = TRUE) @@ -395,7 +401,7 @@ as.numeric.mic <- function(x, ...) { #' @rdname as.mic #' @method droplevels mic -#' @param as.mic a [logical] to indicate whether the `mic` class should be kept - the default is `TRUE` for [rescale_mic()] and `FALSE` for [droplevels()]. When setting this to `FALSE` in [rescale_mic()], the output will have factor levels that acknowledge `mic_range`. +#' @param as.mic A [logical] to indicate whether the `mic` class should be kept - the default is `TRUE` for [rescale_mic()] and `FALSE` for [droplevels()]. When setting this to `FALSE` in [rescale_mic()], the output will have factor levels that acknowledge `mic_range`. #' @export droplevels.mic <- function(x, as.mic = FALSE, ...) { x <- as.mic(x) # make sure that currently implemented MIC levels are used diff --git a/R/mo.R b/R/mo.R index 479c0d82d..6cc33ba20 100755 --- a/R/mo.R +++ b/R/mo.R @@ -30,22 +30,22 @@ #' Transform Arbitrary Input to Valid Microbial Taxonomy #' #' 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 `r vector_and(unique(microorganisms$kingdom[which(!grepl("(unknown|Fungi)", microorganisms$kingdom))]), quotes = FALSE)`, 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*. -#' @param x a [character] vector or a [data.frame] with one or two columns -#' @param Becker a [logical] to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker *et al.* (see *Source*). Please see *Details* for a full list of staphylococcal species that will be converted. +#' @param x A [character] vector or a [data.frame] with one or two columns +#' @param Becker A [logical] to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker *et al.* (see *Source*). Please see *Details* for a full list of staphylococcal species that will be converted. #' #' This excludes *Staphylococcus aureus* at default, use `Becker = "all"` to also categorise *S. aureus* as "CoPS". -#' @param Lancefield a [logical] to indicate whether a beta-haemolytic *Streptococcus* should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see *Source*). These streptococci will be categorised in their first group, e.g. *Streptococcus dysgalactiae* will be group C, although officially it was also categorised into groups G and L. . Please see *Details* for a full list of streptococcal species that will be converted. +#' @param Lancefield A [logical] to indicate whether a beta-haemolytic *Streptococcus* should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see *Source*). These streptococci will be categorised in their first group, e.g. *Streptococcus dysgalactiae* will be group C, although officially it was also categorised into groups G and L. . Please see *Details* for a full list of streptococcal species that will be converted. #' #' This excludes enterococci at default (who are in group D), use `Lancefield = "all"` to also categorise all enterococci as group D. -#' @param minimum_matching_score a numeric value to set as the lower limit for the [MO matching score][mo_matching_score()]. When left blank, this will be determined automatically based on the character length of `x`, its [taxonomic kingdom][microorganisms] and [human pathogenicity][mo_matching_score()]. -#' @param keep_synonyms a [logical] to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is `FALSE`, which will return a note if old taxonomic names were processed. The default can be set with the package option [`AMR_keep_synonyms`][AMR-options], i.e. `options(AMR_keep_synonyms = TRUE)` or `options(AMR_keep_synonyms = FALSE)`. -#' @param reference_df a [data.frame] to be used for extra reference when translating `x` to a valid [`mo`]. See [set_mo_source()] and [get_mo_source()] to automate the usage of your own codes (e.g. used in your analysis or organisation). -#' @param ignore_pattern a Perl-compatible [regular expression][base::regex] (case-insensitive) of which all matches in `x` must return `NA`. This can be convenient to exclude known non-relevant input and can also be set with the package option [`AMR_ignore_pattern`][AMR-options], e.g. `options(AMR_ignore_pattern = "(not reported|contaminated flora)")`. -#' @param cleaning_regex a Perl-compatible [regular expression][base::regex] (case-insensitive) to clean the input of `x`. Every matched part in `x` will be removed. At default, this is the outcome of [mo_cleaning_regex()], which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option [`AMR_cleaning_regex`][AMR-options]. -#' @param only_fungi a [logical] to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for [all microorganism functions][mo_property()] with the package option [`AMR_only_fungi`][AMR-options], i.e. `options(AMR_only_fungi = TRUE)`. -#' @param language language to translate text like "no growth", which defaults to the system language (see [get_AMR_locale()]) -#' @param info a [logical] to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is `TRUE` only in interactive mode. -#' @param ... other arguments passed on to functions +#' @param minimum_matching_score A numeric value to set as the lower limit for the [MO matching score][mo_matching_score()]. When left blank, this will be determined automatically based on the character length of `x`, its [taxonomic kingdom][microorganisms] and [human pathogenicity][mo_matching_score()]. +#' @param keep_synonyms A [logical] to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is `FALSE`, which will return a note if old taxonomic names were processed. The default can be set with the package option [`AMR_keep_synonyms`][AMR-options], i.e. `options(AMR_keep_synonyms = TRUE)` or `options(AMR_keep_synonyms = FALSE)`. +#' @param reference_df A [data.frame] to be used for extra reference when translating `x` to a valid [`mo`]. See [set_mo_source()] and [get_mo_source()] to automate the usage of your own codes (e.g. used in your analysis or organisation). +#' @param ignore_pattern A Perl-compatible [regular expression][base::regex] (case-insensitive) of which all matches in `x` must return `NA`. This can be convenient to exclude known non-relevant input and can also be set with the package option [`AMR_ignore_pattern`][AMR-options], e.g. `options(AMR_ignore_pattern = "(not reported|contaminated flora)")`. +#' @param cleaning_regex A Perl-compatible [regular expression][base::regex] (case-insensitive) to clean the input of `x`. Every matched part in `x` will be removed. At default, this is the outcome of [mo_cleaning_regex()], which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option [`AMR_cleaning_regex`][AMR-options]. +#' @param only_fungi A [logical] to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for [all microorganism functions][mo_property()] with the package option [`AMR_only_fungi`][AMR-options], i.e. `options(AMR_only_fungi = TRUE)`. +#' @param language Language to translate text like "no growth", which defaults to the system language (see [get_AMR_locale()]) +#' @param info A [logical] to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is `TRUE` only in interactive mode. +#' @param ... Other arguments passed on to functions #' @rdname as.mo #' @aliases mo #' @details diff --git a/R/mo_property.R b/R/mo_property.R index 25cb106c4..38ced6760 100755 --- a/R/mo_property.R +++ b/R/mo_property.R @@ -30,12 +30,12 @@ #' Get Properties of a Microorganism #' #' Use these functions to return a specific property of a microorganism based on the latest accepted taxonomy. All input values will be evaluated internally with [as.mo()], which makes it possible to use microbial abbreviations, codes and names as input. See *Examples*. -#' @param x any [character] (vector) that can be coerced to a valid microorganism code with [as.mo()]. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see *Examples*. -#' @param property one of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`, or must be `"shortname"` +#' @param x Any [character] (vector) that can be coerced to a valid microorganism code with [as.mo()]. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see *Examples*. +#' @param property One of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`, or must be `"shortname"` #' @inheritParams as.mo -#' @param ... other arguments passed on to [as.mo()], such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input' -#' @param ab any (vector of) text that can be coerced to a valid antibiotic drug code with [as.ab()] -#' @param open browse the URL using [`browseURL()`][utils::browseURL()] +#' @param ... Other arguments passed on to [as.mo()], such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input' +#' @param ab Any (vector of) text that can be coerced to a valid antibiotic drug code with [as.ab()] +#' @param open Browse the URL using [`browseURL()`][utils::browseURL()] #' @details All functions will, at default, **not** keep old taxonomic properties, as synonyms are automatically replaced with the current taxonomy. Take for example *Enterobacter aerogenes*, which was initially named in 1960 but renamed to *Klebsiella aerogenes* in 2017: #' - `mo_genus("Enterobacter aerogenes")` will return `"Klebsiella"` (with a note about the renaming) #' - `mo_genus("Enterobacter aerogenes", keep_synonyms = TRUE)` will return `"Enterobacter"` (with a once-per-session warning that the name is outdated) diff --git a/R/mo_source.R b/R/mo_source.R index 13b860945..55b6aa7a8 100755 --- a/R/mo_source.R +++ b/R/mo_source.R @@ -32,8 +32,8 @@ #' @description These functions can be used to predefine your own reference to be used in [as.mo()] and consequently all [`mo_*`][mo_property()] functions (such as [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, since you don't have to bother about it again after setting it up once. -#' @param path location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see *Details*). Can also be `""`, `NULL` or `FALSE` to delete the reference file. -#' @param destination destination of the compressed data file - the default is the user's home directory. +#' @param path Location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see *Details*). Can also be `""`, `NULL` or `FALSE` to delete the reference file. +#' @param destination Destination of the compressed data file - the default is the user's home directory. #' @rdname mo_source #' @name mo_source #' @aliases set_mo_source get_mo_source diff --git a/R/pca.R b/R/pca.R index 0a9d7049c..4c7303b5b 100755 --- a/R/pca.R +++ b/R/pca.R @@ -30,8 +30,8 @@ #' Principal Component Analysis (for AMR) #' #' Performs a principal component analysis (PCA) based on a data set with automatic determination for afterwards plotting the groups and labels, and automatic filtering on only suitable (i.e. non-empty and numeric) variables. -#' @param x a [data.frame] containing [numeric] columns -#' @param ... columns of `x` to be selected for PCA, can be unquoted since it supports quasiquotation. +#' @param x A [data.frame] containing [numeric] columns +#' @param ... Columns of `x` to be selected for PCA, can be unquoted since it supports quasiquotation. #' @inheritParams stats::prcomp #' @details The [pca()] function takes a [data.frame] as input and performs the actual PCA with the \R function [prcomp()]. #' diff --git a/R/plotting.R b/R/plotting.R index 3df9a5596..ca59a5ed3 100755 --- a/R/plotting.R +++ b/R/plotting.R @@ -33,17 +33,17 @@ #' Functions to plot classes `sir`, `mic` and `disk`, with support for base \R and `ggplot2`. #' #' Especially the `scale_*_mic()` functions are relevant wrappers to plot MIC values for `ggplot2`. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values. -#' @param x,object values created with [as.mic()], [as.disk()] or [as.sir()] (or their `random_*` variants, such as [random_mic()]) -#' @param mo any (vector of) text that can be coerced to a valid microorganism code with [as.mo()] -#' @param ab any (vector of) text that can be coerced to a valid antimicrobial drug code with [as.ab()] -#' @param guideline interpretation guideline to use - the default is the latest included EUCAST guideline, see *Details* -#' @param main,title title of the plot -#' @param xlab,ylab axis title -#' @param colours_SIR colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly. -#' @param language language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see [get_AMR_locale()]) and can be overwritten by setting the package option [`AMR_locale`][AMR-options], e.g. `options(AMR_locale = "de")`, see [translate]. Use `language = NULL` to prevent translation. -#' @param expand a [logical] to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled. -#' @param aesthetics aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size" -#' @param eucast_I a [logical] to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be `TRUE` if the default [AMR interpretation guideline][as.sir()] is set to EUCAST (which is the default). With `FALSE`, it will be interpreted as "Intermediate". +#' @param x,object Values created with [as.mic()], [as.disk()] or [as.sir()] (or their `random_*` variants, such as [random_mic()]) +#' @param mo Any (vector of) text that can be coerced to a valid microorganism code with [as.mo()] +#' @param ab Any (vector of) text that can be coerced to a valid antimicrobial drug code with [as.ab()] +#' @param guideline Interpretation guideline to use - the default is the latest included EUCAST guideline, see *Details* +#' @param main,title Title of the plot +#' @param xlab,ylab Axis title +#' @param colours_SIR Colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly. +#' @param language Language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see [get_AMR_locale()]) and can be overwritten by setting the package option [`AMR_locale`][AMR-options], e.g. `options(AMR_locale = "de")`, see [translate]. Use `language = NULL` to prevent translation. +#' @param expand A [logical] to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled. +#' @param aesthetics Aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size" +#' @param eucast_I A [logical] to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be `TRUE` if the default [AMR interpretation guideline][as.sir()] is set to EUCAST (which is the default). With `FALSE`, it will be interpreted as "Intermediate". #' @inheritParams as.sir #' @param mic_range A manual range to rescale the MIC values (using [rescale_mic()]), e.g., `mic_range = c(0.001, 32)`. Use `NA` to prevent rescaling on one side, e.g., `mic_range = c(NA, 32)`. **Note:** This rescales values but does not filter them - use the ggplot2 `limits` argument separately to exclude values from the plot. #' @inheritParams as.mic @@ -65,7 +65,7 @@ #' * [facet_sir()] creates 2d plots (at default based on S/I/R) using [ggplot2::facet_wrap()]. #' * [scale_y_percent()] transforms the y axis to a 0 to 100% range using [ggplot2::scale_y_continuous()]. #' * [scale_sir_colours()] allows to set colours to any aesthetic, even for `shape` or `linetype`. -#' * [theme_sir()] is a [ggplot2 theme][[ggplot2::theme()] with minimal distraction. +#' * [theme_sir()] is a [ggplot2 theme][ggplot2::theme()] with minimal distraction. #' * [labels_sir_count()] print datalabels on the bars with percentage and number of isolates, using [ggplot2::geom_text()]. #' #' The interpretation of "I" will be named "Increased exposure" for all EUCAST guidelines since 2019, and will be named "Intermediate" in all other cases. @@ -74,7 +74,7 @@ #' @name plot #' @rdname plot #' @return The `autoplot()` functions return a [`ggplot`][ggplot2::ggplot()] model that is extendible with any `ggplot2` function. -#' @param ... arguments passed on to methods +#' @param ... Arguments passed on to methods #' @examples #' some_mic_values <- random_mic(size = 100) #' some_disk_values <- random_disk(size = 100, mo = "Escherichia coli", ab = "cipro") diff --git a/R/proportion.R b/R/proportion.R index f27f70bad..3e3262fd4 100644 --- a/R/proportion.R +++ b/R/proportion.R @@ -32,18 +32,18 @@ #' @description These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in `summarise()` from the `dplyr` package and also support grouped variables, see *Examples*. #' #' [resistance()] should be used to calculate resistance, [susceptibility()] should be used to calculate susceptibility.\cr -#' @param ... one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with [as.sir()] if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See *Examples*. -#' @param minimum the minimum allowed number of available (tested) isolates. Any isolate count lower than `minimum` will return `NA` with a warning. The default number of `30` isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see *Source*. -#' @param as_percent a [logical] to indicate whether the output must be returned as a hundred fold with % sign (a character). A value of `0.123456` will then be returned as `"12.3%"`. +#' @param ... One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with [as.sir()] if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See *Examples*. +#' @param minimum The minimum allowed number of available (tested) isolates. Any isolate count lower than `minimum` will return `NA` with a warning. The default number of `30` isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see *Source*. +#' @param as_percent A [logical] to indicate whether the output must be returned as a hundred fold with % sign (a character). A value of `0.123456` will then be returned as `"12.3%"`. #' @param only_all_tested (for combination therapies, i.e. using more than one variable for `...`): a [logical] to indicate that isolates must be tested for all antimicrobials, see section *Combination Therapy* below -#' @param data a [data.frame] containing columns with class [`sir`] (see [as.sir()]) -#' @param translate_ab a column name of the [antimicrobials] data set to translate the antibiotic abbreviations to, using [ab_property()] +#' @param data A [data.frame] containing columns with class [`sir`] (see [as.sir()]) +#' @param translate_ab A column name of the [antimicrobials] data set to translate the antibiotic abbreviations to, using [ab_property()] #' @inheritParams ab_property -#' @param combine_SI a [logical] to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is `TRUE` -#' @param ab_result antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R" -#' @param confidence_level the confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using [binom.test()], i.e., the Clopper-Pearson method. -#' @param side the side of the confidence interval to return. The default is `"both"` for a length 2 vector, but can also be (abbreviated as) `"min"`/`"left"`/`"lower"`/`"less"` or `"max"`/`"right"`/`"higher"`/`"greater"`. -#' @param collapse a [logical] to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing +#' @param combine_SI A [logical] to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is `TRUE` +#' @param ab_result Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R" +#' @param confidence_level The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using [binom.test()], i.e., the Clopper-Pearson method. +#' @param side The side of the confidence interval to return. The default is `"both"` for a length 2 vector, but can also be (abbreviated as) `"min"`/`"left"`/`"lower"`/`"less"` or `"max"`/`"right"`/`"higher"`/`"greater"`. +#' @param collapse A [logical] to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing #' @inheritSection as.sir Interpretation of SIR #' @details #' For a more automated and comprehensive analysis, consider using [antibiogram()] or [wisca()], which streamline many aspects of susceptibility reporting and, importantly, also support WISCA. The functions described here offer a more hands-on, manual approach for greater customisation. diff --git a/R/random.R b/R/random.R index 60443e875..33a3582a5 100755 --- a/R/random.R +++ b/R/random.R @@ -30,11 +30,11 @@ #' Random MIC Values/Disk Zones/SIR Generation #' #' These functions can be used for generating random MIC values and disk diffusion diameters, for AMR data analysis practice. By providing a microorganism and antimicrobial drug, the generated results will reflect reality as much as possible. -#' @param size desired size of the returned vector. If used in a [data.frame] call or `dplyr` verb, will get the current (group) size if left blank. -#' @param mo any [character] that can be coerced to a valid microorganism code with [as.mo()] -#' @param ab any [character] that can be coerced to a valid antimicrobial drug code with [as.ab()] -#' @param prob_SIR a vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value) -#' @param ... ignored, only in place to allow future extensions +#' @param size Desired size of the returned vector. If used in a [data.frame] call or `dplyr` verb, will get the current (group) size if left blank. +#' @param mo Any [character] that can be coerced to a valid microorganism code with [as.mo()] +#' @param ab Any [character] that can be coerced to a valid antimicrobial drug code with [as.ab()] +#' @param prob_SIR A vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value) +#' @param ... Ignored, only in place to allow future extensions #' @details The base \R function [sample()] is used for generating values. #' #' Generated values are based on the EUCAST `r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))` guideline as implemented in the [clinical_breakpoints] data set. To create specific generated values per bug or drug, set the `mo` and/or `ab` argument. diff --git a/R/resistance_predict.R b/R/resistance_predict.R index e55d22334..434339990 100755 --- a/R/resistance_predict.R +++ b/R/resistance_predict.R @@ -30,20 +30,20 @@ #' Predict Antimicrobial Resistance #' #' Create a prediction model to predict antimicrobial resistance for the next years on statistical solid ground. Standard errors (SE) will be returned as columns `se_min` and `se_max`. See *Examples* for a real live example. -#' @param object model data to be plotted -#' @param col_ab column name of `x` containing antimicrobial interpretations (`"R"`, `"I"` and `"S"`) -#' @param col_date column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class -#' @param year_min lowest year to use in the prediction model, dafaults to the lowest year in `col_date` -#' @param year_max highest year to use in the prediction model - the default is 10 years after today -#' @param year_every unit of sequence between lowest year found in the data and `year_max` -#' @param minimum minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model. -#' @param model the statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using `glm(..., family = binomial)`, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See *Details* for all valid options. -#' @param I_as_S a [logical] to indicate whether values `"I"` should be treated as `"S"` (will otherwise be treated as `"R"`). The default, `TRUE`, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section *Interpretation of S, I and R* below. -#' @param preserve_measurements a [logical] to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be `NA`. -#' @param info a [logical] to indicate whether textual analysis should be printed with the name and [summary()] of the statistical model. -#' @param main title of the plot -#' @param ribbon a [logical] to indicate whether a ribbon should be shown (default) or error bars -#' @param ... arguments passed on to functions +#' @param object Model data to be plotted +#' @param col_ab Column name of `x` containing antimicrobial interpretations (`"R"`, `"I"` and `"S"`) +#' @param col_date Column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class +#' @param year_min Lowest year to use in the prediction model, dafaults to the lowest year in `col_date` +#' @param year_max Highest year to use in the prediction model - the default is 10 years after today +#' @param year_every Unit of sequence between lowest year found in the data and `year_max` +#' @param minimum Minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model. +#' @param model The statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using `glm(..., family = binomial)`, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See *Details* for all valid options. +#' @param I_as_S A [logical] to indicate whether values `"I"` should be treated as `"S"` (will otherwise be treated as `"R"`). The default, `TRUE`, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section *Interpretation of S, I and R* below. +#' @param preserve_measurements A [logical] to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be `NA`. +#' @param info A [logical] to indicate whether textual analysis should be printed with the name and [summary()] of the statistical model. +#' @param main Title of the plot +#' @param ribbon A [logical] to indicate whether a ribbon should be shown (default) or error bars +#' @param ... Arguments passed on to functions #' @inheritSection as.sir Interpretation of SIR #' @inheritParams first_isolate #' @inheritParams graphics::plot diff --git a/R/sir.R b/R/sir.R index f3e787dff..02a8d4181 100755 --- a/R/sir.R +++ b/R/sir.R @@ -38,12 +38,12 @@ #' #' All breakpoints used for interpretation are available in our [clinical_breakpoints] data set. #' @rdname as.sir -#' @param x vector of values (for class [`mic`]: MIC values in mg/L, for class [`disk`]: a disk diffusion radius in millimetres) -#' @param mo a vector (or column name) with [character]s that can be coerced to valid microorganism codes with [as.mo()], can be left empty to determine it automatically -#' @param ab a vector (or column name) with [character]s that can be coerced to a valid antimicrobial drug code with [as.ab()] +#' @param x Vector of values (for class [`mic`]: MIC values in mg/L, for class [`disk`]: a disk diffusion radius in millimetres) +#' @param mo A vector (or column name) with [character]s that can be coerced to valid microorganism codes with [as.mo()], can be left empty to determine it automatically +#' @param ab A vector (or column name) with [character]s that can be coerced to a valid antimicrobial drug code with [as.ab()] #' @param uti (Urinary Tract Infection) a vector (or column name) with [logical]s (`TRUE` or `FALSE`) to specify whether a UTI specific interpretation from the guideline should be chosen. For using [as.sir()] on a [data.frame], this can also be a column containing [logical]s or when left blank, the data set will be searched for a column 'specimen', and rows within this column containing 'urin' (such as 'urine', 'urina') will be regarded isolates from a UTI. See *Examples*. #' @inheritParams first_isolate -#' @param guideline defaults to `r AMR::clinical_breakpoints$guideline[1]` (the latest implemented EUCAST guideline in the [AMR::clinical_breakpoints] data set), but can be set with the package option [`AMR_guideline`][AMR-options]. Currently supports EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`) and CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`), see *Details*. +#' @param guideline Defaults to `r AMR::clinical_breakpoints$guideline[1]` (the latest implemented EUCAST guideline in the [AMR::clinical_breakpoints] data set), but can be set with the package option [`AMR_guideline`][AMR-options]. Currently supports EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`) and CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`), see *Details*. #' @param capped_mic_handling A [character] string that controls how MIC values with a cap (i.e., starting with `<`, `<=`, `>`, or `>=`) are interpreted. Supports the following options: #' #' `"none"` @@ -64,16 +64,16 @@ #' #' The default `"standard"` setting ensures cautious handling of uncertain values while preserving interpretability. This option can also be set with the package option [`AMR_capped_mic_handling`][AMR-options]. #' @param add_intrinsic_resistance *(only useful when using a EUCAST guideline)* a [logical] to indicate whether intrinsic antibiotic resistance must also be considered for applicable bug-drug combinations, meaning that e.g. ampicillin will always return "R" in *Klebsiella* species. Determination is based on the [intrinsic_resistant] data set, that itself is based on `r format_eucast_version_nr(3.3)`. -#' @param substitute_missing_r_breakpoint a [logical] to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is `FALSE`. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be `"S"` or `NA`. Setting this to `TRUE` will convert the `NA`s to `"R"` only if the R breakpoint is missing. Can also be set with the package option [`AMR_substitute_missing_r_breakpoint`][AMR-options]. -#' @param include_screening a [logical] to indicate that clinical breakpoints for screening are allowed - the default is `FALSE`. Can also be set with the package option [`AMR_include_screening`][AMR-options]. -#' @param include_PKPD a [logical] to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is `TRUE`. Can also be set with the package option [`AMR_include_PKPD`][AMR-options]. -#' @param breakpoint_type the type of breakpoints to use, either `r vector_or(clinical_breakpoints$type)`. ECOFF stands for Epidemiological Cut-Off values. The default is `"human"`, which can also be set with the package option [`AMR_breakpoint_type`][AMR-options]. If `host` is set to values of veterinary species, this will automatically be set to `"animal"`. -#' @param host a vector (or column name) with [character]s to indicate the host. Only useful for veterinary breakpoints, as it requires `breakpoint_type = "animal"`. The values can be any text resembling the animal species, even in any of the `r length(LANGUAGES_SUPPORTED)` supported languages of this package. For foreign languages, be sure to set the language with [set_AMR_locale()] (though it will be automatically guessed based on the system language). -#' @param verbose a [logical] to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values. -#' @param reference_data a [data.frame] to be used for interpretation, which defaults to the [clinical_breakpoints] data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the [clinical_breakpoints] data set (same column names and column types). Please note that the `guideline` argument will be ignored when `reference_data` is manually set. -#' @param threshold maximum fraction of invalid antimicrobial interpretations of `x`, see *Examples* -#' @param conserve_capped_values deprecated, use `capped_mic_handling` instead -#' @param ... for using on a [data.frame]: names of columns to apply [as.sir()] on (supports tidy selection such as `column1:column4`). Otherwise: arguments passed on to methods. +#' @param substitute_missing_r_breakpoint A [logical] to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is `FALSE`. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be `"S"` or `NA`. Setting this to `TRUE` will convert the `NA`s to `"R"` only if the R breakpoint is missing. Can also be set with the package option [`AMR_substitute_missing_r_breakpoint`][AMR-options]. +#' @param include_screening A [logical] to indicate that clinical breakpoints for screening are allowed - the default is `FALSE`. Can also be set with the package option [`AMR_include_screening`][AMR-options]. +#' @param include_PKPD A [logical] to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is `TRUE`. Can also be set with the package option [`AMR_include_PKPD`][AMR-options]. +#' @param breakpoint_type The type of breakpoints to use, either `r vector_or(clinical_breakpoints$type)`. ECOFF stands for Epidemiological Cut-Off values. The default is `"human"`, which can also be set with the package option [`AMR_breakpoint_type`][AMR-options]. If `host` is set to values of veterinary species, this will automatically be set to `"animal"`. +#' @param host A vector (or column name) with [character]s to indicate the host. Only useful for veterinary breakpoints, as it requires `breakpoint_type = "animal"`. The values can be any text resembling the animal species, even in any of the `r length(LANGUAGES_SUPPORTED)` supported languages of this package. For foreign languages, be sure to set the language with [set_AMR_locale()] (though it will be automatically guessed based on the system language). +#' @param verbose A [logical] to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values. +#' @param reference_data A [data.frame] to be used for interpretation, which defaults to the [clinical_breakpoints] data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the [clinical_breakpoints] data set (same column names and column types). Please note that the `guideline` argument will be ignored when `reference_data` is manually set. +#' @param threshold Maximum fraction of invalid antimicrobial interpretations of `x`, see *Examples* +#' @param conserve_capped_values Deprecated, use `capped_mic_handling` instead +#' @param ... For using on a [data.frame]: names of columns to apply [as.sir()] on (supports tidy selection such as `column1:column4`). Otherwise: arguments passed on to methods. #' @details #' *Note: The clinical breakpoints in this package were validated through, and imported from, [WHONET](https://whonet.org). The public use of this `AMR` package has been endorsed by both CLSI and EUCAST. See [clinical_breakpoints] for more information.* #' @@ -147,7 +147,7 @@ #' #' ### 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 function [is.sir()] detects if the input contains class `sir`. If the input is a [data.frame] or [list], it iterates over all columns/items 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. #' @@ -398,7 +398,7 @@ NA_sir_ <- as_sir_structure(NA_character_) #' @rdname as.sir #' @export is.sir <- function(x) { - if (inherits(x, "data.frame")) { + if (identical(typeof(x), "list")) { unname(vapply(FUN.VALUE = logical(1), x, is.sir)) } else { isTRUE(inherits(x, "sir")) @@ -410,7 +410,7 @@ is.sir <- function(x) { is_sir_eligible <- function(x, threshold = 0.05) { meet_criteria(threshold, allow_class = "numeric", has_length = 1) - if (inherits(x, "data.frame")) { + if (identical(typeof(x), "list")) { # iterate this function over all columns return(unname(vapply(FUN.VALUE = logical(1), x, is_sir_eligible))) } @@ -463,8 +463,8 @@ is_sir_eligible <- function(x, threshold = 0.05) { #' @rdname as.sir #' @export -#' @param S,I,R,NI,SDD a case-independent [regular expression][base::regex] to translate input to this result. This regular expression will be run *after* all non-letters and whitespaces are removed from the input. -#' @param info a [logical] to print information about the process +#' @param S,I,R,NI,SDD A case-independent [regular expression][base::regex] to translate input to this result. This regular expression will be run *after* all non-letters and whitespaces are removed from the input. +#' @param info A [logical] to print information about the process # extra param: warn (logical, to never throw a warning) as.sir.default <- function(x, S = "^(S|U)+$", @@ -1677,7 +1677,7 @@ as_sir_method <- function(method_short, } #' @rdname as.sir -#' @param clean a [logical] to indicate whether previously stored results should be forgotten after returning the 'logbook' with results +#' @param clean A [logical] to indicate whether previously stored results should be forgotten after returning the 'logbook' with results #' @export sir_interpretation_history <- function(clean = FALSE) { meet_criteria(clean, allow_class = "logical", has_length = 1) diff --git a/R/skewness.R b/R/skewness.R index e0c510b8c..7920fb4bd 100755 --- a/R/skewness.R +++ b/R/skewness.R @@ -32,8 +32,8 @@ #' @description Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. #' #' When negative ('left-skewed'): the left tail is longer; the mass of the distribution is concentrated on the right of a histogram. When positive ('right-skewed'): the right tail is longer; the mass of the distribution is concentrated on the left of a histogram. A normal distribution has a skewness of 0. -#' @param x a vector of values, a [matrix] or a [data.frame] -#' @param na.rm a [logical] value indicating whether `NA` values should be stripped before the computation proceeds +#' @param x A vector of values, a [matrix] or a [data.frame] +#' @param na.rm A [logical] value indicating whether `NA` values should be stripped before the computation proceeds #' @seealso [kurtosis()] #' @rdname skewness #' @export diff --git a/R/top_n_microorganisms.R b/R/top_n_microorganisms.R index 2ecbb0c6e..dad7a7988 100755 --- a/R/top_n_microorganisms.R +++ b/R/top_n_microorganisms.R @@ -30,10 +30,10 @@ #' Filter Top *n* Microorganisms #' #' This function filters a data set to include only the top *n* microorganisms based on a specified property, such as taxonomic family or genus. For example, it can filter a data set to the top 3 species, or to any species in the top 5 genera, or to the top 3 species in each of the top 5 genera. -#' @param x a data frame containing microbial data -#' @param n an integer specifying the maximum number of unique values of the `property` to include in the output -#' @param property a character string indicating the microorganism property to use for filtering. Must be one of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`. If `NULL`, the raw values from `col_mo` will be used without transformation. -#' @param n_for_each an optional integer specifying the maximum number of rows to retain for each value of the selected property. If `NULL`, all rows within the top *n* groups will be included. +#' @param x A data frame containing microbial data +#' @param n An integer specifying the maximum number of unique values of the `property` to include in the output +#' @param property A character string indicating the microorganism property to use for filtering. Must be one of the column names of the [microorganisms] data set: `r vector_or(colnames(microorganisms), sort = FALSE, quotes = TRUE)`. If `NULL`, the raw values from `col_mo` will be used without transformation. +#' @param n_for_each An optional integer specifying the maximum number of rows to retain for each value of the selected property. If `NULL`, all rows within the top *n* groups will be included. #' @param col_mo A character string indicating the column in `x` that contains microorganism names or codes. Defaults to the first column of class [`mo`]. Values will be coerced using [as.mo()]. #' @param ... Additional arguments passed on to [mo_property()] when `property` is not `NULL`. #' @details This function is useful for preprocessing data before creating [antibiograms][antibiogram()] or other analyses that require focused subsets of microbial data. For example, it can filter a data set to only include isolates from the top 10 species. diff --git a/R/translate.R b/R/translate.R index 8bcbf926d..0b5d6d021 100755 --- a/R/translate.R +++ b/R/translate.R @@ -30,8 +30,8 @@ #' Translate Strings from the AMR Package #' #' For language-dependent output of `AMR` functions, such as [mo_name()], [mo_gramstain()], [mo_type()] and [ab_name()]. -#' @param x text to translate -#' @param language language to choose. Use one of these supported language names or ISO-639-1 codes: `r vector_or(paste0(sapply(LANGUAGES_SUPPORTED_NAMES, function(x) x[[1]]), " (" , LANGUAGES_SUPPORTED, ")"), quotes = FALSE, sort = FALSE)`. +#' @param x Text to translate +#' @param language Language to choose. Use one of these supported language names or ISO-639-1 codes: `r vector_or(paste0(sapply(LANGUAGES_SUPPORTED_NAMES, function(x) x[[1]]), " (" , LANGUAGES_SUPPORTED, ")"), quotes = FALSE, sort = FALSE)`. #' @details The currently `r length(LANGUAGES_SUPPORTED)` supported languages are `r vector_and(paste0(sapply(LANGUAGES_SUPPORTED_NAMES, function(x) x[[1]]), " (" , LANGUAGES_SUPPORTED, ")"), quotes = FALSE, sort = FALSE)`. All these languages have translations available for all antimicrobial drugs and colloquial microorganism names. #' #' To permanently silence the once-per-session language note on a non-English operating system, you can set the package option [`AMR_locale`][AMR-options] in your `.Rprofile` file like this: diff --git a/data-raw/gpt_training_text_v2.1.1.9231.txt b/data-raw/gpt_training_text_v2.1.1.9232.txt similarity index 96% rename from data-raw/gpt_training_text_v2.1.1.9231.txt rename to data-raw/gpt_training_text_v2.1.1.9232.txt index 7581903a3..8c95dbd39 100644 --- a/data-raw/gpt_training_text_v2.1.1.9231.txt +++ b/data-raw/gpt_training_text_v2.1.1.9232.txt @@ -1,6 +1,6 @@ This knowledge base contains all context you must know about the AMR package for R. You are a GPT trained to be an assistant for the AMR package in R. You are an incredible R specialist, especially trained in this package and in the tidyverse. -First and foremost, you are trained on version 2.1.1.9231. Remember this whenever someone asks which AMR package version you’re at. +First and foremost, you are trained on version 2.1.1.9232. Remember this whenever someone asks which AMR package version you’re at. Below are the contents of the NAMESPACE file, the index.md file, and all the man/*.Rd files (documentation) in the package. Every file content is split using 100 hypens. ---------------------------------------------------------------------------------------------------- @@ -1032,19 +1032,19 @@ ab_from_text(text, type = c("drug", "dose", "administration"), info = interactive(), ...) } \arguments{ -\item{text}{text to analyse} +\item{text}{Text to analyse} -\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} +\item{type}{Type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} -\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} +\item{collapse}{A \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} -\item{translate_ab}{if \code{type = "drug"}: a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} +\item{translate_ab}{If \code{type = "drug"}: a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} -\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} +\item{thorough_search}{A \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to \code{\link[=as.ab]{as.ab()}}} +\item{...}{Arguments passed on to \code{\link[=as.ab]{as.ab()}}} } \value{ A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL} @@ -1175,25 +1175,25 @@ set_ab_names(data, ..., property = "name", language = get_AMR_locale(), snake_case = NULL) } \arguments{ -\item{x}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} +\item{x}{Any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}. This will lead to e.g. "polymyxin B" and not "polymyxin b".} +\item{tolower}{A \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}. This will lead to e.g. "polymyxin B" and not "polymyxin b".} -\item{...}{in case of \code{\link[=set_ab_names]{set_ab_names()}} and \code{data} is a \link{data.frame}: columns to select (supports tidy selection such as \code{column1:column4}), otherwise other arguments passed on to \code{\link[=as.ab]{as.ab()}}} +\item{...}{In case of \code{\link[=set_ab_names]{set_ab_names()}} and \code{data} is a \link{data.frame}: columns to select (supports tidy selection such as \code{column1:column4}), otherwise other arguments passed on to \code{\link[=as.ab]{as.ab()}}} -\item{only_first}{a \link{logical} to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group)} +\item{only_first}{A \link{logical} to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group)} -\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}} +\item{administration}{Way of administration, either \code{"oral"} or \code{"iv"}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} -\item{property}{one of the column names of one of the \link{antimicrobials} data set: \code{vector_or(colnames(antimicrobials), sort = FALSE)}.} +\item{property}{One of the column names of one of the \link{antimicrobials} data set: \code{vector_or(colnames(antimicrobials), sort = FALSE)}.} -\item{data}{a \link{data.frame} of which the columns need to be renamed, or a \link{character} vector of column names} +\item{data}{A \link{data.frame} of which the columns need to be renamed, or a \link{character} vector of column names} -\item{snake_case}{a \link{logical} to indicate whether the names should be in so-called \href{https://en.wikipedia.org/wiki/Snake_case}{snake case}: in lower case and all spaces/slashes replaced with an underscore (\verb{_})} +\item{snake_case}{A \link{logical} to indicate whether the names should be in so-called \href{https://en.wikipedia.org/wiki/Snake_case}{snake case}: in lower case and all spaces/slashes replaced with an underscore (\verb{_})} } \value{ \itemize{ @@ -1317,7 +1317,7 @@ add_custom_antimicrobials(x) clear_custom_antimicrobials() } \arguments{ -\item{x}{a \link{data.frame} resembling the \link{antimicrobials} data set, at least containing columns "ab" and "name"} +\item{x}{A \link{data.frame} resembling the \link{antimicrobials} data set, at least containing columns "ab" and "name"} } \description{ With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own custom antimicrobial drug names and codes. @@ -1426,7 +1426,7 @@ add_custom_microorganisms(x) clear_custom_microorganisms() } \arguments{ -\item{x}{a \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)} +\item{x}{A \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)} } \description{ With \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis. @@ -1543,15 +1543,15 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/age.Rd': age(x, reference = Sys.Date(), exact = FALSE, na.rm = FALSE, ...) } \arguments{ -\item{x}{date(s), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} +\item{x}{Date(s), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} -\item{reference}{reference date(s) (default is today), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} +\item{reference}{Reference date(s) (default is today), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} -\item{exact}{a \link{logical} to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of \href{https://en.wikipedia.org/wiki/Year-to-date}{year-to-date} (YTD) of \code{x} by the number of days in the year of \code{reference} (either 365 or 366).} +\item{exact}{A \link{logical} to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of \href{https://en.wikipedia.org/wiki/Year-to-date}{year-to-date} (YTD) of \code{x} by the number of days in the year of \code{reference} (either 365 or 366).} -\item{na.rm}{a \link{logical} to indicate whether missing values should be removed} +\item{na.rm}{A \link{logical} to indicate whether missing values should be removed} -\item{...}{arguments passed on to \code{\link[=as.POSIXlt]{as.POSIXlt()}}, such as \code{origin}} +\item{...}{Arguments passed on to \code{\link[=as.POSIXlt]{as.POSIXlt()}}, such as \code{origin}} } \value{ An \link{integer} (no decimals) if \code{exact = FALSE}, a \link{double} (with decimals) otherwise @@ -1598,11 +1598,11 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/age_groups.Rd': age_groups(x, split_at = c(12, 25, 55, 75), na.rm = FALSE) } \arguments{ -\item{x}{age, e.g. calculated with \code{\link[=age]{age()}}} +\item{x}{Age, e.g. calculated with \code{\link[=age]{age()}}} -\item{split_at}{values to split \code{x} at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See \emph{Details}.} +\item{split_at}{Values to split \code{x} at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See \emph{Details}.} -\item{na.rm}{a \link{logical} to indicate whether missing values should be removed} +\item{na.rm}{A \link{logical} to indicate whether missing values should be removed} } \value{ Ordered \link{factor} @@ -1718,9 +1718,9 @@ retrieve_wisca_parameters(wisca_model, ...) na = getOption("knitr.kable.NA", default = ""), ...) } \arguments{ -\item{x}{a \link{data.frame} containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see \code{\link[=as.sir]{as.sir()}})} +\item{x}{A \link{data.frame} containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see \code{\link[=as.sir]{as.sir()}})} -\item{antimicrobials}{a vector specifying the antimicrobials to include in the antibiogram (see \emph{Examples}). Will be evaluated using \code{\link[=guess_ab_col]{guess_ab_col()}}. This can be: +\item{antimicrobials}{A vector specifying the antimicrobials to include in the antibiogram (see \emph{Examples}). Will be evaluated using \code{\link[=guess_ab_col]{guess_ab_col()}}. This can be: \itemize{ \item Any antimicrobial name or code \item A column name in \code{x} that contains SIR values @@ -1741,49 +1741,49 @@ retrieve_wisca_parameters(wisca_model, ...) } }} -\item{mo_transform}{a character to transform microorganism input - must be \code{"name"}, \code{"shortname"} (default), \code{"gramstain"}, or one of the column names of the \link{microorganisms} data set: "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", or "snomed". Can also be \code{NULL} to not transform the input or \code{NA} to consider all microorganisms 'unknown'.} +\item{mo_transform}{A character to transform microorganism input - must be \code{"name"}, \code{"shortname"} (default), \code{"gramstain"}, or one of the column names of the \link{microorganisms} data set: "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", or "snomed". Can also be \code{NULL} to not transform the input or \code{NA} to consider all microorganisms 'unknown'.} -\item{ab_transform}{a character to transform antimicrobial input - must be one of the column names of the \link{antimicrobials} data set (defaults to \code{"name"}): "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.} +\item{ab_transform}{A character to transform antimicrobial input - must be one of the column names of the \link{antimicrobials} data set (defaults to \code{"name"}): "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.} -\item{syndromic_group}{a column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.} +\item{syndromic_group}{A column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.} -\item{add_total_n}{a \link{logical} to indicate whether \code{n_tested} available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when \code{wisca = TRUE}; in that case, use \code{\link[=retrieve_wisca_parameters]{retrieve_wisca_parameters()}} to get the parameters used for WISCA.} +\item{add_total_n}{A \link{logical} to indicate whether \code{n_tested} available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when \code{wisca = TRUE}; in that case, use \code{\link[=retrieve_wisca_parameters]{retrieve_wisca_parameters()}} to get the parameters used for WISCA.} \item{only_all_tested}{(for combination antibiograms): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see \emph{Details}} -\item{digits}{number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise} +\item{digits}{Number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise} -\item{formatting_type}{numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See \emph{Details} > \emph{Formatting Type} for a list of options.} +\item{formatting_type}{Numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See \emph{Details} > \emph{Formatting Type} for a list of options.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{language}{language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is \code{TRUE})} +\item{combine_SI}{A \link{logical} to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is \code{TRUE})} -\item{sep}{a separating character for antimicrobial columns in combination antibiograms} +\item{sep}{A separating character for antimicrobial columns in combination antibiograms} -\item{wisca}{a \link{logical} to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is \code{FALSE}). This will use a Bayesian decision model to estimate regimen coverage probabilities using \href{https://en.wikipedia.org/wiki/Monte_Carlo_method}{Monte Carlo simulations}. Set \code{simulations}, \code{conf_interval}, and \code{interval_side} to adjust.} +\item{wisca}{A \link{logical} to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is \code{FALSE}). This will use a Bayesian decision model to estimate regimen coverage probabilities using \href{https://en.wikipedia.org/wiki/Monte_Carlo_method}{Monte Carlo simulations}. Set \code{simulations}, \code{conf_interval}, and \code{interval_side} to adjust.} \item{simulations}{(for WISCA) a numerical value to set the number of Monte Carlo simulations} -\item{conf_interval}{a numerical value to set confidence interval (default is \code{0.95})} +\item{conf_interval}{A numerical value to set confidence interval (default is \code{0.95})} -\item{interval_side}{the side of the confidence interval, either \code{"two-tailed"} (default), \code{"left"} or \code{"right"}} +\item{interval_side}{The side of the confidence interval, either \code{"two-tailed"} (default), \code{"left"} or \code{"right"}} -\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{when used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)} +\item{...}{When used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)} -\item{wisca_model}{the outcome of \code{\link[=wisca]{wisca()}} or \code{\link[=antibiogram]{antibiogram(..., wisca = TRUE)}}} +\item{wisca_model}{The outcome of \code{\link[=wisca]{wisca()}} or \code{\link[=antibiogram]{antibiogram(..., wisca = TRUE)}}} -\item{object}{an \code{\link[=antibiogram]{antibiogram()}} object} +\item{object}{An \code{\link[=antibiogram]{antibiogram()}} object} -\item{italicise}{a \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.} +\item{italicise}{A \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.} -\item{na}{character to use for showing \code{NA} values} +\item{na}{Character to use for showing \code{NA} values} } \description{ Create detailed antibiograms with options for traditional, combination, syndromic, and Bayesian WISCA methods. @@ -2281,21 +2281,21 @@ not_intrinsic_resistant(only_sir_columns = FALSE, col_mo = NULL, version_expected_phenotypes = 1.2, ...) } \arguments{ -\item{only_sir_columns}{a \link{logical} to indicate whether only columns of class \code{sir} must be selected (default is \code{FALSE}), see \code{\link[=as.sir]{as.sir()}}} +\item{only_sir_columns}{A \link{logical} to indicate whether only columns of class \code{sir} must be selected (default is \code{FALSE}), see \code{\link[=as.sir]{as.sir()}}} -\item{only_treatable}{a \link{logical} to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is \code{TRUE}), such as gentamicin-high (\code{GEH}) and imipenem/EDTA (\code{IPE})} +\item{only_treatable}{A \link{logical} to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is \code{TRUE}), such as gentamicin-high (\code{GEH}) and imipenem/EDTA (\code{IPE})} -\item{return_all}{a \link{logical} to indicate whether all matched columns must be returned (default is \code{TRUE}). With \code{FALSE}, only the first of each unique antimicrobial will be returned, e.g. if both columns \code{"genta"} and \code{"gentamicin"} exist in the data, only the first hit for gentamicin will be returned.} +\item{return_all}{A \link{logical} to indicate whether all matched columns must be returned (default is \code{TRUE}). With \code{FALSE}, only the first of each unique antimicrobial will be returned, e.g. if both columns \code{"genta"} and \code{"gentamicin"} exist in the data, only the first hit for gentamicin will be returned.} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} -\item{amr_class}{an antimicrobial class or a part of it, such as \code{"carba"} and \code{"carbapenems"}. The columns \code{group}, \code{atc_group1} and \code{atc_group2} of the \link{antimicrobials} data set will be searched (case-insensitive) for this value.} +\item{amr_class}{An antimicrobial class or a part of it, such as \code{"carba"} and \code{"carbapenems"}. The columns \code{group}, \code{atc_group1} and \code{atc_group2} of the \link{antimicrobials} data set will be searched (case-insensitive) for this value.} -\item{filter}{an \link{expression} to be evaluated in the \link{antimicrobials} data set, such as \code{name \%like\% "trim"}} +\item{filter}{An \link{expression} to be evaluated in the \link{antimicrobials} data set, such as \code{name \%like\% "trim"}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{version_expected_phenotypes}{the version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} +\item{version_expected_phenotypes}{The version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} } \value{ When used inside selecting or filtering, this returns a \link{character} vector of column names, with additional class \code{"amr_selector"}. When used individually, this returns an \link[=as.ab]{'ab' vector} with all possible antimicrobials that the function would be able to select or filter. @@ -2668,15 +2668,15 @@ is.ab(x) ab_reset_session() } \arguments{ -\item{x}{a \link{character} vector to determine to antibiotic ID} +\item{x}{A \link{character} vector to determine to antibiotic ID} -\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value.} +\item{flag_multiple_results}{A \link{logical} to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value.} -\item{language}{language to coerce input values from any of the 20 supported languages - default to the system language if supported (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to coerce input values from any of the 20 supported languages - default to the system language if supported (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to internal functions} +\item{...}{Arguments passed on to internal functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{ab}} @@ -2785,13 +2785,13 @@ as.av(x, flag_multiple_results = TRUE, info = interactive(), ...) is.av(x) } \arguments{ -\item{x}{a \link{character} vector to determine to antiviral drug ID} +\item{x}{A \link{character} vector to determine to antiviral drug ID} -\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value.} +\item{flag_multiple_results}{A \link{logical} to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to internal functions} +\item{...}{Arguments passed on to internal functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{ab}} @@ -2893,9 +2893,9 @@ NA_disk_ is.disk(x) } \arguments{ -\item{x}{vector} +\item{x}{Vector} -\item{na.rm}{a \link{logical} indicating whether missing values should be removed} +\item{na.rm}{A \link{logical} indicating whether missing values should be removed} } \value{ An \link{integer} with additional class \code{\link{disk}} @@ -2980,17 +2980,17 @@ mic_p90(x, na.rm = FALSE, ...) \method{droplevels}{mic}(x, as.mic = FALSE, ...) } \arguments{ -\item{x}{a \link{character} or \link{numeric} vector} +\item{x}{A \link{character} or \link{numeric} vector} -\item{na.rm}{a \link{logical} indicating whether missing values should be removed} +\item{na.rm}{A \link{logical} indicating whether missing values should be removed} -\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} +\item{keep_operators}{A \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} -\item{mic_range}{a manual range to rescale the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}.} +\item{mic_range}{A manual range to rescale the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}.} -\item{as.mic}{a \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{TRUE} for \code{\link[=rescale_mic]{rescale_mic()}} and \code{FALSE} for \code{\link[=droplevels]{droplevels()}}. When setting this to \code{FALSE} in \code{\link[=rescale_mic]{rescale_mic()}}, the output will have factor levels that acknowledge \code{mic_range}.} +\item{as.mic}{A \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{TRUE} for \code{\link[=rescale_mic]{rescale_mic()}} and \code{FALSE} for \code{\link[=droplevels]{droplevels()}}. When setting this to \code{FALSE} in \code{\link[=rescale_mic]{rescale_mic()}}, the output will have factor levels that acknowledge \code{mic_range}.} -\item{...}{arguments passed on to methods} +\item{...}{Arguments passed on to methods} } \value{ Ordered \link{factor} with additional class \code{\link{mic}}, that in mathematical operations acts as a \link{numeric} vector. Bear in mind that the outcome of any mathematical operation on MICs will return a \link{numeric} value. @@ -3035,10 +3035,12 @@ subset(df, x > 4) # or with dplyr: df \%>\% filter(x > 4) #> 10 16 A }\if{html}{\out{}} -All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some functions of the \code{stats} package are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values. +All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some mathematical functions are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values. Using \code{\link[=as.double]{as.double()}} or \code{\link[=as.numeric]{as.numeric()}} on MIC values will remove the operators and return a numeric vector. Do \strong{not} use \code{\link[=as.integer]{as.integer()}} on MIC values as by the \R convention on \link{factor}s, it will return the index of the factor levels (which is often useless for regular users). +The function \code{\link[=is.mic]{is.mic()}} detects if the input contains class \code{mic}. If the input is a \link{data.frame} or \link{list}, it iterates over all columns/items and returns a \link{logical} vector. + Use \code{\link[=droplevels]{droplevels()}} to drop unused levels. At default, it will return a plain factor. Use \code{droplevels(..., as.mic = TRUE)} to maintain the \code{mic} class. With \code{\link[=rescale_mic]{rescale_mic()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. @@ -3136,33 +3138,33 @@ mo_reset_session() mo_cleaning_regex() } \arguments{ -\item{x}{a \link{character} vector or a \link{data.frame} with one or two columns} +\item{x}{A \link{character} vector or a \link{data.frame} with one or two columns} -\item{Becker}{a \link{logical} to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker \emph{et al.} (see \emph{Source}). Please see \emph{Details} for a full list of staphylococcal species that will be converted. +\item{Becker}{A \link{logical} to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker \emph{et al.} (see \emph{Source}). Please see \emph{Details} for a full list of staphylococcal species that will be converted. This excludes \emph{Staphylococcus aureus} at default, use \code{Becker = "all"} to also categorise \emph{S. aureus} as "CoPS".} -\item{Lancefield}{a \link{logical} to indicate whether a beta-haemolytic \emph{Streptococcus} should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see \emph{Source}). These streptococci will be categorised in their first group, e.g. \emph{Streptococcus dysgalactiae} will be group C, although officially it was also categorised into groups G and L. . Please see \emph{Details} for a full list of streptococcal species that will be converted. +\item{Lancefield}{A \link{logical} to indicate whether a beta-haemolytic \emph{Streptococcus} should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see \emph{Source}). These streptococci will be categorised in their first group, e.g. \emph{Streptococcus dysgalactiae} will be group C, although officially it was also categorised into groups G and L. . Please see \emph{Details} for a full list of streptococcal species that will be converted. This excludes enterococci at default (who are in group D), use \code{Lancefield = "all"} to also categorise all enterococci as group D.} -\item{minimum_matching_score}{a numeric value to set as the lower limit for the \link[=mo_matching_score]{MO matching score}. When left blank, this will be determined automatically based on the character length of \code{x}, its \link[=microorganisms]{taxonomic kingdom} and \link[=mo_matching_score]{human pathogenicity}.} +\item{minimum_matching_score}{A numeric value to set as the lower limit for the \link[=mo_matching_score]{MO matching score}. When left blank, this will be determined automatically based on the character length of \code{x}, its \link[=microorganisms]{taxonomic kingdom} and \link[=mo_matching_score]{human pathogenicity}.} -\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} +\item{keep_synonyms}{A \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} -\item{reference_df}{a \link{data.frame} to be used for extra reference when translating \code{x} to a valid \code{\link{mo}}. See \code{\link[=set_mo_source]{set_mo_source()}} and \code{\link[=get_mo_source]{get_mo_source()}} to automate the usage of your own codes (e.g. used in your analysis or organisation).} +\item{reference_df}{A \link{data.frame} to be used for extra reference when translating \code{x} to a valid \code{\link{mo}}. See \code{\link[=set_mo_source]{set_mo_source()}} and \code{\link[=get_mo_source]{get_mo_source()}} to automate the usage of your own codes (e.g. used in your analysis or organisation).} -\item{ignore_pattern}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) of which all matches in \code{x} must return \code{NA}. This can be convenient to exclude known non-relevant input and can also be set with the package option \code{\link[=AMR-options]{AMR_ignore_pattern}}, e.g. \code{options(AMR_ignore_pattern = "(not reported|contaminated flora)")}.} +\item{ignore_pattern}{A Perl-compatible \link[base:regex]{regular expression} (case-insensitive) of which all matches in \code{x} must return \code{NA}. This can be convenient to exclude known non-relevant input and can also be set with the package option \code{\link[=AMR-options]{AMR_ignore_pattern}}, e.g. \code{options(AMR_ignore_pattern = "(not reported|contaminated flora)")}.} -\item{cleaning_regex}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) to clean the input of \code{x}. Every matched part in \code{x} will be removed. At default, this is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option \code{\link[=AMR-options]{AMR_cleaning_regex}}.} +\item{cleaning_regex}{A Perl-compatible \link[base:regex]{regular expression} (case-insensitive) to clean the input of \code{x}. Every matched part in \code{x} will be removed. At default, this is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option \code{\link[=AMR-options]{AMR_cleaning_regex}}.} -\item{only_fungi}{a \link{logical} to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for \link[=mo_property]{all microorganism functions} with the package option \code{\link[=AMR-options]{AMR_only_fungi}}, i.e. \code{options(AMR_only_fungi = TRUE)}.} +\item{only_fungi}{A \link{logical} to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for \link[=mo_property]{all microorganism functions} with the package option \code{\link[=AMR-options]{AMR_only_fungi}}, i.e. \code{options(AMR_only_fungi = TRUE)}.} -\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{info}{a \link{logical} to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is \code{TRUE} only in interactive mode.} +\item{info}{A \link{logical} to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is \code{TRUE} only in interactive mode.} -\item{...}{other arguments passed on to functions} +\item{...}{Other arguments passed on to functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{mo}} @@ -3442,21 +3444,21 @@ is_sir_eligible(x, threshold = 0.05) sir_interpretation_history(clean = FALSE) } \arguments{ -\item{x}{vector of values (for class \code{\link{mic}}: MIC values in mg/L, for class \code{\link{disk}}: a disk diffusion radius in millimetres)} +\item{x}{Vector of values (for class \code{\link{mic}}: MIC values in mg/L, for class \code{\link{disk}}: a disk diffusion radius in millimetres)} -\item{...}{for using on a \link{data.frame}: names of columns to apply \code{\link[=as.sir]{as.sir()}} on (supports tidy selection such as \code{column1:column4}). Otherwise: arguments passed on to methods.} +\item{...}{For using on a \link{data.frame}: names of columns to apply \code{\link[=as.sir]{as.sir()}} on (supports tidy selection such as \code{column1:column4}). Otherwise: arguments passed on to methods.} -\item{threshold}{maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}} +\item{threshold}{Maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}} -\item{S, I, R, NI, SDD}{a case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters and whitespaces are removed from the input.} +\item{S, I, R, NI, SDD}{A case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters and whitespaces are removed from the input.} -\item{info}{a \link{logical} to print information about the process} +\item{info}{A \link{logical} to print information about the process} -\item{mo}{a vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically} +\item{mo}{A vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically} -\item{ab}{a vector (or column name) with \link{character}s that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{A vector (or column name) with \link{character}s that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{guideline}{defaults to EUCAST 2024 (the latest implemented EUCAST guideline in the \link{clinical_breakpoints} data set), but can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}. Currently supports EUCAST (2011-2024) and CLSI (2011-2024), see \emph{Details}.} +\item{guideline}{Defaults to EUCAST 2024 (the latest implemented EUCAST guideline in the \link{clinical_breakpoints} data set), but can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}. Currently supports EUCAST (2011-2024) and CLSI (2011-2024), see \emph{Details}.} \item{uti}{(Urinary Tract Infection) a vector (or column name) with \link{logical}s (\code{TRUE} or \code{FALSE}) to specify whether a UTI specific interpretation from the guideline should be chosen. For using \code{\link[=as.sir]{as.sir()}} on a \link{data.frame}, this can also be a column containing \link{logical}s or when left blank, the data set will be searched for a column 'specimen', and rows within this column containing 'urin' (such as 'urine', 'urina') will be regarded isolates from a UTI. See \emph{Examples}.} @@ -3490,25 +3492,25 @@ The default \code{"standard"} setting ensures cautious handling of uncertain val \item{add_intrinsic_resistance}{\emph{(only useful when using a EUCAST guideline)} a \link{logical} to indicate whether intrinsic antibiotic resistance must also be considered for applicable bug-drug combinations, meaning that e.g. ampicillin will always return "R" in \emph{Klebsiella} species. Determination is based on the \link{intrinsic_resistant} data set, that itself is based on \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021).} -\item{reference_data}{a \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.} +\item{reference_data}{A \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.} -\item{substitute_missing_r_breakpoint}{a \link{logical} to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is \code{FALSE}. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be \code{"S"} or \code{NA}. Setting this to \code{TRUE} will convert the \code{NA}s to \code{"R"} only if the R breakpoint is missing. Can also be set with the package option \code{\link[=AMR-options]{AMR_substitute_missing_r_breakpoint}}.} +\item{substitute_missing_r_breakpoint}{A \link{logical} to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is \code{FALSE}. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be \code{"S"} or \code{NA}. Setting this to \code{TRUE} will convert the \code{NA}s to \code{"R"} only if the R breakpoint is missing. Can also be set with the package option \code{\link[=AMR-options]{AMR_substitute_missing_r_breakpoint}}.} -\item{include_screening}{a \link{logical} to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_screening}}.} +\item{include_screening}{A \link{logical} to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_screening}}.} -\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} +\item{include_PKPD}{A \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} -\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} +\item{breakpoint_type}{The type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} -\item{host}{a vector (or column name) with \link{character}s to indicate the host. Only useful for veterinary breakpoints, as it requires \code{breakpoint_type = "animal"}. The values can be any text resembling the animal species, even in any of the 20 supported languages of this package. For foreign languages, be sure to set the language with \code{\link[=set_AMR_locale]{set_AMR_locale()}} (though it will be automatically guessed based on the system language).} +\item{host}{A vector (or column name) with \link{character}s to indicate the host. Only useful for veterinary breakpoints, as it requires \code{breakpoint_type = "animal"}. The values can be any text resembling the animal species, even in any of the 20 supported languages of this package. For foreign languages, be sure to set the language with \code{\link[=set_AMR_locale]{set_AMR_locale()}} (though it will be automatically guessed based on the system language).} -\item{verbose}{a \link{logical} to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values.} +\item{verbose}{A \link{logical} to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values.} -\item{conserve_capped_values}{deprecated, use \code{capped_mic_handling} instead} +\item{conserve_capped_values}{Deprecated, use \code{capped_mic_handling} instead} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{clean}{a \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results} +\item{clean}{A \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results} } \value{ Ordered \link{factor} with new class \code{sir} @@ -3601,7 +3603,7 @@ The repository of this package \href{https://github.com/msberends/AMR/blob/main/ \subsection{Other}{ -The function \code{\link[=is.sir]{is.sir()}} detects if the input contains class \code{sir}. If the input is a \link{data.frame}, it iterates over all columns and returns a \link{logical} vector. +The function \code{\link[=is.sir]{is.sir()}} detects if the input contains class \code{sir}. If the input is a \link{data.frame} or \link{list}, it iterates over all columns/items and returns a \link{logical} vector. The base R function \code{\link[=as.double]{as.double()}} can be used to retrieve quantitative values from a \code{sir} object: \code{"S"} = 1, \code{"I"}/\code{"SDD"} = 2, \code{"R"} = 3. All other values are rendered \code{NA} . \strong{Note:} Do not use \code{as.integer()}, since that (because of how R works internally) will return the factor level indices, and not these aforementioned quantitative values. @@ -3855,17 +3857,17 @@ atc_online_ddd(atc_code, ...) atc_online_ddd_units(atc_code, ...) } \arguments{ -\item{atc_code}{a \link{character} (vector) with ATC code(s) of antimicrobials, will be coerced with \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_atc]{ab_atc()}} internally if not a valid ATC code} +\item{atc_code}{A \link{character} (vector) with ATC code(s) of antimicrobials, will be coerced with \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_atc]{ab_atc()}} internally if not a valid ATC code} -\item{property}{property of an ATC code. Valid values are \code{"ATC"}, \code{"Name"}, \code{"DDD"}, \code{"U"} (\code{"unit"}), \code{"Adm.R"}, \code{"Note"} and \code{groups}. For this last option, all hierarchical groups of an ATC code will be returned, see \emph{Examples}.} +\item{property}{Property of an ATC code. Valid values are \code{"ATC"}, \code{"Name"}, \code{"DDD"}, \code{"U"} (\code{"unit"}), \code{"Adm.R"}, \code{"Note"} and \code{groups}. For this last option, all hierarchical groups of an ATC code will be returned, see \emph{Examples}.} -\item{administration}{type of administration when using \code{property = "Adm.R"}, see \emph{Details}} +\item{administration}{Type of administration when using \code{property = "Adm.R"}, see \emph{Details}} -\item{url}{url of website of the WHOCC. The sign \verb{\%s} can be used as a placeholder for ATC codes.} +\item{url}{URL of website of the WHOCC. The sign \verb{\%s} can be used as a placeholder for ATC codes.} -\item{url_vet}{url of website of the WHOCC for veterinary medicine. The sign \verb{\%s} can be used as a placeholder for ATC_vet codes (that all start with "Q").} +\item{url_vet}{URL of website of the WHOCC for veterinary medicine. The sign \verb{\%s} can be used as a placeholder for ATC_vet codes (that all start with "Q").} -\item{...}{arguments to pass on to \code{atc_property}} +\item{...}{Arguments to pass on to \code{atc_property}} } \description{ Gets data from the WHOCC website to determine properties of an Anatomical Therapeutic Chemical (ATC) (e.g. an antimicrobial), such as the name, defined daily dose (DDD) or standard unit. @@ -3931,19 +3933,19 @@ av_from_text(text, type = c("drug", "dose", "administration"), info = interactive(), ...) } \arguments{ -\item{text}{text to analyse} +\item{text}{Text to analyse} -\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} +\item{type}{Type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} -\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} +\item{collapse}{A \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} -\item{translate_av}{if \code{type = "drug"}: a column name of the \link{antivirals} data set to translate the antibiotic abbreviations to, using \code{\link[=av_property]{av_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} +\item{translate_av}{If \code{type = "drug"}: a column name of the \link{antivirals} data set to translate the antibiotic abbreviations to, using \code{\link[=av_property]{av_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} -\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} +\item{thorough_search}{A \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to \code{\link[=as.av]{as.av()}}} +\item{...}{Arguments passed on to \code{\link[=as.av]{as.av()}}} } \value{ A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL} @@ -4026,19 +4028,19 @@ av_url(x, open = FALSE, ...) av_property(x, property = "name", language = get_AMR_locale(), ...) } \arguments{ -\item{x}{any (vector of) text that can be coerced to a valid antiviral drug code with \code{\link[=as.av]{as.av()}}} +\item{x}{Any (vector of) text that can be coerced to a valid antiviral drug code with \code{\link[=as.av]{as.av()}}} -\item{language}{language of the returned text - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}.} +\item{tolower}{A \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}.} -\item{...}{other arguments passed on to \code{\link[=as.av]{as.av()}}} +\item{...}{Other arguments passed on to \code{\link[=as.av]{as.av()}}} -\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}} +\item{administration}{Way of administration, either \code{"oral"} or \code{"iv"}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} -\item{property}{one of the column names of one of the \link{antivirals} data set: \code{vector_or(colnames(antivirals), sort = FALSE)}.} +\item{property}{One of the column names of one of the \link{antivirals} data set: \code{vector_or(colnames(antivirals), sort = FALSE)}.} } \value{ \itemize{ @@ -4121,9 +4123,9 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/availability.Rd': availability(tbl, width = NULL) } \arguments{ -\item{tbl}{a \link{data.frame} or \link{list}} +\item{tbl}{A \link{data.frame} or \link{list}} -\item{width}{number of characters to present the visual availability - the default is filling the width of the console} +\item{width}{Number of characters to present the visual availability - the default is filling the width of the console} } \value{ \link{data.frame} with column names of \code{tbl} as row names @@ -4169,25 +4171,25 @@ bug_drug_combinations(x, col_mo = NULL, FUN = mo_shortname, ",", ".", ","), ...) } \arguments{ -\item{x}{a data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} +\item{x}{A data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{FUN}{the function to call on the \code{mo} column to transform the microorganism codes - the default is \code{\link[=mo_shortname]{mo_shortname()}}} +\item{FUN}{The function to call on the \code{mo} column to transform the microorganism codes - the default is \code{\link[=mo_shortname]{mo_shortname()}}} -\item{include_n_rows}{a \link{logical} to indicate if the total number of rows must be included in the output} +\item{include_n_rows}{A \link{logical} to indicate if the total number of rows must be included in the output} -\item{...}{arguments passed on to \code{FUN}} +\item{...}{Arguments passed on to \code{FUN}} -\item{translate_ab}{a \link{character} of length 1 containing column names of the \link{antimicrobials} data set} +\item{translate_ab}{A \link{character} of length 1 containing column names of the \link{antimicrobials} data set} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is \code{TRUE}} -\item{add_ab_group}{a \link{logical} to indicate where the group of the antimicrobials must be included as a first column} +\item{add_ab_group}{A \link{logical} to indicate where the group of the antimicrobials must be included as a first column} \item{remove_intrinsic_resistant}{\link{logical} to indicate that rows and columns with 100\% resistance for all tested antimicrobials must be removed from the table} @@ -4365,17 +4367,17 @@ count_df(data, translate_ab = "name", language = get_AMR_locale(), combine_SI = TRUE) } \arguments{ -\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed.} +\item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed.} \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below} -\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} } \value{ An \link{integer} @@ -4540,7 +4542,7 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/custom_eucast_rules.Rd': custom_eucast_rules(...) } \arguments{ -\item{...}{rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}} +\item{...}{Rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}} } \value{ A \link{list} containing the custom rules @@ -4767,35 +4769,35 @@ eucast_rules(x, col_mo = NULL, info = interactive(), eucast_dosage(ab, administration = "iv", version_breakpoints = 12) } \arguments{ -\item{x}{a data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} +\item{x}{A data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} +\item{info}{A \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} -\item{rules}{a \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.} +\item{rules}{A \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.} -\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.} +\item{verbose}{A \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.} -\item{version_breakpoints}{the version number to use for the EUCAST Clinical Breakpoints guideline. Can be "14.0", "13.1", "12.0", "11.0", or "10.0".} +\item{version_breakpoints}{The version number to use for the EUCAST Clinical Breakpoints guideline. Can be "14.0", "13.1", "12.0", "11.0", or "10.0".} -\item{version_expected_phenotypes}{the version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} +\item{version_expected_phenotypes}{The version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} -\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".} +\item{version_expertrules}{The version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".} \item{ampc_cephalosporin_resistance}{(only applies when \code{rules} contains \code{"expert"} or \code{"all"}) a \link{character} value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants - the default is \code{NA}. Currently only works when \code{version_expertrules} is \code{3.2} and higher; these versions of '\emph{EUCAST Expert Rules on Enterobacterales}' state that results of cefotaxime, ceftriaxone and ceftazidime should be reported with a note, or results should be suppressed (emptied) for these three drugs. A value of \code{NA} (the default) for this argument will remove results for these three drugs, while e.g. a value of \code{"R"} will make the results for these drugs resistant. Use \code{NULL} or \code{FALSE} to not alter results for these three drugs of AmpC de-repressed cephalosporin-resistant mutants. Using \code{TRUE} is equal to using \code{"R"}. \cr For \emph{EUCAST Expert Rules} v3.2, this rule applies to: \emph{Citrobacter braakii}, \emph{Citrobacter freundii}, \emph{Citrobacter gillenii}, \emph{Citrobacter murliniae}, \emph{Citrobacter rodenticum}, \emph{Citrobacter sedlakii}, \emph{Citrobacter werkmanii}, \emph{Citrobacter youngae}, \emph{Enterobacter}, \emph{Hafnia alvei}, \emph{Klebsiella aerogenes}, \emph{Morganella morganii}, \emph{Providencia}, and \emph{Serratia}.} -\item{only_sir_columns}{a \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{custom_rules}{custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}} +\item{custom_rules}{Custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}} \item{overwrite}{A \link{logical} indicating whether to overwrite non-\code{NA} values (default: \code{FALSE}). When \code{FALSE}, only \code{NA} values are modified. To ensure compliance with EUCAST guidelines, \strong{this should remain} \code{FALSE}, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant."} -\item{...}{column name of an antimicrobial, see section \emph{Antimicrobials} below} +\item{...}{Column name of an antimicrobial, see section \emph{Antimicrobials} below} -\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{administration}{route of administration, either "im", "iv", or "oral"} +\item{administration}{Route of administration, either "im", "iv", or "oral"} } \value{ The input of \code{x}, possibly with edited values of antimicrobials. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations. @@ -4997,11 +4999,11 @@ export_ncbi_biosample(x, filename = paste0("biosample_", format(Sys.time(), columns = where(is.mic), save_as_xlsx = TRUE) } \arguments{ -\item{x}{a data set} +\item{x}{A data set} -\item{filename}{a character string specifying the file name} +\item{filename}{A character string specifying the file name} -\item{type}{a character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see \url{https://www.ncbi.nlm.nih.gov/biosample/docs/}} +\item{type}{A character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see \url{https://www.ncbi.nlm.nih.gov/biosample/docs/}} } \description{ Export Data Set as NCBI BioSample Antibiogram @@ -5042,45 +5044,45 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, "episode-based", "patient-based", "isolate-based"), ...) } \arguments{ -\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} +\item{x}{A \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} -\item{col_date}{column name of the result date (or date that is was received on the lab) - the default is the first column with a date class} +\item{col_date}{Column name of the result date (or date that is was received on the lab) - the default is the first column with a date class} -\item{col_patient_id}{column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive)} +\item{col_patient_id}{Column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive)} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{col_testcode}{column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.} +\item{col_testcode}{Column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.} -\item{col_specimen}{column name of the specimen type or group} +\item{col_specimen}{Column name of the specimen type or group} -\item{col_icu}{column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU). This can also be a \link{logical} vector with the same length as rows in \code{x}.} +\item{col_icu}{Column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU). This can also be a \link{logical} vector with the same length as rows in \code{x}.} \item{col_keyantimicrobials}{(only useful when \code{method = "phenotype-based"}) column name of the key antimicrobials to determine first isolates, see \code{\link[=key_antimicrobials]{key_antimicrobials()}}. The default is the first column that starts with 'key' followed by 'ab' or 'antibiotics' or 'antimicrobials' (case insensitive). Use \code{col_keyantimicrobials = FALSE} to prevent this. Can also be the output of \code{\link[=key_antimicrobials]{key_antimicrobials()}}.} -\item{episode_days}{episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see \emph{Source}.} +\item{episode_days}{Episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see \emph{Source}.} -\item{testcodes_exclude}{a \link{character} vector with test codes that should be excluded (case-insensitive)} +\item{testcodes_exclude}{A \link{character} vector with test codes that should be excluded (case-insensitive)} -\item{icu_exclude}{a \link{logical} to indicate whether ICU isolates should be excluded (rows with value \code{TRUE} in the column set with \code{col_icu})} +\item{icu_exclude}{A \link{logical} to indicate whether ICU isolates should be excluded (rows with value \code{TRUE} in the column set with \code{col_icu})} -\item{specimen_group}{value in the column set with \code{col_specimen} to filter on} +\item{specimen_group}{Value in the column set with \code{col_specimen} to filter on} -\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} +\item{type}{Type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} -\item{method}{the method to apply, either \code{"phenotype-based"}, \code{"episode-based"}, \code{"patient-based"} or \code{"isolate-based"} (can be abbreviated), see \emph{Details}. The default is \code{"phenotype-based"} if antimicrobial test results are present in the data, and \code{"episode-based"} otherwise.} +\item{method}{The method to apply, either \code{"phenotype-based"}, \code{"episode-based"}, \code{"patient-based"} or \code{"isolate-based"} (can be abbreviated), see \emph{Details}. The default is \code{"phenotype-based"} if antimicrobial test results are present in the data, and \code{"episode-based"} otherwise.} \item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}} -\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} +\item{points_threshold}{Minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} -\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} -\item{include_unknown}{a \link{logical} to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code \code{"UNKNOWN"}, which defaults to \code{FALSE}. For WHONET users, this means that all records with organism code \code{"con"} (\emph{contamination}) will be excluded at default. Isolates with a microbial ID of \code{NA} will always be excluded as first isolate.} +\item{include_unknown}{A \link{logical} to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code \code{"UNKNOWN"}, which defaults to \code{FALSE}. For WHONET users, this means that all records with organism code \code{"con"} (\emph{contamination}) will be excluded at default. Isolates with a microbial ID of \code{NA} will always be excluded as first isolate.} -\item{include_untested_sir}{a \link{logical} to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use \code{include_untested_sir = FALSE} to always return \code{FALSE} for such rows. This checks the data set for columns of class \code{sir} and consequently requires transforming columns with antibiotic results using \code{\link[=as.sir]{as.sir()}} first.} +\item{include_untested_sir}{A \link{logical} to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use \code{include_untested_sir = FALSE} to always return \code{FALSE} for such rows. This checks the data set for columns of class \code{sir} and consequently requires transforming columns with antibiotic results using \code{\link[=as.sir]{as.sir()}} first.} -\item{...}{arguments passed on to \code{\link[=first_isolate]{first_isolate()}} when using \code{\link[=filter_first_isolate]{filter_first_isolate()}}, otherwise arguments passed on to \code{\link[=key_antimicrobials]{key_antimicrobials()}} (such as \code{universal}, \code{gram_negative}, \code{gram_positive})} +\item{...}{Arguments passed on to \code{\link[=first_isolate]{first_isolate()}} when using \code{\link[=filter_first_isolate]{filter_first_isolate()}}, otherwise arguments passed on to \code{\link[=key_antimicrobials]{key_antimicrobials()}} (such as \code{universal}, \code{gram_negative}, \code{gram_positive})} } \value{ A \link{logical} vector @@ -5360,13 +5362,13 @@ get_episode(x, episode_days = NULL, case_free_days = NULL, ...) is_new_episode(x, episode_days = NULL, case_free_days = NULL, ...) } \arguments{ -\item{x}{vector of dates (class \code{Date} or \code{POSIXt}), will be sorted internally to determine episodes} +\item{x}{Vector of dates (class \code{Date} or \code{POSIXt}), will be sorted internally to determine episodes} -\item{episode_days}{episode length in days to specify the time period after which a new episode begins, can also be less than a day or \code{Inf}, see \emph{Details}} +\item{episode_days}{Episode length in days to specify the time period after which a new episode begins, can also be less than a day or \code{Inf}, see \emph{Details}} \item{case_free_days}{(inter-epidemic) interval length in days after which a new episode will start, can also be less than a day or \code{Inf}, see \emph{Details}} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} } \value{ \itemize{ @@ -5576,7 +5578,7 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, arrows_alpha = 0.75, base_textsize = 10, ...) } \arguments{ -\item{x}{an object returned by \code{\link[=pca]{pca()}}, \code{\link[=prcomp]{prcomp()}} or \code{\link[=princomp]{princomp()}}} +\item{x}{An object returned by \code{\link[=pca]{pca()}}, \code{\link[=prcomp]{prcomp()}} or \code{\link[=princomp]{princomp()}}} \item{choices}{ length 2 vector specifying the components to plot. Only the default @@ -5599,41 +5601,41 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, approximate Mahalanobis distance. } -\item{labels}{an optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} +\item{labels}{An optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} -\item{labels_textsize}{the size of the text used for the labels} +\item{labels_textsize}{The size of the text used for the labels} -\item{labels_text_placement}{adjustment factor the placement of the variable names (\verb{>=1} means further away from the arrow head)} +\item{labels_text_placement}{Adjustment factor the placement of the variable names (\verb{>=1} means further away from the arrow head)} -\item{groups}{an optional vector of groups for the labels, with the same length as \code{labels}. If set, the points and labels will be coloured according to these groups. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} +\item{groups}{An optional vector of groups for the labels, with the same length as \code{labels}. If set, the points and labels will be coloured according to these groups. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} -\item{ellipse}{a \link{logical} to indicate whether a normal data ellipse should be drawn for each group (set with \code{groups})} +\item{ellipse}{A \link{logical} to indicate whether a normal data ellipse should be drawn for each group (set with \code{groups})} -\item{ellipse_prob}{statistical size of the ellipse in normal probability} +\item{ellipse_prob}{Statistical size of the ellipse in normal probability} -\item{ellipse_size}{the size of the ellipse line} +\item{ellipse_size}{The size of the ellipse line} -\item{ellipse_alpha}{the alpha (transparency) of the ellipse line} +\item{ellipse_alpha}{The alpha (transparency) of the ellipse line} -\item{points_size}{the size of the points} +\item{points_size}{The size of the points} -\item{points_alpha}{the alpha (transparency) of the points} +\item{points_alpha}{The alpha (transparency) of the points} -\item{arrows}{a \link{logical} to indicate whether arrows should be drawn} +\item{arrows}{A \link{logical} to indicate whether arrows should be drawn} -\item{arrows_colour}{the colour of the arrow and their text} +\item{arrows_colour}{The colour of the arrow and their text} -\item{arrows_size}{the size (thickness) of the arrow lines} +\item{arrows_size}{The size (thickness) of the arrow lines} -\item{arrows_textsize}{the size of the text at the end of the arrows} +\item{arrows_textsize}{The size of the text at the end of the arrows} -\item{arrows_textangled}{a \link{logical} whether the text at the end of the arrows should be angled} +\item{arrows_textangled}{A \link{logical} whether the text at the end of the arrows should be angled} -\item{arrows_alpha}{the alpha (transparency) of the arrows and their text} +\item{arrows_alpha}{The alpha (transparency) of the arrows and their text} -\item{base_textsize}{the text size for all plot elements except the labels and arrows} +\item{base_textsize}{The text size for all plot elements except the labels and arrows} -\item{...}{arguments passed on to functions} +\item{...}{Arguments passed on to functions} } \description{ Produces a \code{ggplot2} variant of a so-called \href{https://en.wikipedia.org/wiki/Biplot}{biplot} for PCA (principal component analysis), but is more flexible and more appealing than the base \R \code{\link[=biplot]{biplot()}} function. @@ -5707,49 +5709,49 @@ geom_sir(position = NULL, x = c("antibiotic", "interpretation"), language = get_AMR_locale(), combine_SI = TRUE, ...) } \arguments{ -\item{data}{a \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{position}{position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} +\item{position}{Position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} -\item{x}{variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} +\item{x}{Variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} -\item{fill}{variable to categorise using the plots legend, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} +\item{fill}{Variable to categorise using the plots legend, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} -\item{facet}{variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} +\item{facet}{Variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} -\item{breaks}{a \link{numeric} vector of positions} +\item{breaks}{A \link{numeric} vector of positions} -\item{limits}{a \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} +\item{limits}{A \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} \item{nrow}{(when using \code{facet}) number of rows} -\item{colours}{a named vactor with colour to be used for filling. The default colours are colour-blind friendly.} +\item{colours}{A named vactor with colour to be used for filling. The default colours are colour-blind friendly.} -\item{datalabels}{show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}} +\item{datalabels}{Show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}} -\item{datalabels.size}{size of the datalabels} +\item{datalabels.size}{Size of the datalabels} -\item{datalabels.colour}{colour of the datalabels} +\item{datalabels.colour}{Colour of the datalabels} -\item{title}{text to show as title of the plot} +\item{title}{Text to show as title of the plot} -\item{subtitle}{text to show as subtitle of the plot} +\item{subtitle}{Text to show as subtitle of the plot} -\item{caption}{text to show as caption of the plot} +\item{caption}{Text to show as caption of the plot} -\item{x.title}{text to show as x axis description} +\item{x.title}{Text to show as x axis description} -\item{y.title}{text to show as y axis description} +\item{y.title}{Text to show as y axis description} -\item{...}{other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.} +\item{...}{Other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.} } \description{ Use these functions to create bar plots for AMR data analysis. All functions rely on \link[ggplot2:ggplot]{ggplot2} functions. @@ -5764,7 +5766,7 @@ Additional functions include: \item \code{\link[=facet_sir]{facet_sir()}} creates 2d plots (at default based on S/I/R) using \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}}. \item \code{\link[=scale_y_percent]{scale_y_percent()}} transforms the y axis to a 0 to 100\% range using \code{\link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous()}}. \item \code{\link[=scale_sir_colours]{scale_sir_colours()}} sets colours to the bars (green for S, yellow for I, and red for R). with multilingual support. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. -\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction. +\item \code{\link[=theme_sir]{theme_sir()}} is a \link[ggplot2:theme]{ggplot2 theme} with minimal distraction. \item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and amount of isolates using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}. } @@ -5886,13 +5888,13 @@ guess_ab_col(x = NULL, search_string = NULL, verbose = FALSE, only_sir_columns = FALSE) } \arguments{ -\item{x}{a \link{data.frame}} +\item{x}{A \link{data.frame}} -\item{search_string}{a text to search \code{x} for, will be checked with \code{\link[=as.ab]{as.ab()}} if this value is not a column in \code{x}} +\item{search_string}{A text to search \code{x} for, will be checked with \code{\link[=as.ab]{as.ab()}} if this value is not a column in \code{x}} -\item{verbose}{a \link{logical} to indicate whether additional info should be printed} +\item{verbose}{A \link{logical} to indicate whether additional info should be printed} -\item{only_sir_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} } \value{ A column name of \code{x}, or \code{NULL} when no result is found. @@ -5991,9 +5993,9 @@ italicise_taxonomy(string, type = c("markdown", "ansi", "html")) italicize_taxonomy(string, type = c("markdown", "ansi", "html")) } \arguments{ -\item{string}{a \link{character} (vector)} +\item{string}{A \link{character} (vector)} -\item{type}{type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see \emph{Details}} +\item{type}{Type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see \emph{Details}} } \description{ According to the binomial nomenclature, the lowest four taxonomic levels (family, genus, species, subspecies) should be printed in italics. This function finds taxonomic names within strings and makes them italic. @@ -6044,13 +6046,13 @@ semi_join_microorganisms(x, by = NULL, ...) anti_join_microorganisms(x, by = NULL, ...) } \arguments{ -\item{x}{existing data set to join, or \link{character} vector. In case of a \link{character} vector, the resulting \link{data.frame} will contain a column 'x' with these values.} +\item{x}{Existing data set to join, or \link{character} vector. In case of a \link{character} vector, the resulting \link{data.frame} will contain a column 'x' with these values.} -\item{by}{a variable to join by - if left empty will search for a column with class \code{\link{mo}} (created with \code{\link[=as.mo]{as.mo()}}) or will be \code{"mo"} if that column name exists in \code{x}, could otherwise be a column name of \code{x} with values that exist in \code{microorganisms$mo} (such as \code{by = "bacteria_id"}), or another column in \link{microorganisms} (but then it should be named, like \code{by = c("bacteria_id" = "fullname")})} +\item{by}{A variable to join by - if left empty will search for a column with class \code{\link{mo}} (created with \code{\link[=as.mo]{as.mo()}}) or will be \code{"mo"} if that column name exists in \code{x}, could otherwise be a column name of \code{x} with values that exist in \code{microorganisms$mo} (such as \code{by = "bacteria_id"}), or another column in \link{microorganisms} (but then it should be named, like \code{by = c("bacteria_id" = "fullname")})} -\item{suffix}{if there are non-joined duplicate variables in \code{x} and \code{y}, these suffixes will be added to the output to disambiguate them. Should be a \link{character} vector of length 2.} +\item{suffix}{If there are non-joined duplicate variables in \code{x} and \code{y}, these suffixes will be added to the output to disambiguate them. Should be a \link{character} vector of length 2.} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} } \value{ a \link{data.frame} @@ -6122,29 +6124,29 @@ antimicrobials_equal(y, z, type = c("points", "keyantimicrobials"), ignore_I = TRUE, points_threshold = 2, ...) } \arguments{ -\item{x}{a \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically.} +\item{x}{A \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{universal}{names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs} +\item{universal}{Names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs} -\item{gram_negative}{names of antibiotic drugs for \strong{Gram-positives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} +\item{gram_negative}{Names of antibiotic drugs for \strong{Gram-positives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} -\item{gram_positive}{names of antibiotic drugs for \strong{Gram-negatives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} +\item{gram_positive}{Names of antibiotic drugs for \strong{Gram-negatives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} -\item{antifungal}{names of antifungal drugs for \strong{fungi}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antifungal drugs} +\item{antifungal}{Names of antifungal drugs for \strong{fungi}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antifungal drugs} -\item{only_sir_columns}{a \link{logical} to indicate whether only columns must be included that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only columns must be included that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} \item{y, z}{\link{character} vectors to compare} -\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} +\item{type}{Type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} \item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}} -\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} +\item{points_threshold}{Minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} } \description{ These functions can be used to determine first weighted isolates by considering the phenotype for isolate selection (see \code{\link[=first_isolate]{first_isolate()}}). Using a phenotype-based method to determine first isolates is more reliable than methods that disregard phenotypes. @@ -6257,11 +6259,11 @@ kurtosis(x, na.rm = FALSE, excess = FALSE) \method{kurtosis}{data.frame}(x, na.rm = FALSE, excess = FALSE) } \arguments{ -\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}} +\item{x}{A vector of values, a \link{matrix} or a \link{data.frame}} -\item{na.rm}{a \link{logical} to indicate whether \code{NA} values should be stripped before the computation proceeds} +\item{na.rm}{A \link{logical} to indicate whether \code{NA} values should be stripped before the computation proceeds} -\item{excess}{a \link{logical} to indicate whether the \emph{excess kurtosis} should be returned, defined as the kurtosis minus 3.} +\item{excess}{A \link{logical} to indicate whether the \emph{excess kurtosis} should be returned, defined as the kurtosis minus 3.} } \description{ Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. A normal distribution has a kurtosis of 3 and a excess kurtosis of 0. @@ -6304,11 +6306,11 @@ x \%like_case\% pattern x \%unlike_case\% pattern } \arguments{ -\item{x}{a \link{character} vector where matches are sought, or an object which can be coerced by \code{\link[=as.character]{as.character()}} to a \link{character} vector.} +\item{x}{A \link{character} vector where matches are sought, or an object which can be coerced by \code{\link[=as.character]{as.character()}} to a \link{character} vector.} -\item{pattern}{a \link{character} vector containing regular expressions (or a \link{character} string for \code{fixed = TRUE}) to be matched in the given \link{character} vector. Coerced by \code{\link[=as.character]{as.character()}} to a \link{character} string if possible.} +\item{pattern}{A \link{character} vector containing regular expressions (or a \link{character} string for \code{fixed = TRUE}) to be matched in the given \link{character} vector. Coerced by \code{\link[=as.character]{as.character()}} to a \link{character} string if possible.} -\item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case sensitive} and if \code{TRUE}, case is ignored during matching.} +\item{ignore.case}{If \code{FALSE}, the pattern matching is \emph{case sensitive} and if \code{TRUE}, case is ignored during matching.} } \value{ A \link{logical} vector @@ -6405,11 +6407,11 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, verbose = FALSE, ...) } \arguments{ -\item{x}{a \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank for automatic determination.} +\item{x}{A \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank for automatic determination.} -\item{guideline}{a specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.} +\item{guideline}{A specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} \item{esbl}{\link{logical} values, or a column name containing logical values, indicating the presence of an ESBL gene (or production of its proteins)} @@ -6423,19 +6425,19 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \item{vanB}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanB} gene (or production of its proteins)} -\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} +\item{info}{A \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} -\item{pct_required_classes}{minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for \emph{S. aureus}. Setting this \code{pct_required_classes} argument to \code{0.5} (default) means that for every \emph{S. aureus} isolate at least 8 different classes must be available. Any lower number of available classes will return \code{NA} for that isolate.} +\item{pct_required_classes}{Minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for \emph{S. aureus}. Setting this \code{pct_required_classes} argument to \code{0.5} (default) means that for every \emph{S. aureus} isolate at least 8 different classes must be available. Any lower number of available classes will return \code{NA} for that isolate.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the \code{\link[=mdro]{mdro()}} function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using \code{combine_SI = FALSE}, resistance is considered when isolates are R or I.} +\item{combine_SI}{A \link{logical} to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the \code{\link[=mdro]{mdro()}} function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using \code{combine_SI = FALSE}, resistance is considered when isolates are R or I.} -\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.} +\item{verbose}{A \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.} -\item{only_sir_columns}{a \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{...}{in case of \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}}: a set of rules, see section \emph{Using Custom Guidelines} below. Otherwise: column name of an antibiotic, see section \emph{Antimicrobials} below.} +\item{...}{In case of \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}}: a set of rules, see section \emph{Using Custom Guidelines} below. Otherwise: column name of an antibiotic, see section \emph{Antimicrobials} below.} -\item{as_factor}{a \link{logical} to indicate whether the returned value should be an ordered \link{factor} (\code{TRUE}, default), or otherwise a \link{character} vector} +\item{as_factor}{A \link{logical} to indicate whether the returned value should be an ordered \link{factor} (\code{TRUE}, default), or otherwise a \link{character} vector} } \value{ \itemize{ @@ -6622,15 +6624,15 @@ mean_amr_distance(x, ...) amr_distance_from_row(amr_distance, row) } \arguments{ -\item{x}{a vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes} +\item{x}{A vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes} -\item{...}{variables to select (supports \link[tidyselect:language]{tidyselect language} such as \code{column1:column4} and \code{where(is.mic)}, and can thus also be \link[=amr_selector]{antimicrobial selectors}} +\item{...}{Variables to select. Supports \link[tidyselect:language]{tidyselect language} (such as \code{column1:column4} and \code{where(is.mic)}), and can thus also be \link[=amr_selector]{antimicrobial selectors}} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{amr_distance}{the outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}} +\item{amr_distance}{The outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}} -\item{row}{an index, such as a row number} +\item{row}{An index, such as a row number} } \description{ Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand. @@ -6675,7 +6677,7 @@ y <- data.frame( ) y mean_amr_distance(y) -y$amr_distance <- mean_amr_distance(y, where(is.mic)) +y$amr_distance <- mean_amr_distance(y, is.mic(y)) y[order(y$amr_distance), ] if (require("dplyr")) { @@ -7154,19 +7156,19 @@ mo_property(x, property = "fullname", language = get_AMR_locale(), keep_synonyms = getOption("AMR_keep_synonyms", FALSE), ...) } \arguments{ -\item{x}{any \link{character} (vector) that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see \emph{Examples}.} +\item{x}{Any \link{character} (vector) that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see \emph{Examples}.} -\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} +\item{keep_synonyms}{A \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} -\item{...}{other arguments passed on to \code{\link[=as.mo]{as.mo()}}, such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input'} +\item{...}{Other arguments passed on to \code{\link[=as.mo]{as.mo()}}, such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input'} -\item{ab}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{browseURL()}}} -\item{property}{one of the column names of the \link{microorganisms} data set: "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", or "snomed", or must be \code{"shortname"}} +\item{property}{One of the column names of the \link{microorganisms} data set: "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", or "snomed", or must be \code{"shortname"}} } \value{ \itemize{ @@ -7388,9 +7390,9 @@ set_mo_source(path, destination = getOption("AMR_mo_source", get_mo_source(destination = getOption("AMR_mo_source", "~/mo_source.rds")) } \arguments{ -\item{path}{location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see \emph{Details}). Can also be \code{""}, \code{NULL} or \code{FALSE} to delete the reference file.} +\item{path}{Location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see \emph{Details}). Can also be \code{""}, \code{NULL} or \code{FALSE} to delete the reference file.} -\item{destination}{destination of the compressed data file - the default is the user's home directory.} +\item{destination}{Destination of the compressed data file - the default is the user's home directory.} } \description{ These functions can be used to predefine your own reference to be used in \code{\link[=as.mo]{as.mo()}} and consequently all \code{\link[=mo_property]{mo_*}} functions (such as \code{\link[=mo_genus]{mo_genus()}} and \code{\link[=mo_gramstain]{mo_gramstain()}}). @@ -7498,9 +7500,9 @@ pca(x, ..., retx = TRUE, center = TRUE, scale. = TRUE, tol = NULL, rank. = NULL) } \arguments{ -\item{x}{a \link{data.frame} containing \link{numeric} columns} +\item{x}{A \link{data.frame} containing \link{numeric} columns} -\item{...}{columns of \code{x} to be selected for PCA, can be unquoted since it supports quasiquotation.} +\item{...}{Columns of \code{x} to be selected for PCA, can be unquoted since it supports quasiquotation.} \item{retx}{a logical value indicating whether the rotated variables should be returned.} @@ -7695,57 +7697,57 @@ labels_sir_count(position = NULL, x = "antibiotic", combine_SI = TRUE, datalabels.size = 3, datalabels.colour = "grey15") } \arguments{ -\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} +\item{keep_operators}{A \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} \item{mic_range}{A manual range to rescale the MIC values (using \code{\link[=rescale_mic]{rescale_mic()}}), e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}. \strong{Note:} This rescales values but does not filter them - use the ggplot2 \code{limits} argument separately to exclude values from the plot.} -\item{...}{arguments passed on to methods} +\item{...}{Arguments passed on to methods} -\item{colours_SIR}{colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly.} +\item{colours_SIR}{Colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly.} -\item{language}{language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can be overwritten by setting the package option \code{\link[=AMR-options]{AMR_locale}}, e.g. \code{options(AMR_locale = "de")}, see \link{translate}. Use \code{language = NULL} to prevent translation.} +\item{language}{Language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can be overwritten by setting the package option \code{\link[=AMR-options]{AMR_locale}}, e.g. \code{options(AMR_locale = "de")}, see \link{translate}. Use \code{language = NULL} to prevent translation.} -\item{eucast_I}{a \link{logical} to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be \code{TRUE} if the default \link[=as.sir]{AMR interpretation guideline} is set to EUCAST (which is the default). With \code{FALSE}, it will be interpreted as "Intermediate".} +\item{eucast_I}{A \link{logical} to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be \code{TRUE} if the default \link[=as.sir]{AMR interpretation guideline} is set to EUCAST (which is the default). With \code{FALSE}, it will be interpreted as "Intermediate".} -\item{x, object}{values created with \code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}} or \code{\link[=as.sir]{as.sir()}} (or their \verb{random_*} variants, such as \code{\link[=random_mic]{random_mic()}})} +\item{x, object}{Values created with \code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}} or \code{\link[=as.sir]{as.sir()}} (or their \verb{random_*} variants, such as \code{\link[=random_mic]{random_mic()}})} -\item{mo}{any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} +\item{mo}{Any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} -\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{guideline}{interpretation guideline to use - the default is the latest included EUCAST guideline, see \emph{Details}} +\item{guideline}{Interpretation guideline to use - the default is the latest included EUCAST guideline, see \emph{Details}} -\item{main, title}{title of the plot} +\item{main, title}{Title of the plot} -\item{xlab, ylab}{axis title} +\item{xlab, ylab}{Axis title} -\item{expand}{a \link{logical} to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.} +\item{expand}{A \link{logical} to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.} -\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} +\item{include_PKPD}{A \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} -\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} +\item{breakpoint_type}{The type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} -\item{facet}{variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} +\item{facet}{Variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} \item{nrow}{(when using \code{facet}) number of rows} -\item{breaks}{a \link{numeric} vector of positions} +\item{breaks}{A \link{numeric} vector of positions} -\item{limits}{a \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} +\item{limits}{A \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} -\item{aesthetics}{aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size"} +\item{aesthetics}{Aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size"} -\item{position}{position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} +\item{position}{Position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{datalabels.size}{size of the datalabels} +\item{datalabels.size}{Size of the datalabels} -\item{datalabels.colour}{colour of the datalabels} +\item{datalabels.colour}{Colour of the datalabels} } \value{ The \code{autoplot()} functions return a \code{\link[ggplot2:ggplot]{ggplot}} model that is extendible with any \code{ggplot2} function. @@ -7773,7 +7775,7 @@ This package contains more functions that extend the \code{ggplot2} package, to \item \code{\link[=facet_sir]{facet_sir()}} creates 2d plots (at default based on S/I/R) using \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}}. \item \code{\link[=scale_y_percent]{scale_y_percent()}} transforms the y axis to a 0 to 100\% range using \code{\link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous()}}. \item \code{\link[=scale_sir_colours]{scale_sir_colours()}} allows to set colours to any aesthetic, even for \code{shape} or \code{linetype}. -\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction. +\item \code{\link[=theme_sir]{theme_sir()}} is a \link[ggplot2:theme]{ggplot2 theme} with minimal distraction. \item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and number of isolates, using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}. } @@ -7992,29 +7994,29 @@ sir_df(data, translate_ab = "name", language = get_AMR_locale(), confidence_level = 0.95) } \arguments{ -\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.} +\item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{as_percent}{a \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.} +\item{as_percent}{A \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.} \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below} -\item{ab_result}{antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R"} +\item{ab_result}{Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R"} -\item{confidence_level}{the confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} +\item{confidence_level}{The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} -\item{side}{the side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.} +\item{side}{The side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.} -\item{collapse}{a \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing} +\item{collapse}{A \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing} -\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} } \value{ A \link{double} or, when \code{as_percent = TRUE}, a \link{character}. @@ -8242,15 +8244,15 @@ random_disk(size = NULL, mo = NULL, ab = NULL, ...) random_sir(size = NULL, prob_SIR = c(0.33, 0.33, 0.33), ...) } \arguments{ -\item{size}{desired size of the returned vector. If used in a \link{data.frame} call or \code{dplyr} verb, will get the current (group) size if left blank.} +\item{size}{Desired size of the returned vector. If used in a \link{data.frame} call or \code{dplyr} verb, will get the current (group) size if left blank.} -\item{mo}{any \link{character} that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} +\item{mo}{Any \link{character} that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} -\item{ab}{any \link{character} that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any \link{character} that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} -\item{prob_SIR}{a vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value)} +\item{prob_SIR}{A vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value)} } \value{ class \code{mic} for \code{\link[=random_mic]{random_mic()}} (see \code{\link[=as.mic]{as.mic()}}) and class \code{disk} for \code{\link[=random_disk]{random_disk()}} (see \code{\link[=as.disk]{as.disk()}}) @@ -8314,35 +8316,35 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), main = paste("Resistance Prediction of", x_name), ribbon = TRUE, ...) } \arguments{ -\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} +\item{x}{A \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} -\item{col_ab}{column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"})} +\item{col_ab}{Column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"})} -\item{col_date}{column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class} +\item{col_date}{Column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class} -\item{year_min}{lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}} +\item{year_min}{Lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}} -\item{year_max}{highest year to use in the prediction model - the default is 10 years after today} +\item{year_max}{Highest year to use in the prediction model - the default is 10 years after today} -\item{year_every}{unit of sequence between lowest year found in the data and \code{year_max}} +\item{year_every}{Unit of sequence between lowest year found in the data and \code{year_max}} -\item{minimum}{minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.} +\item{minimum}{Minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.} -\item{model}{the statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.} +\item{model}{The statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.} -\item{I_as_S}{a \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.} +\item{I_as_S}{A \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.} -\item{preserve_measurements}{a \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.} +\item{preserve_measurements}{A \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.} -\item{info}{a \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.} +\item{info}{A \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.} -\item{...}{arguments passed on to functions} +\item{...}{Arguments passed on to functions} -\item{main}{title of the plot} +\item{main}{Title of the plot} -\item{ribbon}{a \link{logical} to indicate whether a ribbon should be shown (default) or error bars} +\item{ribbon}{A \link{logical} to indicate whether a ribbon should be shown (default) or error bars} -\item{object}{model data to be plotted} +\item{object}{Model data to be plotted} } \value{ A \link{data.frame} with extra class \code{\link{resistance_predict}} with columns: @@ -8458,9 +8460,9 @@ skewness(x, na.rm = FALSE) \method{skewness}{data.frame}(x, na.rm = FALSE) } \arguments{ -\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}} +\item{x}{A vector of values, a \link{matrix} or a \link{data.frame}} -\item{na.rm}{a \link{logical} value indicating whether \code{NA} values should be stripped before the computation proceeds} +\item{na.rm}{A \link{logical} value indicating whether \code{NA} values should be stripped before the computation proceeds} } \description{ Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. @@ -8490,13 +8492,13 @@ top_n_microorganisms(x, n, property = "fullname", n_for_each = NULL, col_mo = NULL, ...) } \arguments{ -\item{x}{a data frame containing microbial data} +\item{x}{A data frame containing microbial data} -\item{n}{an integer specifying the maximum number of unique values of the \code{property} to include in the output} +\item{n}{An integer specifying the maximum number of unique values of the \code{property} to include in the output} -\item{property}{a character string indicating the microorganism property to use for filtering. Must be one of the column names of the \link{microorganisms} data set: "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", or "snomed". If \code{NULL}, the raw values from \code{col_mo} will be used without transformation.} +\item{property}{A character string indicating the microorganism property to use for filtering. Must be one of the column names of the \link{microorganisms} data set: "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", or "snomed". If \code{NULL}, the raw values from \code{col_mo} will be used without transformation.} -\item{n_for_each}{an optional integer specifying the maximum number of rows to retain for each value of the selected property. If \code{NULL}, all rows within the top \emph{n} groups will be included.} +\item{n_for_each}{An optional integer specifying the maximum number of rows to retain for each value of the selected property. If \code{NULL}, all rows within the top \emph{n} groups will be included.} \item{col_mo}{A character string indicating the column in \code{x} that contains microorganism names or codes. Defaults to the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} @@ -8553,9 +8555,9 @@ reset_AMR_locale() translate_AMR(x, language = get_AMR_locale()) } \arguments{ -\item{language}{language to choose. Use one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk).} +\item{language}{Language to choose. Use one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk).} -\item{x}{text to translate} +\item{x}{Text to translate} } \description{ For language-dependent output of \code{AMR} functions, such as \code{\link[=mo_name]{mo_name()}}, \code{\link[=mo_gramstain]{mo_gramstain()}}, \code{\link[=mo_type]{mo_type()}} and \code{\link[=ab_name]{ab_name()}}. diff --git a/man/ab_from_text.Rd b/man/ab_from_text.Rd index da549f34f..dafe94568 100644 --- a/man/ab_from_text.Rd +++ b/man/ab_from_text.Rd @@ -9,19 +9,19 @@ ab_from_text(text, type = c("drug", "dose", "administration"), info = interactive(), ...) } \arguments{ -\item{text}{text to analyse} +\item{text}{Text to analyse} -\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} +\item{type}{Type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} -\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} +\item{collapse}{A \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} -\item{translate_ab}{if \code{type = "drug"}: a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} +\item{translate_ab}{If \code{type = "drug"}: a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} -\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} +\item{thorough_search}{A \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to \code{\link[=as.ab]{as.ab()}}} +\item{...}{Arguments passed on to \code{\link[=as.ab]{as.ab()}}} } \value{ A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL} diff --git a/man/ab_property.Rd b/man/ab_property.Rd index 6b1b6ab6c..0b3a64363 100644 --- a/man/ab_property.Rd +++ b/man/ab_property.Rd @@ -51,25 +51,25 @@ set_ab_names(data, ..., property = "name", language = get_AMR_locale(), snake_case = NULL) } \arguments{ -\item{x}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} +\item{x}{Any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}. This will lead to e.g. "polymyxin B" and not "polymyxin b".} +\item{tolower}{A \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}. This will lead to e.g. "polymyxin B" and not "polymyxin b".} -\item{...}{in case of \code{\link[=set_ab_names]{set_ab_names()}} and \code{data} is a \link{data.frame}: columns to select (supports tidy selection such as \code{column1:column4}), otherwise other arguments passed on to \code{\link[=as.ab]{as.ab()}}} +\item{...}{In case of \code{\link[=set_ab_names]{set_ab_names()}} and \code{data} is a \link{data.frame}: columns to select (supports tidy selection such as \code{column1:column4}), otherwise other arguments passed on to \code{\link[=as.ab]{as.ab()}}} -\item{only_first}{a \link{logical} to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group)} +\item{only_first}{A \link{logical} to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group)} -\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}} +\item{administration}{Way of administration, either \code{"oral"} or \code{"iv"}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} -\item{property}{one of the column names of one of the \link{antimicrobials} data set: \code{vector_or(colnames(antimicrobials), sort = FALSE)}.} +\item{property}{One of the column names of one of the \link{antimicrobials} data set: \code{vector_or(colnames(antimicrobials), sort = FALSE)}.} -\item{data}{a \link{data.frame} of which the columns need to be renamed, or a \link{character} vector of column names} +\item{data}{A \link{data.frame} of which the columns need to be renamed, or a \link{character} vector of column names} -\item{snake_case}{a \link{logical} to indicate whether the names should be in so-called \href{https://en.wikipedia.org/wiki/Snake_case}{snake case}: in lower case and all spaces/slashes replaced with an underscore (\verb{_})} +\item{snake_case}{A \link{logical} to indicate whether the names should be in so-called \href{https://en.wikipedia.org/wiki/Snake_case}{snake case}: in lower case and all spaces/slashes replaced with an underscore (\verb{_})} } \value{ \itemize{ diff --git a/man/add_custom_antimicrobials.Rd b/man/add_custom_antimicrobials.Rd index 913b05e2c..e6b23ca19 100644 --- a/man/add_custom_antimicrobials.Rd +++ b/man/add_custom_antimicrobials.Rd @@ -10,7 +10,7 @@ add_custom_antimicrobials(x) clear_custom_antimicrobials() } \arguments{ -\item{x}{a \link{data.frame} resembling the \link{antimicrobials} data set, at least containing columns "ab" and "name"} +\item{x}{A \link{data.frame} resembling the \link{antimicrobials} data set, at least containing columns "ab" and "name"} } \description{ With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own custom antimicrobial drug names and codes. diff --git a/man/add_custom_microorganisms.Rd b/man/add_custom_microorganisms.Rd index be7be3afe..1e8572be6 100644 --- a/man/add_custom_microorganisms.Rd +++ b/man/add_custom_microorganisms.Rd @@ -10,7 +10,7 @@ add_custom_microorganisms(x) clear_custom_microorganisms() } \arguments{ -\item{x}{a \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)} +\item{x}{A \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)} } \description{ With \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis. diff --git a/man/age.Rd b/man/age.Rd index 50a1cd64e..12bc693ab 100644 --- a/man/age.Rd +++ b/man/age.Rd @@ -7,15 +7,15 @@ age(x, reference = Sys.Date(), exact = FALSE, na.rm = FALSE, ...) } \arguments{ -\item{x}{date(s), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} +\item{x}{Date(s), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} -\item{reference}{reference date(s) (default is today), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} +\item{reference}{Reference date(s) (default is today), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}} -\item{exact}{a \link{logical} to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of \href{https://en.wikipedia.org/wiki/Year-to-date}{year-to-date} (YTD) of \code{x} by the number of days in the year of \code{reference} (either 365 or 366).} +\item{exact}{A \link{logical} to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of \href{https://en.wikipedia.org/wiki/Year-to-date}{year-to-date} (YTD) of \code{x} by the number of days in the year of \code{reference} (either 365 or 366).} -\item{na.rm}{a \link{logical} to indicate whether missing values should be removed} +\item{na.rm}{A \link{logical} to indicate whether missing values should be removed} -\item{...}{arguments passed on to \code{\link[=as.POSIXlt]{as.POSIXlt()}}, such as \code{origin}} +\item{...}{Arguments passed on to \code{\link[=as.POSIXlt]{as.POSIXlt()}}, such as \code{origin}} } \value{ An \link{integer} (no decimals) if \code{exact = FALSE}, a \link{double} (with decimals) otherwise diff --git a/man/age_groups.Rd b/man/age_groups.Rd index df8a722fe..775eb325b 100644 --- a/man/age_groups.Rd +++ b/man/age_groups.Rd @@ -7,11 +7,11 @@ age_groups(x, split_at = c(12, 25, 55, 75), na.rm = FALSE) } \arguments{ -\item{x}{age, e.g. calculated with \code{\link[=age]{age()}}} +\item{x}{Age, e.g. calculated with \code{\link[=age]{age()}}} -\item{split_at}{values to split \code{x} at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See \emph{Details}.} +\item{split_at}{Values to split \code{x} at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See \emph{Details}.} -\item{na.rm}{a \link{logical} to indicate whether missing values should be removed} +\item{na.rm}{A \link{logical} to indicate whether missing values should be removed} } \value{ Ordered \link{factor} diff --git a/man/antibiogram.Rd b/man/antibiogram.Rd index 01f117bd1..333eaa9c4 100644 --- a/man/antibiogram.Rd +++ b/man/antibiogram.Rd @@ -44,9 +44,9 @@ retrieve_wisca_parameters(wisca_model, ...) na = getOption("knitr.kable.NA", default = ""), ...) } \arguments{ -\item{x}{a \link{data.frame} containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see \code{\link[=as.sir]{as.sir()}})} +\item{x}{A \link{data.frame} containing at least a column with microorganisms and columns with antimicrobial results (class 'sir', see \code{\link[=as.sir]{as.sir()}})} -\item{antimicrobials}{a vector specifying the antimicrobials to include in the antibiogram (see \emph{Examples}). Will be evaluated using \code{\link[=guess_ab_col]{guess_ab_col()}}. This can be: +\item{antimicrobials}{A vector specifying the antimicrobials to include in the antibiogram (see \emph{Examples}). Will be evaluated using \code{\link[=guess_ab_col]{guess_ab_col()}}. This can be: \itemize{ \item Any antimicrobial name or code \item A column name in \code{x} that contains SIR values @@ -67,49 +67,49 @@ retrieve_wisca_parameters(wisca_model, ...) } }} -\item{mo_transform}{a character to transform microorganism input - must be \code{"name"}, \code{"shortname"} (default), \code{"gramstain"}, or one of the column names of the \link{microorganisms} data set: "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", or "snomed". Can also be \code{NULL} to not transform the input or \code{NA} to consider all microorganisms 'unknown'.} +\item{mo_transform}{A character to transform microorganism input - must be \code{"name"}, \code{"shortname"} (default), \code{"gramstain"}, or one of the column names of the \link{microorganisms} data set: "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", or "snomed". Can also be \code{NULL} to not transform the input or \code{NA} to consider all microorganisms 'unknown'.} -\item{ab_transform}{a character to transform antimicrobial input - must be one of the column names of the \link{antimicrobials} data set (defaults to \code{"name"}): "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.} +\item{ab_transform}{A character to transform antimicrobial input - must be one of the column names of the \link{antimicrobials} data set (defaults to \code{"name"}): "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.} -\item{syndromic_group}{a column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.} +\item{syndromic_group}{A column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.} -\item{add_total_n}{a \link{logical} to indicate whether \code{n_tested} available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when \code{wisca = TRUE}; in that case, use \code{\link[=retrieve_wisca_parameters]{retrieve_wisca_parameters()}} to get the parameters used for WISCA.} +\item{add_total_n}{A \link{logical} to indicate whether \code{n_tested} available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolates per antimicrobial (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200"). This option is unavailable when \code{wisca = TRUE}; in that case, use \code{\link[=retrieve_wisca_parameters]{retrieve_wisca_parameters()}} to get the parameters used for WISCA.} \item{only_all_tested}{(for combination antibiograms): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see \emph{Details}} -\item{digits}{number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise} +\item{digits}{Number of digits to use for rounding the antimicrobial coverage, defaults to 1 for WISCA and 0 otherwise} -\item{formatting_type}{numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See \emph{Details} > \emph{Formatting Type} for a list of options.} +\item{formatting_type}{Numeric value (1–22 for WISCA, 1-12 for non-WISCA) indicating how the 'cells' of the antibiogram table should be formatted. See \emph{Details} > \emph{Formatting Type} for a list of options.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{language}{language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is \code{TRUE})} +\item{combine_SI}{A \link{logical} to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is \code{TRUE})} -\item{sep}{a separating character for antimicrobial columns in combination antibiograms} +\item{sep}{A separating character for antimicrobial columns in combination antibiograms} -\item{wisca}{a \link{logical} to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is \code{FALSE}). This will use a Bayesian decision model to estimate regimen coverage probabilities using \href{https://en.wikipedia.org/wiki/Monte_Carlo_method}{Monte Carlo simulations}. Set \code{simulations}, \code{conf_interval}, and \code{interval_side} to adjust.} +\item{wisca}{A \link{logical} to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is \code{FALSE}). This will use a Bayesian decision model to estimate regimen coverage probabilities using \href{https://en.wikipedia.org/wiki/Monte_Carlo_method}{Monte Carlo simulations}. Set \code{simulations}, \code{conf_interval}, and \code{interval_side} to adjust.} \item{simulations}{(for WISCA) a numerical value to set the number of Monte Carlo simulations} -\item{conf_interval}{a numerical value to set confidence interval (default is \code{0.95})} +\item{conf_interval}{A numerical value to set confidence interval (default is \code{0.95})} -\item{interval_side}{the side of the confidence interval, either \code{"two-tailed"} (default), \code{"left"} or \code{"right"}} +\item{interval_side}{The side of the confidence interval, either \code{"two-tailed"} (default), \code{"left"} or \code{"right"}} -\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{when used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)} +\item{...}{When used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)} -\item{wisca_model}{the outcome of \code{\link[=wisca]{wisca()}} or \code{\link[=antibiogram]{antibiogram(..., wisca = TRUE)}}} +\item{wisca_model}{The outcome of \code{\link[=wisca]{wisca()}} or \code{\link[=antibiogram]{antibiogram(..., wisca = TRUE)}}} -\item{object}{an \code{\link[=antibiogram]{antibiogram()}} object} +\item{object}{An \code{\link[=antibiogram]{antibiogram()}} object} -\item{italicise}{a \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.} +\item{italicise}{A \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.} -\item{na}{character to use for showing \code{NA} values} +\item{na}{Character to use for showing \code{NA} values} } \description{ Create detailed antibiograms with options for traditional, combination, syndromic, and Bayesian WISCA methods. diff --git a/man/antimicrobial_selectors.Rd b/man/antimicrobial_selectors.Rd index 355ded935..2a3567e17 100644 --- a/man/antimicrobial_selectors.Rd +++ b/man/antimicrobial_selectors.Rd @@ -131,21 +131,21 @@ not_intrinsic_resistant(only_sir_columns = FALSE, col_mo = NULL, version_expected_phenotypes = 1.2, ...) } \arguments{ -\item{only_sir_columns}{a \link{logical} to indicate whether only columns of class \code{sir} must be selected (default is \code{FALSE}), see \code{\link[=as.sir]{as.sir()}}} +\item{only_sir_columns}{A \link{logical} to indicate whether only columns of class \code{sir} must be selected (default is \code{FALSE}), see \code{\link[=as.sir]{as.sir()}}} -\item{only_treatable}{a \link{logical} to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is \code{TRUE}), such as gentamicin-high (\code{GEH}) and imipenem/EDTA (\code{IPE})} +\item{only_treatable}{A \link{logical} to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is \code{TRUE}), such as gentamicin-high (\code{GEH}) and imipenem/EDTA (\code{IPE})} -\item{return_all}{a \link{logical} to indicate whether all matched columns must be returned (default is \code{TRUE}). With \code{FALSE}, only the first of each unique antimicrobial will be returned, e.g. if both columns \code{"genta"} and \code{"gentamicin"} exist in the data, only the first hit for gentamicin will be returned.} +\item{return_all}{A \link{logical} to indicate whether all matched columns must be returned (default is \code{TRUE}). With \code{FALSE}, only the first of each unique antimicrobial will be returned, e.g. if both columns \code{"genta"} and \code{"gentamicin"} exist in the data, only the first hit for gentamicin will be returned.} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} -\item{amr_class}{an antimicrobial class or a part of it, such as \code{"carba"} and \code{"carbapenems"}. The columns \code{group}, \code{atc_group1} and \code{atc_group2} of the \link{antimicrobials} data set will be searched (case-insensitive) for this value.} +\item{amr_class}{An antimicrobial class or a part of it, such as \code{"carba"} and \code{"carbapenems"}. The columns \code{group}, \code{atc_group1} and \code{atc_group2} of the \link{antimicrobials} data set will be searched (case-insensitive) for this value.} -\item{filter}{an \link{expression} to be evaluated in the \link{antimicrobials} data set, such as \code{name \%like\% "trim"}} +\item{filter}{An \link{expression} to be evaluated in the \link{antimicrobials} data set, such as \code{name \%like\% "trim"}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{version_expected_phenotypes}{the version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} +\item{version_expected_phenotypes}{The version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} } \value{ When used inside selecting or filtering, this returns a \link{character} vector of column names, with additional class \code{"amr_selector"}. When used individually, this returns an \link[=as.ab]{'ab' vector} with all possible antimicrobials that the function would be able to select or filter. diff --git a/man/as.ab.Rd b/man/as.ab.Rd index 7817761dc..e5f37fb75 100644 --- a/man/as.ab.Rd +++ b/man/as.ab.Rd @@ -15,15 +15,15 @@ is.ab(x) ab_reset_session() } \arguments{ -\item{x}{a \link{character} vector to determine to antibiotic ID} +\item{x}{A \link{character} vector to determine to antibiotic ID} -\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value.} +\item{flag_multiple_results}{A \link{logical} to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value.} -\item{language}{language to coerce input values from any of the 20 supported languages - default to the system language if supported (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to coerce input values from any of the 20 supported languages - default to the system language if supported (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to internal functions} +\item{...}{Arguments passed on to internal functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{ab}} diff --git a/man/as.av.Rd b/man/as.av.Rd index 4013d2daa..31519e669 100644 --- a/man/as.av.Rd +++ b/man/as.av.Rd @@ -11,13 +11,13 @@ as.av(x, flag_multiple_results = TRUE, info = interactive(), ...) is.av(x) } \arguments{ -\item{x}{a \link{character} vector to determine to antiviral drug ID} +\item{x}{A \link{character} vector to determine to antiviral drug ID} -\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value.} +\item{flag_multiple_results}{A \link{logical} to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to internal functions} +\item{...}{Arguments passed on to internal functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{ab}} diff --git a/man/as.disk.Rd b/man/as.disk.Rd index ad514090e..b4e195e19 100644 --- a/man/as.disk.Rd +++ b/man/as.disk.Rd @@ -18,9 +18,9 @@ NA_disk_ is.disk(x) } \arguments{ -\item{x}{vector} +\item{x}{Vector} -\item{na.rm}{a \link{logical} indicating whether missing values should be removed} +\item{na.rm}{A \link{logical} indicating whether missing values should be removed} } \value{ An \link{integer} with additional class \code{\link{disk}} diff --git a/man/as.mic.Rd b/man/as.mic.Rd index 6f6c03bb0..7ee0781f8 100644 --- a/man/as.mic.Rd +++ b/man/as.mic.Rd @@ -27,17 +27,17 @@ mic_p90(x, na.rm = FALSE, ...) \method{droplevels}{mic}(x, as.mic = FALSE, ...) } \arguments{ -\item{x}{a \link{character} or \link{numeric} vector} +\item{x}{A \link{character} or \link{numeric} vector} -\item{na.rm}{a \link{logical} indicating whether missing values should be removed} +\item{na.rm}{A \link{logical} indicating whether missing values should be removed} -\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} +\item{keep_operators}{A \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} -\item{mic_range}{a manual range to rescale the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}.} +\item{mic_range}{A manual range to rescale the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}.} -\item{as.mic}{a \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{TRUE} for \code{\link[=rescale_mic]{rescale_mic()}} and \code{FALSE} for \code{\link[=droplevels]{droplevels()}}. When setting this to \code{FALSE} in \code{\link[=rescale_mic]{rescale_mic()}}, the output will have factor levels that acknowledge \code{mic_range}.} +\item{as.mic}{A \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{TRUE} for \code{\link[=rescale_mic]{rescale_mic()}} and \code{FALSE} for \code{\link[=droplevels]{droplevels()}}. When setting this to \code{FALSE} in \code{\link[=rescale_mic]{rescale_mic()}}, the output will have factor levels that acknowledge \code{mic_range}.} -\item{...}{arguments passed on to methods} +\item{...}{Arguments passed on to methods} } \value{ Ordered \link{factor} with additional class \code{\link{mic}}, that in mathematical operations acts as a \link{numeric} vector. Bear in mind that the outcome of any mathematical operation on MICs will return a \link{numeric} value. @@ -82,10 +82,12 @@ subset(df, x > 4) # or with dplyr: df \%>\% filter(x > 4) #> 10 16 A }\if{html}{\out{}} -All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some functions of the \code{stats} package are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values. +All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some mathematical functions are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values. Using \code{\link[=as.double]{as.double()}} or \code{\link[=as.numeric]{as.numeric()}} on MIC values will remove the operators and return a numeric vector. Do \strong{not} use \code{\link[=as.integer]{as.integer()}} on MIC values as by the \R convention on \link{factor}s, it will return the index of the factor levels (which is often useless for regular users). +The function \code{\link[=is.mic]{is.mic()}} detects if the input contains class \code{mic}. If the input is a \link{data.frame} or \link{list}, it iterates over all columns/items and returns a \link{logical} vector. + Use \code{\link[=droplevels]{droplevels()}} to drop unused levels. At default, it will return a plain factor. Use \code{droplevels(..., as.mic = TRUE)} to maintain the \code{mic} class. With \code{\link[=rescale_mic]{rescale_mic()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. diff --git a/man/as.mo.Rd b/man/as.mo.Rd index c746ffa34..547701ccc 100644 --- a/man/as.mo.Rd +++ b/man/as.mo.Rd @@ -33,33 +33,33 @@ mo_reset_session() mo_cleaning_regex() } \arguments{ -\item{x}{a \link{character} vector or a \link{data.frame} with one or two columns} +\item{x}{A \link{character} vector or a \link{data.frame} with one or two columns} -\item{Becker}{a \link{logical} to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker \emph{et al.} (see \emph{Source}). Please see \emph{Details} for a full list of staphylococcal species that will be converted. +\item{Becker}{A \link{logical} to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker \emph{et al.} (see \emph{Source}). Please see \emph{Details} for a full list of staphylococcal species that will be converted. This excludes \emph{Staphylococcus aureus} at default, use \code{Becker = "all"} to also categorise \emph{S. aureus} as "CoPS".} -\item{Lancefield}{a \link{logical} to indicate whether a beta-haemolytic \emph{Streptococcus} should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see \emph{Source}). These streptococci will be categorised in their first group, e.g. \emph{Streptococcus dysgalactiae} will be group C, although officially it was also categorised into groups G and L. . Please see \emph{Details} for a full list of streptococcal species that will be converted. +\item{Lancefield}{A \link{logical} to indicate whether a beta-haemolytic \emph{Streptococcus} should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see \emph{Source}). These streptococci will be categorised in their first group, e.g. \emph{Streptococcus dysgalactiae} will be group C, although officially it was also categorised into groups G and L. . Please see \emph{Details} for a full list of streptococcal species that will be converted. This excludes enterococci at default (who are in group D), use \code{Lancefield = "all"} to also categorise all enterococci as group D.} -\item{minimum_matching_score}{a numeric value to set as the lower limit for the \link[=mo_matching_score]{MO matching score}. When left blank, this will be determined automatically based on the character length of \code{x}, its \link[=microorganisms]{taxonomic kingdom} and \link[=mo_matching_score]{human pathogenicity}.} +\item{minimum_matching_score}{A numeric value to set as the lower limit for the \link[=mo_matching_score]{MO matching score}. When left blank, this will be determined automatically based on the character length of \code{x}, its \link[=microorganisms]{taxonomic kingdom} and \link[=mo_matching_score]{human pathogenicity}.} -\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} +\item{keep_synonyms}{A \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} -\item{reference_df}{a \link{data.frame} to be used for extra reference when translating \code{x} to a valid \code{\link{mo}}. See \code{\link[=set_mo_source]{set_mo_source()}} and \code{\link[=get_mo_source]{get_mo_source()}} to automate the usage of your own codes (e.g. used in your analysis or organisation).} +\item{reference_df}{A \link{data.frame} to be used for extra reference when translating \code{x} to a valid \code{\link{mo}}. See \code{\link[=set_mo_source]{set_mo_source()}} and \code{\link[=get_mo_source]{get_mo_source()}} to automate the usage of your own codes (e.g. used in your analysis or organisation).} -\item{ignore_pattern}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) of which all matches in \code{x} must return \code{NA}. This can be convenient to exclude known non-relevant input and can also be set with the package option \code{\link[=AMR-options]{AMR_ignore_pattern}}, e.g. \code{options(AMR_ignore_pattern = "(not reported|contaminated flora)")}.} +\item{ignore_pattern}{A Perl-compatible \link[base:regex]{regular expression} (case-insensitive) of which all matches in \code{x} must return \code{NA}. This can be convenient to exclude known non-relevant input and can also be set with the package option \code{\link[=AMR-options]{AMR_ignore_pattern}}, e.g. \code{options(AMR_ignore_pattern = "(not reported|contaminated flora)")}.} -\item{cleaning_regex}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) to clean the input of \code{x}. Every matched part in \code{x} will be removed. At default, this is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option \code{\link[=AMR-options]{AMR_cleaning_regex}}.} +\item{cleaning_regex}{A Perl-compatible \link[base:regex]{regular expression} (case-insensitive) to clean the input of \code{x}. Every matched part in \code{x} will be removed. At default, this is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option \code{\link[=AMR-options]{AMR_cleaning_regex}}.} -\item{only_fungi}{a \link{logical} to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for \link[=mo_property]{all microorganism functions} with the package option \code{\link[=AMR-options]{AMR_only_fungi}}, i.e. \code{options(AMR_only_fungi = TRUE)}.} +\item{only_fungi}{A \link{logical} to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for \link[=mo_property]{all microorganism functions} with the package option \code{\link[=AMR-options]{AMR_only_fungi}}, i.e. \code{options(AMR_only_fungi = TRUE)}.} -\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{info}{a \link{logical} to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is \code{TRUE} only in interactive mode.} +\item{info}{A \link{logical} to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is \code{TRUE} only in interactive mode.} -\item{...}{other arguments passed on to functions} +\item{...}{Other arguments passed on to functions} } \value{ A \link{character} \link{vector} with additional class \code{\link{mo}} diff --git a/man/as.sir.Rd b/man/as.sir.Rd index 4bbd1983a..64ad0b143 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -70,21 +70,21 @@ is_sir_eligible(x, threshold = 0.05) sir_interpretation_history(clean = FALSE) } \arguments{ -\item{x}{vector of values (for class \code{\link{mic}}: MIC values in mg/L, for class \code{\link{disk}}: a disk diffusion radius in millimetres)} +\item{x}{Vector of values (for class \code{\link{mic}}: MIC values in mg/L, for class \code{\link{disk}}: a disk diffusion radius in millimetres)} -\item{...}{for using on a \link{data.frame}: names of columns to apply \code{\link[=as.sir]{as.sir()}} on (supports tidy selection such as \code{column1:column4}). Otherwise: arguments passed on to methods.} +\item{...}{For using on a \link{data.frame}: names of columns to apply \code{\link[=as.sir]{as.sir()}} on (supports tidy selection such as \code{column1:column4}). Otherwise: arguments passed on to methods.} -\item{threshold}{maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}} +\item{threshold}{Maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}} -\item{S, I, R, NI, SDD}{a case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters and whitespaces are removed from the input.} +\item{S, I, R, NI, SDD}{A case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters and whitespaces are removed from the input.} -\item{info}{a \link{logical} to print information about the process} +\item{info}{A \link{logical} to print information about the process} -\item{mo}{a vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically} +\item{mo}{A vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically} -\item{ab}{a vector (or column name) with \link{character}s that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{A vector (or column name) with \link{character}s that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{guideline}{defaults to EUCAST 2024 (the latest implemented EUCAST guideline in the \link{clinical_breakpoints} data set), but can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}. Currently supports EUCAST (2011-2024) and CLSI (2011-2024), see \emph{Details}.} +\item{guideline}{Defaults to EUCAST 2024 (the latest implemented EUCAST guideline in the \link{clinical_breakpoints} data set), but can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}. Currently supports EUCAST (2011-2024) and CLSI (2011-2024), see \emph{Details}.} \item{uti}{(Urinary Tract Infection) a vector (or column name) with \link{logical}s (\code{TRUE} or \code{FALSE}) to specify whether a UTI specific interpretation from the guideline should be chosen. For using \code{\link[=as.sir]{as.sir()}} on a \link{data.frame}, this can also be a column containing \link{logical}s or when left blank, the data set will be searched for a column 'specimen', and rows within this column containing 'urin' (such as 'urine', 'urina') will be regarded isolates from a UTI. See \emph{Examples}.} @@ -118,25 +118,25 @@ The default \code{"standard"} setting ensures cautious handling of uncertain val \item{add_intrinsic_resistance}{\emph{(only useful when using a EUCAST guideline)} a \link{logical} to indicate whether intrinsic antibiotic resistance must also be considered for applicable bug-drug combinations, meaning that e.g. ampicillin will always return "R" in \emph{Klebsiella} species. Determination is based on the \link{intrinsic_resistant} data set, that itself is based on \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021).} -\item{reference_data}{a \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.} +\item{reference_data}{A \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.} -\item{substitute_missing_r_breakpoint}{a \link{logical} to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is \code{FALSE}. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be \code{"S"} or \code{NA}. Setting this to \code{TRUE} will convert the \code{NA}s to \code{"R"} only if the R breakpoint is missing. Can also be set with the package option \code{\link[=AMR-options]{AMR_substitute_missing_r_breakpoint}}.} +\item{substitute_missing_r_breakpoint}{A \link{logical} to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is \code{FALSE}. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning the outcome can only be \code{"S"} or \code{NA}. Setting this to \code{TRUE} will convert the \code{NA}s to \code{"R"} only if the R breakpoint is missing. Can also be set with the package option \code{\link[=AMR-options]{AMR_substitute_missing_r_breakpoint}}.} -\item{include_screening}{a \link{logical} to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_screening}}.} +\item{include_screening}{A \link{logical} to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_screening}}.} -\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} +\item{include_PKPD}{A \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} -\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} +\item{breakpoint_type}{The type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} -\item{host}{a vector (or column name) with \link{character}s to indicate the host. Only useful for veterinary breakpoints, as it requires \code{breakpoint_type = "animal"}. The values can be any text resembling the animal species, even in any of the 20 supported languages of this package. For foreign languages, be sure to set the language with \code{\link[=set_AMR_locale]{set_AMR_locale()}} (though it will be automatically guessed based on the system language).} +\item{host}{A vector (or column name) with \link{character}s to indicate the host. Only useful for veterinary breakpoints, as it requires \code{breakpoint_type = "animal"}. The values can be any text resembling the animal species, even in any of the 20 supported languages of this package. For foreign languages, be sure to set the language with \code{\link[=set_AMR_locale]{set_AMR_locale()}} (though it will be automatically guessed based on the system language).} -\item{verbose}{a \link{logical} to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values.} +\item{verbose}{A \link{logical} to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values.} -\item{conserve_capped_values}{deprecated, use \code{capped_mic_handling} instead} +\item{conserve_capped_values}{Deprecated, use \code{capped_mic_handling} instead} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{clean}{a \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results} +\item{clean}{A \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results} } \value{ Ordered \link{factor} with new class \code{sir} @@ -229,7 +229,7 @@ The repository of this package \href{https://github.com/msberends/AMR/blob/main/ \subsection{Other}{ -The function \code{\link[=is.sir]{is.sir()}} detects if the input contains class \code{sir}. If the input is a \link{data.frame}, it iterates over all columns and returns a \link{logical} vector. +The function \code{\link[=is.sir]{is.sir()}} detects if the input contains class \code{sir}. If the input is a \link{data.frame} or \link{list}, it iterates over all columns/items and returns a \link{logical} vector. The base R function \code{\link[=as.double]{as.double()}} can be used to retrieve quantitative values from a \code{sir} object: \code{"S"} = 1, \code{"I"}/\code{"SDD"} = 2, \code{"R"} = 3. All other values are rendered \code{NA} . \strong{Note:} Do not use \code{as.integer()}, since that (because of how R works internally) will return the factor level indices, and not these aforementioned quantitative values. diff --git a/man/atc_online.Rd b/man/atc_online.Rd index 95ae2c4c8..01502ef61 100644 --- a/man/atc_online.Rd +++ b/man/atc_online.Rd @@ -21,17 +21,17 @@ atc_online_ddd(atc_code, ...) atc_online_ddd_units(atc_code, ...) } \arguments{ -\item{atc_code}{a \link{character} (vector) with ATC code(s) of antimicrobials, will be coerced with \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_atc]{ab_atc()}} internally if not a valid ATC code} +\item{atc_code}{A \link{character} (vector) with ATC code(s) of antimicrobials, will be coerced with \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_atc]{ab_atc()}} internally if not a valid ATC code} -\item{property}{property of an ATC code. Valid values are \code{"ATC"}, \code{"Name"}, \code{"DDD"}, \code{"U"} (\code{"unit"}), \code{"Adm.R"}, \code{"Note"} and \code{groups}. For this last option, all hierarchical groups of an ATC code will be returned, see \emph{Examples}.} +\item{property}{Property of an ATC code. Valid values are \code{"ATC"}, \code{"Name"}, \code{"DDD"}, \code{"U"} (\code{"unit"}), \code{"Adm.R"}, \code{"Note"} and \code{groups}. For this last option, all hierarchical groups of an ATC code will be returned, see \emph{Examples}.} -\item{administration}{type of administration when using \code{property = "Adm.R"}, see \emph{Details}} +\item{administration}{Type of administration when using \code{property = "Adm.R"}, see \emph{Details}} -\item{url}{url of website of the WHOCC. The sign \verb{\%s} can be used as a placeholder for ATC codes.} +\item{url}{URL of website of the WHOCC. The sign \verb{\%s} can be used as a placeholder for ATC codes.} -\item{url_vet}{url of website of the WHOCC for veterinary medicine. The sign \verb{\%s} can be used as a placeholder for ATC_vet codes (that all start with "Q").} +\item{url_vet}{URL of website of the WHOCC for veterinary medicine. The sign \verb{\%s} can be used as a placeholder for ATC_vet codes (that all start with "Q").} -\item{...}{arguments to pass on to \code{atc_property}} +\item{...}{Arguments to pass on to \code{atc_property}} } \description{ Gets data from the WHOCC website to determine properties of an Anatomical Therapeutic Chemical (ATC) (e.g. an antimicrobial), such as the name, defined daily dose (DDD) or standard unit. diff --git a/man/av_from_text.Rd b/man/av_from_text.Rd index e486f04aa..56c765a34 100644 --- a/man/av_from_text.Rd +++ b/man/av_from_text.Rd @@ -9,19 +9,19 @@ av_from_text(text, type = c("drug", "dose", "administration"), info = interactive(), ...) } \arguments{ -\item{text}{text to analyse} +\item{text}{Text to analyse} -\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} +\item{type}{Type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}} -\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} +\item{collapse}{A \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}} -\item{translate_av}{if \code{type = "drug"}: a column name of the \link{antivirals} data set to translate the antibiotic abbreviations to, using \code{\link[=av_property]{av_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} +\item{translate_av}{If \code{type = "drug"}: a column name of the \link{antivirals} data set to translate the antibiotic abbreviations to, using \code{\link[=av_property]{av_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".} -\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} +\item{thorough_search}{A \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.} -\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode} -\item{...}{arguments passed on to \code{\link[=as.av]{as.av()}}} +\item{...}{Arguments passed on to \code{\link[=as.av]{as.av()}}} } \value{ A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL} diff --git a/man/av_property.Rd b/man/av_property.Rd index 473032e73..ac7f4c630 100644 --- a/man/av_property.Rd +++ b/man/av_property.Rd @@ -40,19 +40,19 @@ av_url(x, open = FALSE, ...) av_property(x, property = "name", language = get_AMR_locale(), ...) } \arguments{ -\item{x}{any (vector of) text that can be coerced to a valid antiviral drug code with \code{\link[=as.av]{as.av()}}} +\item{x}{Any (vector of) text that can be coerced to a valid antiviral drug code with \code{\link[=as.av]{as.av()}}} -\item{language}{language of the returned text - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}.} +\item{tolower}{A \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}.} -\item{...}{other arguments passed on to \code{\link[=as.av]{as.av()}}} +\item{...}{Other arguments passed on to \code{\link[=as.av]{as.av()}}} -\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}} +\item{administration}{Way of administration, either \code{"oral"} or \code{"iv"}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}} -\item{property}{one of the column names of one of the \link{antivirals} data set: \code{vector_or(colnames(antivirals), sort = FALSE)}.} +\item{property}{One of the column names of one of the \link{antivirals} data set: \code{vector_or(colnames(antivirals), sort = FALSE)}.} } \value{ \itemize{ diff --git a/man/availability.Rd b/man/availability.Rd index 4fe1e0c5e..0893cc7fa 100644 --- a/man/availability.Rd +++ b/man/availability.Rd @@ -7,9 +7,9 @@ availability(tbl, width = NULL) } \arguments{ -\item{tbl}{a \link{data.frame} or \link{list}} +\item{tbl}{A \link{data.frame} or \link{list}} -\item{width}{number of characters to present the visual availability - the default is filling the width of the console} +\item{width}{Number of characters to present the visual availability - the default is filling the width of the console} } \value{ \link{data.frame} with column names of \code{tbl} as row names diff --git a/man/bug_drug_combinations.Rd b/man/bug_drug_combinations.Rd index 550083624..cef3213bf 100644 --- a/man/bug_drug_combinations.Rd +++ b/man/bug_drug_combinations.Rd @@ -15,25 +15,25 @@ bug_drug_combinations(x, col_mo = NULL, FUN = mo_shortname, ",", ".", ","), ...) } \arguments{ -\item{x}{a data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} +\item{x}{A data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{FUN}{the function to call on the \code{mo} column to transform the microorganism codes - the default is \code{\link[=mo_shortname]{mo_shortname()}}} +\item{FUN}{The function to call on the \code{mo} column to transform the microorganism codes - the default is \code{\link[=mo_shortname]{mo_shortname()}}} -\item{include_n_rows}{a \link{logical} to indicate if the total number of rows must be included in the output} +\item{include_n_rows}{A \link{logical} to indicate if the total number of rows must be included in the output} -\item{...}{arguments passed on to \code{FUN}} +\item{...}{Arguments passed on to \code{FUN}} -\item{translate_ab}{a \link{character} of length 1 containing column names of the \link{antimicrobials} data set} +\item{translate_ab}{A \link{character} of length 1 containing column names of the \link{antimicrobials} data set} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is \code{TRUE}} -\item{add_ab_group}{a \link{logical} to indicate where the group of the antimicrobials must be included as a first column} +\item{add_ab_group}{A \link{logical} to indicate where the group of the antimicrobials must be included as a first column} \item{remove_intrinsic_resistant}{\link{logical} to indicate that rows and columns with 100\% resistance for all tested antimicrobials must be removed from the table} diff --git a/man/count.Rd b/man/count.Rd index 3603024d1..bf0455e69 100644 --- a/man/count.Rd +++ b/man/count.Rd @@ -36,17 +36,17 @@ count_df(data, translate_ab = "name", language = get_AMR_locale(), combine_SI = TRUE) } \arguments{ -\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed.} +\item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed.} \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below} -\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} } \value{ An \link{integer} diff --git a/man/custom_eucast_rules.Rd b/man/custom_eucast_rules.Rd index 152b7e224..d41a10800 100644 --- a/man/custom_eucast_rules.Rd +++ b/man/custom_eucast_rules.Rd @@ -7,7 +7,7 @@ custom_eucast_rules(...) } \arguments{ -\item{...}{rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}} +\item{...}{Rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}} } \value{ A \link{list} containing the custom rules diff --git a/man/eucast_rules.Rd b/man/eucast_rules.Rd index 146468e1d..011ca2d04 100644 --- a/man/eucast_rules.Rd +++ b/man/eucast_rules.Rd @@ -29,35 +29,35 @@ eucast_rules(x, col_mo = NULL, info = interactive(), eucast_dosage(ab, administration = "iv", version_breakpoints = 12) } \arguments{ -\item{x}{a data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} +\item{x}{A data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} +\item{info}{A \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} -\item{rules}{a \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.} +\item{rules}{A \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.} -\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.} +\item{verbose}{A \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.} -\item{version_breakpoints}{the version number to use for the EUCAST Clinical Breakpoints guideline. Can be "14.0", "13.1", "12.0", "11.0", or "10.0".} +\item{version_breakpoints}{The version number to use for the EUCAST Clinical Breakpoints guideline. Can be "14.0", "13.1", "12.0", "11.0", or "10.0".} -\item{version_expected_phenotypes}{the version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} +\item{version_expected_phenotypes}{The version number to use for the EUCAST Expected Phenotypes. Can be "1.2".} -\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".} +\item{version_expertrules}{The version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".} \item{ampc_cephalosporin_resistance}{(only applies when \code{rules} contains \code{"expert"} or \code{"all"}) a \link{character} value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants - the default is \code{NA}. Currently only works when \code{version_expertrules} is \code{3.2} and higher; these versions of '\emph{EUCAST Expert Rules on Enterobacterales}' state that results of cefotaxime, ceftriaxone and ceftazidime should be reported with a note, or results should be suppressed (emptied) for these three drugs. A value of \code{NA} (the default) for this argument will remove results for these three drugs, while e.g. a value of \code{"R"} will make the results for these drugs resistant. Use \code{NULL} or \code{FALSE} to not alter results for these three drugs of AmpC de-repressed cephalosporin-resistant mutants. Using \code{TRUE} is equal to using \code{"R"}. \cr For \emph{EUCAST Expert Rules} v3.2, this rule applies to: \emph{Citrobacter braakii}, \emph{Citrobacter freundii}, \emph{Citrobacter gillenii}, \emph{Citrobacter murliniae}, \emph{Citrobacter rodenticum}, \emph{Citrobacter sedlakii}, \emph{Citrobacter werkmanii}, \emph{Citrobacter youngae}, \emph{Enterobacter}, \emph{Hafnia alvei}, \emph{Klebsiella aerogenes}, \emph{Morganella morganii}, \emph{Providencia}, and \emph{Serratia}.} -\item{only_sir_columns}{a \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{custom_rules}{custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}} +\item{custom_rules}{Custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}} \item{overwrite}{A \link{logical} indicating whether to overwrite non-\code{NA} values (default: \code{FALSE}). When \code{FALSE}, only \code{NA} values are modified. To ensure compliance with EUCAST guidelines, \strong{this should remain} \code{FALSE}, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant."} -\item{...}{column name of an antimicrobial, see section \emph{Antimicrobials} below} +\item{...}{Column name of an antimicrobial, see section \emph{Antimicrobials} below} -\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{administration}{route of administration, either "im", "iv", or "oral"} +\item{administration}{Route of administration, either "im", "iv", or "oral"} } \value{ The input of \code{x}, possibly with edited values of antimicrobials. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations. diff --git a/man/export_ncbi_biosample.Rd b/man/export_ncbi_biosample.Rd index c3977618c..003a19782 100644 --- a/man/export_ncbi_biosample.Rd +++ b/man/export_ncbi_biosample.Rd @@ -9,11 +9,11 @@ export_ncbi_biosample(x, filename = paste0("biosample_", format(Sys.time(), columns = where(is.mic), save_as_xlsx = TRUE) } \arguments{ -\item{x}{a data set} +\item{x}{A data set} -\item{filename}{a character string specifying the file name} +\item{filename}{A character string specifying the file name} -\item{type}{a character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see \url{https://www.ncbi.nlm.nih.gov/biosample/docs/}} +\item{type}{A character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see \url{https://www.ncbi.nlm.nih.gov/biosample/docs/}} } \description{ Export Data Set as NCBI BioSample Antibiogram diff --git a/man/first_isolate.Rd b/man/first_isolate.Rd index 23e38b0df..3dd668122 100644 --- a/man/first_isolate.Rd +++ b/man/first_isolate.Rd @@ -26,45 +26,45 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, "episode-based", "patient-based", "isolate-based"), ...) } \arguments{ -\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} +\item{x}{A \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} -\item{col_date}{column name of the result date (or date that is was received on the lab) - the default is the first column with a date class} +\item{col_date}{Column name of the result date (or date that is was received on the lab) - the default is the first column with a date class} -\item{col_patient_id}{column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive)} +\item{col_patient_id}{Column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive)} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{col_testcode}{column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.} +\item{col_testcode}{Column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.} -\item{col_specimen}{column name of the specimen type or group} +\item{col_specimen}{Column name of the specimen type or group} -\item{col_icu}{column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU). This can also be a \link{logical} vector with the same length as rows in \code{x}.} +\item{col_icu}{Column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU). This can also be a \link{logical} vector with the same length as rows in \code{x}.} \item{col_keyantimicrobials}{(only useful when \code{method = "phenotype-based"}) column name of the key antimicrobials to determine first isolates, see \code{\link[=key_antimicrobials]{key_antimicrobials()}}. The default is the first column that starts with 'key' followed by 'ab' or 'antibiotics' or 'antimicrobials' (case insensitive). Use \code{col_keyantimicrobials = FALSE} to prevent this. Can also be the output of \code{\link[=key_antimicrobials]{key_antimicrobials()}}.} -\item{episode_days}{episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see \emph{Source}.} +\item{episode_days}{Episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see \emph{Source}.} -\item{testcodes_exclude}{a \link{character} vector with test codes that should be excluded (case-insensitive)} +\item{testcodes_exclude}{A \link{character} vector with test codes that should be excluded (case-insensitive)} -\item{icu_exclude}{a \link{logical} to indicate whether ICU isolates should be excluded (rows with value \code{TRUE} in the column set with \code{col_icu})} +\item{icu_exclude}{A \link{logical} to indicate whether ICU isolates should be excluded (rows with value \code{TRUE} in the column set with \code{col_icu})} -\item{specimen_group}{value in the column set with \code{col_specimen} to filter on} +\item{specimen_group}{Value in the column set with \code{col_specimen} to filter on} -\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} +\item{type}{Type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} -\item{method}{the method to apply, either \code{"phenotype-based"}, \code{"episode-based"}, \code{"patient-based"} or \code{"isolate-based"} (can be abbreviated), see \emph{Details}. The default is \code{"phenotype-based"} if antimicrobial test results are present in the data, and \code{"episode-based"} otherwise.} +\item{method}{The method to apply, either \code{"phenotype-based"}, \code{"episode-based"}, \code{"patient-based"} or \code{"isolate-based"} (can be abbreviated), see \emph{Details}. The default is \code{"phenotype-based"} if antimicrobial test results are present in the data, and \code{"episode-based"} otherwise.} \item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}} -\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} +\item{points_threshold}{Minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} -\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} +\item{info}{A \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode} -\item{include_unknown}{a \link{logical} to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code \code{"UNKNOWN"}, which defaults to \code{FALSE}. For WHONET users, this means that all records with organism code \code{"con"} (\emph{contamination}) will be excluded at default. Isolates with a microbial ID of \code{NA} will always be excluded as first isolate.} +\item{include_unknown}{A \link{logical} to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code \code{"UNKNOWN"}, which defaults to \code{FALSE}. For WHONET users, this means that all records with organism code \code{"con"} (\emph{contamination}) will be excluded at default. Isolates with a microbial ID of \code{NA} will always be excluded as first isolate.} -\item{include_untested_sir}{a \link{logical} to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use \code{include_untested_sir = FALSE} to always return \code{FALSE} for such rows. This checks the data set for columns of class \code{sir} and consequently requires transforming columns with antibiotic results using \code{\link[=as.sir]{as.sir()}} first.} +\item{include_untested_sir}{A \link{logical} to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use \code{include_untested_sir = FALSE} to always return \code{FALSE} for such rows. This checks the data set for columns of class \code{sir} and consequently requires transforming columns with antibiotic results using \code{\link[=as.sir]{as.sir()}} first.} -\item{...}{arguments passed on to \code{\link[=first_isolate]{first_isolate()}} when using \code{\link[=filter_first_isolate]{filter_first_isolate()}}, otherwise arguments passed on to \code{\link[=key_antimicrobials]{key_antimicrobials()}} (such as \code{universal}, \code{gram_negative}, \code{gram_positive})} +\item{...}{Arguments passed on to \code{\link[=first_isolate]{first_isolate()}} when using \code{\link[=filter_first_isolate]{filter_first_isolate()}}, otherwise arguments passed on to \code{\link[=key_antimicrobials]{key_antimicrobials()}} (such as \code{universal}, \code{gram_negative}, \code{gram_positive})} } \value{ A \link{logical} vector diff --git a/man/get_episode.Rd b/man/get_episode.Rd index e47235cfb..c278a3495 100644 --- a/man/get_episode.Rd +++ b/man/get_episode.Rd @@ -10,13 +10,13 @@ get_episode(x, episode_days = NULL, case_free_days = NULL, ...) is_new_episode(x, episode_days = NULL, case_free_days = NULL, ...) } \arguments{ -\item{x}{vector of dates (class \code{Date} or \code{POSIXt}), will be sorted internally to determine episodes} +\item{x}{Vector of dates (class \code{Date} or \code{POSIXt}), will be sorted internally to determine episodes} -\item{episode_days}{episode length in days to specify the time period after which a new episode begins, can also be less than a day or \code{Inf}, see \emph{Details}} +\item{episode_days}{Episode length in days to specify the time period after which a new episode begins, can also be less than a day or \code{Inf}, see \emph{Details}} \item{case_free_days}{(inter-epidemic) interval length in days after which a new episode will start, can also be less than a day or \code{Inf}, see \emph{Details}} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} } \value{ \itemize{ diff --git a/man/ggplot_pca.Rd b/man/ggplot_pca.Rd index bec3c36a6..1af5ad4dc 100644 --- a/man/ggplot_pca.Rd +++ b/man/ggplot_pca.Rd @@ -26,7 +26,7 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, arrows_alpha = 0.75, base_textsize = 10, ...) } \arguments{ -\item{x}{an object returned by \code{\link[=pca]{pca()}}, \code{\link[=prcomp]{prcomp()}} or \code{\link[=princomp]{princomp()}}} +\item{x}{An object returned by \code{\link[=pca]{pca()}}, \code{\link[=prcomp]{prcomp()}} or \code{\link[=princomp]{princomp()}}} \item{choices}{ length 2 vector specifying the components to plot. Only the default @@ -49,41 +49,41 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, approximate Mahalanobis distance. } -\item{labels}{an optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} +\item{labels}{An optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} -\item{labels_textsize}{the size of the text used for the labels} +\item{labels_textsize}{The size of the text used for the labels} -\item{labels_text_placement}{adjustment factor the placement of the variable names (\verb{>=1} means further away from the arrow head)} +\item{labels_text_placement}{Adjustment factor the placement of the variable names (\verb{>=1} means further away from the arrow head)} -\item{groups}{an optional vector of groups for the labels, with the same length as \code{labels}. If set, the points and labels will be coloured according to these groups. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} +\item{groups}{An optional vector of groups for the labels, with the same length as \code{labels}. If set, the points and labels will be coloured according to these groups. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.} -\item{ellipse}{a \link{logical} to indicate whether a normal data ellipse should be drawn for each group (set with \code{groups})} +\item{ellipse}{A \link{logical} to indicate whether a normal data ellipse should be drawn for each group (set with \code{groups})} -\item{ellipse_prob}{statistical size of the ellipse in normal probability} +\item{ellipse_prob}{Statistical size of the ellipse in normal probability} -\item{ellipse_size}{the size of the ellipse line} +\item{ellipse_size}{The size of the ellipse line} -\item{ellipse_alpha}{the alpha (transparency) of the ellipse line} +\item{ellipse_alpha}{The alpha (transparency) of the ellipse line} -\item{points_size}{the size of the points} +\item{points_size}{The size of the points} -\item{points_alpha}{the alpha (transparency) of the points} +\item{points_alpha}{The alpha (transparency) of the points} -\item{arrows}{a \link{logical} to indicate whether arrows should be drawn} +\item{arrows}{A \link{logical} to indicate whether arrows should be drawn} -\item{arrows_colour}{the colour of the arrow and their text} +\item{arrows_colour}{The colour of the arrow and their text} -\item{arrows_size}{the size (thickness) of the arrow lines} +\item{arrows_size}{The size (thickness) of the arrow lines} -\item{arrows_textsize}{the size of the text at the end of the arrows} +\item{arrows_textsize}{The size of the text at the end of the arrows} -\item{arrows_textangled}{a \link{logical} whether the text at the end of the arrows should be angled} +\item{arrows_textangled}{A \link{logical} whether the text at the end of the arrows should be angled} -\item{arrows_alpha}{the alpha (transparency) of the arrows and their text} +\item{arrows_alpha}{The alpha (transparency) of the arrows and their text} -\item{base_textsize}{the text size for all plot elements except the labels and arrows} +\item{base_textsize}{The text size for all plot elements except the labels and arrows} -\item{...}{arguments passed on to functions} +\item{...}{Arguments passed on to functions} } \description{ Produces a \code{ggplot2} variant of a so-called \href{https://en.wikipedia.org/wiki/Biplot}{biplot} for PCA (principal component analysis), but is more flexible and more appealing than the base \R \code{\link[=biplot]{biplot()}} function. diff --git a/man/ggplot_sir.Rd b/man/ggplot_sir.Rd index eb3aab4d1..ea04f2968 100644 --- a/man/ggplot_sir.Rd +++ b/man/ggplot_sir.Rd @@ -19,49 +19,49 @@ geom_sir(position = NULL, x = c("antibiotic", "interpretation"), language = get_AMR_locale(), combine_SI = TRUE, ...) } \arguments{ -\item{data}{a \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{position}{position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} +\item{position}{Position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} -\item{x}{variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} +\item{x}{Variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} -\item{fill}{variable to categorise using the plots legend, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} +\item{fill}{Variable to categorise using the plots legend, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable} -\item{facet}{variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} +\item{facet}{Variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} -\item{breaks}{a \link{numeric} vector of positions} +\item{breaks}{A \link{numeric} vector of positions} -\item{limits}{a \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} +\item{limits}{A \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} \item{nrow}{(when using \code{facet}) number of rows} -\item{colours}{a named vactor with colour to be used for filling. The default colours are colour-blind friendly.} +\item{colours}{A named vactor with colour to be used for filling. The default colours are colour-blind friendly.} -\item{datalabels}{show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}} +\item{datalabels}{Show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}} -\item{datalabels.size}{size of the datalabels} +\item{datalabels.size}{Size of the datalabels} -\item{datalabels.colour}{colour of the datalabels} +\item{datalabels.colour}{Colour of the datalabels} -\item{title}{text to show as title of the plot} +\item{title}{Text to show as title of the plot} -\item{subtitle}{text to show as subtitle of the plot} +\item{subtitle}{Text to show as subtitle of the plot} -\item{caption}{text to show as caption of the plot} +\item{caption}{Text to show as caption of the plot} -\item{x.title}{text to show as x axis description} +\item{x.title}{Text to show as x axis description} -\item{y.title}{text to show as y axis description} +\item{y.title}{Text to show as y axis description} -\item{...}{other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.} +\item{...}{Other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.} } \description{ Use these functions to create bar plots for AMR data analysis. All functions rely on \link[ggplot2:ggplot]{ggplot2} functions. @@ -76,7 +76,7 @@ Additional functions include: \item \code{\link[=facet_sir]{facet_sir()}} creates 2d plots (at default based on S/I/R) using \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}}. \item \code{\link[=scale_y_percent]{scale_y_percent()}} transforms the y axis to a 0 to 100\% range using \code{\link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous()}}. \item \code{\link[=scale_sir_colours]{scale_sir_colours()}} sets colours to the bars (green for S, yellow for I, and red for R). with multilingual support. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. -\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction. +\item \code{\link[=theme_sir]{theme_sir()}} is a \link[ggplot2:theme]{ggplot2 theme} with minimal distraction. \item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and amount of isolates using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}. } diff --git a/man/guess_ab_col.Rd b/man/guess_ab_col.Rd index 9f189858f..ae770691a 100644 --- a/man/guess_ab_col.Rd +++ b/man/guess_ab_col.Rd @@ -8,13 +8,13 @@ guess_ab_col(x = NULL, search_string = NULL, verbose = FALSE, only_sir_columns = FALSE) } \arguments{ -\item{x}{a \link{data.frame}} +\item{x}{A \link{data.frame}} -\item{search_string}{a text to search \code{x} for, will be checked with \code{\link[=as.ab]{as.ab()}} if this value is not a column in \code{x}} +\item{search_string}{A text to search \code{x} for, will be checked with \code{\link[=as.ab]{as.ab()}} if this value is not a column in \code{x}} -\item{verbose}{a \link{logical} to indicate whether additional info should be printed} +\item{verbose}{A \link{logical} to indicate whether additional info should be printed} -\item{only_sir_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} } \value{ A column name of \code{x}, or \code{NULL} when no result is found. diff --git a/man/italicise_taxonomy.Rd b/man/italicise_taxonomy.Rd index 18b83e323..b51012df4 100644 --- a/man/italicise_taxonomy.Rd +++ b/man/italicise_taxonomy.Rd @@ -10,9 +10,9 @@ italicise_taxonomy(string, type = c("markdown", "ansi", "html")) italicize_taxonomy(string, type = c("markdown", "ansi", "html")) } \arguments{ -\item{string}{a \link{character} (vector)} +\item{string}{A \link{character} (vector)} -\item{type}{type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see \emph{Details}} +\item{type}{Type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see \emph{Details}} } \description{ According to the binomial nomenclature, the lowest four taxonomic levels (family, genus, species, subspecies) should be printed in italics. This function finds taxonomic names within strings and makes them italic. diff --git a/man/join.Rd b/man/join.Rd index 0c7e85cb1..701d00b67 100644 --- a/man/join.Rd +++ b/man/join.Rd @@ -24,13 +24,13 @@ semi_join_microorganisms(x, by = NULL, ...) anti_join_microorganisms(x, by = NULL, ...) } \arguments{ -\item{x}{existing data set to join, or \link{character} vector. In case of a \link{character} vector, the resulting \link{data.frame} will contain a column 'x' with these values.} +\item{x}{Existing data set to join, or \link{character} vector. In case of a \link{character} vector, the resulting \link{data.frame} will contain a column 'x' with these values.} -\item{by}{a variable to join by - if left empty will search for a column with class \code{\link{mo}} (created with \code{\link[=as.mo]{as.mo()}}) or will be \code{"mo"} if that column name exists in \code{x}, could otherwise be a column name of \code{x} with values that exist in \code{microorganisms$mo} (such as \code{by = "bacteria_id"}), or another column in \link{microorganisms} (but then it should be named, like \code{by = c("bacteria_id" = "fullname")})} +\item{by}{A variable to join by - if left empty will search for a column with class \code{\link{mo}} (created with \code{\link[=as.mo]{as.mo()}}) or will be \code{"mo"} if that column name exists in \code{x}, could otherwise be a column name of \code{x} with values that exist in \code{microorganisms$mo} (such as \code{by = "bacteria_id"}), or another column in \link{microorganisms} (but then it should be named, like \code{by = c("bacteria_id" = "fullname")})} -\item{suffix}{if there are non-joined duplicate variables in \code{x} and \code{y}, these suffixes will be added to the output to disambiguate them. Should be a \link{character} vector of length 2.} +\item{suffix}{If there are non-joined duplicate variables in \code{x} and \code{y}, these suffixes will be added to the output to disambiguate them. Should be a \link{character} vector of length 2.} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} } \value{ a \link{data.frame} diff --git a/man/key_antimicrobials.Rd b/man/key_antimicrobials.Rd index 7fb2e9968..e4501d8bd 100644 --- a/man/key_antimicrobials.Rd +++ b/man/key_antimicrobials.Rd @@ -21,29 +21,29 @@ antimicrobials_equal(y, z, type = c("points", "keyantimicrobials"), ignore_I = TRUE, points_threshold = 2, ...) } \arguments{ -\item{x}{a \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically.} +\item{x}{A \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} -\item{universal}{names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs} +\item{universal}{Names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs} -\item{gram_negative}{names of antibiotic drugs for \strong{Gram-positives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} +\item{gram_negative}{Names of antibiotic drugs for \strong{Gram-positives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} -\item{gram_positive}{names of antibiotic drugs for \strong{Gram-negatives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} +\item{gram_positive}{Names of antibiotic drugs for \strong{Gram-negatives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs} -\item{antifungal}{names of antifungal drugs for \strong{fungi}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antifungal drugs} +\item{antifungal}{Names of antifungal drugs for \strong{fungi}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antifungal drugs} -\item{only_sir_columns}{a \link{logical} to indicate whether only columns must be included that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only columns must be included that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} \item{y, z}{\link{character} vectors to compare} -\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} +\item{type}{Type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}} \item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}} -\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} +\item{points_threshold}{Minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}} } \description{ These functions can be used to determine first weighted isolates by considering the phenotype for isolate selection (see \code{\link[=first_isolate]{first_isolate()}}). Using a phenotype-based method to determine first isolates is more reliable than methods that disregard phenotypes. diff --git a/man/kurtosis.Rd b/man/kurtosis.Rd index 3dd712165..0bbc35407 100644 --- a/man/kurtosis.Rd +++ b/man/kurtosis.Rd @@ -16,11 +16,11 @@ kurtosis(x, na.rm = FALSE, excess = FALSE) \method{kurtosis}{data.frame}(x, na.rm = FALSE, excess = FALSE) } \arguments{ -\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}} +\item{x}{A vector of values, a \link{matrix} or a \link{data.frame}} -\item{na.rm}{a \link{logical} to indicate whether \code{NA} values should be stripped before the computation proceeds} +\item{na.rm}{A \link{logical} to indicate whether \code{NA} values should be stripped before the computation proceeds} -\item{excess}{a \link{logical} to indicate whether the \emph{excess kurtosis} should be returned, defined as the kurtosis minus 3.} +\item{excess}{A \link{logical} to indicate whether the \emph{excess kurtosis} should be returned, defined as the kurtosis minus 3.} } \description{ Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. A normal distribution has a kurtosis of 3 and a excess kurtosis of 0. diff --git a/man/like.Rd b/man/like.Rd index 76ba8a994..c1c72187c 100644 --- a/man/like.Rd +++ b/man/like.Rd @@ -22,11 +22,11 @@ x \%like_case\% pattern x \%unlike_case\% pattern } \arguments{ -\item{x}{a \link{character} vector where matches are sought, or an object which can be coerced by \code{\link[=as.character]{as.character()}} to a \link{character} vector.} +\item{x}{A \link{character} vector where matches are sought, or an object which can be coerced by \code{\link[=as.character]{as.character()}} to a \link{character} vector.} -\item{pattern}{a \link{character} vector containing regular expressions (or a \link{character} string for \code{fixed = TRUE}) to be matched in the given \link{character} vector. Coerced by \code{\link[=as.character]{as.character()}} to a \link{character} string if possible.} +\item{pattern}{A \link{character} vector containing regular expressions (or a \link{character} string for \code{fixed = TRUE}) to be matched in the given \link{character} vector. Coerced by \code{\link[=as.character]{as.character()}} to a \link{character} string if possible.} -\item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case sensitive} and if \code{TRUE}, case is ignored during matching.} +\item{ignore.case}{If \code{FALSE}, the pattern matching is \emph{case sensitive} and if \code{TRUE}, case is ignored during matching.} } \value{ A \link{logical} vector diff --git a/man/mdro.Rd b/man/mdro.Rd index 20e053dbd..b416625af 100644 --- a/man/mdro.Rd +++ b/man/mdro.Rd @@ -38,11 +38,11 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, verbose = FALSE, ...) } \arguments{ -\item{x}{a \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank for automatic determination.} +\item{x}{A \link{data.frame} with antimicrobials columns, like \code{AMX} or \code{amox}. Can be left blank for automatic determination.} -\item{guideline}{a specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.} +\item{guideline}{A specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.} -\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} +\item{col_mo}{Column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} \item{esbl}{\link{logical} values, or a column name containing logical values, indicating the presence of an ESBL gene (or production of its proteins)} @@ -56,19 +56,19 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \item{vanB}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanB} gene (or production of its proteins)} -\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} +\item{info}{A \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions} -\item{pct_required_classes}{minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for \emph{S. aureus}. Setting this \code{pct_required_classes} argument to \code{0.5} (default) means that for every \emph{S. aureus} isolate at least 8 different classes must be available. Any lower number of available classes will return \code{NA} for that isolate.} +\item{pct_required_classes}{Minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for \emph{S. aureus}. Setting this \code{pct_required_classes} argument to \code{0.5} (default) means that for every \emph{S. aureus} isolate at least 8 different classes must be available. Any lower number of available classes will return \code{NA} for that isolate.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the \code{\link[=mdro]{mdro()}} function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using \code{combine_SI = FALSE}, resistance is considered when isolates are R or I.} +\item{combine_SI}{A \link{logical} to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the \code{\link[=mdro]{mdro()}} function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using \code{combine_SI = FALSE}, resistance is considered when isolates are R or I.} -\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.} +\item{verbose}{A \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.} -\item{only_sir_columns}{a \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} +\item{only_sir_columns}{A \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})} -\item{...}{in case of \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}}: a set of rules, see section \emph{Using Custom Guidelines} below. Otherwise: column name of an antibiotic, see section \emph{Antimicrobials} below.} +\item{...}{In case of \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}}: a set of rules, see section \emph{Using Custom Guidelines} below. Otherwise: column name of an antibiotic, see section \emph{Antimicrobials} below.} -\item{as_factor}{a \link{logical} to indicate whether the returned value should be an ordered \link{factor} (\code{TRUE}, default), or otherwise a \link{character} vector} +\item{as_factor}{A \link{logical} to indicate whether the returned value should be an ordered \link{factor} (\code{TRUE}, default), or otherwise a \link{character} vector} } \value{ \itemize{ diff --git a/man/mean_amr_distance.Rd b/man/mean_amr_distance.Rd index a00cefd23..2c19093c8 100644 --- a/man/mean_amr_distance.Rd +++ b/man/mean_amr_distance.Rd @@ -16,15 +16,15 @@ mean_amr_distance(x, ...) amr_distance_from_row(amr_distance, row) } \arguments{ -\item{x}{a vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes} +\item{x}{A vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes} -\item{...}{variables to select (supports \link[tidyselect:language]{tidyselect language} such as \code{column1:column4} and \code{where(is.mic)}, and can thus also be \link[=amr_selector]{antimicrobial selectors}} +\item{...}{Variables to select. Supports \link[tidyselect:language]{tidyselect language} (such as \code{column1:column4} and \code{where(is.mic)}), and can thus also be \link[=amr_selector]{antimicrobial selectors}} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{amr_distance}{the outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}} +\item{amr_distance}{The outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}} -\item{row}{an index, such as a row number} +\item{row}{An index, such as a row number} } \description{ Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand. @@ -69,7 +69,7 @@ y <- data.frame( ) y mean_amr_distance(y) -y$amr_distance <- mean_amr_distance(y, where(is.mic)) +y$amr_distance <- mean_amr_distance(y, is.mic(y)) y[order(y$amr_distance), ] if (require("dplyr")) { diff --git a/man/mo_property.Rd b/man/mo_property.Rd index 0d0b3e1aa..108d3fbe1 100644 --- a/man/mo_property.Rd +++ b/man/mo_property.Rd @@ -151,19 +151,19 @@ mo_property(x, property = "fullname", language = get_AMR_locale(), keep_synonyms = getOption("AMR_keep_synonyms", FALSE), ...) } \arguments{ -\item{x}{any \link{character} (vector) that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see \emph{Examples}.} +\item{x}{Any \link{character} (vector) that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see \emph{Examples}.} -\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} +\item{language}{Language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})} -\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} +\item{keep_synonyms}{A \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.} -\item{...}{other arguments passed on to \code{\link[=as.mo]{as.mo()}}, such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input'} +\item{...}{Other arguments passed on to \code{\link[=as.mo]{as.mo()}}, such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input'} -\item{ab}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}} -\item{open}{browse the URL using \code{\link[utils:browseURL]{browseURL()}}} +\item{open}{Browse the URL using \code{\link[utils:browseURL]{browseURL()}}} -\item{property}{one of the column names of the \link{microorganisms} data set: "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", or "snomed", or must be \code{"shortname"}} +\item{property}{One of the column names of the \link{microorganisms} data set: "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", or "snomed", or must be \code{"shortname"}} } \value{ \itemize{ diff --git a/man/mo_source.Rd b/man/mo_source.Rd index caec7b19f..17b83755f 100644 --- a/man/mo_source.Rd +++ b/man/mo_source.Rd @@ -12,9 +12,9 @@ set_mo_source(path, destination = getOption("AMR_mo_source", get_mo_source(destination = getOption("AMR_mo_source", "~/mo_source.rds")) } \arguments{ -\item{path}{location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see \emph{Details}). Can also be \code{""}, \code{NULL} or \code{FALSE} to delete the reference file.} +\item{path}{Location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see \emph{Details}). Can also be \code{""}, \code{NULL} or \code{FALSE} to delete the reference file.} -\item{destination}{destination of the compressed data file - the default is the user's home directory.} +\item{destination}{Destination of the compressed data file - the default is the user's home directory.} } \description{ These functions can be used to predefine your own reference to be used in \code{\link[=as.mo]{as.mo()}} and consequently all \code{\link[=mo_property]{mo_*}} functions (such as \code{\link[=mo_genus]{mo_genus()}} and \code{\link[=mo_gramstain]{mo_gramstain()}}). diff --git a/man/pca.Rd b/man/pca.Rd index a2ae6c1ef..bc015b6a1 100644 --- a/man/pca.Rd +++ b/man/pca.Rd @@ -8,9 +8,9 @@ pca(x, ..., retx = TRUE, center = TRUE, scale. = TRUE, tol = NULL, rank. = NULL) } \arguments{ -\item{x}{a \link{data.frame} containing \link{numeric} columns} +\item{x}{A \link{data.frame} containing \link{numeric} columns} -\item{...}{columns of \code{x} to be selected for PCA, can be unquoted since it supports quasiquotation.} +\item{...}{Columns of \code{x} to be selected for PCA, can be unquoted since it supports quasiquotation.} \item{retx}{a logical value indicating whether the rotated variables should be returned.} diff --git a/man/plot.Rd b/man/plot.Rd index 0e12dce4e..37f295846 100644 --- a/man/plot.Rd +++ b/man/plot.Rd @@ -109,57 +109,57 @@ labels_sir_count(position = NULL, x = "antibiotic", combine_SI = TRUE, datalabels.size = 3, datalabels.colour = "grey15") } \arguments{ -\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} +\item{keep_operators}{A \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.} \item{mic_range}{A manual range to rescale the MIC values (using \code{\link[=rescale_mic]{rescale_mic()}}), e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to prevent rescaling on one side, e.g., \code{mic_range = c(NA, 32)}. \strong{Note:} This rescales values but does not filter them - use the ggplot2 \code{limits} argument separately to exclude values from the plot.} -\item{...}{arguments passed on to methods} +\item{...}{Arguments passed on to methods} -\item{colours_SIR}{colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly.} +\item{colours_SIR}{Colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly.} -\item{language}{language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can be overwritten by setting the package option \code{\link[=AMR-options]{AMR_locale}}, e.g. \code{options(AMR_locale = "de")}, see \link{translate}. Use \code{language = NULL} to prevent translation.} +\item{language}{Language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can be overwritten by setting the package option \code{\link[=AMR-options]{AMR_locale}}, e.g. \code{options(AMR_locale = "de")}, see \link{translate}. Use \code{language = NULL} to prevent translation.} -\item{eucast_I}{a \link{logical} to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be \code{TRUE} if the default \link[=as.sir]{AMR interpretation guideline} is set to EUCAST (which is the default). With \code{FALSE}, it will be interpreted as "Intermediate".} +\item{eucast_I}{A \link{logical} to indicate whether the 'I' must be interpreted as "Susceptible, under increased exposure". Will be \code{TRUE} if the default \link[=as.sir]{AMR interpretation guideline} is set to EUCAST (which is the default). With \code{FALSE}, it will be interpreted as "Intermediate".} -\item{x, object}{values created with \code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}} or \code{\link[=as.sir]{as.sir()}} (or their \verb{random_*} variants, such as \code{\link[=random_mic]{random_mic()}})} +\item{x, object}{Values created with \code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}} or \code{\link[=as.sir]{as.sir()}} (or their \verb{random_*} variants, such as \code{\link[=random_mic]{random_mic()}})} -\item{mo}{any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} +\item{mo}{Any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} -\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{guideline}{interpretation guideline to use - the default is the latest included EUCAST guideline, see \emph{Details}} +\item{guideline}{Interpretation guideline to use - the default is the latest included EUCAST guideline, see \emph{Details}} -\item{main, title}{title of the plot} +\item{main, title}{Title of the plot} -\item{xlab, ylab}{axis title} +\item{xlab, ylab}{Axis title} -\item{expand}{a \link{logical} to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.} +\item{expand}{A \link{logical} to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.} -\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} +\item{include_PKPD}{A \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.} -\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} +\item{breakpoint_type}{The type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.} -\item{facet}{variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} +\item{facet}{Variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable} \item{nrow}{(when using \code{facet}) number of rows} -\item{breaks}{a \link{numeric} vector of positions} +\item{breaks}{A \link{numeric} vector of positions} -\item{limits}{a \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} +\item{limits}{A \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum} -\item{aesthetics}{aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size"} +\item{aesthetics}{Aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size"} -\item{position}{position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} +\item{position}{Position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} -\item{datalabels.size}{size of the datalabels} +\item{datalabels.size}{Size of the datalabels} -\item{datalabels.colour}{colour of the datalabels} +\item{datalabels.colour}{Colour of the datalabels} } \value{ The \code{autoplot()} functions return a \code{\link[ggplot2:ggplot]{ggplot}} model that is extendible with any \code{ggplot2} function. @@ -187,7 +187,7 @@ This package contains more functions that extend the \code{ggplot2} package, to \item \code{\link[=facet_sir]{facet_sir()}} creates 2d plots (at default based on S/I/R) using \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}}. \item \code{\link[=scale_y_percent]{scale_y_percent()}} transforms the y axis to a 0 to 100\% range using \code{\link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous()}}. \item \code{\link[=scale_sir_colours]{scale_sir_colours()}} allows to set colours to any aesthetic, even for \code{shape} or \code{linetype}. -\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction. +\item \code{\link[=theme_sir]{theme_sir()}} is a \link[ggplot2:theme]{ggplot2 theme} with minimal distraction. \item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and number of isolates, using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}. } diff --git a/man/proportion.Rd b/man/proportion.Rd index a26f5c728..7cd0b750c 100644 --- a/man/proportion.Rd +++ b/man/proportion.Rd @@ -52,29 +52,29 @@ sir_df(data, translate_ab = "name", language = get_AMR_locale(), confidence_level = 0.95) } \arguments{ -\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.} +\item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.} -\item{minimum}{the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} +\item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} -\item{as_percent}{a \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.} +\item{as_percent}{A \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.} \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below} -\item{ab_result}{antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R"} +\item{ab_result}{Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R"} -\item{confidence_level}{the confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} +\item{confidence_level}{The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} -\item{side}{the side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.} +\item{side}{The side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.} -\item{collapse}{a \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing} +\item{collapse}{A \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing} -\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} +\item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})} -\item{translate_ab}{a column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} +\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}} -\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} +\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} -\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} +\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}} } \value{ A \link{double} or, when \code{as_percent = TRUE}, a \link{character}. diff --git a/man/random.Rd b/man/random.Rd index 51c971237..68882d4f0 100644 --- a/man/random.Rd +++ b/man/random.Rd @@ -14,15 +14,15 @@ random_disk(size = NULL, mo = NULL, ab = NULL, ...) random_sir(size = NULL, prob_SIR = c(0.33, 0.33, 0.33), ...) } \arguments{ -\item{size}{desired size of the returned vector. If used in a \link{data.frame} call or \code{dplyr} verb, will get the current (group) size if left blank.} +\item{size}{Desired size of the returned vector. If used in a \link{data.frame} call or \code{dplyr} verb, will get the current (group) size if left blank.} -\item{mo}{any \link{character} that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} +\item{mo}{Any \link{character} that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} -\item{ab}{any \link{character} that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} +\item{ab}{Any \link{character} that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}} -\item{...}{ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions} -\item{prob_SIR}{a vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value)} +\item{prob_SIR}{A vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value)} } \value{ class \code{mic} for \code{\link[=random_mic]{random_mic()}} (see \code{\link[=as.mic]{as.mic()}}) and class \code{disk} for \code{\link[=random_disk]{random_disk()}} (see \code{\link[=as.disk]{as.disk()}}) diff --git a/man/resistance_predict.Rd b/man/resistance_predict.Rd index e67a8afcc..40c517c88 100644 --- a/man/resistance_predict.Rd +++ b/man/resistance_predict.Rd @@ -26,35 +26,35 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), main = paste("Resistance Prediction of", x_name), ribbon = TRUE, ...) } \arguments{ -\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} +\item{x}{A \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.} -\item{col_ab}{column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"})} +\item{col_ab}{Column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"})} -\item{col_date}{column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class} +\item{col_date}{Column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class} -\item{year_min}{lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}} +\item{year_min}{Lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}} -\item{year_max}{highest year to use in the prediction model - the default is 10 years after today} +\item{year_max}{Highest year to use in the prediction model - the default is 10 years after today} -\item{year_every}{unit of sequence between lowest year found in the data and \code{year_max}} +\item{year_every}{Unit of sequence between lowest year found in the data and \code{year_max}} -\item{minimum}{minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.} +\item{minimum}{Minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.} -\item{model}{the statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.} +\item{model}{The statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.} -\item{I_as_S}{a \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.} +\item{I_as_S}{A \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.} -\item{preserve_measurements}{a \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.} +\item{preserve_measurements}{A \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.} -\item{info}{a \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.} +\item{info}{A \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.} -\item{...}{arguments passed on to functions} +\item{...}{Arguments passed on to functions} -\item{main}{title of the plot} +\item{main}{Title of the plot} -\item{ribbon}{a \link{logical} to indicate whether a ribbon should be shown (default) or error bars} +\item{ribbon}{A \link{logical} to indicate whether a ribbon should be shown (default) or error bars} -\item{object}{model data to be plotted} +\item{object}{Model data to be plotted} } \value{ A \link{data.frame} with extra class \code{\link{resistance_predict}} with columns: diff --git a/man/skewness.Rd b/man/skewness.Rd index 125d32ae6..4a2a1ff1f 100644 --- a/man/skewness.Rd +++ b/man/skewness.Rd @@ -16,9 +16,9 @@ skewness(x, na.rm = FALSE) \method{skewness}{data.frame}(x, na.rm = FALSE) } \arguments{ -\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}} +\item{x}{A vector of values, a \link{matrix} or a \link{data.frame}} -\item{na.rm}{a \link{logical} value indicating whether \code{NA} values should be stripped before the computation proceeds} +\item{na.rm}{A \link{logical} value indicating whether \code{NA} values should be stripped before the computation proceeds} } \description{ Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. diff --git a/man/top_n_microorganisms.Rd b/man/top_n_microorganisms.Rd index 3f07f31c0..599431f69 100644 --- a/man/top_n_microorganisms.Rd +++ b/man/top_n_microorganisms.Rd @@ -8,13 +8,13 @@ top_n_microorganisms(x, n, property = "fullname", n_for_each = NULL, col_mo = NULL, ...) } \arguments{ -\item{x}{a data frame containing microbial data} +\item{x}{A data frame containing microbial data} -\item{n}{an integer specifying the maximum number of unique values of the \code{property} to include in the output} +\item{n}{An integer specifying the maximum number of unique values of the \code{property} to include in the output} -\item{property}{a character string indicating the microorganism property to use for filtering. Must be one of the column names of the \link{microorganisms} data set: "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", or "snomed". If \code{NULL}, the raw values from \code{col_mo} will be used without transformation.} +\item{property}{A character string indicating the microorganism property to use for filtering. Must be one of the column names of the \link{microorganisms} data set: "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", or "snomed". If \code{NULL}, the raw values from \code{col_mo} will be used without transformation.} -\item{n_for_each}{an optional integer specifying the maximum number of rows to retain for each value of the selected property. If \code{NULL}, all rows within the top \emph{n} groups will be included.} +\item{n_for_each}{An optional integer specifying the maximum number of rows to retain for each value of the selected property. If \code{NULL}, all rows within the top \emph{n} groups will be included.} \item{col_mo}{A character string indicating the column in \code{x} that contains microorganism names or codes. Defaults to the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} diff --git a/man/translate.Rd b/man/translate.Rd index 9d7d7745c..a6b15873f 100644 --- a/man/translate.Rd +++ b/man/translate.Rd @@ -17,9 +17,9 @@ reset_AMR_locale() translate_AMR(x, language = get_AMR_locale()) } \arguments{ -\item{language}{language to choose. Use one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk).} +\item{language}{Language to choose. Use one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk).} -\item{x}{text to translate} +\item{x}{Text to translate} } \description{ For language-dependent output of \code{AMR} functions, such as \code{\link[=mo_name]{mo_name()}}, \code{\link[=mo_gramstain]{mo_gramstain()}}, \code{\link[=mo_type]{mo_type()}} and \code{\link[=ab_name]{ab_name()}}.