---
title: "CodelistGenerator options: examples with a with mock vocabulary"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{03_Options_for_CodelistGenerator}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

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

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

Let´s say we have a mock vocabulary database with these hypothetical concepts and relationships.

```{r,echo=FALSE}
knitr::include_graphics("mock_db_fig1.png")
```

```{r,  message=FALSE, warning=FALSE,echo=FALSE, results='hide'}
cdm <- mockVocabRef(backend = "data_frame")
```

## Search for exact keyword match 
```{r,echo=FALSE}
knitr::include_graphics("mock_db_fig2.png")
```

To find "Musculoskeletal disorder" we can search for that like so 
```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "Musculoskeletal disorder",
  domains = "Condition",
  includeDescendants = FALSE,
)

codes %>% 
  glimpse()
```

Note, we would also identify it based on a partial match
```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "Musculoskeletal",
  domains = "Condition",
  includeDescendants = FALSE
)

codes %>% 
  glimpse()
```

## Add descendants
```{r,echo=FALSE}
knitr::include_graphics("mock_db_fig7.png")
```

To include descendants of an identified code, we can set includeDescendants to TRUE
```{r}
getCandidateCodes(
  cdm = cdm,
  keywords = "Musculoskeletal disorder",
  domains = "Condition",
  includeDescendants = TRUE
) %>% 
  glimpse()
```

## Multiple search terms 
We can also search for multiple keywords at the same time, and would have picked these all up with the following search
```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = c(
    "Musculoskeletal disorder",
    "arthritis",
    "arthrosis"
  ),
  domains = "Condition",
  includeDescendants = FALSE
)

codes %>% 
  glimpse()
```

## Add ancestor
```{r, echo=FALSE}
knitr::include_graphics("mock_db_fig5.png")
```

To include the ancestors one level above the identified concepts we can set includeAncestor to TRUE

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "Osteoarthritis of knee",
  includeAncestor = TRUE,
  domains = "Condition"
)

codes %>% 
  glimpse()
```

## Searches with multiple words
```{r, echo=FALSE}
knitr::include_graphics("mock_db_fig4.png")
```

We can also find concepts with multiple words even if they are in a different order. For example, a search for "Knee osteoarthritis" will pick up "Osteoarthritis of knee".

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "Knee osteoarthritis",
  domains = "Condition",
  includeDescendants = TRUE
)

codes %>% 
  glimpse()
```


## With exclusions
```{r, echo=FALSE}
knitr::include_graphics("mock_db_fig5.png")
```

We can also exclude specific terms 

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "arthritis",
  exclude = "Hip osteoarthritis",
  domains = "Condition"
)

codes %>% 
  glimpse()
```

## Search using synonyms
```{r, echo=FALSE}
knitr::include_graphics("mock_db_fig6.png")
```

We can also pick up codes based on their synonyms. In this case "Arthritis" has a synonym of "Osteoarthrosis" and so a search of both the primary name of a concept and any of its associated synonyms would pick up this synonym and it would be included.

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthrosis",
  domains = "Condition",
  searchInSynonyms = TRUE
)

codes %>% 
  glimpse()
```

## Search via non-standard
Or we could have also picked up "Osteoarthrosis" by searching via non-standard.

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = c("arthritis", "arthropathy"),
  domains = "Condition",
  searchNonStandard = TRUE
)

codes %>% 
  glimpse()
```

## Search for both standard and non-standard concepts

```{r, echo=FALSE}
knitr::include_graphics("mock_db_fig8.png")
```

We can also include non-standard codes in our results like so

```{r}
codes <- getCandidateCodes(
  cdm = cdm,
  keywords = c(
    "Musculoskeletal disorder",
    "arthritis",
    "arthropathy",
    "arthrosis"
  ),
  domains = "Condition",
  standardConcept = c("Standard", "Non-standard")
)

codes %>% 
  glimpse()
```