Merge branch 'develop'

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: Ramses
 Type: Package
 Title: R Package for Antimicrobial Stewardship & Surveillance 
-Version: 0.4.0
+Version: 0.4.1
 Authors@R: c(
     person(given = "Peter",
            family = "Dutey-Magni",
@@ -63,7 +63,6 @@ RoxygenNote: 7.1.1
 VignetteBuilder: knitr,rmarkdown
 Collate: 
     'Ramses-package.R'
-    'antibiotic_icd_indications.R'
     'objects.R'
     'clinical_features.R'
     'database.R'

NEWS.md

@@ -1,4 +1,13 @@
 
+# Ramses 0.4.1
+
+*5 August 2021*
+
+## Improvements
+
+* clarifications on `vignette("load-data")`
+* corrections to `antibiotic_icd_indications`
+
 
 # Ramses 0.4.0
 

R/database.R

@@ -1562,7 +1562,7 @@ create_mock_database <- function(file,
 #' @description This wrapper function for \link[dplyr]{collect} will convert
 #' relevant character columns to \code{Date} and \code{POSIXct} type when collecting 
 #' SQLite tables. This addresses the absence of date and time data types
-#' in SQLite. Tables from other relational database systems are note affected.
+#' in SQLite. Tables from other relational database systems are not affected.
 #' @param tbl a `tbl_sql` object
 #' @return a `tbl_df` object
 #' @seealso \url{https://www.sqlite.org/datatype3.html#date_and_time_datatype}

R/objects.R

@@ -134,11 +134,14 @@ MedicationRequest <- function(conn, id) {
 
 #' An S4 class to represent therapy episodes
 #'
-#' @slot id a character therapy episode identifier
+#' @slot id a therapy episode identifier
 #' @slot conn a database connection
 #' @slot record a \code{tbl_sql} for the corresponding database record
 #' @slot therapy_table a \code{tbl_sql} for the longitudinal therapy table
-#' @param id a vector of one or several therapy episode identifiers
+#' @param id a vector of one or several therapy episode identifiers (from
+#' database field \code{drug_therapy_episodes.therapy_id} as generated by 
+#' \code{\link{load_medications}()} or
+#' \code{\link{create_therapy_episodes}()})
 #' @param conn a database connection
 #' @param object an object of class \code{MedicationRequest} or 
 #' \code{Prescription}

R/reference.R

@@ -1,3 +1,30 @@
+#' Common infections and indications for antimicrobial therapy
+#' 
+#' @description Look up table of common infections and whether 
+#' they are commonly treated with antibiotics.
+#' @format Data frame of 276 rows describing ICD-10 codes with 6 columns:
+#' \describe{
+#' \item{\code{icd_root}}{character vector of 3- to 4-character ICD-10 codes}
+#' \item{\code{infection_group1_label}}{character vector referencing 17 infection groups}
+#' \item{\code{infection_group2_label}}{character vector referencing 74 infections}
+#' \item{\code{antibiotics_indicated}}{character vector indicating whether antibiotics
+#' are indicated ("potentially", "rarely", "usually")}
+#' \item{\code{infection_group1_code}}{character vector containing 3-character short codes
+#' for infection groups}
+#' \item{\code{infection_group2_code}}{character vector containing 5-character short codes
+#' for infections}
+#' }
+#' @docType data
+#' @name antibiotic_icd_indications
+#' @source Adapted from Supplementary Table S1 in \insertCite{Hashimoto2020}{Ramses}.
+#' @references
+#'   \insertAllCited{}
+#' @examples 
+#' data("antibiotic_icd_indications")
+#' head(antibiotic_icd_indications)
+"antibiotic_icd_indications"
+
+
 #' English Adaptation of the WHO AWaRe Index
 #'
 #' @description This `AWaRe Index' is a classification by the World Health
@@ -44,6 +71,9 @@
 #' Therapeutic Moiety equivalents from the NHS Dictionary of Medicines (dm+d)
 #' \insertCite{SNOMEDDrugUK2020}{Ramses}.
 #' @references{\insertAllCited{}}
+#' @examples 
+#' data("reference_aware")
+#' head(reference_aware)
 "reference_aware"
 
 #' Clinical Classifications Software (CCS): map to 4-character ICD codes
@@ -89,6 +119,9 @@
 #' @source Adapted from \insertCite{HCUP-CCS}{Ramses} for 4-character ICD-10 codes.
 #' @references
 #'   \insertAllCited{}
+#' @examples 
+#' data("ccs")
+#' head(ccs)
 "ccs"
 
 
@@ -118,6 +151,9 @@
 #' 4-character ICD-10 codes.
 #' @references
 #'   \insertAllCited{}
+#' @examples 
+#' data("ccsr")
+#' head(ccsr)
 "ccsr"
 
 #' Prescription frequency abbreviations
@@ -131,6 +167,10 @@
 #' @format A data frame with 64 abbreviations and their corresponding daily frequency value.
 #' @docType data
 #' @name reference_drug_frequency
+#' @seealso \href{https://en.wikipedia.org/wiki/List_of_medical_abbreviations:_Latin_abbreviations}{Latin medical abbreviations}
+#' @examples 
+#' data("reference_drug_frequency")
+#' head(reference_drug_frequency)
 "reference_drug_frequency"
 
 #' LOINC codes for clinical investigations and observations
@@ -170,4 +210,7 @@
 #' @format A data frame.
 #' @docType data
 #' @name reference_specimen_type
+#' @examples 
+#' data("reference_specimen_type")
+#' head(reference_specimen_type)
 "reference_specimen_type"

R/validate_data.R

@@ -211,21 +211,24 @@
 #' @param episodes data frame containing one row per episode of care
 #' @param wards (optional) data frame containing one row per ward stay. 
 #'   Default is `NULL`.
-#' @section Patient variables:
+#' @section Patient mandatory variables:
 #' \describe{
 #'   \item{\code{patient_id}}{a patient identifier with no missing value}
-#'   \item{\code{forename}}{[optional] the patient's forename}
-#'   \item{\code{surname}}{[optional] the patient's surname}
-#'   \item{\code{date_of_birth}}{[optional] a \code{Date} for the birth date}
-#'   \item{\code{date_of_death}}{[optional] a missing value or a \code{Date} of death}
-#'   \item{\code{sex}}{[optional] the following values are valid: \itemize{
+#'   }
+#' @section Patient optional variables:
+#' \describe{
+#'   \item{\code{forename}}{the patient's forename}
+#'   \item{\code{surname}}{the patient's surname}
+#'   \item{\code{date_of_birth}}{a \code{Date} for the birth date}
+#'   \item{\code{date_of_death}}{a missing value or a \code{Date} of death}
+#'   \item{\code{sex}}{the following values are valid: \itemize{
 #'        \item \code{"male"}  
 #'        \item \code{"female"}  
 #'        \item \code{"other"}
 #'        \item \code{"unknown"}
 #'    }
 #'   Must not be missing.}
-#'   \item{\code{ethnic_category_UK}}{[optional] reserved for UK users for \code{Ramses} to compute
+#'   \item{\code{ethnic_category_UK}}{reserved for UK users for \code{Ramses} to compute
 #'   the empirical glomerular filtration rate (eGFR). The following codes are valid:
 #'   
 #'   White \itemize{
@@ -370,9 +373,9 @@ validate_inpatient_episodes <- function(patients,
     stop("All patients in `episodes` must exist in `patients`")
   }
 
-  validation_result <- validate_inpatient_spells(episodes)
+  validation_result <- .validate_inpatient_spells(episodes)
   validation_result <- append(
-    validate_inpatient_episode_dates(data = episodes,
+    .validate_inpatient_episode_dates(data = episodes,
                                      type = "episodes"), 
     validation_result)
 
@@ -420,7 +423,7 @@ validate_inpatient_episodes <- function(patients,
                     discharge_date), 
     all.x = TRUE)
 
-  validate_inpatient_episode_dates(data = wards,
+  .validate_inpatient_episode_dates(data = wards,
                                    type = "wards")
 }
 
@@ -430,7 +433,8 @@ validate_inpatient_episodes <- function(patients,
 #' @param data a data frame object
 #' @importFrom data.table data.table
 #' @return A logical value indicating success
-validate_inpatient_spells <- function(data) {
+#' @noRd
+.validate_inpatient_spells <- function(data) {
 
   validation_result <- TRUE
 
@@ -481,7 +485,8 @@ validate_inpatient_spells <- function(data) {
 #' either \code{"wards"} for ward stays or \code{"episodes"} for inpatient episodes.
 #' @importFrom data.table data.table := 
 #' @return A logical value indicating success
-validate_inpatient_episode_dates <- function(data, type = "episodes") {
+#' @noRd
+.validate_inpatient_episode_dates <- function(data, type = "episodes") {
 
   if(type == "episodes") {
     data$start <- data[["episode_start"]]
@@ -704,9 +709,10 @@ validate_inpatient_diagnoses <- function(diagnoses_data, diagnoses_lookup) {
 #'      \item{\code{prescription_id}}{a prescription identifier with no missing value}
 #'      \item{\code{prescription_text}}{a character string summarising the prescription 
 #'      (to be displayed in user interfaces, eg: \code{'Amoxicillin oral 500mg BDS'})}
-#'      \item{\code{drug_code}}{identifier of the drug (from a dictionary such as SNOMED CT or
-#'       from \code{\link[AMR]{as.ab}()})}
-#'      \item{\code{drug_name}}{preferred name of the drug in the drug dictionary}
+#'      \item{\code{drug_code}}{identifier of the drug (for antibacterials/antifungals, 
+#'      use \code{\link[AMR]{as.ab}()})}
+#'      \item{\code{drug_name}}{preferred name of the drug in the drug dictionary
+#'      (see \code{\link[AMR]{ab_name}()})}
 #'      \item{\code{drug_display_name}}{drug name to display in reports and user interfaces
 #'      (can be the same as \code{drug_name})}
 #'      \item{\code{drug_group}}{the antimicrobial class see \code{\link[AMR]{ab_group}()}}
@@ -756,8 +762,12 @@ validate_inpatient_diagnoses <- function(diagnoses_data, diagnoses_lookup) {
 #'      \item{\code{dose}}{a numeric vector of dosage quantities}
 #'      \item{\code{unit}}{a character vector of dosage units}
 #'      \item{\code{route}}{the route of administration value natively assigned by system}
-#'      \item{\code{daily_frequency}}{a numeric value indicating the number of times the drug 
-#'      is to be administered per day. The following values are considered valid:
+#'      \item{\code{frequency}}{a character vector of frequencies of administrations
+#'       (eg: "BDS" or "Twice a day"). See also: \code{\link{reference_drug_frequency}}}
+#'      \item{\code{daily_frequency}}{a numeric translation of variable \code{frequency}
+#'      indicating the number of times the drug is to be administered per day. 
+#'      Values can be lower than 1 for prescriptions administered less than daily.
+#'      Values must be strictly positive, except for the following codes:
 #'      \itemize{ 
 #'         \item -1 for a single one-off administration
 #'         \item -9 for 'as required' (\emph{Pro Re Nata}) prescriptions
@@ -770,7 +780,7 @@ validate_inpatient_diagnoses <- function(diagnoses_data, diagnoses_lookup) {
 #'        (eg doxicycline 200mg followed by 100mg). Unless provided, 
 #'        such identifiers will be created by \code{Ramses} using 
 #'        transitive closure.}
-#'   \item{\code{DDD}}{the prescribed daily dose (dose x freq. administrations/day)
+#'   \item{\code{DDD}}{the prescribed daily dose (dose x \code{daily_frequency})
 #'   expressed in defined daily doses, see \code{\link{compute_DDDs}()}}
 #'   \item{\code{...}}{any other field, as desired, can be loaded into the database}
 #' }
@@ -907,9 +917,10 @@ validate_prescriptions <- function(data) {
 #'      \item{\code{administration_id}}{an administration identifier with no missing value}
 #'      \item{\code{administration_text}}{a character string summarising the drug to administer 
 #'      (to be displayed in user interfaces, eg: \code{'Amoxicillin oral 500mg'})}
-#'      \item{\code{drug_code}}{identifier of the drug (from a dictionary such as SNOMED CT or
-#'       from \code{\link[AMR]{as.ab}()})}
-#'      \item{\code{drug_name}}{preferred name of the drug in the drug dictionary}
+#'      \item{\code{drug_code}}{identifier of the drug (for antibacterials/antifungals, 
+#'      use \code{\link[AMR]{as.ab}()})}
+#'      \item{\code{drug_name}}{preferred name of the drug in the drug dictionary
+#'      (see \code{\link[AMR]{ab_name}()})}
 #'      \item{\code{drug_display_name}}{drug name to display in reports and user interfaces
 #'      (can be the same as \code{drug_name})}
 #'      \item{\code{drug_group}}{the antimicrobial class see \code{\link[AMR]{ab_group}()}}

_pkgdown.yml

@@ -48,6 +48,17 @@ reference:
   - parenteral_changes
   - starts_with("clinical_feature_")
   - therapy_timeline
+- title: Transform and validate data
+  desc:  Functions to enrich and validate data before loading into the warehouse.
+  contents:
+  - starts_with("map_")
+  - compute_DDDs
+  - get_ATC_name
+  - starts_with("validate_inpatient")
+  - validate_prescriptions
+  - validate_administrations
+  - validate_investigations
+  - validate_microbiology
 - title: Load & link data
   desc:  Load records into the warehouse and create secondary information.
   contents:
@@ -81,17 +92,6 @@ reference:
   - starts_with("bridge_")
   - create_therapy_episodes
   - collect_ramses_tbl
-- title: Transform and validate data
-  desc:  Functions to enrich and validate data before loading into the warehouse.
-  contents:
-  - starts_with("map_")
-  - compute_DDDs
-  - get_ATC_name
-  - starts_with("validate_inpatient")
-  - validate_prescriptions
-  - validate_administrations
-  - validate_investigations
-  - validate_microbiology
 - title: Index
   desc:  All functions in alphabetical order
   contents: