docs: 🚧 separate file for algorithm details, plus make pseudocode for internals

R/include-gld-purchases.R

@@ -1,9 +1,30 @@
 #' Include only those who have a purchase of a glucose lowering drug (GLD).
 #'
-#' See [algorithm] for the logic used to filter these patients.
+#' But don't include glucose-lowering drugs that may be used for other
+#' conditions than diabetes like GLP-RAs or dapagliflozin/empagliflozin drugs.
+#' Since the diagnosis code data on pregnancies (see below) is insufficient to
+#' perform censoring prior to 1997, `include_gld_purchases()` only extracts
+#' dates from 1997 onward by default (if Medical Birth Register data is
+#' available to use for censoring, the extraction window can be extended).
+#'
+#' @param lmdb The `lmdb` register.
+#'
+#' @return The same type as the input data, default as a [tibble::tibble()], in
+#'   a long format with all dates of purchases kept and the following variables:
+#'
+#'   -   `pnr`: Personal identification variable.
+#'   -   `date`: The dates of all purchases of GLD.
+#'   -   `atc`: The ATC code for the type of drug.
+#'   -   `contained_doses`: The amount of doses purchased, in number of defined daily
+#'       doses (DDD).
+#'   -   `indication_code`: The indication code of the prescription (renamed from
+#'       `indo`).
+#'
+#'   These events are then passed to a chain of exclusion functions:
+#'   `exclude_potential_pcos()` and `exclude_pregnancy()`.
 #'
-#' @return The same type as the input data, default as a [tibble::tibble()].
 #' @keywords internal
+#' @inherit algorithm seealso
 #'
 #' @examples
 #' \dontrun{
@@ -18,16 +39,16 @@ include_gld_purchases <- function(lmdb) {
     column_names_to_lower() |>
     # Use !! to inject the expression into filter.
     dplyr::filter(!!criteria) |>
+    # `volume` is the doses contained in the purchased package and `apk` is the
+    # number of packages purchased
+    dplyr::mutate(contained_doses = .data$volume * .data$apk) |>
     # Keep only the columns we need.
     dplyr::select(
       "pnr",
       # Change to date to work with later functions.
       date = "eksd",
       "atc",
-      "volume",
-      "apk",
-      "indo",
-      "name",
-      "vnr"
+      "contained_doses",
+      "indication_code"
     )
 }

R/include-hba1c.R

@@ -1,24 +1,37 @@
 #' Include only those with HbA1c in the required range.
 #'
 #' In the `lab_forsker` register, NPU27300 is HbA1c in the modern units (IFCC)
-#' while NPU03835 is HbA1c in old units (DCCT).
+#' while NPU03835 is HbA1c in old units (DCCT). Multiple elevated results on the
+#' same day within each individual are deduplicated, to account for the same
+#' test result often being reported twice (one for IFCC, one for DCCT units).
 #'
-#' @param data The `lab_forsker` register.
+#' The output is passed to the `exclude_pregnancy()` function for
+#' filtering of elevated results due to potential gestational diabetes (see
+#' below).
+#'
+#' @param lab_forsker The `lab_forsker` register.
 #'
 #' @return An object of the same input type, default as a [tibble::tibble()],
-#'   with two columns: `pnr` and `included_hba1c`.
+#'   with three columns:
+#'
+#'   - `pnr`: Personal identification variable.
+#'   - `dates`: The dates of all elevated HbA1c test results.
+#'   - `included_hba1c`: A logical variable indicating that the HbA1c test
+#'   was included. Used as an indicator and reminder in other internal
+#'   functions.
+#'
 #' @keywords internal
 #'
 #' @examples
 #' \dontrun{
 #' register_data$lab_forsker |> include_hba1c()
 #' }
