docs: ✨ initial draft of functions to classify diabetes type

vignettes/functionality-flow.Rmd

@@ -178,3 +178,82 @@ 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.
+
+## Classifying the diabetes type {#classifying-diabetes-type}
+
+The second component of the OSDC algorithm classifies individuals from
+the extracted diabetes population as having either type 1 or type 2
+diabetes. The output of this component is a `data.frame` that includes
+the diabetes type as well as the classification date (i.e., the date
+of the second instance of the inclusion criteria described in the
+sections above).
+
+This component will also have one user-facing function:
+`classify_diabetes_type`. This function takes the output of
+`extract_diabetes_population` as input.
+
+### Type 1 classification
+
+The classification of type 1 diabetes relies on the following criteria.
+To be classified as having type 1 diabetes, individuals must have:
+
+1. At least one T1D diagnosis and only purchased insulins (i.e., no
+    purchases of any other type of GLDs).
+2. A majority of T1D diagnoses, purchased insulin within 180 days of
+    diagnosis, and 2/3 of GLD doses are insulin.
+
+Functions for the above criteria are described in the following
+sections.
+
+![Flow of functions for classifying the diabetes type using the `osdc`
+package. The dark grey box denotes the user-facing function, while the
+remaining boxes are internal
+functions.](images/classify-diabetes-type-functions.png)
+
+#### Criteria 1: Any T1D diagnoses and all GLD purchases are insulins
+
+The first criteria includes two parts: 1) Whether individuals have any
+T1D diagnoses and 2) whether all GLD purchases are insulin.
+
+Thus, this criteria contains two functions:
+
+1. `t1d_include_at_least_one_t1d_diagnosis`, which relies on the
+    hospital diagnoses from DNPR extracted in component 1.
+2. `t1d_include_only_purchased_insulins` which relies on the GLD
+    purchases from Lægemiddelsdatabasen.
+
+<!-- TODO: Add English translations for Lægemiddelsdatabasen  -->
+
+#### Criteria 2: Majority of T1D diagnoses, insulin within 180 days of diagnosis and insulin constitutes 2/3 of all GLD doses
+
+The second criteria is three-fold: 1) Whether individuals have a
+majority of T1D diagnoses, 2) whether they purchased insulin within 180
+days of diagnosis, and 3) whether insulin constitutes 2/3 of all their
+GLD doses.
+
+This results in three functions:
+
+1. `t1d_include_majority_of_diagnoses_is_t1d()` (as compared to T2D
+    diagnoses) which again relies on hospital diagnoses from DNPR.
+2. `t1d_include_insulin_purchase_within_180_days_of_diagnosis` which
+    relies on both diagnosis from DNPR and GLD purchases from
+    Lægemiddelsdatabasen.
+3. `t1d_include_two_thirds_of_purchased_gld_doses_are_insulin` which
+    relies on the GLD purchases from Lægemiddelsdatabasen.
+
+Note that in the first function, individuals must have a majority of T1D
+diagnoses from endocrinological departments (or from other medical
+departments, in the absence of contacts to endocrinological
+departments).
+
+### Type 2 classification
+
+As described in the [design](design.Rmd) vignette, individuals not
+classified as type 1 cases are classified as type 2 cases.
+
+## Output
+
+The output of the second component, and therefore, the OSDC algorithm is
+a `data.frame` including a background population and a diabetes
+population. For the diabetes population, both the classification (type 1
+or type 2) and the classification date is included.

vignettes/images/classify-diabetes-type-functions.puml

@@ -0,0 +1,18 @@
+@startuml classify-diabetes-type-functions
+
+skinparam defaultTextAlignment center
+
+#darkgrey: Classify_diabetes_type;
+!pragma useVerticalIf on
+if (**Filter 1**\nt1d_include_at_least_one_t1d_diagnosis\nt1d_include_only_purchased_insulins) then (no)
+  :Type 2;
+  detach
+elseif (**Filter 2**\nt1d_include_majority_of_diagnoses_is_t1d\nt1d_include_insulin_purchase_within_180_days_of_diagnosis\nt1d_include_two_thirds_of_purchased_gld_doses_are_insulin) then (no)
+  :Type 2;
+  detach
+else (\nyes)
+endif
+:Type 1;
+detach
+
+@enduml