# Generating vocabulary based codelists

For this vignette we are going to produce codelists based on the OMOP CDM vocabulary tables. First we will create medication codelists based on ATC classifications and drug ingredients. Second, we will create condition codes based on ICD10 chapters and subchapters.

### Medication codelists based on drug ingredients

The function `getDrugIngredientCodes()` can be used to generate the medication codelists based around ingredient codes. Here, for example, we will create a codelist using ingredient codes only for acetaminophen. We´ll do this using the Eunomia example data.

By default the function will return a codelist. As Eunomia only contains a subset of the OMOP CDM vocabularies we see a few codes returned, but we would get many more if working with the full set of vocabularies.

    acetaminophen_codes <- getDrugIngredientCodes(
      cdm = cdm,
      name = "acetaminophen"
    )

    acetaminophen_codes
    #>
    #> ── 1 codelist ──────────────────────────────────────────────────────────────────
    #>
    #> - acetaminophen (7 codes)
    acetaminophen_codes$acetaminophen
    #> [1]  1125315  1127078  1127433 40229134 40231925 40162522 19133768

Alternatively, instead of returning a codelist we could instead get back a tibble that contains additional information on each conept such as their names and domains by setting `withConceptDetails` to TRUE

    acetaminophen_codes_with_details <- getDrugIngredientCodes(
      cdm = cdm,
      name = "acetaminophen",
      withConceptDetails = TRUE
    )

    acetaminophen_codes_with_details$acetaminophen |>
      glimpse()
    #> Rows: 7
    #> Columns: 4
    #> $ concept_id    <int> 1125315, 1127078, 1127433, 40229134, 40231925, 40162522,…
    #> $ concept_name  <chr> "Acetaminophen", "Acetaminophen 160 MG Oral Tablet", "Ac…
    #> $ domain_id     <chr> "Drug", "Drug", "Drug", "Drug", "Drug", "Drug", "Drug"
    #> $ vocabulary_id <chr> "RxNorm", "RxNorm", "RxNorm", "RxNorm", "RxNorm", "RxNor…

Instead of getting back all concepts for acetaminophen, we could require that only concepts associated with acetaminophen and at least one more drug ingredient (i.e. combination therapies) are returned.

    acetaminophen_two_or_more_ingredients <- getDrugIngredientCodes(
      cdm = cdm,
      name = "acetaminophen",
      ingredientRange = c(2,Inf),
      withConceptDetails = TRUE
    )

    acetaminophen_two_or_more_ingredients$acetaminophen |>
      glimpse()
    #> Rows: 4
    #> Columns: 4
    #> $ concept_id    <int> 40229134, 40231925, 40162522, 19133768
    #> $ concept_name  <chr> "Acetaminophen 21.7 MG/ML / Dextromethorphan Hydrobromid…
    #> $ domain_id     <chr> "Drug", "Drug", "Drug", "Drug"
    #> $ vocabulary_id <chr> "RxNorm", "RxNorm", "RxNorm", "RxNorm"

Or we could instead only return concepts associated with acetaminophen and no other drug ingredient.

    acetaminophen_one_ingredient <- getDrugIngredientCodes(
      cdm = cdm,
      name = "acetaminophen",
      ingredientRange = c(1,1),
      withConceptDetails = TRUE
    )

    acetaminophen_one_ingredient$acetaminophen |>
      glimpse()
    #> Rows: 3
    #> Columns: 4
    #> $ concept_id    <int> 1125315, 1127078, 1127433
    #> $ concept_name  <chr> "Acetaminophen", "Acetaminophen 160 MG Oral Tablet", "Ac…
    #> $ domain_id     <chr> "Drug", "Drug", "Drug"
    #> $ vocabulary_id <chr> "RxNorm", "RxNorm", "RxNorm"

Lastly, we could also restrict to a particular dose form. Let’s try to see if there are any injection dose form of acetaminophen.

    acetaminophen_injections <- getDrugIngredientCodes(
      cdm = cdm,
      name = "acetaminophen",
      doseForm = "injection",
      withConceptDetails = TRUE
    )
    #> Warning: No descendant codes found

    acetaminophen_injections$acetaminophen |>
      glimpse()
    #>  NULL

In this case we see that in Eunomia there no concept for acetaminophen with an injection dose form.