-include_hba1c <- function(data) {
-  verify_required_variables(data, "lab_forsker")
+include_hba1c <- function(lab_forsker) {
+  verify_required_variables(lab_forsker, "lab_forsker")
   criteria <- get_algorithm_logic("hba1c") |>
     # To convert the string into an R expression.
     rlang::parse_expr()
-  data |>
+  lab_forsker |>
     column_names_to_lower() |>
     # Use !! to inject the expression into filter.
     dplyr::filter(!!criteria) |>

R/osdc-package.R

@@ -29,7 +29,12 @@ utils::globalVariables(".data")
 #' Is a [tibble::tibble()] with two columns:
 #'
 #' \describe{
+#'  \item{register}{Optional. The register used for this criteria.}
 #'  \item{name}{The inclusion or exclusion criteria name.}
+#'  \item{title}{The title to use when displaying the algorithmic logic in tables.}
 #'  \item{logic}{The logic for the criteria.}
+#'  \item{comments}{Some additional comments on the criteria.}
 #' }
+#' @seealso See the `vignette("alogrithm")` and [algorithm] for the logic used
+#'   to filter these patients.
 "algorithm"

data-raw/algorithm.csv

@@ -1,4 +1,6 @@
-name,logic
-hba1c,(analysiscode == 'NPU27300' AND value >= 48) OR (analysiscode == 'NPU03835' AND value >= 6.5)
-gld,atc =~ '^A10'
-
+register,name,title,logic,comments
+lab_forsker,hba1c,HbA1c inclusion,(analysiscode == 'NPU27300' AND value >= 48) OR (analysiscode == 'NPU03835' AND value >= 6.5),Is the IFCC units for NPU27300 and DCCT units for NPU03835
+lmdb,gld,Glucose-lowering drug inclusion,atc =~ '^A10' & !(atc =~ '^(A10BJ|A10BK01|A10BK03)'),Do not keep GLP-RAs or dapagliflozin/empagliflozin drugs
+lpr_diag,lpr2,LPR2 diabetes diagnoses codes,c_diag =~ '^(DO0[0-6]|DO8[0-4]|DZ3[37]|DE1[0-4]|249|250)' AND (c_diagtype == 'A' OR c_diagtype == 'B'),'A' c_diagtype means primary diagnosis.
+lpr_diag,lpr2_is_t1d,LPR2 diagnoses codes for T1D,c_diag =~ '^(DE10|249)',
+lpr_diag,lpr2_is_t2d,LPR2 diagnoses codes for T2D,c_diag =~ '^(DE11|250)',

vignettes/algorithm.Rmd

@@ -0,0 +1,88 @@
+---
+title: "Algorithm"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Algorithm}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(osdc)
+library(tidyverse)
+```
+
+## `lpr_diag`
+
+```{r, echo=FALSE}
+algorithm |>
+  filter(str_detect(register, "lpr_diag") |>
+  knitr::kable()
+```
+
+## `lpr_adm`
+
+-   `c_spec` (hospital department) categorize as "endocrinology" if it
+    equals 8 or as "other medical" if it is \< 8 or equals either 9 to
+    30. 
+
+## `diagnoser`
+
+-   `diagnosekode` starts with "DO0[0-6]", "DO8[0-4]", "DZ3[37]" or
+    "DE1[0-4]".
+    -   Is T1D if `diagnosekode` starts with "DE10".
+    -   Is T2D if `diagnosekode` starts with "DE11".
+-   `diagnosetype` is equal to either "A" or "B".
+    -   Is a primary diagnosis if it equals "A".
+-   `senere_afkraeftet` (if the diagnosis was later retracted) is equal
+    to "Nej".
+
+## `kontakter`
+
+-   `hovedspeciale_ans` (hospital department) is categorized as
+    "endocrinology" if it equals "medicinsk endokrinologi" or as "other
+    medical" if it equals any of "Blandet medicin og kirurgi", "Intern
+    medicin", "Geriatri", "Hepatologi", "Hæmatologi",
+    "Infektionsmedicin", "Kardiologi", "Medicinsk allergologi",
+    "Medicinsk gastroenterologi", "Medicinsk lungesygdomme",
+    "Nefrologi", "Reumatologi", "Palliativ medicin", "Akut medicin",
+    "Dermato-venerologi", "Neurologi", "Onkologi", "Fysiurgi", or
+    "Tropemedicin".
+
+## `lab_forsker`
+
+```{r, echo=FALSE}
+algorithm |>
+  filter(name == "hba1c") |>
+  knitr::kable()
+```
+
+## `ssyi` and `sssy`
+
+-   `speciale` starts with "54".
+    -   Alternatively, use `spec2` if available.
+-   `barnmark` (services provided to a child of the individual) is not
+    equal to 0.
+
+## `lmdb`
+
+```{r, echo=FALSE}
+algorithm |>
+  filter(name == "gld") |>
+  knitr::kable()
+```
+
+## `bef` and only GLD (via `lmdb`)
+
+To remove those with potential polycystic ovary syndrome:
+
+-   `atc` starts with "A10BA02" and `koen` is equal to 2 (woman) and
+    (`date` minus `foed_dato` (birth date) is less than 40 or
+    `indication_code` equals one of "0000092", "0000276" or "0000781")