Docs/general functionality flow

vignettes/functionality-flow.Rmd

@@ -0,0 +1,50 @@
+---
+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
+- Classifying the diabetes type (type 1 and type 2)
+
+## Extracting the diabetes population 
+
+This component extracts the diabetes population based on the following four data sources:
+
+- 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` which takes an `index_date` and the data sources as arguments.
+
+As described in  `vignette("design")`, inclusion date is the date of the second inclusion criteria. Inclusion events include HbA1c measurements of ≥48 mmol/mol, hospital diagnoses of diabetes, diabetes-specific services received at podiatrist, and purchase of glucose-lowering drugs (GLD), while HbA1c samples and GLD purchases during pregnancies* are excluded, as are glucose-lowering brand drugs for weight loss and metformin purchases for women below age 40.
+
+This results in the following functionality flow:
+
+![Functions for extracting the diabetes population using the osdc package](images/diabetes-population-functions.png)
+
+Note: All functions take a `data.frame` as input and outputs a `data.frame`.
+

vignettes/images/diabetes-population-functions.puml

@@ -0,0 +1,28 @@
+@startuml diabetes-population-functions 
+
+title Functions for extracting a diabetes population using OSDC
+
+#darkgrey: Extract_diabetes_population;
+
+
+switch (Extract Dates of Inclusion Events)
+case ( Dates of\n HbA1c Tests)
+    :include_dates_of_hba1c_tests_over_48_mmol_per_mol;
+    :exclude_dates_during_pregnancy_windows;
+case ( Dates of\n Diabetes Diagnosis)
+    :include_dates_of_diabetes_diagnoses (ICD 8 and 10);
+case ( Dates of\n Diabetes-Specific Podiatrist Services)
+    :include_dates_of_diabetes_specific_podiatrist_services;
+case ( Dates of\n GLD Purchases)
+    :include_dates_of_gld_purchases;
+    :exclude_dates_during_pregnancy_windows;
+    :exclude_dates_of_potential_pcos;
+    :exclude_dates_of_weight_loss_drug_purchases;
+endswitch
+
+:join_inclusion_events;
+:extract_classification_dates;
+
+center footer \nDark grey box: User-facing functions; Light grey boxes: Internal functions;
+
+@enduml

vignettes/images/functions-exclusion-pregnancy-window.puml

@@ -0,0 +1,21 @@
+@startuml functions-exclusion-pregnancy-window
+
+title Exclusion: Pregnancy Window\nData Source: DNPR\n\nTo be used to filter both gld and hbA1c inclusion events
+
+start
+-> Exclude Event During Pregnancy\nData Source: DNPR;
+#darkgrey:**exclude_events_during_pregnancy_windows(data: data.table) -> data.table**;
+:**extract_pregnancy_index_dates(data: data.table) -> data.table**
+- This function will extract pregnancy index dates using diagnoses (ICD 8 and 10?) from DNPR; 
+
+:**Helper function: extract_pregnancy_end_dates(data: data.table) -> data.table**
+- This might be removed with the inclusion of birth register;
+
+:**Helper function: extract_maternal_care_visit_dates_without_end(data: data.table) -> data.table**
+- Extract mc visits with end date (visits between 40 weeks before end date to 12 weeks after end date)
+- Use these to identify mc visits without end dates to be used in the function below;
+
+:**Helper function: calculate_pregnancy_index_date_based_mc_visits_wo_end_dates(data.table) -> data.table**;
+stop
+
+@enduml

vignettes/images/functions-overall.puml

@@ -0,0 +1,104 @@
+@startuml functions-overall
+
+title Overview of Functions to Used to Create an OSDC Population
+
+#darkgrey:**Extract Diabetes Population**
+User-Facing Function: extract_diabetes_population(index_date: date, data_sources: list[data.table]) -> data.table;
+:**Inclusion Criteria**
+
+**HbA1c Tests (=>48 mmol/mol) (RLRR)**
+  - Function: include_hba1c_tests_over_threshold(
+    data: data.table, threshold: int = 48) -> data.table
+
+**Purchase of Glucose Lowering Drugs (GLDs) (Lægemiddelsdatabasen)**:
+  - Function: include_gld_purchases(data: data.table) -> data.table
+
+**Hospital Diagnosis of Diabetes (DNPR) **
+  - Function: include_diabetes_diagnoses(data: data.table) -> data.table
+      - include_diabetes_diagnoses_icd_10(data: data.table) -> data.table
+      - include_diabetes_diagnoses_icd_8(data: data.table) -> data.table
+
+**Health Services (Diabetes-specific Podiatrist Services)**
+  - Function: include_podiatrist_services(data: data.table) -> data.table
+      - placeholder helper functions;
+
+:**Exclusion Criteria**
+
+**HbA1c and GLD: Events during pregnancies (potential GDM) (DNPR)**
+    - Function: exclude_events_during_pregnancy_windows(data: data.table) -> data.table
+       - extract_pregnancy_index_dates(data: data.table) 
+          -> data.table
+        - calculate_pregnancy_index_date_for_mc_visits_wo_end_dates(
+            data.table) -> data.table
+        - extract_pregnancy_end_dates(data: data.table) -> data.table
+        - extract_maternal_care_visit_dates_without_end(
+            data: data.table) -> data.table
+
+**GLD: Metformin purchase for women below age 40 (potential PCOS)**
+    - Functions: exclude_potential_pcos(data: data.table, 
+      sex: str = "F", age: int = 40) -> data.table
+
+**Weight Loss Drugs: Purchase of brand drugs for weight loss, e.g., Saxenda.**
+'GLD only?
+    - Function: exclude_weight_loss_drugs(data: data.table) -> data.table;
+
+:**Classification Date:**
+    - Functions: 
+        - join_inclusion_events(data: list[data.table]) -> data.table
+        - extract_second_inclusion_event_date(data: data.table) -> data.table;
+
+#darkgrey:**Classify Diabetes Type**
+User-Facing Function: classify_diabetes_type(data: data.table) -> data.table;
+
+
+:**Type 2 Diabetes**
+
+**Inclusion Criteria:**
+
+**Any purchases of Non-Insulin GLDs**
+- Function: include_any_non_insulin_gld_purchases(data: data.table) -> data.table
+
+**Most recent type-specific diabetes diagnosis is hospital diagnosis of type 2 diabetes**
+- Function: include_latest_diabetes_diagnosis_is_type_2(data: data.table) -> data.table
+
+**Exclusion Criteria:**
+
+**Women that have purchased only metformin and have any diagnoses of PCOS or have**
+**purchases of clomifene or combination drugs containing antiandrogens and oestrogens**
+- Functions: 
+    - exclude_women_with_only_metformin_purchases(data: data.table) -> data.table
+    - exclude_women_with_psoc_diagnoses(data: data.table) -> data.table
+    - exclude_women_with_combination_drug_purchases(data: data.table) -> data.table
+
+**No recorded inclusion events in the last 10 years prior to the most recent date**
+**available for the individual (index date)**
+;
+
+:**Type 1 Diabetes**
+
+**Inclusion Criteria:**
+
+**Any purchases of insulin drugs.**
+
+**A hospital diagnosis of type 1 diabetes as the most recent**
+
+**type-specific diabetes diagnosis.**
+
+**Exclusion criteria:**
+
+**Women with any diagnoses of gestational diabetes mellitus, who have purchased**
+**glucose-lowering drugs only in the period from 280 days prior to their first**
+**diagnosis of gestational diabetes mellitus until 280 days after their last diagnosis.**
+
+**No purchases of glucose-lowering drugs or only one purchase and no hospital records of**
+**type 1 diabetes.**
+
+**No insulin drug purchases in the last 10 years prior to the index date.**
+;
+
+#palegreen:OSDC Population Created;
+kill
+
+'Do we want to support export? (e.g. to csv, parquet, SASS?)
+
+@enduml