AMR/R/custom_microorganisms.R

328 lines
14 KiB
R
Raw Normal View History

2022-12-27 15:16:15 +01:00
# ==================================================================== #
# TITLE: #
2022-12-27 15:16:15 +01:00
# AMR: An R Package for Working with Antimicrobial Resistance Data #
# #
# SOURCE CODE: #
2022-12-27 15:16:15 +01:00
# https://github.com/msberends/AMR #
# #
# PLEASE CITE THIS SOFTWARE AS: #
2022-12-27 15:16:15 +01:00
# Berends MS, Luz CF, Friedrich AW, Sinha BNM, Albers CJ, Glasner C #
# (2022). AMR: An R Package for Working with Antimicrobial Resistance #
# Data. Journal of Statistical Software, 104(3), 1-31. #
2023-05-27 10:39:22 +02:00
# https://doi.org/10.18637/jss.v104.i03 #
2022-12-27 15:16:15 +01:00
# #
# Developed at the University of Groningen and the University Medical #
# Center Groningen in The Netherlands, in collaboration with many #
# colleagues from around the world, see our website. #
# #
# This R package is free software; you can freely use and distribute #
# it for both personal and commercial purposes under the terms of the #
# GNU General Public License version 2.0 (GNU GPL-2), as published by #
# the Free Software Foundation. #
# We created this package for both routine data analysis and academic #
# research and it was publicly released in the hope that it will be #
# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY. #
# #
# Visit our website for the full manual and a complete tutorial about #
# how to conduct AMR data analysis: https://msberends.github.io/AMR/ #
# ==================================================================== #
2023-01-14 19:50:25 +01:00
#' Add Custom Microorganisms
2022-12-27 15:16:15 +01:00
#'
2023-01-14 19:50:25 +01:00
#' With [add_custom_microorganisms()] you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis.
2023-01-14 17:10:10 +01:00
#' @param x a [data.frame] resembling the [microorganisms] data set, at least containing column "genus" (case-insensitive)
2022-12-27 15:16:15 +01:00
#' @details This function will fill in missing taxonomy for you, if specific taxonomic columns are missing, see *Examples*.
2023-01-23 15:01:21 +01:00
#'
#' **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.
#'
2023-03-12 13:02:37 +01:00
#' There are two ways to circumvent this and automate the process of adding microorganisms:
2023-01-23 15:01:21 +01:00
#'
#' **Method 1:** Using the [package option][AMR-options] [`AMR_custom_mo`][AMR-options], which is the preferred method. To use this method:
2023-01-23 15:01:21 +01:00
#'
2023-01-14 17:10:10 +01:00
#' 1. Create a data set in the structure of the [microorganisms] data set (containing at the very least column "genus") and save it with [saveRDS()] to a location of choice, e.g. `"~/my_custom_mo.rds"`, or any remote location.
2023-01-23 15:01:21 +01:00
#'
#' 2. Set the file location to the [package option][AMR-options] [`AMR_custom_mo`][AMR-options]: `options(AMR_custom_mo = "~/my_custom_mo.rds")`. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the `.Rprofile` file so that it will be loaded on start-up of \R. To do this, open the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`, add this text and save the file:
2022-12-27 15:16:15 +01:00
#'
#' ```r
#' # Add custom microorganism codes:
#' options(AMR_custom_mo = "~/my_custom_mo.rds")
#' ```
2023-01-23 15:01:21 +01:00
#'
2022-12-27 15:16:15 +01:00
#' Upon package load, this file will be loaded and run through the [add_custom_microorganisms()] function.
2023-01-23 15:01:21 +01:00
#'
2023-03-12 13:02:37 +01:00
#' **Method 2:** Loading the microorganism directly from your `.Rprofile` file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method:
2023-01-23 15:01:21 +01:00
#'
2022-12-27 15:16:15 +01:00
#' 1. Edit the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`.
#'
#' 2. Add a text like below and save the file:
#'
#' ```r
#' # Add custom antibiotic drug codes:
2023-01-19 12:54:53 +01:00
#' AMR::add_custom_microorganisms(
2022-12-28 14:20:10 +01:00
#' data.frame(genus = "Enterobacter",
2022-12-27 15:16:15 +01:00
#' species = "asburiae/cloacae")
#' )
#' ```
#'
2023-03-12 13:02:37 +01:00
#' Use [clear_custom_microorganisms()] to clear the previously added microorganisms.
2023-01-14 19:50:25 +01:00
#' @seealso [add_custom_antimicrobials()] to add custom antimicrobials.
2022-12-27 15:16:15 +01:00
#' @rdname add_custom_microorganisms
#' @export
#' @examples
#' \donttest{
#' # a combination of species is not formal taxonomy, so
2023-05-26 20:37:00 +02:00
#' # this will result in "Enterobacter cloacae cloacae",
#' # since it resembles the input best:
2022-12-27 15:16:15 +01:00
#' mo_name("Enterobacter asburiae/cloacae")
#'
#' # now add a custom entry - it will be considered by as.mo() and
#' # all mo_*() functions
#' add_custom_microorganisms(
2023-01-23 15:01:21 +01:00
#' data.frame(
#' genus = "Enterobacter",
#' species = "asburiae/cloacae"
2022-12-27 15:16:15 +01:00
#' )
#' )
#'
2022-12-28 14:20:10 +01:00
#' # E. asburiae/cloacae is now a new microorganism:
2022-12-27 15:16:15 +01:00
#' mo_name("Enterobacter asburiae/cloacae")
2023-01-23 15:01:21 +01:00
#'
2022-12-28 14:20:10 +01:00
#' # its code:
#' as.mo("Enterobacter asburiae/cloacae")
2023-01-23 15:01:21 +01:00
#'
2022-12-27 15:16:15 +01:00
#' # all internal algorithms will work as well:
#' mo_name("Ent asburia cloacae")
2023-01-23 15:01:21 +01:00
#'
2022-12-27 15:16:15 +01:00
#' # and even the taxonomy was added based on the genus!
2022-12-28 14:20:10 +01:00
#' mo_family("E. asburiae/cloacae")
2022-12-27 15:16:15 +01:00
#' mo_gramstain("Enterobacter asburiae/cloacae")
#'
2022-12-28 14:20:10 +01:00
#' mo_info("Enterobacter asburiae/cloacae")
2023-01-23 15:01:21 +01:00
#'
#'
2023-01-14 17:10:10 +01:00
#' # the function tries to be forgiving:
#' add_custom_microorganisms(
2023-01-23 15:01:21 +01:00
#' data.frame(
#' GENUS = "BACTEROIDES / PARABACTEROIDES SLASHLINE",
#' SPECIES = "SPECIES"
#' )
2023-01-14 19:50:25 +01:00
#' )
2023-01-19 12:54:53 +01:00
#' mo_name("BACTEROIDES / PARABACTEROIDES")
#' mo_rank("BACTEROIDES / PARABACTEROIDES")
2023-01-23 15:01:21 +01:00
#'
2023-05-26 20:37:00 +02:00
#' # taxonomy still works, even though a slashline genus was given as input:
2023-01-19 12:54:53 +01:00
#' mo_family("Bacteroides/Parabacteroides")
2023-01-23 15:01:21 +01:00
#'
#'
2023-01-14 19:50:25 +01:00
#' # for groups and complexes, set them as species or subspecies:
2023-01-14 17:10:10 +01:00
#' add_custom_microorganisms(
2023-01-23 15:01:21 +01:00
#' data.frame(
#' genus = "Citrobacter",
#' species = c("freundii", "braakii complex"),
#' subspecies = c("complex", "")
#' )
2023-01-14 19:50:25 +01:00
#' )
#' mo_name(c("C. freundii complex", "C. braakii complex"))
#' mo_species(c("C. freundii complex", "C. braakii complex"))
#' mo_gramstain(c("C. freundii complex", "C. braakii complex"))
2022-12-27 15:16:15 +01:00
#' }
add_custom_microorganisms <- function(x) {
meet_criteria(x, allow_class = "data.frame")
2023-01-14 17:10:10 +01:00
stop_ifnot("genus" %in% tolower(colnames(x)), paste0("`x` must contain column 'genus'."))
2023-01-23 15:01:21 +01:00
2023-01-21 23:47:20 +01:00
add_MO_lookup_to_AMR_env()
2023-01-23 15:01:21 +01:00
2022-12-27 15:16:15 +01:00
# remove any extra class/type, such as grouped tbl, or data.table:
x <- as.data.frame(x, stringsAsFactors = FALSE)
2023-01-14 17:10:10 +01:00
colnames(x) <- tolower(colnames(x))
2022-12-27 15:16:15 +01:00
# rename 'name' to 'fullname' if it's in the data set
if ("name" %in% colnames(x) && !"fullname" %in% colnames(x)) {
colnames(x)[colnames(x) == "name"] <- "fullname"
}
# keep only columns available in the microorganisms data set
x <- x[, colnames(AMR_env$MO_lookup)[colnames(AMR_env$MO_lookup) %in% colnames(x)], drop = FALSE]
2023-01-23 15:01:21 +01:00
2022-12-27 15:16:15 +01:00
# clean the input ----
2023-01-14 17:10:10 +01:00
for (col in c("genus", "species", "subspecies")) {
if (!col %in% colnames(x)) {
x[, col] <- ""
}
if (is.factor(x[, col, drop = TRUE])) {
x[, col] <- as.character(x[, col, drop = TRUE])
}
col_ <- x[, col, drop = TRUE]
2023-01-14 19:50:25 +01:00
col_ <- tolower(col_)
col_ <- gsub("slashline", "", col_, fixed = TRUE)
col_ <- trimws2(col_)
2023-01-14 17:10:10 +01:00
col_[col_ %like% "(sub)?species"] <- ""
col_ <- gsub(" *([/-]) *", "\\1", col_, perl = TRUE)
2023-01-14 19:50:25 +01:00
# groups are in our taxonomic table with a capital G
2023-01-14 17:10:10 +01:00
col_ <- gsub(" group( |$)", " Group\\1", col_, perl = TRUE)
2023-01-23 15:01:21 +01:00
2023-01-14 17:10:10 +01:00
col_[is.na(col_)] <- ""
if (col == "genus") {
substr(col_, 1, 1) <- toupper(substr(col_, 1, 1))
col_ <- gsub("/([a-z])", "/\\U\\1", col_, perl = TRUE)
stop_if(any(col_ == ""), "the 'genus' column cannot be empty")
stop_if(any(col_ %like% " "), "the 'genus' column must not contain spaces")
}
x[, col] <- col_
2022-12-27 15:16:15 +01:00
}
2023-01-14 19:50:25 +01:00
# if subspecies is a group or complex, add it to the species and empty the subspecies
2023-01-23 15:01:21 +01:00
x$species[which(x$subspecies %in% c("group", "Group", "complex"))] <- paste(
x$species[which(x$subspecies %in% c("group", "Group", "complex"))],
x$subspecies[which(x$subspecies %in% c("group", "Group", "complex"))]
)
2023-01-14 19:50:25 +01:00
x$subspecies[which(x$subspecies %in% c("group", "Group", "complex"))] <- ""
2023-01-23 15:01:21 +01:00
2022-12-27 15:16:15 +01:00
if ("rank" %in% colnames(x)) {
2023-01-23 15:01:21 +01:00
stop_ifnot(
all(x$rank %in% AMR_env$MO_lookup$rank),
"the 'rank' column can only contain these values: ", vector_or(AMR_env$MO_lookup$rank)
)
2022-12-27 15:16:15 +01:00
} else {
x$rank <- ifelse(x$subspecies != "", "subspecies",
2023-01-23 15:01:21 +01:00
ifelse(x$species != "", "species",
ifelse(x$genus != "", "genus",
stop("in add_custom_microorganisms(): only microorganisms up to the genus level can be added",
call. = FALSE
)
)
)
)
2022-12-27 15:16:15 +01:00
}
x$source <- "Added by user"
2022-12-27 15:16:15 +01:00
if (!"fullname" %in% colnames(x)) {
2022-12-28 14:20:10 +01:00
x$fullname <- trimws2(paste(x$genus, x$species, x$subspecies))
2022-12-27 15:16:15 +01:00
}
2022-12-28 14:20:10 +01:00
if (!"kingdom" %in% colnames(x)) x$kingdom <- ""
if (!"phylum" %in% colnames(x)) x$phylum <- ""
if (!"class" %in% colnames(x)) x$class <- ""
if (!"order" %in% colnames(x)) x$order <- ""
if (!"family" %in% colnames(x)) x$family <- ""
x$kingdom[is.na(x$kingdom)] <- ""
x$phylum[is.na(x$phylum)] <- ""
x$class[is.na(x$class)] <- ""
x$order[is.na(x$order)] <- ""
x$family[is.na(x$family)] <- ""
2023-01-23 15:01:21 +01:00
2022-12-27 15:16:15 +01:00
for (col in colnames(x)) {
2023-01-14 17:10:10 +01:00
if (is.factor(x[, col, drop = TRUE])) {
x[, col] <- as.character(x[, col, drop = TRUE])
}
2022-12-27 15:16:15 +01:00
if (is.list(AMR_env$MO_lookup[, col, drop = TRUE])) {
x[, col] <- as.list(x[, col, drop = TRUE])
}
}
2023-01-23 15:01:21 +01:00
2023-01-14 17:10:10 +01:00
# fill in taxonomy based on genus
genus_to_check <- gsub("^(.*)[^a-zA-Z].*", "\\1", x$genus, perl = TRUE)
x$kingdom[which(x$kingdom == "" & genus_to_check != "")] <- AMR_env$MO_lookup$kingdom[match(genus_to_check[which(x$kingdom == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
x$phylum[which(x$phylum == "" & genus_to_check != "")] <- AMR_env$MO_lookup$phylum[match(genus_to_check[which(x$phylum == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
x$class[which(x$class == "" & genus_to_check != "")] <- AMR_env$MO_lookup$class[match(genus_to_check[which(x$class == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
x$order[which(x$order == "" & genus_to_check != "")] <- AMR_env$MO_lookup$order[match(genus_to_check[which(x$order == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
x$family[which(x$family == "" & genus_to_check != "")] <- AMR_env$MO_lookup$family[match(genus_to_check[which(x$family == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
2023-01-23 15:01:21 +01:00
2023-01-14 17:10:10 +01:00
# fill in other columns that are used in internal algorithms
2023-01-19 12:54:53 +01:00
x$prevalence <- NA_real_
x$prevalence[which(genus_to_check != "")] <- AMR_env$MO_lookup$prevalence[match(genus_to_check[which(genus_to_check != "")], AMR_env$MO_lookup$genus)]
x$prevalence[is.na(x$prevalence)] <- 1.25
2022-12-27 15:16:15 +01:00
x$status <- "accepted"
2023-01-14 17:10:10 +01:00
x$ref <- paste("Self-added,", format(Sys.Date(), "%Y"))
x$kingdom_index <- AMR_env$MO_lookup$kingdom_index[match(genus_to_check, AMR_env$MO_lookup$genus)]
# complete missing kingdom index, so mo_matching_score() will not return NA
x$kingdom_index[is.na(x$kingdom_index)] <- 1
2022-12-27 15:16:15 +01:00
x$fullname_lower <- tolower(x$fullname)
x$full_first <- substr(x$fullname_lower, 1, 1)
x$species_first <- tolower(substr(x$species, 1, 1))
x$subspecies_first <- tolower(substr(x$subspecies, 1, 1))
2023-01-23 15:01:21 +01:00
2022-12-28 14:20:10 +01:00
if (!"mo" %in% colnames(x)) {
# create the mo code
x$mo <- NA_character_
}
2023-01-14 17:10:10 +01:00
x$mo <- trimws2(as.character(x$mo))
2022-12-28 14:20:10 +01:00
x$mo[x$mo == ""] <- NA_character_
2023-01-14 17:10:10 +01:00
current <- sum(AMR_env$MO_lookup$source == "Added by user", na.rm = TRUE)
2023-01-23 15:01:21 +01:00
x$mo[is.na(x$mo)] <- paste0(
"CUSTOM",
seq.int(from = current + 1, to = current + nrow(x), by = 1),
"_",
2023-05-11 21:56:27 +02:00
trimws(
paste(abbreviate_mo(x$genus, 5),
abbreviate_mo(x$species, 4, hyphen_as_space = TRUE),
abbreviate_mo(x$subspecies, 4, hyphen_as_space = TRUE),
sep = "_"),
whitespace = "_"))
2023-01-14 17:10:10 +01:00
stop_if(anyDuplicated(c(as.character(AMR_env$MO_lookup$mo), x$mo)), "MO codes must be unique and not match existing MO codes of the AMR package")
2023-05-11 21:56:27 +02:00
2022-12-28 14:20:10 +01:00
# add to package ----
2022-12-27 15:16:15 +01:00
AMR_env$custom_mo_codes <- c(AMR_env$custom_mo_codes, x$mo)
class(AMR_env$MO_lookup$mo) <- "character"
2023-01-23 15:01:21 +01:00
2022-12-27 15:16:15 +01:00
new_df <- AMR_env$MO_lookup[0, , drop = FALSE][seq_len(NROW(x)), , drop = FALSE]
rownames(new_df) <- NULL
list_cols <- vapply(FUN.VALUE = logical(1), new_df, is.list)
for (l in which(list_cols)) {
# prevent binding NULLs in lists, replace with NA
new_df[, l] <- as.list(NA_character_)
}
for (col in colnames(x)) {
# assign new values
new_df[, col] <- x[, col, drop = TRUE]
}
2023-01-23 15:01:21 +01:00
2022-12-28 14:20:10 +01:00
# clear previous coercions
suppressMessages(mo_reset_session())
2023-01-23 15:01:21 +01:00
2023-03-12 13:02:37 +01:00
AMR_env$MO_lookup <- unique(rbind_AMR(AMR_env$MO_lookup, new_df))
2022-12-27 15:16:15 +01:00
class(AMR_env$MO_lookup$mo) <- c("mo", "character")
2023-01-14 17:10:10 +01:00
if (nrow(x) <= 3) {
message_("Added ", vector_and(italicise(x$fullname), quotes = FALSE), " to the internal `microorganisms` data set.")
} else {
message_("Added ", nr2char(nrow(x)), " records to the internal `microorganisms` data set.")
}
2022-12-27 15:16:15 +01:00
}
#' @rdname add_custom_microorganisms
#' @export
clear_custom_microorganisms <- function() {
n <- nrow(AMR_env$MO_lookup)
2023-01-23 15:01:21 +01:00
2023-01-21 23:47:20 +01:00
# reset
AMR_env$MO_lookup <- NULL
add_MO_lookup_to_AMR_env()
2023-01-23 15:01:21 +01:00
2023-03-12 13:02:37 +01:00
# clear previous coercions
suppressMessages(mo_reset_session())
2022-12-27 15:16:15 +01:00
n2 <- nrow(AMR_env$MO_lookup)
AMR_env$custom_mo_codes <- character(0)
AMR_env$mo_previously_coerced <- AMR_env$mo_previously_coerced[which(AMR_env$mo_previously_coerced$mo %in% AMR_env$MO_lookup$mo), , drop = FALSE]
AMR_env$mo_uncertainties <- AMR_env$mo_uncertainties[0, , drop = FALSE]
message_("Cleared ", nr2char(n - n2), " custom record", ifelse(n - n2 > 1, "s", ""), " from the internal `microorganisms` data set.")
}
2023-05-11 21:56:27 +02:00
abbreviate_mo <- function(x, minlength = 5, prefix = "", hyphen_as_space = FALSE, ...) {
if (hyphen_as_space == TRUE) {
x <- gsub("-", " ", x, fixed = TRUE)
}
# keep a starting Latin ae
suppressWarnings(
gsub("(\u00C6|\u00E6)+",
"AE",
toupper(
paste0(prefix,
abbreviate(
gsub("^ae",
"\u00E6\u00E6",
x,
ignore.case = TRUE),
minlength = minlength,
use.classes = TRUE,
method = "both.sides",
...
))))
)
}