### Example: Subset Codelist Using Mock CDM Data

Source: https://darwin-eu.github.io/CodelistGenerator/reference/subsetToCodesInUse.html

Demonstrates filtering a codelist using mock OMOP CDM data. This example shows how to get candidate codes, create a codelist, and then subset it to include only codes found in the mock database. It also shows how to disconnect from the mock CDM.

```r
# \donttest{
library(CodelistGenerator)
library(omopgenerics)
cdm <- mockVocabRef("database")
codes <- getCandidateCodes(cdm = cdm,
                           keywords = "arthritis",
                           domains = "Condition",
                           includeDescendants = FALSE)
#> Limiting to domains of interest
#> Getting concepts to include
#> Search completed. Finishing up.
#> ✔ 3 candidate concepts identified
#> Time taken: 0 minutes and 0 seconds
x <- subsetToCodesInUse(newCodelist(list("cs1" = codes$concept_id,
                               "cs2" = 999)),
                                cdm = cdm)
#> Warning: ! `codelist` casted to integers.
#> No codes from codelist cs2 found in the database
#> Warning: "cs2" codelist will be removed from the final codelist, as there are no
#> elements left after subsetting.

x
#> 
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#>
#> - cs1 (2 codes)
CDMConnector::cdmDisconnect(cdm)
# }
```

--------------------------------

### Example: Generate and Display Code Use Table

Source: https://darwin-eu.github.io/CodelistGenerator/reference/tableCodeUse.html

This example demonstrates how to generate a code use table using summariseCodeUse and tableCodeUse. It requires connecting to a CDM database, defining codelists, and then formatting the results.

```r
if (FALSE) { # \dontrun{ 
library(omopgenerics)
library(CodelistGenerator)
con <- DBI::dbConnect(duckdb::duckdb(),
                      dbdir = CDMConnector::eunomiaDir())
cdm <- CDMConnector::cdmFromCon(con,
                                cdmSchema = "main",
                                writeSchema = "main")
acetiminophen <- c(1125315,  1127433, 40229134,
40231925, 40162522, 19133768,  1127078)
poliovirus_vaccine <- c(40213160)
cs <- list(acetiminophen = acetiminophen,
          poliovirus_vaccine = poliovirus_vaccine)
results <- summariseCodeUse(newCodelist(cs),cdm = cdm)
tableCodeUse(results)
CDMConnector::cdmDisconnect(cdm)
} # } 

```

--------------------------------

### Example of Summarising Cohort Code Use

Source: https://darwin-eu.github.io/CodelistGenerator/reference/summariseCohortCodeUse.html

This example demonstrates how to use `summariseCohortCodeUse` to analyze code usage at cohort entry. It requires setting up a CDM connection and generating a concept cohort set first.

```r
if (FALSE) { # \dontrun{
library(CodelistGenerator)
library(duckdb)
library(DBI)
library(CDMConnector)
con <- dbConnect(duckdb(),
                 dbdir = eunomiaDir())
cdm <- cdmFromCon(con, 
                 cdmSchema = "main", 
                 writeSchema = "main")
cdm <- generateConceptCohortSet(cdm = cdm,
                  conceptSet = list(a = 260139,
                                    b = 1127433),
                  name = "cohorts",
                  end = "observation_period_end_date",
                  overwrite = TRUE)

results_cohort_mult <- 
summariseCohortCodeUse(omopgenerics::newCodelist(list(cs = c(260139,19133873))),
                      cdm = cdm,
                      cohortTable = "cohorts",
                      timing = "entry")

results_cohort_mult
CDMConnector::cdmDisconnect(cdm)
} # }
```

--------------------------------

### Example Usage of tableCohortCodeUse

Source: https://darwin-eu.github.io/CodelistGenerator/reference/tableCohortCodeUse.html

Demonstrates how to generate cohort code use results and then format them into a table using tableCohortCodeUse. This example sets up a connection to a database, generates a concept cohort set, summarises cohort code use, and finally formats the results.

```R
if (FALSE) { # \dontrun{ 
con <- DBI::dbConnect(duckdb::duckdb(),
                      dbdir = CDMConnector::eunomiaDir())
cdm <- CDMConnector::cdmFromCon(con,
                                  cdmSchema = "main",
                                  writeSchema = "main")
cdm <- CDMConnector::generateConceptCohortSet(cdm = cdm,
conceptSet = list(a = 260139,
                  b = 1127433),
                  name = "cohorts",
                  end = "observation_period_end_date",
                  overwrite = TRUE)

results_cohort_mult <-
summariseCohortCodeUse(list(cs = c(260139,19133873)),
                      cdm = cdm,
                      cohortTable = "cohorts",
                      timing = "entry")

tableCohortCodeUse(results_cohort_mult)
CDMConnector::cdmDisconnect(cdm)
} # } 

```

--------------------------------

### Example: Finding Orphan Codes for a Codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/summariseOrphanCodes.html

Demonstrates how to use summariseOrphanCodes to find codes related to a 'msk' codelist within a mock OMOP CDM database. It includes setup for the CDM and codelist, and subsequent disconnection.

