docs: Required variables in design docs

vignettes/design.Rmd

@@ -1,8 +1,10 @@
 ---
 title: "Design"
 output: rmarkdown::html_vignette
+bibliography: references.bib
+csl: vancouver.csl
 vignette: >
-  %\VignetteIndexEntry{design}
+  %\VignetteIndexEntry{Design}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -12,6 +14,7 @@ knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>"
 )
+library(dplyr)
 ```
 
 ## Principles
@@ -27,6 +30,9 @@ These are the guiding principles for this package:
     is a data frame, the output is a data frame).
 4.  Functions have consistent naming based on their action.
 5.  Functions have limited additional arguments.
+6.  Casing of input variables (upper or lower case) is agnostic, all
+    internal variables are lower case, and output variables are lower
+    case.
 
 ## Use cases
 
@@ -72,3 +78,90 @@ This is the list of functionality we aim to have in the osdc package
 5.  Provide a common and easily accessible standard for determining
     diabetes status within the context of research using Danish
     registers.
+
+## Classifier algorithm
+
+A more complete description of the classifier is found in Anders Aasted
+Isaksen's [PhD Thesis](https://aastedet.github.io/dissertation/) as well
+as the validation paper [@Isaksen2023]. The description below is a brief
+and concise version of those documents.
+
+The algorithm for classifying individuals with diabetes is described
+below. The overall output of this algorithm is first to classify those
+with diabetes, then to further classify and check if the individuals
+might have type 1 diabetes, otherwise classify as type 2 diabetes.
+
+Initial **diabetes** classification is defined as the second occurrence
+of any of the listed inclusion events. Wherever possible, all available
+data for each event is used, except for the purchases of
+glucose-lowering drugs, since data is only available from 1997 onwards.
+Inclusion criteria are:
+
+1.  HbA1c measurement of ≥48 mmol/mol.
+2.  Hospital diagnosis of diabetes.
+3.  Diabetes-specific services received at podiatrist.
+4.  Purchase of glucose-lowering drugs.
+
+Exclusions are:
+
+1.  HbA1c:
+    -   Taken during pregnancies, as that could be a potential
+        gestational diabetes mellitus.
+2.  Drugs:
+    -   Brand drugs for weight loss, e.g. *Saxenda.*.
+    -   Purchases during pregnancies, as that is a potential treatment
+        for gestational diabetes mellitus.
+    -   Metformin for women below age 40, as that could be a treatment
+        for polycystic ovary syndrome.
+
+### Classifying type 2 diabetes
+
+The inclusion criteria after being classified with non-specific diabetes
+are any of:
+
+-   Any purchases of non-insulin glucose-lowering drugs.
+-   A hospital diagnosis of type 2 diabetes as the most recent
+    type-specific diabetes diagnosis.
+
+The exclusion criteria are:
+
+-   Women that have purchased only metformin and have any diagnoses of
+    polycystic ovarian syndrome or have purchases of clomifene or
+    combination drugs containing antiandrogens and oestrogens.
+-   Only one recorded inclusion event.
+-   No recorded inclusion events in the last 10 years prior to the most
+    recent date available for the individual (index date).
+
+### Classifying type 1 diabetes
+
+The inclusion criteria after being classified with non-specific diabetes
+are any of:
+
+-   Any purchases of insulin drugs.
+-   A hospital diagnosis of type 1 diabetes as the most recent
+    type-specific diabetes diagnosis.
+
+The exclusion criteria are:
+
+-   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.
+
+## Data required from registers
+
+The following is a list of the variables required from specific
+registers in order for the package to classify diabetes status:
+
+```{r, echo=FALSE}
+variable_description |> 
+  mutate(Register = paste0(register_name, "(", register_abbrev, ")")) |> 
+  select(Register, Variable = variable_name) |> 
+  knitr::kable()
+```
+
+## References

vignettes/references.bib

@@ -0,0 +1,14 @@
+@Article{Isaksen2023,
+  author    = {Isaksen, Anders Aasted and Sandbæk, Annelli and Bjerg, Lasse},
+  journal   = {Clinical Epidemiology},
+  title     = {Validation of Register-Based Diabetes Classifiers in Danish Data},
+  year      = {2023},
+  issn      = {1179-1349},
+  month     = may,
+  pages     = {569--581},
+  volume    = {Volume 15},
+  doi       = {10.2147/clep.s407019},
+  publisher = {Informa UK Limited},
+}
+
+@Comment{jabref-meta: databaseType:bibtex;}