# Compare, subset or stratify codelists

## Introduction: Generate codelist subsets, exploring codelist utility functions

This vignette introduces a set of functions designed to manipulate and explore codelists within an OMOP CDM. Specifically, we will learn how to:

- Subset a codelist to keep only codes meeting a certain criteria.
- Stratify a codelist based on attributes like dose unit or route of administration.
- Compare two codelists to identify shared and unique concepts.

First of all, we will load the required packages and connect to a mock database.

    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")

We will start by generating a codelist for acetaminophen using `getDrugIngredientCodes()`

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

### Subsetting a Codelist

Subsetting a codelist will allow us to reduce a codelist to only those concepts that meet certain conditions.

#### Subset to Codes in Use

This function keeps only those codes observed in the database with at least a specified frequency (`minimumCount`) and in the table specified (`table`). Note that this function depends on ACHILLES tables being available in your CDM object.

    acetaminophen_in_use <- subsetToCodesInUse(x = acetaminophen,
                                               cdm,
                                               minimumCount = 0,
                                               table = "drug_exposure")
    acetaminophen_in_use # Only the first 5 concepts will be shown

#### Subset by Domain

We will now subset to those concepts that have `domain = "Drug"`. Remember that, to see the domains available in the cdm, you can use `getDomains(cdm)`.

    acetaminophen_drug <- subsetOnDomain(acetaminophen_in_use, cdm, domain = "Drug")

    acetaminophen_drug

We can use the `negate` argument to exclude concepts with a certain domain:

    acetaminophen_no_drug <- subsetOnDomain(acetaminophen_in_use, cdm, domain = "Drug", negate = TRUE)

    acetaminophen_no_drug

#### Subset on Dose Unit

We will now filter to only include concepts with specified dose units. Remember that you can use `getDoseUnit(cdm)` to explore the dose units available in your cdm.

    acetaminophen_mg_unit <- subsetOnDoseUnit(acetaminophen_drug, cdm, c("milligram", "unit"))
    acetaminophen_mg_unit

As before, we can use argument `negate = TRUE` to exclude instead.

#### Subset on route category

We will now subset to those concepts that do not have an “unclassified_route” or “transmucosal_rectal”:

    acetaminophen_route <- subsetOnRouteCategory(acetaminophen_mg_unit,
                                                 cdm, c("transmucosal_rectal","unclassified_route"),
                                                 negate = TRUE)
    acetaminophen_route

### Stratify codelist

Instead of filtering, stratification allows us to split a codelist into subgroups based on defined vocabulary properties.

#### Stratify by Dose Unit

    acetaminophen_doses <- stratifyByDoseUnit(acetaminophen, cdm, keepOriginal = TRUE)

    acetaminophen_doses

#### Stratify by Route Category

    acetaminophen_routes <- stratifyByRouteCategory(acetaminophen, cdm)

    acetaminophen_routes

### Compare codelists

Now we will compare two codelists to identify overlapping and unique codes.

    acetaminophen <- getDrugIngredientCodes(cdm,
                                               name = "acetaminophen",
                                               nameStyle = "{concept_name}",
                                               type = "codelist_with_details")
    hydrocodone <- getDrugIngredientCodes(cdm,
                                          name = "hydrocodone",
                                          doseUnit = "milligram",
                                          nameStyle = "{concept_name}",
                                          type = "codelist_with_details")

Compare the two sets:

    comparison <- compareCodelists(acetaminophen$acetaminophen, hydrocodone$hydrocodone)

    comparison |> glimpse()

    comparison |> filter(codelist == "Both")