```r
# 
library(CodelistGenerator)

cdm <- mockVocabRef("database")
codes <- getCandidateCodes(cdm = cdm,
                          keywords = "Musculoskeletal disorder",
                          domains = "Condition",
                          includeDescendants = FALSE)
#> Limiting to domains of interest
#> Getting concepts to include
#> Search completed. Finishing up.
#> ✔ 1 candidate concept identified
#> Time taken: 0 minutes and 0 seconds
codelist <- omopgenerics::newCodelist(list("msk" = codes$concept_id))
orphan_codes <- summariseOrphanCodes(x = codelist,
                                      cdm = cdm)
#> Warning: The domains "Device", "Measurement", "Procedure", and "Visit" are not present
#> in the cdm.
#> Getting orphan codes for msk
#> 

orphan_codes
#> # A tibble: 4 × 13
#>   result_id cdm_name group_name    group_level strata_name strata_level
#>       <int> <chr>    <chr>         <chr>       <chr>       <chr>       
#> 1         1 mock     codelist_name msk         domain_id   condition   
#> 2         1 mock     codelist_name msk         domain_id   condition   
#> 3         1 mock     codelist_name msk         domain_id   condition   
#> 4         1 mock     codelist_name msk         domain_id   condition   
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>
CDMConnector::cdmDisconnect(cdm)
# 
```

--------------------------------

### Construct Codelist with Pipeable Functions

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a08_ManipulateCodelists.html

Demonstrates a pipeable workflow for constructing a codelist. It starts by getting drug ingredient codes for 'acetaminophen', then adds concepts, subsets by domain, stratifies by dose unit, and finally excludes a specific concept. The output shows the resulting codelist structure.

```r
acetaminophen <- getDrugIngredientCodes(cdm, 
                                        name = "acetaminophen",
                                        nameStyle = "{concept_name}",
                                        type = "codelist")

new_codelist <- acetaminophen |>
  addConcepts(cdm, 
              concepts = c(1L, 2L, 3L)) |>
  subsetOnDomain(cdm, 
                 domain = "Drug") |>
  stratifyByDoseUnit(cdm = cdm) |
  excludeConcepts(cdm, 
                  concepts = c(1127898)) 

new_codelist
```

--------------------------------

### Install CodelistGenerator Development Version

Source: https://darwin-eu.github.io/CodelistGenerator/index.html

Install the latest development version of CodelistGenerator from GitHub. Ensure 'remotes' package is installed first.

```r
install.packages("remotes")
remotes::install_github("darwin-eu/CodelistGenerator")
```

--------------------------------

### Get all dose forms available in a codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedRouteCategories.html

This example demonstrates how to get all available dose forms from a codelist using the `associatedRouteCategories` function. It requires the `CodelistGenerator` and `omock` libraries and a mock CDM reference.

```r
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all dose forms available in a codelist
codelist <- newCodelist(list("codes1" = c(194152L, 1830279L, 40558872L),
                             "codes2" = c(44022939L)))
# }
```

--------------------------------

### Example Usage of tableAchillesCodeUse

Source: https://darwin-eu.github.io/CodelistGenerator/reference/tableAchillesCodeUse.html

This example demonstrates how to use tableAchillesCodeUse to format the results of summariseAchillesCodeUse. It includes setting up a mock CDM database, retrieving candidate codes, summarising code use, and then formatting the results into a table.

```r
library(CodelistGenerator)
library(omopgenerics)

cdm <- mockVocabRef("database")
oa <- getCandidateCodes(cdm = cdm, keywords = "osteoarthritis")
result_achilles <- summariseAchillesCodeUse(newCodelist(list(oa = oa$concept_id)),
                                            cdm = cdm)
tableAchillesCodeUse(result_achilles)



  
      | 
        Database name
      
      
---
---

      | 
        mock
      
      
Codelist name
      | Domain ID
      | Standard concept name
      | Standard concept ID
      | Vocabulary ID
      | Source concept name
      | 
        Estimate name
      
      
Record count
      | Person count
      
oa
| condition
| Osteoarthritis of knee
| 4
| SNOMED
| NA
| 200
| 200  

| 
| Osteoarthritis of hip
| 5
| SNOMED
| NA
| 200
| 200  
CDMConnector::cdmDisconnect(cdm)
```

--------------------------------

### Get all domains available in a codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedDomains.html

This example demonstrates how to use the associatedDomains function to get all domains for codes within a codelist. It requires the CodelistGenerator and omock libraries and a mock CDM reference. The standardConcept argument can be used to filter by concept status.

```r
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all domains available in a codelist
codelist <- newCodelist(list("codes1" = c(194152L, 1830279L, 40558872L),
                             "codes2" = c(44022939L)))
associatedDomains(x = codelist, cdm = cdm,
                 standardConcept = c("Non-standard", "Standard"))
#> $codes1
#> [1] "Condition" "Drug"      "Procedure"
#>
#> $codes2
#> [1] "Drug"
#>
# }

```

--------------------------------

### Load Packages and Connect to Database

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a09_RunCodelistDiagnostics.html

Loads necessary R packages and establishes a connection to a DuckDB database using eunomia. This setup is required before generating or analyzing codelists.

