AMR/man/add_custom_microorganisms.Rd

114 lines
4.7 KiB
Plaintext
Raw Normal View History

2022-12-27 15:16:15 +01:00
% Generated by roxygen2: do not edit by hand
2023-01-14 17:10:10 +01:00
% Please edit documentation in R/custom_microorganisms.R
2022-12-27 15:16:15 +01:00
\name{add_custom_microorganisms}
\alias{add_custom_microorganisms}
\alias{clear_custom_microorganisms}
2023-01-14 19:50:25 +01:00
\title{Add Custom Microorganisms}
2022-12-27 15:16:15 +01:00
\usage{
add_custom_microorganisms(x)
clear_custom_microorganisms()
}
\arguments{
2023-01-14 17:10:10 +01:00
\item{x}{a \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)}
2022-12-27 15:16:15 +01:00
}
\description{
2023-01-14 19:50:25 +01:00
With \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis.
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 \emph{Examples}.
\strong{Important:} Due to how \R works, the \code{\link[=add_custom_microorganisms]{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:
2022-12-27 15:16:15 +01:00
\strong{Method 1:} Using the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_mo}}, which is the preferred method. To use this method:
2022-12-27 15:16:15 +01:00
\enumerate{
2023-01-14 17:10:10 +01:00
\item Create a data set in the structure of the \link{microorganisms} data set (containing at the very least column "genus") and save it with \code{\link[=saveRDS]{saveRDS()}} to a location of choice, e.g. \code{"~/my_custom_mo.rds"}, or any remote location.
\item Set the file location to the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_mo}}: \code{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 \code{.Rprofile} file so that it will be loaded on start-up of \R. To do this, open the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}, add this text and save the file:
2022-12-27 15:16:15 +01:00
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom microorganism codes:
options(AMR_custom_mo = "~/my_custom_mo.rds")
}\if{html}{\out{</div>}}
Upon package load, this file will be loaded and run through the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function.
}
2023-03-12 13:02:37 +01:00
\strong{Method 2:} Loading the microorganism directly from your \code{.Rprofile} file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method:
2022-12-27 15:16:15 +01:00
\enumerate{
\item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}.
\item Add a text like below and save the file:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ # 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")
)
}\if{html}{\out{</div>}}
}
2023-03-12 13:02:37 +01:00
Use \code{\link[=clear_custom_microorganisms]{clear_custom_microorganisms()}} to clear the previously added microorganisms.
2022-12-27 15:16:15 +01:00
}
\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")
2022-12-28 15:04:59 +01:00
2022-12-28 14:20:10 +01:00
# its code:
as.mo("Enterobacter asburiae/cloacae")
2022-12-28 15:04:59 +01:00
2022-12-27 15:16:15 +01:00
# all internal algorithms will work as well:
mo_name("Ent asburia cloacae")
# 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-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-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-14 17:10:10 +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
}
}
\seealso{
2023-01-14 19:50:25 +01:00
\code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} to add custom antimicrobials.
2022-12-27 15:16:15 +01:00
}