AMR/man/add_custom_antimicrobials.Rd

105 lines
4.0 KiB
Plaintext
Raw Normal View History

2022-10-10 20:20:39 +02:00
% Generated by roxygen2: do not edit by hand
2023-01-14 17:10:10 +01:00
% Please edit documentation in R/custom_antimicrobials.R
2022-10-10 20:20:39 +02:00
\name{add_custom_antimicrobials}
\alias{add_custom_antimicrobials}
\alias{clear_custom_antimicrobials}
2023-01-14 19:50:25 +01:00
\title{Add Custom Antimicrobials}
2022-10-10 20:20:39 +02:00
\usage{
add_custom_antimicrobials(x)
clear_custom_antimicrobials()
}
\arguments{
\item{x}{a \link{data.frame} resembling the \link{antibiotics} data set, at least containing columns "ab" and "name"}
}
\description{
2023-01-14 19:50:25 +01:00
With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own custom antimicrobial drug names and codes.
2022-10-10 20:20:39 +02:00
}
\details{
2022-12-27 15:16:15 +01:00
\strong{Important:} Due to how \R works, the \code{\link[=add_custom_antimicrobials]{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.
2022-10-10 20:20:39 +02:00
2023-03-12 13:02:37 +01:00
There are two ways to circumvent this and automate the process of adding antimicrobials:
2022-10-10 21:03:39 +02:00
\strong{Method 1:} Using the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_ab}}, which is the preferred method. To use this method:
2022-12-27 15:16:15 +01:00
\enumerate{
\item Create a data set in the structure of the \link{antibiotics} data set (containing at the very least columns "ab" and "name") and save it with \code{\link[=saveRDS]{saveRDS()}} to a location of choice, e.g. \code{"~/my_custom_ab.rds"}, or any remote location.
\item Set the file location to the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_ab}}: \code{options(AMR_custom_ab = "~/my_custom_ab.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
2023-01-23 20:07:57 +01:00
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom antimicrobial codes:
2022-12-27 15:16:15 +01:00
options(AMR_custom_ab = "~/my_custom_ab.rds")
}\if{html}{\out{</div>}}
Upon package load, this file will be loaded and run through the \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} function.
}
2023-03-12 13:02:37 +01:00
\strong{Method 2:} Loading the antimicrobial additions 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-23 20:07:57 +01:00
AMR::add_custom_antimicrobials(
2022-12-27 15:16:15 +01:00
data.frame(ab = "TESTAB",
name = "Test Antibiotic",
group = "Test Group")
)
2022-10-10 20:20:39 +02:00
}\if{html}{\out{</div>}}
2022-12-27 15:16:15 +01:00
}
2022-10-10 20:20:39 +02:00
Use \code{\link[=clear_custom_antimicrobials]{clear_custom_antimicrobials()}} to clear the previously added antimicrobials.
}
\examples{
2022-10-15 15:20:13 +02:00
\donttest{
2023-01-14 19:50:25 +01:00
# returns NA and throws a warning (which is suppressed here):
2022-10-10 21:03:39 +02:00
suppressWarnings(
2022-10-30 21:05:46 +01:00
as.ab("testab")
2022-10-10 21:03:39 +02:00
)
2022-10-10 20:20:39 +02:00
2022-10-10 21:38:39 +02:00
# now add a custom entry - it will be considered by as.ab() and
2022-10-10 20:20:39 +02:00
# all ab_*() functions
add_custom_antimicrobials(
2022-10-30 14:31:45 +01:00
data.frame(
2022-10-30 21:05:46 +01:00
ab = "TESTAB",
2022-10-30 14:31:45 +01:00
name = "Test Antibiotic",
# you can add any property present in the
# 'antibiotics' data set, such as 'group':
group = "Test Group"
)
2022-10-10 20:20:39 +02:00
)
2022-10-30 21:05:46 +01:00
# "testab" is now a new antibiotic:
as.ab("testab")
ab_name("testab")
ab_group("testab")
2022-10-10 21:03:39 +02:00
2022-10-30 21:05:46 +01:00
ab_info("testab")
# Add Co-fluampicil, which is one of the many J01CR50 codes, see
2024-03-03 23:24:57 +01:00
# https://atcddd.fhi.no/ddd/list_of_ddds_combined_products/
add_custom_antimicrobials(
2022-10-30 14:31:45 +01:00
data.frame(
ab = "COFLU",
name = "Co-fluampicil",
atc = "J01CR50",
2022-12-27 15:16:15 +01:00
group = "Beta-lactams/penicillins"
2022-10-30 14:31:45 +01:00
)
)
ab_atc("Co-fluampicil")
ab_name("J01CR50")
# even antibiotic selectors work
2022-10-30 14:31:45 +01:00
x <- data.frame(
2022-10-30 21:05:46 +01:00
random_column = "some value",
2023-01-21 23:47:20 +01:00
coflu = as.sir("S"),
ampicillin = as.sir("R")
2022-10-30 14:31:45 +01:00
)
x
x[, betalactams()]
2022-10-10 20:20:39 +02:00
}
2022-10-15 15:20:13 +02:00
}
2022-12-27 15:16:15 +01:00
\seealso{
2023-01-14 19:50:25 +01:00
\code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} to add custom microorganisms.
2022-12-27 15:16:15 +01:00
}