```r
library(DBI)
library(duckdb)
library(dplyr)
library(CDMConnector)
library(CodelistGenerator)
library(CohortConstructor)
library(omopgenerics)

# Connect to the database and create the cdm object
con <- dbConnect(duckdb(), 
                      eunomiaDir("synpuf-1k", "5.3"))
cdm <- cdmFromCon(con = con, 
                  cdmName = "Eunomia Synpuf",
                  cdmSchema   = "main",
                  writeSchema = "main", 
                  achillesSchema = "main")

# Create a codelist for depression
depression <- getCandidateCodes(cdm,
                                keywords = "depression")
depression <- newCodelist(list("depression" = depression$concept_id))
```

--------------------------------

### Get all vocabularies from a codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedVocabularies.html

This example demonstrates how to use the associatedVocabularies function to find all vocabularies associated with a codelist. It requires the CodelistGenerator and omock libraries and a mock CDM reference.

```r
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all vocabularies from a codelist
codelist <- newCodelist(list("codes1" = c(35604877L, 35604394L),
                             "codes2" = c(4214687L)))
associatedVocabularies(cdm = cdm,
                      x = codelist)
#> $codes1
#> character(0)
#>
#> $codes2
#> character(0)
#>
# }

```

--------------------------------

### Example of Using getMappings

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getMappings.html

This example demonstrates how to use the getMappings function. It first generates mock vocabulary data and retrieves candidate codes for 'osteoarthritis', then uses these codes to find mappings to the 'READ' vocabulary.

```R
# \donttest{
cdm <- CodelistGenerator::mockVocabRef()
codes <- CodelistGenerator::getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis"
)
#> Limiting to domains of interest
#> Getting concepts to include
#> Adding descendants
#> Search completed. Finishing up.
#> ✔ 2 candidate concepts identified
#> Time taken: 0 minutes and 0 seconds
CodelistGenerator::getMappings(
  cdm = cdm,
  candidateCodelist = codes,
  nonStandardVocabularies = "READ"
)
#> # A tibble: 1 × 7
#>   standard_concept_id standard_concept_name  standard_vocabulary_id
#>                 <int> <chr>                  <chr>                 
#> 1                   4 Osteoarthritis of knee SNOMED                
#> # ℹ 4 more variables: non_standard_concept_id <int>,
#> #   non_standard_concept_name <chr>, non_standard_concept_code <chr>,
#> #   non_standard_vocabulary_id <chr>
# }
```

--------------------------------

### Example: Summarising Acetaminophen and Poliovirus Vaccine Code Use

Source: https://darwin-eu.github.io/CodelistGenerator/reference/summariseCodeUse.html

This example demonstrates how to use the summariseCodeUse function to count occurrences of acetaminophen and poliovirus vaccine codes within an OMOP CDM database. It sets up a connection to a Eunomia database, creates a CDM reference, defines a codelist, and then calls summariseCodeUse. Ensure the necessary libraries are loaded and the CDM connection is properly established before running.

```R
if (FALSE) { # \dontrun{ 
library(omopgenerics)
library(CodelistGenerator)
con <- DBI::dbConnect(duckdb::duckdb(),
                      dbdir = CDMConnector::eunomiaDir())
cdm <- CDMConnector::cdmFromCon(con,
                                cdmSchema = "main",
                                writeSchema = "main")
acetiminophen <- c(1125315,  1127433, 40229134,
                  40231925, 40162522, 19133768,  1127078)
poliovirus_vaccine <- c(40213160)
cs <- newCodelist(list(acetiminophen = acetiminophen,
                       poliovirus_vaccine = poliovirus_vaccine))
results <- summariseCodeUse(cs,cdm = cdm)
results
CDMConnector::cdmDisconnect(cdm)
} # }
```

--------------------------------

### Get all available dose units

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableDoseUnits.html

This snippet demonstrates how to get all dose units available in the CDM. It requires the `CodelistGenerator` and `omock` libraries and a CDM reference object.

```r
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all dose units available in the CDM
availableDoseUnits(cdm = cdm)
#> [1] "milligram" "percent"  
# }

```

--------------------------------

### Install CodelistGenerator from CRAN

Source: https://darwin-eu.github.io/CodelistGenerator/index.html

Use this command to install the stable version of the CodelistGenerator package from CRAN.

```r
install.packages("CodelistGenerator")
```

--------------------------------

### Get Available Domains in CDM

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableDomains.html

Use this function to get all domains available in the CDM for standard concepts. Ensure the 'omock' and 'CodelistGenerator' libraries are loaded.

```r
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all domains available in the CDM for standard concepts
availableDomains(cdm = cdm, standardConcept = "Standard")
#>  [1] "Condition"   "Drug"        "Ethnicity"   "Gender"      "Meas Value" 
#>  [6] "Measurement" "Observation" "Procedure"   "Race"        "Unit"       
#>  [11] "Visit"      
# }

```

--------------------------------

### Run Package Tests

Source: https://darwin-eu.github.io/CodelistGenerator/CONTRIBUTING.html

Execute all package tests to ensure code integrity. Ensure all necessary packages are installed before running.

```r
devtools::test()
```

--------------------------------

### Create Concept Set Expression from Codelist with Details

