---
title: "CodelistGenerator search options: codes for osteoarthritis"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{a02_Candidate_codes_OA}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r,  message=FALSE, warning=FALSE,echo=FALSE}
library(DBI)
library(dplyr)
library(CodelistGenerator)
library(CDMConnector)
```


## Creating a codelist for osteoarthritis
For this example we are going to generate a candidate codelist for osteoarthritis, looking at the impact of alternative search strategies.

```{r, eval=FALSE}
library(DBI)
library(RPostgres)
```

```{r, eval=FALSE}
# postgres database connection details
serverDbi <- Sys.getenv("server")
user <- Sys.getenv("user")
password <- Sys.getenv("password")
port <- Sys.getenv("port")
host <- Sys.getenv("host")

db <- dbConnect(RPostgres::Postgres(),
  dbname = serverDbi,
  port = port,
  host = host,
  user = user,
  password = password
)

# name of vocabulary schema
vocabularyDatabaseSchema <- "vocabulary"

# create cdm reference
cdm <- CDMConnector::cdm_from_con(
  con = db,
  cdm_schema = vocabularyDatabaseSchema
)
```


## Search strategies
### Condition domain, without searching synonyms, with exclusions, without including descendants or ancestor
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes1 <- readRDS(system.file("optionsData01.RData", 
                                            package = "CodelistGenerator"))
```

To start we will search for "osteoarthritis", while excluding "post-infection" and "post-traumatic", but without searching synonyms, without searching via non-standard codes, and without including descendants or the direct ancestor of the included concepts.

```{r, eval=FALSE}
oaCodes1 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = "Condition",
  searchInSynonyms = FALSE,
  searchNonStandard = FALSE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = FALSE,
  includeAncestor = FALSE
)
```

What is the candidate codelist?
```{r,  message=FALSE, warning=FALSE }  
oaCodes1 |> 
  glimpse()
```


### Including descendants
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes2 <- readRDS(system.file("optionsData02.RData", 
                                            package = "CodelistGenerator"))
```

Now we will also include the descendants of included concepts.
```{r, eval=FALSE}
oaCodes2 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = "Condition",
  searchInSynonyms = FALSE,
  searchNonStandard = FALSE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = TRUE,
  includeAncestor = FALSE
)
```

What new codes do we pick up?
```{r,  message=FALSE, warning=FALSE }  
newCodes1To2 <- compareCodelists(oaCodes1, oaCodes2) |>
  filter(codelist == "Only codelist 2") |>
  select(-"codelist")

newCodes1To2 |> 
  glimpse()
```

### Including observation domain
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes3 <- readRDS(system.file("optionsData03.RData", 
                                            package = "CodelistGenerator"))
```

Now we will search the observation domain as well as the condition domain.
```{r, eval=FALSE}
oaCodes3 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = c("Condition", "Observation"),
  searchInSynonyms = FALSE,
  searchNonStandard = FALSE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = FALSE,
  includeAncestor = FALSE
)
```

What new codes do we pick up?
```{r,  message=FALSE, warning=FALSE }  
newCodes1To3 <- compareCodelists(oaCodes1, oaCodes3) |>
  filter(codelist == "Only codelist 2") |>
  select(-"codelist")

newCodes1To3 |> 
  glimpse()
```

### Search synonyms
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes4 <- readRDS(system.file("optionsData04.RData", 
                                            package = "CodelistGenerator"))
```

Now we will search the concept synonym table to identify concepts to include.
```{r, eval=FALSE}
oaCodes4 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = "Condition",
  searchInSynonyms = TRUE,
  searchNonStandard = FALSE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = FALSE,
  includeAncestor = FALSE
)
```

What new codes do we pick up?
```{r,  message=FALSE, warning=FALSE }  
newCodes1To4 <- compareCodelists(oaCodes1, oaCodes4) |>
  filter(codelist == "Only codelist 2") |>
  select(-"codelist")

newCodes1To4 |> 
  glimpse()
```

### Search via non-standard
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes5 <- readRDS(system.file("optionsData05.RData", 
                                            package = "CodelistGenerator"))
```

Now we will search the concept synonym table to identify concepts to include.
```{r, eval=FALSE}
oaCodes5 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = "Condition",
  searchInSynonyms = FALSE,
  searchNonStandard = TRUE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = FALSE,
  includeAncestor = FALSE
)
```

What new codes do we pick up?
```{r,  message=FALSE, warning=FALSE }  
newCodes1To5 <- compareCodelists(oaCodes1, oaCodes5) |>
  filter(codelist == "Only codelist 2") |>
  select(-"codelist")

newCodes1To5 |> 
  glimpse()
```

### Include ancestor
```{r,  message=FALSE, warning=FALSE,echo=FALSE}
oaCodes8 <- readRDS(system.file("optionsData07.RData", 
                                            package = "CodelistGenerator"))
```

Now we include the direct ancestor of included terms.
```{r, eval=FALSE}
oaCodes8 <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis",
  domains = "Condition",
  searchInSynonyms = FALSE,
  searchNonStandard = FALSE,
  exclude = c(
    "post-infection",
    "post-traumatic"
  ),
  includeDescendants = FALSE,
  includeAncestor = TRUE
)
```

What new codes do we pick up?
```{r,  message=FALSE, warning=FALSE }  
newCodes1To8 <- compareCodelists(oaCodes1, oaCodes8) |>
  filter(codelist == "Only codelist 2") |>
  select(-"codelist")

newCodes1To8 |> 
  glimpse()
```