docs: ✨ Initial draft of functions to extract osdc population

vignettes/functionality-flow.Rmd

@@ -0,0 +1,188 @@
+---
+title: "Functionality Flow"
+output: rmarkdown::html_vignette
+bibliography: references.bib
+csl: vancouver.csl
+vignette: >
+  %\VignetteIndexEntry{Functionality Flow}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+library(dplyr)
+```
+
+## Overview
+
+The OSDC algorithm - and thereby, the `osdc` package - contains two main
+components:
+
+- [Extracting the diabetes population](#extracting-diabetes-population)
+- [Classifying the diabetes type (type 1 and type2)](#classifying-diabetes-type)
+
+In the following sections, we will go through each of these components
+and the functions they contain.
+
+## Extracting the diabetes population {#extracting-diabetes-population}
+
+This component extracts the diabetes population based on the following
+five data sources (Danish names in parantheses):
+
+- The Register of Laboratory Results for Research, *RLRR*
+  (Laboratoriedatabasens Forskertabel)
+- The Danish National Patient Registry, *DNPR* (Landspatient
+  Registeret, *LPR*)
+- (Lægemiddelsdatabasen)
+- (CPR-registerets befolkningstabel, *BEF*)
+- The Health Service Register (Sygesikringsregisteret)
+
+<!-- TODO: Add English translations for Lægemiddelsdatabasen and BEF -->
+
+This component will have one user-facing function:
+`extract_diabetes_population`. This function takes the data sources and
+an `index_date` (i.e., the day of the wanted classification) as
+arguments.
+
+As described in `vignette("design")`, inclusion date is the date of the
+second inclusion criteria. Inclusion events include:
+
+<!-- TODO: Add hyperlink to vignette(design) -->
+
+- HbA1c measurements of ≥48 mmol/mol
+- Hospital diagnoses of diabetes
+- Diabetes-specific services received at podiatrists
+- Purchase of glucose-lowering drugs (GLD)
+
+Note that HbA1c tests and GLD purchases during pregnancies are excluded,
+as are glucose-lowering brand drugs for weight loss and metformin
+purchases for women below age 40. See section \[Exclusion: HbA1c tests
+and GLD purchases during estimated pregnancy
+windows\](#exclusion-pregnancy-windows) for how pregnancy windows are
+estimated.
+
+This results in the functionality flow for extracting the diabetes
+population seen below. All functions take a `data.frame` as input and
+outputs a `data.frame`.
+
+![Flow of functions for extracting a diabetes population using the osdc
+package. The dark grey box denotes the user-facing function, while the
+remaining boxes are internal functions. Green and red boxes represent
+filtering functions (inclusion and exclusion events,
+respectively).](images/diabetes-population-functions.png)
+
+<!-- Q: How are we feeling about the colours? All internal functions could also just be light grey -->
+
+<!-- Q: Generally, Do we want to include arguments in inclusion and exclusion functions so a (technically inclined) user will be able to alter the algorithm for their needs? E.g., age could be an argument in `exclude_potential_pcos` -->
+
+### Inclusion event: HbA1c tests above 48 mmol/mol
+
+The function `include_hba1c_tests_over_48_mmol_per_mol` uses RLRR as
+data source to extract all events of tests above 48 mmol/mol before the
+index date.
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+<!-- TODO: Is it really *all* or is there a time window before the index date we're extracting from? -->
+
+### Inclusion event: Hospital diagnosis of diabetes
+
+The function `include_diabetes_diagnoses` uses the hospital contacts
+from DNPR to include all dates of diabetes diagnoses before the index
+date. Diabetes diagnoses from both ICD 8 and ICD 10 are included.
+
+This function contains two helper functions:
+
+- `extract_diabetes_diagnoses_icd_10`
+- `extract_diabetes_diagnoses_icd_8`
+
+<!-- TODO: Add details on how this filtering should be done, e.g., diagnosis codes -->
+
+<!-- TODO: Which specific ICD 8 and 10 codes are included? -->
+
+<!-- TODO: Is it really *all* or is there a time window before the index date we're extracting from? -->
+
+### Inclusion event: Diabetes-specific podiatrist services
+
+The function `include_diabetes_specific_podiatrist_services` uses the
+Health Service Register to extract the dates of all diabetes-specific
+podiatrist services before the index date.
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+<!-- TODO: Is it really *all* or is there a time window before the index date we're extracting from? -->
+
+### Inclusion event: GLD purchases
+
+The function `include_gld_purchases` uses Lægemiddelsdatabasen to
+extract the dates of all GLD purchases before the index date.
+
+<!-- TODO: Add English translation of data source -->
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+<!-- TODO: Is it really *all* or is there a time window before the index date we're extracting from? -->
+
+### Exclusion: HbA1c tests and GLD purchases during estimated pregnancy windows {#exclusion-pregnancy-windows}
+
+The function `exclude_events_during_pregnancy_windows` uses diagnoses
+from DNPR as a data source and is used to exclude both HbA1c tests and
+GLD purchases during estimated pregnancy windows.
+
+Under the hood, this relies on the function
+`extract_pregnancy_index_dates` and contains the following three helper
+functions:
+
+- `calculate_pregnancy_index_date_for_mc_visits_wo_end_date` (this
+  might be removed with the inclusion of )
+- `extract_pregnancy_end_dates`
+- `extract_maternal_care_visit_dates_without_end_date`
+
+`calculate_pregnancy_index_date_for_mc_visits_wo_end_date` might be
+removed with the inclusion of the birth register.
+
+`extract_pregnancy_end_dates` extracts maternal care visits with an end
+date and exclude visits between 40 weeks before end date to 12 weeks
+after end date.
+
+`extract_maternal_care_visit_dates_without_end_date` uses the output
+from `extract_pregnancy_end_dates` which identifies maternal care visits
+*with* end dates to derive maternal care visits *without* end dates.
+below.
+<!-- TOOD: What is done with the mc visits without end dates then? -->
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### Exclusion: Glucose-lowering brand drugs for weight loss
+
+The function `exclude_weight_loss_drugs` uses \*\* as a data source and
+excludes **which brands**?
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### Exclusion: Metformin purchases for women below age 40
+
+The function `exclude_potential_pcos` uses BEF to exclude all purchases
+of metformin by women below age 40 (i.e., <= 39 years old) at the date of
+purchase.
+
+This function contains two helper functions:
+
+- `exclude_women`
+- `exclude_age_40_or_younger`
+
+<!-- TODO: Add English translation of BEF -->
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### Extract diagnosis classification date
+
+Finally, the inclusion events from each inclusion criteria are joined in
+the function `extract_classification_dates`. For each individual with
+inclusion events, the date of the *second* event is extracted as the
+classification date, i.e., the date the OSDC algorithm defines as the
+diagnosis date.

vignettes/images/diabetes-population-functions.puml

@@ -0,0 +1,25 @@
+@startuml diabetes-population-functions 
+
+#darkgrey: Extract_diabetes_population;
+
+switch (Extract dates of inclusion events)
+case ( HbA1c tests)
+    #lightgreen:include_hba1c_tests_over_48_mmol_per_mol;
+    #pink:exclude_events_during_pregnancy_windows;
+
+case ( Hospital diabetes\n diagnosis)
+    #lightgreen:include_diabetes_diagnoses;
+
+case ( Diabetes-specific\n podiatrist services)
+    #lightgreen:include_diabetes_specific_podiatrist_services;
+
+case ( GLD purchases)
+    #lightgreen:include_gld_purchases;
+    #pink:exclude_events_during_pregnancy_windows;
+    #pink:exclude_potential_pcos;
+    #pink:exclude_purchases_of_weight_loss_drugs;
+endswitch
+
+:extract_classification_dates;
+
+@enduml