Source: https://darwin-eu.github.io/CodelistGenerator/reference/asConceptSetExpression.html

Illustrates generating a concept set expression from a 'codelist_with_details' object. This example also requires the CDMConnector and omock libraries.

```r
# Create concept_set_expression from a codelist_with_details
codelist <- getDrugIngredientCodes(cdm,
                                   name = "acetaminophen",
                                  nameStyle = "{concept_name}",
                                   type = "codelist_with_details")

asConceptSetExpression(codelist)
```

--------------------------------

### Generate and Display Orphan Codes Table

Source: https://darwin-eu.github.io/CodelistGenerator/reference/tableOrphanCodes.html

This example demonstrates how to generate candidate codes, summarize them as orphan codes, and then format these results into a table using tableOrphanCodes. It requires the CodelistGenerator and omopgenerics packages.

```R
library(CodelistGenerator)
library(omopgenerics)
cdm <- mockVocabRef("database")
codes <- getCandidateCodes(cdm = cdm,
keywords = "Musculoskeletal disorder",
domains = "Condition",
includeDescendants = FALSE)

orphan_codes <- summariseOrphanCodes(x = newCodelist(list("msk" = codes$concept_id)),
cdm = cdm)

tableOrphanCodes(orphan_codes)



  
      |
        Database name
      
      
---
|
        mock
      
      
Codelist name
      | Domain ID
      | Standard concept name
      | Standard concept ID
      | Vocabulary ID
      | Source concept name
      | Relationship
      | 
        Estimate name
      
      
Record count
      | Person count
      
msk
| condition
| Osteoarthritis of knee
| 4
| SNOMED
| NA
| Descendant
| 400
| 400  


| 
| Osteoarthritis of hip
| 5
| SNOMED
| NA
| Descendant
| 200
| 200  

CDMConnector::cdmDisconnect(cdm)
```

--------------------------------

### Search Candidate Codes with Synonyms and Descendants

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a04_GenerateCandidateCodelist.html

This example demonstrates how to include descendants in the search results when using synonyms. Set `includeDescendants` to TRUE.

```r
getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthrosis",
  domains = "Condition",
  searchInSynonyms = TRUE,
  standardConcept = "Standard",
  includeDescendants = TRUE,
  searchNonStandard = FALSE,
  includeAncestor = FALSE
)
```

--------------------------------

### Example Usage of getCandidateCodes

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getCandidateCodes.html

Demonstrates how to use the `getCandidateCodes` function to find concepts related to 'osteoarthritis'. It initializes a mock CDM reference and then calls the function with the specified keyword.

```r
# \donttest{
library(CodelistGenerator)
cdm <- mockVocabRef()
getCandidateCodes(
  cdm = cdm,
  keywords = "osteoarthritis"
 )
#>

```

--------------------------------

### Example Usage of getDrugIngredientCodes

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getDrugIngredientCodes.html

Demonstrates how to use the `getDrugIngredientCodes` function to retrieve codes for a specific drug ingredient, 'Adalimumab', and format the output to show only the concept name.

```r
# \donttest{
library(CodelistGenerator)
cdm <- mockVocabRef()
getDrugIngredientCodes(cdm = cdm,
                       name = "Adalimumab",
                       nameStyle = "{concept_name}")
#>
#>
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#>
#>
#> - adalimumab (2 codes)
# }

```

--------------------------------

### Load and Inspect Mock Vocabulary CDM

Source: https://darwin-eu.github.io/CodelistGenerator/reference/mockVocabRef.html

Load the mock vocabulary into a CDM object using the CodelistGenerator library and inspect its structure. This example is wrapped in \donttest{} to prevent execution during package checks.

```r
# \donttest{
library(CodelistGenerator)
cdm <- mockVocabRef()
cdm
# > 
# > #\033[34m# OMOP CDM reference (local) of mock \033[39m────────────────────────────────────────
# > #• omop tables: cdm_source, concept, concept_ancestor, concept_relationship,
# > #  concept_synonym, condition_occurrence, drug_strength, observation_period,
# > #  person, vocabulary
# > #• cohort tables: -
# > #• achilles tables: achilles_analysis, achilles_results, achilles_results_dist
# > #• other tables: -
# > 
# }           
```

--------------------------------

### Load Libraries and Connect to Mock Database

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a08_ManipulateCodelists.html

Loads necessary R packages and connects to a mock OMOP CDM database using Eunomia.

```r
library(DBI)
library(duckdb)
library(dplyr)
library(CDMConnector)
library(CodelistGenerator)

# Download mock database
requireEunomia(datasetName = "synpuf-1k", cdmVersion = "5.3")

```

--------------------------------

### Get Concept Class IDs for a Codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedConceptClassIds.html

This example demonstrates how to use the `associatedConceptClassIds` function to retrieve concept class IDs for codes within a codelist. It requires the `CodelistGenerator` and `omock` libraries and a mock CDM object.

