mirror of
https://github.com/msberends/AMR.git
synced 2026-11-16 00:10:57 +01:00
tori0513
3eeabf542a
Adds add_custom_antimicrobial_synonyms() to add local names, such as trade names, to existing antimicrobials, also via the AMR_custom_ab option. Matching is language-independent; as.ab() now returns NA with a warning for input that is not valid UTF-8.
121 lines
7.1 KiB
R
121 lines
7.1 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/custom_antimicrobials.R
|
|
\name{add_custom_antimicrobials}
|
|
\alias{add_custom_antimicrobials}
|
|
\alias{add_custom_antimicrobial_synonyms}
|
|
\alias{clear_custom_antimicrobials}
|
|
\title{Add Custom Antimicrobials}
|
|
\usage{
|
|
add_custom_antimicrobials(x)
|
|
|
|
add_custom_antimicrobial_synonyms(ab, synonyms = NULL)
|
|
|
|
clear_custom_antimicrobials()
|
|
}
|
|
\arguments{
|
|
\item{x}{A \link{data.frame} resembling the \link{antimicrobials} data set, at least containing columns "ab" and "name". To add synonyms to existing antimicrobials, columns "ab" and "synonyms" suffice (see \emph{Details}).}
|
|
|
|
\item{ab}{For \code{\link[=add_custom_antimicrobial_synonyms]{add_custom_antimicrobial_synonyms()}}: a \link{character} vector of existing antimicrobial codes (see \code{\link[=as.ab]{as.ab()}}), or a \link{data.frame} with columns "ab" and "synonyms" (one synonym per row).}
|
|
|
|
\item{synonyms}{A \link{character} vector of synonyms. If \code{ab} has length 1, all \code{synonyms} are added to that antimicrobial; otherwise \code{ab} and \code{synonyms} must have the same length.}
|
|
}
|
|
\description{
|
|
With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own custom antimicrobial drug names and codes.
|
|
}
|
|
\details{
|
|
\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.
|
|
|
|
There are two ways to circumvent this and automate the process of adding antimicrobials:
|
|
|
|
\strong{Method 1:} Using the package option \code{\link[=AMR-options]{AMR_custom_ab}}, which is the preferred method. To use this method:
|
|
\enumerate{
|
|
\item Create a data set in the structure of the \link{antimicrobials} data set (containing at the very least columns "ab" and "name", or only columns "ab" and "synonyms" for synonyms of existing antimicrobials) 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 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:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom antimicrobial codes:
|
|
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.
|
|
|
|
This file can also hold synonyms for antimicrobials that already exist, such as local trade names: rows with an existing code in column "ab" and only column "synonyms" filled (one synonym per row, codes may repeat) are passed on to \code{\link[=add_custom_antimicrobial_synonyms]{add_custom_antimicrobial_synonyms()}}. Rows with an existing code that have any other column filled still give an error. Synonyms must be valid UTF-8 text; convert other encodings first, e.g. with \code{iconv(x, from = "CP949", to = "UTF-8")}.
|
|
}
|
|
|
|
\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:
|
|
\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:
|
|
AMR::add_custom_antimicrobials(
|
|
data.frame(ab = "TESTAB",
|
|
name = "Test Antibiotic",
|
|
group = "Test Group")
|
|
)
|
|
}\if{html}{\out{</div>}}
|
|
}
|
|
|
|
Use \code{\link[=add_custom_antimicrobial_synonyms]{add_custom_antimicrobial_synonyms()}} to add extra names, such as local trade names, to antimicrobials that already exist (including antimicrobials added with \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}). These synonyms are recognised by \code{\link[=as.ab]{as.ab()}} and all \verb{ab_*()} functions. Synonyms may contain non-ASCII characters (e.g. trade names in other scripts): they are matched against the input as given, before \code{\link[=as.ab]{as.ab()}} transliterates the input to ASCII. Matching ignores case, all white space (including no-break and ideographic spaces) and zero-width characters. If the input does not match as given, a trailing part in parentheses or brackets (such as \verb{(piperacillin, tazobactam)}) and a trailing strength written as a number with a unit symbol (such as \verb{4.5g}, \verb{4/0.5 g} or \verb{500 mg/mL}) are removed one at a time, and matching is tried again after each removal, so that the longest registered synonym wins. Full-width characters are read as their ASCII equivalents. No words are removed, in any language: to recognise a name with a dosage form (such as \code{Inj}), add that variant as a synonym as well. Only user-added synonyms are matched this way, there is no other fuzzy matching for them, and a strength on its own is never matched to a user-added synonym. A synonym cannot be added if it already identifies another antimicrobial as its code, name, synonym, abbreviation, ATC code, CID or LOINC code, also when written with other punctuation (such as \code{J01-CR05}).
|
|
|
|
Use \code{\link[=clear_custom_antimicrobials]{clear_custom_antimicrobials()}} to clear the previously added antimicrobials and synonyms.
|
|
}
|
|
\examples{
|
|
\donttest{
|
|
# returns a wildly guessed result:
|
|
as.ab("testab")
|
|
|
|
# now add a custom entry - it will be considered by as.ab() and
|
|
# all ab_*() functions
|
|
add_custom_antimicrobials(
|
|
data.frame(
|
|
ab = "TESTAB",
|
|
name = "Test Antibiotic",
|
|
# you can add any property present in the
|
|
# 'antimicrobials' data set, such as 'group':
|
|
group = "Test Group"
|
|
)
|
|
)
|
|
|
|
# "testab" is now a new antibiotic:
|
|
as.ab("testab")
|
|
ab_name("testab")
|
|
ab_group("testab")
|
|
|
|
ab_info("testab")
|
|
|
|
|
|
# Add Co-fluampicil, which is one of the many J01CR50 codes, see
|
|
# https://atcddd.fhi.no/ddd/list_of_ddds_combined_products/
|
|
add_custom_antimicrobials(
|
|
data.frame(
|
|
ab = "COFLU",
|
|
name = "Co-fluampicil",
|
|
atc = "J01CR50",
|
|
group = "Beta-lactams/penicillins"
|
|
)
|
|
)
|
|
ab_atc("Co-fluampicil")
|
|
ab_name("J01CR50")
|
|
|
|
# even antimicrobial selectors work
|
|
# see ?amr_selector
|
|
x <- data.frame(
|
|
random_column = "some value",
|
|
coflu = as.sir("S"),
|
|
ampicillin = as.sir("R")
|
|
)
|
|
x
|
|
x[, betalactams()]
|
|
|
|
# add local trade names as synonyms to existing antimicrobials,
|
|
# here a Korean trade name of piperacillin/tazobactam
|
|
add_custom_antimicrobial_synonyms("TZP", "\uD0C0\uC870\uC2E0\uC8FC")
|
|
ab_name("\uD0C0\uC870\uC2E0\uC8FC")
|
|
# a trailing strength, as in many hospital exports, is ignored
|
|
as.ab("\uD0C0\uC870\uC2E0\uC8FC 4.5g")
|
|
}
|
|
}
|
|
\seealso{
|
|
\code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} to add custom microorganisms.
|
|
}
|