AMR/man/first_isolate.Rd

163 lines
8.3 KiB
Plaintext
Raw Normal View History

2018-02-21 11:52:31 +01:00
% Generated by roxygen2: do not edit by hand
2018-07-23 14:14:03 +02:00
% Please edit documentation in R/first_isolate.R
2018-02-21 11:52:31 +01:00
\name{first_isolate}
\alias{first_isolate}
2018-12-22 22:39:34 +01:00
\alias{filter_first_isolate}
\alias{filter_first_weighted_isolate}
2018-02-21 11:52:31 +01:00
\title{Determine first (weighted) isolates}
2018-04-20 13:45:34 +02:00
\source{
2018-07-29 22:14:51 +02:00
Methodology of this function is based on: \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition}, 2014, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
2018-04-20 13:45:34 +02:00
}
2018-02-21 11:52:31 +01:00
\usage{
2019-05-13 14:56:23 +02:00
first_isolate(x, col_date = NULL, col_patient_id = NULL,
2018-10-23 11:15:05 +02:00
col_mo = NULL, col_testcode = NULL, col_specimen = NULL,
col_icu = NULL, col_keyantibiotics = NULL, episode_days = 365,
testcodes_exclude = NULL, icu_exclude = FALSE,
2018-12-22 22:39:34 +01:00
specimen_group = NULL, type = "keyantibiotics", ignore_I = TRUE,
points_threshold = 2, info = TRUE, include_unknown = FALSE, ...)
2018-12-22 22:39:34 +01:00
2019-05-13 14:56:23 +02:00
filter_first_isolate(x, col_date = NULL, col_patient_id = NULL,
2018-12-22 22:39:34 +01:00
col_mo = NULL, ...)
2019-05-13 14:56:23 +02:00
filter_first_weighted_isolate(x, col_date = NULL,
2018-12-22 22:39:34 +01:00
col_patient_id = NULL, col_mo = NULL, col_keyantibiotics = NULL,
...)
2018-02-21 11:52:31 +01:00
}
\arguments{
2019-05-13 14:56:23 +02:00
\item{x}{a \code{data.frame} containing isolates.}
2018-02-21 11:52:31 +01:00
2019-01-15 12:45:24 +01:00
\item{col_date}{column name of the result date (or date that is was received on the lab), defaults to the first column of with a date class}
2018-02-21 11:52:31 +01:00
2018-12-10 15:14:29 +01:00
\item{col_patient_id}{column name of the unique IDs of the patients, defaults to the first column that starts with 'patient' or 'patid' (case insensitive)}
2018-02-21 11:52:31 +01:00
2019-08-27 22:41:09 +02:00
\item{col_mo}{column name of the IDs of the microorganisms (see \code{\link{as.mo}}), defaults to the first column of class \code{mo}. Values will be coerced using \code{\link{as.mo}}.}
2018-02-21 11:52:31 +01:00
2018-12-14 07:23:25 +01:00
\item{col_testcode}{column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (like test codes for screening). In that case \code{testcodes_exclude} will be ignored.}
2018-02-21 11:52:31 +01:00
2018-04-02 11:11:21 +02:00
\item{col_specimen}{column name of the specimen type or group}
2018-02-21 11:52:31 +01:00
2018-04-02 11:11:21 +02:00
\item{col_icu}{column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU)}
2018-02-21 11:52:31 +01:00
2018-12-14 07:23:25 +01:00
\item{col_keyantibiotics}{column name of the key antibiotics to determine first \emph{weighted} isolates, see \code{\link{key_antibiotics}}. Defaults to the first column that starts with 'key' followed by 'ab' or 'antibiotics' (case insensitive). Use \code{col_keyantibiotics = FALSE} to prevent this.}
2018-02-21 11:52:31 +01:00
\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 Source.}
2018-02-21 11:52:31 +01:00
\item{testcodes_exclude}{character vector with test codes that should be excluded (case-insensitive)}
2018-02-21 11:52:31 +01:00
2018-12-22 22:39:34 +01:00
\item{icu_exclude}{logical whether ICU isolates should be excluded (rows with value \code{TRUE} in column \code{col_icu})}
2018-02-21 11:52:31 +01:00
2018-12-22 22:39:34 +01:00
\item{specimen_group}{value in column \code{col_specimen} to filter on}
2018-02-21 11:52:31 +01:00
\item{type}{type to determine weighed isolates; can be \code{"keyantibiotics"} or \code{"points"}, see Details}
\item{ignore_I}{logical to determine whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantibiotics"}, see Details}
\item{points_threshold}{points until the comparison of key antibiotics will lead to inclusion of an isolate when \code{type = "points"}, see Details}
2018-02-21 11:52:31 +01:00
\item{info}{print progress}
\item{include_unknown}{logical to determine 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.}
2018-12-22 22:39:34 +01:00
\item{...}{parameters passed on to the \code{first_isolate} function}
2018-02-21 11:52:31 +01:00
}
\value{
2018-12-22 22:39:34 +01:00
Logical vector
2018-02-21 11:52:31 +01:00
}
\description{
Determine first (weighted) isolates of all microorganisms of every patient per episode and (if needed) per specimen type.
}
\details{
\strong{WHY THIS IS SO IMPORTANT} \cr
2018-12-22 22:39:34 +01:00
To conduct an analysis of antimicrobial resistance, you should only include the first isolate of every patient per episode \href{https://www.ncbi.nlm.nih.gov/pubmed/17304462}{[1]}. If you would not do this, you could easily get an overestimate or underestimate of the resistance of an antibiotic. Imagine that a patient was admitted with an MRSA and that it was found in 5 different blood cultures the following week. The resistance percentage of oxacillin of all \emph{S. aureus} isolates would be overestimated, because you included this MRSA more than once. It would be \href{https://en.wikipedia.org/wiki/Selection_bias}{selection bias}.
All isolates with a microbial ID of \code{NA} will be excluded as first isolate.
2019-04-09 14:59:17 +02:00
The functions \code{filter_first_isolate} and \code{filter_first_weighted_isolate} are helper functions to quickly filter on first isolates. The function \code{filter_first_isolate} is essentially equal to:
2018-12-22 22:39:34 +01:00
\preformatted{
2019-05-13 14:56:23 +02:00
x \%>\%
mutate(only_firsts = first_isolate(x, ...)) \%>\%
2018-12-22 22:39:34 +01:00
filter(only_firsts == TRUE) \%>\%
select(-only_firsts)
}
The function \code{filter_first_weighted_isolate} is essentially equal to:
\preformatted{
2019-05-13 14:56:23 +02:00
x \%>\%
2018-12-22 22:39:34 +01:00
mutate(keyab = key_antibiotics(.)) \%>\%
2019-05-13 14:56:23 +02:00
mutate(only_weighted_firsts = first_isolate(x,
2018-12-22 22:39:34 +01:00
col_keyantibiotics = "keyab", ...)) \%>\%
filter(only_weighted_firsts == TRUE) \%>\%
select(-only_weighted_firsts)
}
2018-07-17 13:02:05 +02:00
}
\section{Key antibiotics}{
There are two ways to determine whether isolates can be included as first \emph{weighted} isolates which will give generally the same results: \cr
2018-03-13 11:57:30 +01:00
2018-03-19 21:23:21 +01:00
\strong{1. Using} \code{type = "keyantibiotics"} \strong{and parameter} \code{ignore_I} \cr
2019-04-09 14:59:17 +02:00
Any difference from S to R (or vice versa) will (re)select an isolate as a first weighted isolate. With \code{ignore_I = FALSE}, also differences from I to S|R (or vice versa) will lead to this. This is a reliable method and 30-35 times faster than method 2. Read more about this in the \code{\link{key_antibiotics}} function. \cr
2018-07-17 13:02:05 +02:00
2018-03-19 21:23:21 +01:00
\strong{2. Using} \code{type = "points"} \strong{and parameter} \code{points_threshold} \cr
2019-04-09 14:59:17 +02:00
A difference from I to S|R (or vice versa) means 0.5 points, a difference from S to R (or vice versa) means 1 point. When the sum of points exceeds \code{points_threshold}, which default to \code{2}, an isolate will be (re)selected as a first weighted isolate.
2018-02-21 11:52:31 +01:00
}
2018-07-17 13:02:05 +02:00
2019-01-02 23:24:07 +01:00
\section{Read more on our website!}{
On our website \url{https://msberends.gitlab.io/AMR} you can find \href{https://msberends.gitlab.io/AMR/articles/AMR.html}{a tutorial} about how to conduct AMR analysis, the \href{https://msberends.gitlab.io/AMR/reference}{complete documentation of all functions} (which reads a lot easier than here in R) and \href{https://msberends.gitlab.io/AMR/articles/WHONET.html}{an example analysis using WHONET data}.
2019-01-02 23:24:07 +01:00
}
2018-02-21 11:52:31 +01:00
\examples{
# `example_isolates` is a dataset available in the AMR package.
# See ?example_isolates.
library(dplyr)
2018-12-22 22:39:34 +01:00
# Filter on first isolates:
example_isolates \%>\%
2018-08-10 15:01:05 +02:00
mutate(first_isolate = first_isolate(.,
col_date = "date",
col_patient_id = "patient_id",
2018-12-22 22:39:34 +01:00
col_mo = "mo")) \%>\%
filter(first_isolate == TRUE)
# Which can be shortened to:
example_isolates \%>\%
2018-12-22 22:39:34 +01:00
filter_first_isolate()
# or for first weighted isolates:
example_isolates \%>\%
2018-12-22 22:39:34 +01:00
filter_first_weighted_isolate()
2018-04-02 11:11:21 +02:00
# Now let's see if first isolates matter:
A <- example_isolates \%>\%
group_by(hospital_id) \%>\%
2019-05-10 16:44:59 +02:00
summarise(count = n_rsi(GEN), # gentamicin availability
2019-11-10 13:17:20 +01:00
resistance = resistance(GEN)) # gentamicin resistance
B <- example_isolates \%>\%
2019-05-10 16:44:59 +02:00
filter_first_weighted_isolate() \%>\% # the 1st isolate filter
group_by(hospital_id) \%>\%
2019-05-10 16:44:59 +02:00
summarise(count = n_rsi(GEN), # gentamicin availability
2019-11-10 13:17:20 +01:00
resistance = resistance(GEN)) # gentamicin resistance
2018-08-10 15:01:05 +02:00
# Have a look at A and B.
# B is more reliable because every isolate is only counted once.
2019-04-09 14:59:17 +02:00
# Gentamicin resitance in hospital D appears to be 3.1\% higher than
# when you (erroneously) would have used all isolates for analysis.
2018-12-22 22:39:34 +01:00
## OTHER EXAMPLES:
2018-02-21 11:52:31 +01:00
\dontrun{
2018-02-22 20:48:48 +01:00
# set key antibiotics to a new variable
2019-05-13 14:56:23 +02:00
x$keyab <- key_antibiotics(x)
2018-02-21 11:52:31 +01:00
2019-10-11 17:21:02 +02:00
x$first_isolate <- first_isolate(x)
x$first_isolate_weighed <- first_isolate(x, col_keyantibiotics = 'keyab')
x$first_blood_isolate <- first_isolate(x, specimen_group = "Blood")
2018-02-21 11:52:31 +01:00
}
}
2018-07-17 13:02:05 +02:00
\seealso{
2018-07-17 14:48:11 +02:00
\code{\link{key_antibiotics}}
2018-07-17 13:02:05 +02:00
}