```r
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmFromDataset(datasetName = "GiBleed")
#> ℹ Reading GiBleed tables.
#> ℹ Adding drug_strength table.
#> ℹ Creating local <cdm_reference> object.

# Get concept_class_ids in a codelist
x <- newCodelist(list("codes1" = c(1118088L, 40213201L, 35208414L),
                      "codes2" = c(1557272L, 4336464L, 4295880L)))
associatedConceptClassIds(x, cdm,
                         standardConcept = "Standard")
#> $codes1
#> [1] "Branded Drug" "CVX"         
#> 
#> $codes2
#> [1] "Ingredient" "Procedure" 
#> 

# Notice that this corresponds to the information provided by `concept_class_id`
# column in the `concept` table
# }
```

--------------------------------

### Stratify Codelist by Brand Example

Source: https://darwin-eu.github.io/CodelistGenerator/reference/stratifyByBrand.html

Demonstrates how to use stratifyByBrand to stratify a codelist by brand. It shows how to create a mock CDM reference, define a codelist, and then apply the function, including keeping the original codelist and handling potential warnings.

```r
# \donttest{
library(CodelistGenerator)

cdm <- mockVocabRef()
codes <- newCodelist(list(
  concepts_1 = c(20L, 21L, 22L),
  concepts_2 = c(10L, 13L, 21L)
))

new_codes <- stratifyByBrand(x = codes,
                             cdm = cdm,
                             keepOriginal = TRUE)
#> Warning: 1 concept ID have duplicated `brand` and will be assigned to multiple codelists
#> (20).
new_codes
#> 
#> ── 7 codelists ─────────────────────────────────────────────────────────────────
#> 
#> - concepts_1 (3 codes)
#> - concepts_1_brand_1 (1 codes)
#> - concepts_1_brand_2 (2 codes)
#> - concepts_1_unclassified_brand (1 codes)
#> - concepts_2 (3 codes)
#> - concepts_2_brand_2 (2 codes)
#> along with 1 more codelists
# }

```

--------------------------------

### Update and Check Package Documentation

Source: https://darwin-eu.github.io/CodelistGenerator/CONTRIBUTING.html

Run these commands to update and verify package documentation. Ensure `devtools::check_man()` returns no warnings.

```r
devtools::document()
```

```r
devtools::run_examples()
```

```r
devtools::build_readme()
```

```r
devtools::build_vignettes()
```

```r
devtools::check_man()
```

--------------------------------

### Connect to Database and Create CDM Object

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a05_GenerateVocabularyBasedCodelist.html

Establishes a connection to a DuckDB database using Eunomia and creates a CDM reference object. Ensure necessary packages are loaded before execution.

```r
library(DBI)
library(duckdb)
library(dplyr)
library(CDMConnector)
library(CodelistGenerator)

# Connect to the database and create the cdm object
con <- dbConnect(duckdb(), 
                 eunomiaDir("synpuf-1k", "5.3"))
cdm <- cdmFromCon(con = con, 
                  cdmName = "Eunomia Synpuf",
                  cdmSchema = "main",
                  writeSchema = "main",
                  achillesSchema = "main")
```

--------------------------------

### R: Create codelist from codelist_with_details

Source: https://darwin-eu.github.io/CodelistGenerator/reference/asCodelist.html

Demonstrates creating a codelist object from a 'codelist_with_details' object using the asCodelist function. Requires the omock and CDMConnector libraries.

```r
# \donttest{
library(omock)
library(CDMConnector)

# Creating CDM object
cdm <- mockCdmFromDataset(datasetName = "GiBleed")

# Create codelist from a codelist_with_details
codelist <- getDrugIngredientCodes(cdm,
                                   name = "acetaminophen",
                                   nameStyle = "{concept_name}",
                                   type = "codelist_with_details")

asCodelist(codelist)

# }
```

--------------------------------

### Create and list directory for codelists

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a06_ImportExport.html

Creates a temporary directory to store codelists and verifies its creation. This is a preparatory step before exporting codelists.

```r
dir_codes <- file.path(tempdir(), "codelists")
dir.create(dir_codes)
list.files(dir_codes)
```

--------------------------------

### Create a Codelist with Details

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a03_TypesOfCodelist.html

Demonstrates creating a 'codelist_with_details' by providing a named list where each element is a tibble containing at least 'concept_id'. The 'newCodelistWithDetails' function is used for conversion.

```r
codelist_with_details <- list("codes1" = tibble("concept_id" = c(1L, 2L, 3L)),
                              "codes2" = tibble("concept_id" = c(4L, 5L, 10L)))
codelist_with_details <- newCodelistWithDetails(codelist_with_details)

codelist_with_details
```

--------------------------------

### Load Packages and Connect to CDM

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a02_ExploreCDMvocabulary.html

Loads necessary R packages and connects to a eunomia database, creating a CDM object for further analysis. Ensure the eunomiaDir function is correctly configured for your database path.

```r
library(DBI)
library(dplyr)
library(CDMConnector)
library(CodelistGenerator)

# Connect to the database and create the cdm object
con <- dbConnect(duckdb::duckdb(), 
                 eunomiaDir("synpuf-1k", "5.3"))
cdm <- cdmFromCon(con = con, 
                  cdmName = "Eunomia Synpuf",
                  cdmSchema   = "main",
                  writeSchema = "main", 
                  achillesSchema = "main")
```

--------------------------------

