docs: ✨ Initial draft of functions to extract osdc population

.vscode/settings.json

@@ -23,8 +23,9 @@
   "r.session.levelOfObjectDetail": "Detailed",
   "r.session.data.rowLimit": 1000,
   "r.plot.useHttpgd": true,
-  "[r]": {
-    "editor.defaultFormatter": "REditorSupport.r"
+  "[r,quarto]": {
+    "editor.defaultFormatter": "REditorSupport.r",
+    "editor.tabSize": 2,
   },
   "cSpell.language": "en-GB",
   "cSpell.words": [

justfile

@@ -3,8 +3,8 @@
 
 # Generate PNG images from all PlantUML files
 generate-puml-all:
-  docker run --rm -v $(pwd):/puml -w /puml ghcr.io/plantuml/plantuml:latest -tpng "**/*.puml"
+  docker run --rm -v $(pwd):/puml -w /puml ghcr.io/plantuml/plantuml:1.2024.3 -tpng "**/*.puml"
 
 # Generate PNG image from specific PlantUML file
 generate-puml name:
-  docker run --rm -v  $(pwd):/puml -w /puml ghcr.io/plantuml/plantuml:latest -tpng "**/{{name}}.puml"
+  docker run --rm -v  $(pwd):/puml -w /puml ghcr.io/plantuml/plantuml:1.2024.3 -tpng "**/{{name}}.puml"

vignettes/function-flow.Rmd

@@ -0,0 +1,161 @@
+---
+title: "Function Flow"
+output: rmarkdown::html_vignette
+bibliography: references.bib
+csl: vancouver.csl
+vignette: >
+  %\VignetteIndexEntry{Function Flow}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Function conventions
+
+The below conventions are *ideals* only, to be used as a guidelines to
+help with development and understanding of the code. They are not hard
+rules.
+
+### Naming
+
+-   First word is an action verb, later words are objects or conditions.
+-   Exclusion criteria are prefixed with `exclude_`.
+-   Inclusion criteria are prefixed with `include_`.
+-   Helpers that get or extract a condition ("pregnancy" or "date of
+    visit") are prefixed with `get_`.
+-   Helpers that drop or keep a specific condition are prefixed with
+    `drop_` or `keep_` ("first visit date to maternal care for pregnancy
+    after 40 weeks"). These types of helpers likely are contained in the
+    `get_` functions.
+
+### Input and output
+
+-   Few arguments, with one or two core required argument.
+-   `include_` functions take a register as the first argument.
+    -   One input register database at a time.
+-   `exclude_` functions can take a register as the first argument or
+    take the output from an `include_` function.
+-   Second argument can be an output data from another function.
+
+## Function flow
+
+The OSDC algorithm - and thereby, the `osdc` package - contains one main
+function that will classify individuals into those with either type 1 or
+type 2 diabetes using the Danish registers: `classify_diabetes()`. This
+function classifies those with diabetes (type 1 or 2) based on the
+Danish registers described in the `vignette("design")`. All data sources
+are used as input for this function. The specific inclusion and
+exclusion details are also described in the `vignette("design")`.
+
+This results in the functionality flow for classifying diabetes status
+seen below. All functions take a `data.frame` type object as input and
+outputs the same type of object as the input object (a `data.frame`
+type). For instance, if the input is a `data.table` object, the output
+will also be a `data.table`.
+
+![Flow of functions, as well as their required input registers, for
+classifying diabetes status using the `osdc` package. Light blue and
+orange boxes represent filtering functions (inclusion and exclusion
+events, respectively).](images/diabetes-population-functions.png)
+
+## Inclusion events
+
+### HbA1c tests above 48 mmol/mol
+
+The function `include_hba1c()` uses `lab_forsker` as the input data to
+extract all events of tests above 48 mmol/mol.
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### Hospital diagnosis of diabetes
+
+The function `include_diabetes_diagnoses()` uses the hospital contacts
+from LPR2 and 3 to include all dates of diabetes diagnoses. Diabetes
+diagnoses from both ICD 8 and ICD 10 are included.
+
+This function contains two helper functions:
+
+-   `keep_diabetes_icd10()`
+-   `keep_diabetes_icd8()`
+
+<!-- TODO: Add details on how this filtering should be done, e.g., diagnosis codes -->
+
+<!-- TODO: Which specific ICD 8 and 10 codes are included? -->
+
+### Diabetes-specific podiatrist services
+
+The function `include_podiatrist_services()` uses `sysi` or `sssy` as
+input to extract the dates of all diabetes-specific podiatrist services.
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### GLD purchases
+
+The function `include_gld_purchases()` uses `lmdb` to extract the dates
+of all GLD purchases (from 1997 onwards).
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+<!-- TODO: Add this + link to resource "For details about this, see [link]." -->
+
+## Exclusion events
+
+### HbA1c tests and GLD purchases during pregnancy
+
+The function `exclude_pregnancy()` uses diagnoses from LPR2 or LPR3 as
+input and is used to exclude both HbA1c tests and GLD purchases during
+pregnancy.
+
+Internally, this relies on the function `get_pregnancy_dates()` that
+contains the following three helper functions:
+
+-   `calculate_pregnancy_index_date_for_mc_visits_wo_end_date()` (this
+    might be removed with the inclusion of the birth register)
+-   `get_pregnancy_end_dates()`: Keep maternal care visits with an end
+    date and drop visits between 40 weeks before end date and 12 weeks
+    after end date.
+-   `get_maternal_care_visit_dates_without_end_date()`: Uses the output
+    from `get_pregnancy_end_dates()` which identifies maternal care
+    visits *with* end dates to derive maternal care visits *without* end
+    dates. below.
+
+<!-- TODO: What is done with the mc visits without end dates then? -->
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+### Glucose-lowering brand drugs for weight loss
+
+The function `exclude_purchases_weight_loss_drugs()` uses REGISTER as
+input and excludes BRANDS.
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+<!-- TODO: Add data source and which brands are excluded -->
+
+### Metformin purchases for women below age 40
+
+The function `exclude_pcos()` as input 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:
+
+-   `keep_women()`
+-   `drop_age_40_below()`
+
+<!-- TODO: Add details on how this filtering should be done -->
+
+## Get initial diagnosis date
+
+Then, the first inclusion and exclusion events from the function outputs
+are dropped with `drop_first_event()` so that only those with two or
+more events are kepts. This is then used to assign an initial diagnosis
+date with `get_initial_diagnosis_date()`. Then all the outputs are
+joined together at the end.
+
+## Drop diagnosis dates outside of coverage
+
+Finally, from the raw initial diagnosis dates, those dates outside of
+the data coverage period are dropped to end with a final diagnosis date
+using `get_final_diagnosis_date()`. For details on this censoring based
+on the periods with insufficient data coverage, see the
+`vignette("algorithm-logic")`.

vignettes/images/function-flow.puml

@@ -0,0 +1,87 @@
+@startuml function-flow
+!theme cerulean-outline
+<style>
+action {
+    FontColor black
+}
+database {
+    FontColor black
+}
+.inclusion {
+    BackgroundColor lightblue
+}
+.exclusion {
+    BackgroundColor orange
+}
+</style>
+
+hide <<inclusion>> stereotype
+hide <<exclusion>> stereotype
+
+card classify_diabetes() as cd {
+    together {
+        database sssy
+        database sysi
+        database lpr_diag
+        database lpr_adm
+        database lmdb
+        database lab_forsker
+        database kontakter
+        database diagnoser
+        database bef
+    }
+
+    action "get_pregnancy_dates()" as pregnancy
+    action "get_pcos()" as pcos
+    action "get_initial_diagnosis_date()" as first_date
+    action "get_final_diagnosis_date()" as final_date
+    action "join()" as join
+
+    together {
+        action "exclude_pregnancy()" as ex_pregnancy <<exclusion>>
+        action "exclude_purchases_weight_loss_drugs()" as ex_wld <<exclusion>>
+        action "exclude_pcos()" as ex_pcos <<exclusion>>
+    }
+
+    together {
+        action "include_hba1c()" as in_hba1c <<inclusion>>
+        action "include_diabetes_diagnosis()" as in_diagnosis <<inclusion>>
+        action "include_podiatrist_services()" as in_podiatrist <<inclusion>>
+        action "include_purchases_gld()" as in_gld <<inclusion>>
+    }
+
+    lab_forsker --> in_hba1c
+    in_hba1c --> ex_pregnancy
+
+    lpr_diag --> pregnancy
+    lpr_adm --> pregnancy
+    kontakter --> pregnancy
+    diagnoser --> pregnancy
+    pregnancy -> ex_pregnancy
+
+    lpr_diag --> in_diagnosis
+    lpr_adm --> in_diagnosis
+    kontakter --> in_diagnosis
+    diagnoser --> in_diagnosis
+
+    sssy --> in_podiatrist
+    sysi --> in_podiatrist
+
+    lmdb --> in_gld
+    in_gld --> ex_pregnancy
+    in_gld --> ex_wld
+
+    bef --> pcos
+    in_gld --> ex_pcos
+    pcos --> ex_pcos
+
+    ex_wld --> first_date
+    ex_pregnancy --> first_date
+    ex_pcos --> first_date
+    in_podiatrist --> first_date
+    in_diagnosis --> first_date
+
+    first_date -> join
+    join -> final_date
+}
+@enduml