---
title: "Summarising measurement use in a dataset"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{summariseMeasurementUse}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", message = FALSE, warning = FALSE,
  fig.width = 7
)

CDMConnector::requireEunomia()
```

## Introduction

In this vignette we will see how we can summarise the use of measurement concepts in our dataset as a whole. For our example we're going to be interested in measurement concepts related to respiratory function and will use the Eunomia synthetic dataset.

First we will connect to the database and create a cdm reference.

```{r, message=FALSE, warning=FALSE}
library(duckdb)
library(omopgenerics)
library(CDMConnector)
library(dplyr)
```

```{r, message=TRUE, warning=FALSE}
con <- dbConnect(duckdb(), dbdir = eunomiaDir())
cdm <- cdmFromCon(
  con = con, cdmSchem = "main", writeSchema = "main", cdmName = "Eunomia"
)
cdm
```

Now we'll create a codelist with measurement concepts.
```{r}
repiratory_function_codes <- newCodelist(list("respiratory function" = c(4052083, 4133840, 3011505)))
repiratory_function_codes
```

For a general summary of the use of these codes in our dataset we can use summariseCodeUse from the CodelistGenerator R package.

```{r}
library(CodelistGenerator)
code_use <- summariseCodeUse(repiratory_function_codes, cdm)
tableCodeUse(code_use)
```

Although we now have a general summary of the use of our measurement codes, we may well want more information on these measurements to inform study feasibility and design. 

MeasurementDiagnostics helps us to perform additional, measurement specific, diagnostic checks. For this we'll simply call the summariseMeasurementUse() function which will run a series of checks. 
```{r}
library(MeasurementDiagnostics)

repiratory_function_measurements <- summariseMeasurementUse(cdm, repiratory_function_codes)
```

As with similar packages, our results are returned in the summarised_result format as defined by the omopgenerics package.
```{r}
repiratory_function_measurements |> 
  glimpse()
```

We can see each of the checks performed.
```{r}
settings(repiratory_function_measurements) |> 
  pull("result_type") |> 
  unique()
```

One of the checks summarises the numeric values associated with tests. We can quickly create a table summarising these results.
```{r}
tableMeasurementValueAsNumeric(repiratory_function_measurements)
```

Similarly, we can see a summary of concept values associated with measurements. We can see from this that our respiratory function measurements do not have concept value results (instead having numeric values which we see in the table above).
```{r}
tableMeasurementValueAsConcept(repiratory_function_measurements)
```

As well as overview of the values of measurements, we can also see a summary of the timing between measurements for individuals in the dataset.
```{r}
tableMeasurementTimings(repiratory_function_measurements)
```