### associatedDoseForms

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedDoseForms.html

Get the dose forms associated with drug concepts in a codelist.

```APIDOC
## associatedDoseForms

### Description
Get the dose forms associated with drug concepts in a codelist.

### Usage
```R
associatedDoseForms(x, cdm)
```

### Arguments
* `x` (codelist) - A codelist.
* `cdm` (cdm reference) - A cdm reference to an OMOP CDM dataset. If data is held within a database, the vocabulary tables should be in the same schema as the clinical tables (person, observation period, and so on).

### Value
The dose forms available for drug concepts.

### Examples
```R
# 
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all dose forms available in a codelist
codeloist <- newCodelist(list("codes1" = c(194152L, 1830279L, 40558872L),
                             "codes2" = c(44022939L)))
associatedDoseForms(x = codelist, cdm = cdm)

```

--------------------------------

### R: Create codelist from candidate_codes

Source: https://darwin-eu.github.io/CodelistGenerator/reference/asCodelist.html

Demonstrates creating a codelist object from a 'candidate_codes' object using the asCodelist function. Requires the omock and CDMConnector libraries.

```r
# \donttest{
library(omock)
library(CDMConnector)

# Creating CDM object
cdm <- mockCdmFromDataset(datasetName = "GiBleed")

# Create codelist from a candidate_codes
codelist <- getCandidateCodes(cdm,
                              keywords = "arthritis")

asCodelist(codelist)

# }
```

--------------------------------

### Create an Empty Codelist with Details

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a03_TypesOfCodelist.html

Initializes an empty 'codelist_with_details' object using the 'emptyCodelistWithDetails' function from the omopGenerics package.

```r
empty_codelist_with_details <- emptyCodelistWithDetails()

empty_codelist_with_details
```

--------------------------------

### Create codelist_with_details from a codelist

Source: https://darwin-eu.github.io/CodelistGenerator/reference/asCodelistWithDetails.html

This snippet demonstrates how to create a 'codelist_with_details' object from an existing 'codelist' object. It requires the 'omock' and 'CDMConnector' libraries and a CDM reference object.

```r
library(omock)
library(CDMConnector)

# Creating CDM object
path <- downloadMockDataset(datasetName = "GiBleed",
                            path = NULL,
                            overwrite = NULL)
#> ℹ Deleting prior version of GiBleed.
cdm <- mockCdmFromDataset(datasetName = "GiBleed")
#> ℹ Reading GiBleed tables.
#> ℹ Adding drug_strength table.
#> ℹ Creating local <cdm_reference> object.

# Create codelist_with_details from a codelist
codelist <- getDrugIngredientCodes(cdm,
                                   name = "acetaminophen",
                                   nameStyle = "{concept_name}",
                                   type = "codelist")

asCodelistWithDetails(codelist, cdm)
#> 
#> ── 1 codelist with details ─────────────────────────────────────────────────────
#> 
#> - acetaminophen (7 codes)
```

--------------------------------

### availableRouteCategories

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableRouteCategories.html

Gets the dose form categories available in the database. These categories are classified based on a standard detailed in the provided DOI.

```APIDOC
## availableRouteCategories