The previous examples have focused on single drug ingredient. We can though specify multiple ingredients, in which case we will get a codelist back for each.

    acetaminophen_heparin_codes <- getDrugIngredientCodes(
      cdm = cdm,
      name = c("acetaminophen", "heparin")
      )

    acetaminophen_heparin_codes
    #>
    #> ── 2 codelists ─────────────────────────────────────────────────────────────────
    #>
    #> - acetaminophen (7 codes)
    #> - heparin (1 codes)
    acetaminophen_heparin_codes$acetaminophen
    #> [1]  1125315  1127078  1127433 40229134 40231925 40162522 19133768
    acetaminophen_heparin_codes$heparin
    #> [1] 1367571

And if we don´t specify an ingredient, we´ll get a codelist for every drug ingredient in the vocabularies.

    ingredient_codes <- getDrugIngredientCodes(cdm = cdm)
    ingredient_codes
    #>
    #> ── 91 codelists ────────────────────────────────────────────────────────────────
    #>
    #> - ondansetron (2 codes)
    #> - meperidine (2 codes)
    #> - loratadine (3 codes)
    #> - morphine (2 codes)
    #> - aspirin (2 codes)
    #> - naproxen (3 codes)
    #> - celecoxib (1 codes)
    #> - dextromethorphan (2 codes)
    #> - diclofenac (1 codes)
    #> - oxycodone (2 codes)
    #> along with 81 more codelists

### Medication codelists based on ATC classifications

Analogous to `getDrugIngredientCodes()`, `getATCCodes()` can be used to generate a codelist based on a particular ATC class. To show this, we´ll use a the mock vocabulary from CodelistGenerator.

    cdm_mock <- mockVocabRef()

In this example, we will produce an ATC level 1 codelist based on Alimentary Tract and Metabolism Drugs.

    atc_codelist <- getATCCodes(
      cdm = cdm_mock,
      level = "ATC 1st",
      name = "alimentary tract and metabolism"
    )

    atc_codelist
    #>
    #> ── 1 codelist ──────────────────────────────────────────────────────────────────
    #>
    #> - alimentary_tract_and_metabolism (2 codes)

## Condition Codelists using ICD10 chapters and subchapters

We can use `getICD10StandardCodes()` to generate condition codes based on ICD10 chapters and subchapters. As ICD10 is a non-standard vocabulary in the OMOP CDM this function returns standard concepts associated with these ICD10 chapters and subchapters directly via a mapping from them or indirectly from being a descendant concept of a code that is mapped from them. It is important to note that `getICD10StandardCodes()` will only return results if the ICD codes are included in the vocabulary tables.

For this example, we will try to generate a codelist for arthropathies.

    arthropathy_codes <- getICD10StandardCodes(
      cdm = cdm_mock,
      name = "arthropathies"
    )
    arthropathy_codes
    #>
    #> ── 1 codelist ──────────────────────────────────────────────────────────────────
    #>
    #> - arthropathies (3 codes)
    arthropathy_codes$arthropathies
    #> [1] 3 4 5

As with the above functions, we could return concepts with their details rather than as a codelist.

    arthropathy_codes <- getICD10StandardCodes(
      cdm = cdm_mock,
      name = "arthropathies",
      withConceptDetails = TRUE
    )
    arthropathy_codes
    #> $arthropathies
    #> # A tibble: 3 × 5
    #>   name          concept_id concept_name           domain_id vocabulary_id
    #>   <chr>              <int> <chr>                  <chr>     <chr>
    #> 1 arthropathies          3 Arthritis              Condition SNOMED
    #> 2 arthropathies          4 Osteoarthritis of knee Condition SNOMED
    #> 3 arthropathies          5 Osteoarthritis of hip  Condition SNOMED
    arthropathy_codes$arthropathies
    #> # A tibble: 3 × 5
    #>   name          concept_id concept_name           domain_id vocabulary_id
    #>   <chr>              <int> <chr>                  <chr>     <chr>
    #> 1 arthropathies          3 Arthritis              Condition SNOMED
    #> 2 arthropathies          4 Osteoarthritis of knee Condition SNOMED
    #> 3 arthropathies          5 Osteoarthritis of hip  Condition SNOMED