diff --git a/DESCRIPTION b/DESCRIPTION index eaf2f2aa1..2660a304b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: AMR -Version: 2.1.1.9232 +Version: 2.1.1.9233 Date: 2025-03-31 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) diff --git a/NEWS.md b/NEWS.md index d4fd91105..7833285b3 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 2.1.1.9232 +# AMR 2.1.1.9233 *(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).)* diff --git a/R/aa_helper_functions.R b/R/aa_helper_functions.R index b43af1f58..82da5788a 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 d2e540945..54b60dc86 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 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 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 a38fab675..58a65d0a9 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 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 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 823e3484b..ff5a97f58 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 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 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 51fe23d5d..3797f0a90 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 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 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 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 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 5cfc33353..fb3cea76f 100755 --- a/R/amr_selectors.R +++ b/R/amr_selectors.R @@ -39,11 +39,11 @@ #' 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 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 ... 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 b43172961..9bf774c22 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()] @@ -52,21 +52,21 @@ #' @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 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 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 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 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). #' @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.") @@ -1321,7 +1321,7 @@ 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 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 e735e26c7..f18be0438 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 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 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 ... Arguments to pass on to `atc_property`. #' @details #' Options for argument `administration`: #' diff --git a/R/av.R b/R/av.R index 889681f1e..7831dd431 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 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 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 62b00772f..abd1f9697 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 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 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 c49b3cc9f..c9382340d 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 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 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 b0962a12d..b50cd1ba2 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 c064d255b..5161a82b0 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 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 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`. #' @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/custom_antimicrobials.R b/R/custom_antimicrobials.R index 7c98ebe6b..bb0743084 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 b738f7aa0..8e8eee0e0 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 955d9e9df..d86d30d9b 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 929c6ee4d..565a0db5a 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 1dffe8f26..ced1c56b1 100755 --- a/R/eucast_rules.R +++ b/R/eucast_rules.R @@ -59,20 +59,20 @@ 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 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 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." +#' @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 #' **Note:** This function does not translate MIC values to SIR values. Use [as.sir()] for that. \cr diff --git a/R/export_biosample.R b/R/export_biosample.R index a19fc5b7e..a28e1b0f8 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 639f5985c..bd33bf546 100644 --- a/R/first_isolate.R +++ b/R/first_isolate.R @@ -31,25 +31,25 @@ #' #' 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_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_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 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 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 ... 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 9dda45066..4cff831f0 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 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 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. #' @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 f18c451f5..0321cf53d 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 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 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 2741316fa..4afbd2839 100755 --- a/R/ggplot_sir.R +++ b/R/ggplot_sir.R @@ -30,24 +30,24 @@ #' 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 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 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()]. #' diff --git a/R/guess_ab_col.R b/R/guess_ab_col.R index 228e7ab22..2cc333286 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 ddc38fc25..a3ef771aa 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 fadb2feb1..90c808c94 100755 --- a/R/join_microorganisms.R +++ b/R/join_microorganisms.R @@ -34,9 +34,9 @@ #' @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 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 ... 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 4d2f833c3..991c49c67 100755 --- a/R/key_antimicrobials.R +++ b/R/key_antimicrobials.R @@ -31,14 +31,14 @@ #' #' 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 y,z [character] vectors to compare +#' @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 236a5d2e3..85c5b010b 100755 --- a/R/kurtosis.R +++ b/R/kurtosis.R @@ -30,8 +30,8 @@ #' 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 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 diff --git a/R/mdro.R b/R/mdro.R index 00f6ca375..3edae343b 100755 --- a/R/mdro.R +++ b/R/mdro.R @@ -32,14 +32,14 @@ #' 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 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 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 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. diff --git a/R/mean_amr_distance.R b/R/mean_amr_distance.R index cf492b56d..843849476 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))`. @@ -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 3c8f9568e..28f231f29 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 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 ... 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: diff --git a/R/mo.R b/R/mo.R index 6cc33ba20..2c354dc26 100755 --- a/R/mo.R +++ b/R/mo.R @@ -30,7 +30,7 @@ #' 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 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". @@ -43,9 +43,9 @@ #' @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 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 ... Other arguments passed on to functions. #' @rdname as.mo #' @aliases mo #' @details diff --git a/R/mo_matching_score.R b/R/mo_matching_score.R index c25004897..a398581b2 100755 --- a/R/mo_matching_score.R +++ b/R/mo_matching_score.R @@ -30,8 +30,8 @@ #' Calculate the Matching Score for Microorganisms #' #' This algorithm is used by [as.mo()] and all the [`mo_*`][mo_property()] functions to determine the most probable match of taxonomic records based on user input. -#' @param x Any user input value(s) -#' @param n A full taxonomic name, that exists in [`microorganisms$fullname`][microorganisms] +#' @param x Any user input value(s). +#' @param n A full taxonomic name, that exists in [`microorganisms$fullname`][microorganisms]. #' @note This algorithm was originally developed in 2018 and subsequently described in: Berends MS *et al.* (2022). **AMR: An R Package for Working with Antimicrobial Resistance Data**. *Journal of Statistical Software*, 104(3), 1-31; \doi{10.18637/jss.v104.i03}. #' #' Later, the work of Bartlett A *et al.* about bacterial pathogens infecting humans (2022, \doi{10.1099/mic.0.001269}) was incorporated, and optimalisations to the algorithm were made. diff --git a/R/mo_property.R b/R/mo_property.R index 38ced6760..5257dbd7d 100755 --- a/R/mo_property.R +++ b/R/mo_property.R @@ -31,11 +31,11 @@ #' #' 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 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/pca.R b/R/pca.R index 4c7303b5b..8343c3321 100755 --- a/R/pca.R +++ b/R/pca.R @@ -30,7 +30,7 @@ #' 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 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()]. @@ -60,17 +60,18 @@ #' #' pca_result #' summary(pca_result) -#' #' # old base R plotting method: #' biplot(pca_result) -#' # new ggplot2 plotting method using this package: -#' if (require("ggplot2")) { -#' ggplot_pca(pca_result) +#' } #' +#' # new ggplot2 plotting method using this package: +#' if (require("dplyr") && require("ggplot2")) { +#' ggplot_pca(pca_result) +#' } +#' if (require("dplyr") && require("ggplot2")) { #' ggplot_pca(pca_result) + #' scale_colour_viridis_d() + #' labs(title = "Title here") -#' } #' } #' } pca <- function(x, diff --git a/R/plotting.R b/R/plotting.R index ca59a5ed3..7957815ea 100755 --- a/R/plotting.R +++ b/R/plotting.R @@ -33,16 +33,16 @@ #' 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 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 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. @@ -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 3e3262fd4..e8e69f0f9 100644 --- a/R/proportion.R +++ b/R/proportion.R @@ -35,15 +35,15 @@ #' @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 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()]. #' @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 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 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 33a3582a5..83e6ba26d 100755 --- a/R/random.R +++ b/R/random.R @@ -31,10 +31,10 @@ #' #' 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 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 434339990..f0ec70c8a 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 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 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 02a8d4181..b824b0a1c 100755 --- a/R/sir.R +++ b/R/sir.R @@ -38,13 +38,13 @@ #' #' 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 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: +#' @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"` #' * `<=` and `>=` are treated as-is. @@ -71,8 +71,8 @@ #' @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 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.* @@ -464,7 +464,7 @@ 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 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 7920fb4bd..f12badd3f 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 dad7a7988..d3238a706 100755 --- a/R/top_n_microorganisms.R +++ b/R/top_n_microorganisms.R @@ -30,8 +30,8 @@ #' 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 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()]. diff --git a/R/translate.R b/R/translate.R index 0b5d6d021..d1c67e35f 100755 --- a/R/translate.R +++ b/R/translate.R @@ -30,7 +30,7 @@ #' 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 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. #' diff --git a/data-raw/gpt_training_text_v2.1.1.9232.txt b/data-raw/gpt_training_text_v2.1.1.9233.txt similarity index 98% rename from data-raw/gpt_training_text_v2.1.1.9232.txt rename to data-raw/gpt_training_text_v2.1.1.9233.txt index 8c95dbd39..fcd7b94ea 100644 --- a/data-raw/gpt_training_text_v2.1.1.9232.txt +++ b/data-raw/gpt_training_text_v2.1.1.9233.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.9232. Remember this whenever someone asks which AMR package version you’re at. +First and foremost, you are trained on version 2.1.1.9233. 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{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{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{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{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{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 @@ -1749,41 +1749,41 @@ retrieve_wisca_parameters(wisca_model, ...) \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{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{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{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{simulations}{(for WISCA) a numerical value to set the number of Monte Carlo simulations} +\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{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,17 +2281,17 @@ 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{...}{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{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()}}.} @@ -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{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{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,9 +2980,9 @@ 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.} @@ -2990,7 +2990,7 @@ mic_p90(x, na.rm = FALSE, ...) \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. @@ -3138,7 +3138,7 @@ 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. @@ -3160,11 +3160,11 @@ This excludes enterococci at default (who are in group D), use \code{Lancefield \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{...}{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}} @@ -3444,25 +3444,25 @@ 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{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{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{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}.} -\item{capped_mic_handling}{A \link{character} string that controls how MIC values with a cap (i.e., starting with \code{<}, \code{<=}, \code{>}, or \code{>=}) are interpreted. Supports the following options: +\item{capped_mic_handling}{A \link{character} string that controls how MIC values with a cap (i.e., starting with \code{<}, \code{<=}, \code{>}, or \code{>=}) are interpreted. Supports the following options:. \code{"none"} \itemize{ @@ -3506,11 +3506,11 @@ The default \code{"standard"} setting ensures cautious handling of uncertain val \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{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} @@ -3857,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{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_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. @@ -3933,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{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} @@ -4028,17 +4028,17 @@ 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{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)}.} } @@ -4123,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 @@ -4171,27 +4171,27 @@ 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{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{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} +\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.} \item{decimal.mark}{the character to be used to indicate the numeric decimal point.} @@ -4369,15 +4369,15 @@ count_df(data, translate_ab = "name", language = get_AMR_locale(), \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{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{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{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} @@ -4542,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 @@ -4769,11 +4769,11 @@ 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{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()}}.} @@ -4787,17 +4787,17 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 12) \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{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. @@ -4999,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 @@ -5046,15 +5046,15 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, \arguments{ \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_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}.} @@ -5062,27 +5062,27 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, \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{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, 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}.} -\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_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 @@ -5362,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{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{ @@ -5578,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 @@ -5603,39 +5603,39 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, \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{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. @@ -5709,47 +5709,47 @@ 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{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{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{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}.} } @@ -5888,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. @@ -5993,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. @@ -6048,11 +6048,11 @@ 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{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{...}{Ignored, only in place to allow future extensions} +\item{...}{Ignored, only in place to allow future extensions.} } \value{ a \link{data.frame} @@ -6128,25 +6128,25 @@ antimicrobials_equal(y, z, type = c("points", "keyantimicrobials"), \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{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{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. @@ -6259,9 +6259,9 @@ 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.} } @@ -6413,19 +6413,19 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \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)} +\item{esbl}{\link{logical} values, or a column name containing logical values, indicating the presence of an ESBL gene (or production of its proteins).} -\item{carbapenemase}{\link{logical} values, or a column name containing logical values, indicating the presence of a carbapenemase gene (or production of its proteins)} +\item{carbapenemase}{\link{logical} values, or a column name containing logical values, indicating the presence of a carbapenemase gene (or production of its proteins).} -\item{mecA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecA} gene (or production of its proteins)} +\item{mecA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecA} gene (or production of its proteins).} -\item{mecC}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecC} gene (or production of its proteins)} +\item{mecC}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecC} gene (or production of its proteins).} -\item{vanA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanA} gene (or production of its proteins)} +\item{vanA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanA} gene (or production of its proteins).} -\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{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.} @@ -6433,11 +6433,11 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \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{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{ @@ -6624,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. @@ -6927,9 +6927,9 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mo_matching_score.Rd': mo_matching_score(x, n) } \arguments{ -\item{x}{Any user input value(s)} +\item{x}{Any user input value(s).} -\item{n}{A full taxonomic name, that exists in \code{\link[=microorganisms]{microorganisms$fullname}}} +\item{n}{A full taxonomic name, that exists in \code{\link[=microorganisms]{microorganisms$fullname}}.} } \description{ This algorithm is used by \code{\link[=as.mo]{as.mo()}} and all the \code{\link[=mo_property]{mo_*}} functions to determine the most probable match of taxonomic records based on user input. @@ -7158,17 +7158,17 @@ mo_property(x, property = "fullname", language = get_AMR_locale(), \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{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{...}{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{ @@ -7500,7 +7500,7 @@ 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.} @@ -7565,17 +7565,18 @@ if (require("dplyr")) { pca_result summary(pca_result) - # old base R plotting method: biplot(pca_result) - # new ggplot2 plotting method using this package: - if (require("ggplot2")) { - ggplot_pca(pca_result) +} +# new ggplot2 plotting method using this package: +if (require("dplyr") && require("ggplot2")) { + ggplot_pca(pca_result) +} +if (require("dplyr") && require("ggplot2")) { ggplot_pca(pca_result) + scale_colour_viridis_d() + labs(title = "Title here") - } } } } @@ -7701,7 +7702,7 @@ labels_sir_count(position = NULL, x = "antibiotic", \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.} @@ -7709,17 +7710,17 @@ labels_sir_count(position = NULL, x = "antibiotic", \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.} @@ -7727,27 +7728,27 @@ labels_sir_count(position = NULL, x = "antibiotic", \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{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{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. @@ -8000,23 +8001,23 @@ sir_df(data, translate_ab = "name", language = get_AMR_locale(), \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{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{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{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}. @@ -8246,13 +8247,13 @@ 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{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()}}) @@ -8318,15 +8319,15 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), \arguments{ \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.} @@ -8338,13 +8339,13 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), \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: @@ -8460,9 +8461,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. @@ -8492,9 +8493,9 @@ 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.} @@ -8557,7 +8558,7 @@ 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{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()}}. @@ -9299,11 +9300,15 @@ Our goal is to build a predictive model using the `tidymodels` framework to dete We begin by loading the required libraries and preparing the `example_isolates` dataset from the `AMR` package. -```{r} +```{r lib packages, message = FALSE, warning = FALSE, results = 'asis'} # Load required libraries library(AMR) # For AMR data analysis library(tidymodels) # For machine learning workflows, and data manipulation (dplyr, tidyr, ...) +``` +Prepare the data: + +```{r} # Your data could look like this: example_isolates @@ -9497,6 +9502,7 @@ data_time ``` **Explanation:** + - `mo_name(mo)`: Converts microbial codes into proper species names. - `resistance()`: Converts AMR results into numeric values (proportion of resistant isolates). - `group_by(year, ward, species)`: Aggregates resistance rates by year and ward. @@ -9518,6 +9524,7 @@ resistance_recipe_time ``` **Explanation:** + - `step_dummy()`: Encodes categorical variables (`ward`, `species`) as numerical indicators. - `step_normalize()`: Normalises the `year` variable. - `step_nzv()`: Removes near-zero variance predictors. @@ -9535,6 +9542,7 @@ lm_model ``` **Explanation:** + - `linear_reg()`: Defines a linear regression model. - `set_engine("lm")`: Uses R’s built-in linear regression engine. @@ -9579,6 +9587,7 @@ metrics_time ``` **Explanation:** + - `initial_split()`: Splits data into training and testing sets. - `fit()`: Trains the workflow. - `predict()`: Generates resistance predictions. diff --git a/man/ab_from_text.Rd b/man/ab_from_text.Rd index dafe94568..76aba148d 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{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 0b3a64363..3562ebc5e 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{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{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 e6b23ca19..19d708db0 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 1e8572be6..e0f2d85dd 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 12bc693ab..1ef8086b5 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{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 775eb325b..cd93ecb4b 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{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 333eaa9c4..ecba7a80e 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 @@ -75,41 +75,41 @@ retrieve_wisca_parameters(wisca_model, ...) \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{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{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{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{simulations}{(for WISCA) a numerical value to set the number of Monte Carlo simulations} +\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{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 2a3567e17..914453a6a 100644 --- a/man/antimicrobial_selectors.Rd +++ b/man/antimicrobial_selectors.Rd @@ -131,17 +131,17 @@ 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{...}{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{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()}}.} diff --git a/man/as.ab.Rd b/man/as.ab.Rd index e5f37fb75..c8aeeb4d0 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{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 31519e669..a2fa7143a 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{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 b4e195e19..0c4287c37 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 7ee0781f8..65bb2bfb1 100644 --- a/man/as.mic.Rd +++ b/man/as.mic.Rd @@ -27,9 +27,9 @@ 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.} @@ -37,7 +37,7 @@ mic_p90(x, na.rm = FALSE, ...) \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. diff --git a/man/as.mo.Rd b/man/as.mo.Rd index 547701ccc..fb7b54ae4 100644 --- a/man/as.mo.Rd +++ b/man/as.mo.Rd @@ -33,7 +33,7 @@ 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. @@ -55,11 +55,11 @@ This excludes enterococci at default (who are in group D), use \code{Lancefield \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{...}{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 64ad0b143..8f5db334d 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -70,25 +70,25 @@ 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{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{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{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}.} -\item{capped_mic_handling}{A \link{character} string that controls how MIC values with a cap (i.e., starting with \code{<}, \code{<=}, \code{>}, or \code{>=}) are interpreted. Supports the following options: +\item{capped_mic_handling}{A \link{character} string that controls how MIC values with a cap (i.e., starting with \code{<}, \code{<=}, \code{>}, or \code{>=}) are interpreted. Supports the following options:. \code{"none"} \itemize{ @@ -132,11 +132,11 @@ The default \code{"standard"} setting ensures cautious handling of uncertain val \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{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} diff --git a/man/atc_online.Rd b/man/atc_online.Rd index 01502ef61..74ddf9b27 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{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_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 56c765a34..322e42f34 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{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 ac7f4c630..034c371cf 100644 --- a/man/av_property.Rd +++ b/man/av_property.Rd @@ -40,17 +40,17 @@ 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{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)}.} } diff --git a/man/availability.Rd b/man/availability.Rd index 0893cc7fa..02aa8349b 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 cef3213bf..6311ad509 100644 --- a/man/bug_drug_combinations.Rd +++ b/man/bug_drug_combinations.Rd @@ -15,27 +15,27 @@ 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{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{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} +\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.} \item{decimal.mark}{the character to be used to indicate the numeric decimal point.} diff --git a/man/count.Rd b/man/count.Rd index bf0455e69..1406411fd 100644 --- a/man/count.Rd +++ b/man/count.Rd @@ -38,15 +38,15 @@ count_df(data, translate_ab = "name", language = get_AMR_locale(), \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{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{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{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 d41a10800..ebded871e 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 011ca2d04..2f718c5c1 100644 --- a/man/eucast_rules.Rd +++ b/man/eucast_rules.Rd @@ -29,11 +29,11 @@ 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{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()}}.} @@ -47,17 +47,17 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 12) \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{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 003a19782..46bc96842 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 3dd668122..527f77b3c 100644 --- a/man/first_isolate.Rd +++ b/man/first_isolate.Rd @@ -28,15 +28,15 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, \arguments{ \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_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}.} @@ -44,27 +44,27 @@ filter_first_isolate(x = NULL, col_date = NULL, col_patient_id = NULL, \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{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, 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}.} -\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_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 c278a3495..329a635bc 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{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 1af5ad4dc..aff174a6d 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 @@ -51,39 +51,39 @@ ggplot_pca(x, choices = 1:2, scale = 1, pc.biplot = TRUE, \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{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 ea04f2968..cbaa015a4 100644 --- a/man/ggplot_sir.Rd +++ b/man/ggplot_sir.Rd @@ -19,47 +19,47 @@ 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{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{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{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}.} } diff --git a/man/guess_ab_col.Rd b/man/guess_ab_col.Rd index ae770691a..eab6d76d0 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 b51012df4..7d78ca1d2 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 701d00b67..0c2728a42 100644 --- a/man/join.Rd +++ b/man/join.Rd @@ -26,11 +26,11 @@ 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{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{...}{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 e4501d8bd..3dbf860a5 100644 --- a/man/key_antimicrobials.Rd +++ b/man/key_antimicrobials.Rd @@ -25,25 +25,25 @@ antimicrobials_equal(y, z, type = c("points", "keyantimicrobials"), \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{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{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 0bbc35407..5deffd189 100644 --- a/man/kurtosis.Rd +++ b/man/kurtosis.Rd @@ -16,9 +16,9 @@ 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.} } diff --git a/man/mdro.Rd b/man/mdro.Rd index b416625af..44fcb72c3 100644 --- a/man/mdro.Rd +++ b/man/mdro.Rd @@ -44,19 +44,19 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \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)} +\item{esbl}{\link{logical} values, or a column name containing logical values, indicating the presence of an ESBL gene (or production of its proteins).} -\item{carbapenemase}{\link{logical} values, or a column name containing logical values, indicating the presence of a carbapenemase gene (or production of its proteins)} +\item{carbapenemase}{\link{logical} values, or a column name containing logical values, indicating the presence of a carbapenemase gene (or production of its proteins).} -\item{mecA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecA} gene (or production of its proteins)} +\item{mecA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecA} gene (or production of its proteins).} -\item{mecC}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecC} gene (or production of its proteins)} +\item{mecC}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{mecC} gene (or production of its proteins).} -\item{vanA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanA} gene (or production of its proteins)} +\item{vanA}{\link{logical} values, or a column name containing logical values, indicating the presence of a \emph{vanA} gene (or production of its proteins).} -\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{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.} @@ -64,11 +64,11 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, \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{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 2c19093c8..7e2665b1b 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. diff --git a/man/mo_matching_score.Rd b/man/mo_matching_score.Rd index 4854c2edc..f6140b68e 100644 --- a/man/mo_matching_score.Rd +++ b/man/mo_matching_score.Rd @@ -7,9 +7,9 @@ mo_matching_score(x, n) } \arguments{ -\item{x}{Any user input value(s)} +\item{x}{Any user input value(s).} -\item{n}{A full taxonomic name, that exists in \code{\link[=microorganisms]{microorganisms$fullname}}} +\item{n}{A full taxonomic name, that exists in \code{\link[=microorganisms]{microorganisms$fullname}}.} } \description{ This algorithm is used by \code{\link[=as.mo]{as.mo()}} and all the \code{\link[=mo_property]{mo_*}} functions to determine the most probable match of taxonomic records based on user input. diff --git a/man/mo_property.Rd b/man/mo_property.Rd index 108d3fbe1..cdc70fbd4 100644 --- a/man/mo_property.Rd +++ b/man/mo_property.Rd @@ -153,17 +153,17 @@ mo_property(x, property = "fullname", language = get_AMR_locale(), \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{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{...}{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/pca.Rd b/man/pca.Rd index bc015b6a1..c6fd50dc6 100644 --- a/man/pca.Rd +++ b/man/pca.Rd @@ -8,7 +8,7 @@ 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.} @@ -73,17 +73,18 @@ if (require("dplyr")) { pca_result summary(pca_result) - # old base R plotting method: biplot(pca_result) - # new ggplot2 plotting method using this package: - if (require("ggplot2")) { - ggplot_pca(pca_result) +} +# new ggplot2 plotting method using this package: +if (require("dplyr") && require("ggplot2")) { + ggplot_pca(pca_result) +} +if (require("dplyr") && require("ggplot2")) { ggplot_pca(pca_result) + scale_colour_viridis_d() + labs(title = "Title here") - } } } } diff --git a/man/plot.Rd b/man/plot.Rd index 37f295846..419f0e705 100644 --- a/man/plot.Rd +++ b/man/plot.Rd @@ -113,7 +113,7 @@ labels_sir_count(position = NULL, x = "antibiotic", \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.} @@ -121,17 +121,17 @@ labels_sir_count(position = NULL, x = "antibiotic", \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.} @@ -139,27 +139,27 @@ labels_sir_count(position = NULL, x = "antibiotic", \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{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{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. diff --git a/man/proportion.Rd b/man/proportion.Rd index 7cd0b750c..3fb2e5447 100644 --- a/man/proportion.Rd +++ b/man/proportion.Rd @@ -58,23 +58,23 @@ sir_df(data, translate_ab = "name", language = get_AMR_locale(), \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{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{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{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 68882d4f0..66206dafe 100644 --- a/man/random.Rd +++ b/man/random.Rd @@ -16,13 +16,13 @@ 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{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 40c517c88..6cac8f43d 100644 --- a/man/resistance_predict.Rd +++ b/man/resistance_predict.Rd @@ -28,15 +28,15 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), \arguments{ \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.} @@ -48,13 +48,13 @@ ggplot_sir_predict(x, main = paste("Resistance Prediction of", x_name), \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 4a2a1ff1f..c1ac2c3da 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 599431f69..281f58054 100644 --- a/man/top_n_microorganisms.Rd +++ b/man/top_n_microorganisms.Rd @@ -8,9 +8,9 @@ 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.} diff --git a/man/translate.Rd b/man/translate.Rd index a6b15873f..6e4727026 100644 --- a/man/translate.Rd +++ b/man/translate.Rd @@ -19,7 +19,7 @@ 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{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/vignettes/AMR_with_tidymodels.Rmd b/vignettes/AMR_with_tidymodels.Rmd index 15c33b958..f66fe9c10 100644 --- a/vignettes/AMR_with_tidymodels.Rmd +++ b/vignettes/AMR_with_tidymodels.Rmd @@ -44,11 +44,15 @@ Our goal is to build a predictive model using the `tidymodels` framework to dete We begin by loading the required libraries and preparing the `example_isolates` dataset from the `AMR` package. -```{r} +```{r lib packages, message = FALSE, warning = FALSE, results = 'asis'} # Load required libraries library(AMR) # For AMR data analysis library(tidymodels) # For machine learning workflows, and data manipulation (dplyr, tidyr, ...) +``` +Prepare the data: + +```{r} # Your data could look like this: example_isolates @@ -242,6 +246,7 @@ data_time ``` **Explanation:** + - `mo_name(mo)`: Converts microbial codes into proper species names. - `resistance()`: Converts AMR results into numeric values (proportion of resistant isolates). - `group_by(year, ward, species)`: Aggregates resistance rates by year and ward. @@ -263,6 +268,7 @@ resistance_recipe_time ``` **Explanation:** + - `step_dummy()`: Encodes categorical variables (`ward`, `species`) as numerical indicators. - `step_normalize()`: Normalises the `year` variable. - `step_nzv()`: Removes near-zero variance predictors. @@ -280,6 +286,7 @@ lm_model ``` **Explanation:** + - `linear_reg()`: Defines a linear regression model. - `set_engine("lm")`: Uses R’s built-in linear regression engine. @@ -324,6 +331,7 @@ metrics_time ``` **Explanation:** + - `initial_split()`: Splits data into training and testing sets. - `fit()`: Trains the workflow. - `predict()`: Generates resistance predictions.