### Description
Gets the dose form categories available in the database (see https://doi.org/10.1002/pds.5809 for more details on how routes were classified).

### Method
Function Call

### Arguments
- **cdm** (cdm reference) - A cdm reference to an OMOP CDM dataset. If data is held within a database, the vocabulary tables should be in the same schema as the clinical tables (person, observation period, and so on).

### Value
A character vector with all available routes.

### Examples
```R
# \donttest{
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all domains available in the CDM
availableRouteCategories(cdm = cdm)
#> [1] "topical"            "transmucosal_nasal"
# }
```
```

--------------------------------

### Load Libraries and Create Mock CDM Reference

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a04_GenerateCandidateCodelist.html

Loads the dplyr and CodelistGenerator libraries and creates a mock CDM reference for testing purposes.

```R
library(dplyr)
library(CodelistGenerator)

cdm <- mockVocabRef()
```

--------------------------------

### Get all vocabularies

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableVocabularies.html

Retrieves all vocabularies available in the CDM reference. This is useful for understanding the full scope of vocabulary data available for use.

```R
# 
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all vocabularies available in the CDM
availableVocabularies(cdm)

```

--------------------------------

### associatedVocabularies

Source: https://darwin-eu.github.io/CodelistGenerator/reference/associatedVocabularies.html

Gets the vocabularies associated with a codelist. It takes a codelist and an OMOP CDM reference as input and returns the names of available vocabularies.

```APIDOC
## associatedVocabularies

### Description
Get the vocabularies associated with a codelist.

### Usage
associatedVocabularies(x, cdm, standardConcept = "Standard", domain = NULL)

### Arguments

* **x** (codelist) - A codelist.
* **cdm** (cdm reference) - A cdm reference to an OMOP CDM dataset. If data is held within a database, the vocabulary tables should be in the same schema as the clinical tables (person, observation period, and so on).
* **standardConcept** (character vector) - With one or more of "Standard", "Classification", and "Non-standard". These correspond to the flags used for the standard_concept field in the concept table of the cdm.
* **domain** (character vector or NULL) - With one or more of the OMOP CDM domains. The results will be restricted to the given domains. Check the available ones by running availableDomains(). If NULL, all supported domains are included: Condition, Drug, Procedure, Device, Observation, and Measurement.

### Value
Names of available vocabularies.

### Examples
```R
# 
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all vocabularies from a codelist
codelist <- newCodelist(list("codes1" = c(35604877L, 35604394L),
                             "codes2" = c(4214687L)))
associatedVocabularies(cdm = cdm,
                      x = codelist)
#> $codes1
#> character(0)
#> 
#> $codes2
#> character(0)
#> 
# 
```
```

--------------------------------

### List Available Relationship IDs

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a02_ExploreCDMvocabulary.html

Use this function to get a list of all relationship IDs available in the CDM, which describe how concepts are related to each other.

```r
availableRelationshipIds(cdm)
```

--------------------------------

### Get Drug Ingredient Codes Function Signature

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getDrugIngredientCodes.html

This is the function signature for `getDrugIngredientCodes`. It outlines the available parameters for retrieving drug ingredient codes.

```r
getDrugIngredientCodes(
  cdm,
  name = NULL,
  nameStyle = "{concept_code}_{concept_name}",
  doseForm = NULL,
  doseUnit = NULL,
  routeCategory = NULL,
  ingredientRange = c(1, Inf),
  type = "codelist"
)
```

--------------------------------

### Create a CDM reference from a DuckDB vocabulary database

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a01_GettingOmopCdmVocabularies.html

Connects to a previously created DuckDB vocabulary database and establishes it as a CDM reference. This allows for subsequent analysis using OMOP CDM functions.

```R
db <- dbConnect(duckdb(), here(vocab_folder,"vocab.duckdb"))
cdm <- cdmFromCon(db, "main", "main", cdmName = "vocabularise", .softValidation = TRUE)
```

--------------------------------

### Get All ATC Levels

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableATC.html

Retrieves all levels of ATC classification codes (1st through 5th). Requires a CDM reference and a vector of all ATC levels.

```r
# Get all ATC classification codes
availableATC(cdm, level = c("ATC 1st", "ATC 2nd", "ATC 3rd", "ATC 4th", "ATC 5th"))
#>  [1] "combinations of electrolytes; parenteral"  
#>  [2] "ANTINEOPLASTIC AND IMMUNOMODULATING AGENTS"
#>  [3] "ANTINEOPLASTIC AGENTS"                     
#>  [4] "THROAT PREPARATIONS"                       
#>  [5] "DRUGS FOR OBSTRUCTIVE AIRWAY DISEASES"     
#>  [6] "COUGH AND COLD PREPARATIONS"               
#>  [7] "ANTIHISTAMINES FOR SYSTEMIC USE"           
#>  [8] "OTHER RESPIRATORY SYSTEM PRODUCTS"         
#>  [9] "ENDOCRINE THERAPY"                         
#> [10] "IMMUNOSTIMULANTS"                          
#> [11] "IMMUNOSUPPRESSANTS"                        
#> [12] "RESPIRATORY SYSTEM"                        
#> [13] "NASAL PREPARATIONS"                        
# }
```

--------------------------------

### Create codelist_with_details from candidate_codes

Source: https://darwin-eu.github.io/CodelistGenerator/reference/asCodelistWithDetails.html

This snippet shows how to create a 'codelist_with_details' object from a 'candidate_codes' object. It utilizes the 'getCandidateCodes' function and requires the 'omock' and 'CDMConnector' libraries.

```r
library(omock)
library(CDMConnector)

# Creating CDM object
path <- downloadMockDataset(datasetName = "GiBleed",
                            path = NULL,
                            overwrite = NULL)
#> ℹ Deleting prior version of GiBleed.
cdm <- mockCdmFromDataset(datasetName = "GiBleed")
#> ℹ Reading GiBleed tables.
#> ℹ Adding drug_strength table.
#> ℹ Creating local <cdm_reference> object.

# Create codelist from a candidate_codes
codelist <- getCandidateCodes(cdm,
                             keywords = "arthritis")
#> Limiting to domains of interest
#> Getting concepts to include
#> Adding descendants
#> Search completed. Finishing up.
#> ✔ 2 candidate concepts identified
#> Time taken: 0 minutes and 0 seconds

asCodelistWithDetails(codelist)
#> 
#> ── 1 codelist with details ─────────────────────────────────────────────────────
#> 
#> - candidate_codes (2 codes)
```

--------------------------------

### Get CDM Vocabulary Version

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a02_ExploreCDMvocabulary.html

Retrieves the current vocabulary version of the CDM object. This is useful for understanding the data's temporal context.

```r
vocabularyVersion(cdm)
```

--------------------------------

### Apache License 2.0 Boilerplate

Source: https://darwin-eu.github.io/CodelistGenerator/LICENSE.html

Use this text as a boilerplate for your project's license file. Replace bracketed placeholders with your project's specific details. Ensure the text is enclosed in appropriate comment syntax for your file format.

```text
Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

--------------------------------

### Benchmark Codelist Generation with DuckDB

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a10_CodelistGeneratorBenchmark.html

This R code demonstrates how to benchmark the CodelistGenerator package using mock data stored in a DuckDB database. It connects to the database, creates a CDM object, runs the benchmark, and visualizes the timings.

```r
library(DBI)
library(duckdb)
library(dplyr)
library(CDMConnector)
library(CodelistGenerator)
library(visOmopResults)

# Connect to the database and create the cdm object
con <- dbConnect(duckdb(), 
                      eunomiaDir("synpuf-1k", "5.3"))
cdm <- cdmFromCon(con = con, 
                  cdmName = "Eunomia Synpuf",
                  cdmSchema   = "main",
                  writeSchema = "main", 
                  achillesSchema = "main")

timings <- benchmarkCodelistGenerator(cdm)

visOmopTable(timings,
             hide = c("variable_name", "variable_level", "strata_name", "strata_level"),
             groupColumn = "task")
```

--------------------------------

### Get Candidate Codes Function Signature

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getCandidateCodes.html

This is the function signature for `getCandidateCodes`. It outlines the available parameters for searching and filtering OMOP CDM vocabulary tables.

```r
getCandidateCodes(
  cdm,
  keywords,
  exclude = NULL,
  domains = "Condition",
  standardConcept = "Standard",
  searchInSynonyms = FALSE,
  searchNonStandard = FALSE,
  includeDescendants = TRUE,
  includeAncestor = FALSE
)
```

--------------------------------

### Get 1st Level ATC Codes

Source: https://darwin-eu.github.io/CodelistGenerator/reference/getATCCodes.html

Generates a codelist of 1st level ATC codes available in the CDM. Requires the `CodelistGenerator` and `omock` libraries.

```r
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Create a codelist with 1st level ATC codes available in the CDM
codelist <- getATCCodes(
  cdm = cdm,
  level = "ATC 1st"
)
```

--------------------------------

### Get All Drug Ingredients

Source: https://darwin-eu.github.io/CodelistGenerator/reference/availableDrugIngredients.html

Retrieves all drug ingredients from the CDM for standard concepts. Ensure the CodelistGenerator and omock libraries are loaded, and a CDM reference object is created.

```r
library(CodelistGenerator)
library(omock)

# Create CDM object
cdm <- mockCdmReference()

# Get all drug ingredients available in the CDM for standard concepts
availableDrugIngredients(cdm = cdm)
```

--------------------------------

### Create and display a new codelist

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a06_ImportExport.html

Defines a list of codes and then converts it into a newCodelist object. This object is then displayed, showing its structure and content.

```r
codelist <- list("codes1" = c(1L, 2L, 3L),
                 "codes2" = c(4L, 5L, 10L))
codelist <- newCodelist(codelist)

codelist
```

--------------------------------

### Create a local DuckDB vocabulary database

Source: https://darwin-eu.github.io/CodelistGenerator/articles/a01_GettingOmopCdmVocabularies.html

This script reads vocabulary CSV files and writes them into a DuckDB database. It also adds empty person and observation_period tables, which are necessary for creating a CDM reference.

```R
library(readr)
library(DBI)
library(duckdb)
library(omopgenerics)
library(here)

vocab_folder <- here() # add path to directory

# read in files
concept <- read_delim(here(vocab_folder, "CONCEPT.csv"),
                      "\t",
                      escape_double = FALSE, trim_ws = TRUE
)
concept_relationship <- read_delim(here(vocab_folder, "CONCEPT_RELATIONSHIP.csv"),
                                   "\t",
                                   escape_double = FALSE, trim_ws = TRUE
)
concept_ancestor <- read_delim(here(vocab_folder, "CONCEPT_ANCESTOR.csv"),
                               "\t",
                               escape_double = FALSE, trim_ws = TRUE
)
concept_synonym <- read_delim(here(vocab_folder, "CONCEPT_SYNONYM.csv"),
                              "\t",
                              escape_double = FALSE, trim_ws = TRUE
)
vocabulary <- read_delim(here(vocab_folder, "VOCABULARY.csv"), "\t",
                         escape_double = FALSE, trim_ws = TRUE
)

# write to duckdb
db <- dbConnect(duckdb(), here(vocab_folder,"vocab.duckdb"))
dbWriteTable(db, "concept", concept, overwrite = TRUE)
dbWriteTable(db, "concept_relationship", concept_relationship, overwrite = TRUE)
dbWriteTable(db, "concept_ancestor", concept_ancestor, overwrite = TRUE)
dbWriteTable(db, "concept_synonym", concept_synonym, overwrite = TRUE)
dbWriteTable(db, "vocabulary", vocabulary, overwrite = TRUE)
# add empty person and observation period tables
person_cols <- omopColumns("person")
person <- data.frame(matrix(ncol = length(person_cols), nrow = 0))
colnames(person) <- person_cols
dbWriteTable(db, "person", person, overwrite = TRUE)
observation_period_cols <- omopColumns("observation_period")
observation_period <- data.frame(matrix(ncol = length(observation_period_cols), nrow = 0))
colnames(observation_period) <- observation_period_cols
dbWriteTable(db, "observation_period", observation_period, overwrite = TRUE)
dbDisconnect(db)
```