docs: ✨ initial draft of functions to classify diabetes type

vignettes/functionality-flow.Rmd

@@ -183,3 +183,130 @@ Finally, from the raw inclusion dates, a stable inclusion date column is
 added. The column censors inclusion dates from time-periods of
 insufficient data coverage. For details on this, see the [Description of
 algorithm contents & logic](algorithm_logic.Rmd) vignette.
+
+## Classifying the diabetes type {#classifying-diabetes-type}
+
+The second component of the OSDC algorithm classifies individuals from
+the extracted diabetes population as having either T1D or T2D. The
+output of this component is a `data.frame` that includes one row per
+individual in the diabetes population: one column with their PNR, two
+columns with inclusion dates (one "stable" date and one "raw" date - see
+the [Description of algorithm contents & logic](algorithm_logic.Rmd)
+vignette for an elaboration on what that entails), and one column with
+the diabetes type.
+
+<!-- TODO: Make sure this is the correct link - and add a link specific to the specific section where this is described -->
+
+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 two
+filters. To be classified as having type 1 diabetes, individuals must
+have:
+
+1.  At least one T1D primary diagnosis and only purchased insulins
+    (i.e., no purchases of any other type of GLDs), or
+2.  A majority of T1D primary diagnoses, purchased insulin within 180
+    days of diagnosis, and 2/3 of GLD doses are insulin.
+
+Functions for the above filters 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)
+
+#### Filter 1: Any T1D diagnoses and all GLD purchases are insulins
+
+The first filter includes two criteria: 1) Whether individuals have any
+T1D diagnoses and 2) whether all GLD purchases are insulin.
+
+Thus, this filter contains two functions:
+
+1.  `t1d_include_at_least_one_t1d_primary_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  -->
+
+#### Filter 2: Majority of T1D primary diagnoses, insulin within 180 days of diagnosis, and insulin constitutes 2/3 of all GLD doses
+
+The second filter includes three criteria: 1) Whether individuals have a
+majority of T1D primary 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_t1d_primary_diagnoses` (as compared to T2D
+    diagnoses) which again relies on primary 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 the following hierarchy in first function,
+`t1d_include_majority_of_t1d_primary_diagnoses`: First, the function
+checks whether the individual has primary diagnoses from
+endocrinological specialty. If yes, the check of whether they have a
+majority of T1D primary diagnoses are based on data from
+endocrinological specialty. If no, the check will be based on primary
+diagnoses from medical specialties.
+
+### 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` which includes four columns:
+
+1.  **PNR**: The pseudonymised social security number of individuals in
+    the diabetes population (one row per individual)
+2.  **stable_inclusion_date**: The *stable* inclusion date (i.e., the
+    raw date mutated so only individuals included in the time-period
+    where data coverage is sufficient to make incident cases reliable)\*
+    <!-- TODO: Specify this time-period: e.g., later than 1997 -->
+3.  **raw_inclusion_date**: The *raw* inclusion date (i.e., the date of
+    the second inclusion event as described in the [Extracting the
+    diabetes population](#extracting-diabetes-population) section above)
+4.  **diabetes_type** The classified diabetes type
+
+\*For more information on the "raw" versus "stable" inclusion date, see
+the [Description of algorithm contents & logic](algorithm_logic.Rmd)
+vignette.
+
+<!-- TODO: Make sure this is the correct link - and add a link specific to the specific section where this is described -->
+
+For an example, see below.
+
+| PNR        | stable_inclusion_date | raw_inclusion_date | diabetes_type |
+|------------|-----------------------|--------------------|---------------|
+| 0000000001 | 01-01-2020            | 01-01-2020         | T1D           |
+| 0000000004 | NULL                  | 19-04-1995         | T2D           |
+
+: Example rows of the `data.frame` output of the `osdc` package.
+
+The individuals `0000000001` and `0000000004` have been classified as
+having diabetes (`T1D` and `T2D`, respectively). `0000000004` is
+classified as having type 1 diabetes (T1D) with an inclusion date of
+`01-01-2020`. Since this date is within a time-period of sufficient data
+coverage, the column `stable_inclusion_date` is populated with the same
+date as `raw_inclusion_date`.
+
+The individual in the second row, `0000000004` is classified as having
+type 2 diabetes `T2D` with an inclusion date of `19-04-1995`. Since 1995
+is within a time-period of insufficient data coverage,
+`stable_inclusion_date` is `NULL`. However, `raw_inclusion_date` still
+contains the inclusion date of this individual.
+
+<!-- TODO: Specify the "stable" time-period: e.g., later than 1997 -->
+

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 (**Criteria 1**\nt1d_include_at_least_one_t1d_primary_diagnosis\n AND\nt1d_include_only_purchased_insulins) then (no)
+  if (**Criteria 2**\nt1d_include_majority_of_t1d_primary_diagnoses\nAND\nt1d_include_insulin_purchase_within_180_days_of_diagnosis\nAND\nt1d_include_two_thirds_of_purchased_gld_doses_are_insulin) then (no)
+    :Type 2;
+    detach
+  else (\nyes)
+  endif
+else (\nyes)
+endif
+:Type 1;
+detach
+
+@enduml