# Summarise concept id counts

# 2 Introduction

In this vignette, we will explore the OmopSketch functions designed to provide information about the number of counts of concepts in tables. Specifically, there are two key functions that facilitate this, `summariseConceptIdCounts()` and `tableConceptIdCounts()`. The former one creates a summary statistics results with the number of counts per each concept in the clinical table, and the latter one displays the result in a table.

## 2.1 Create a mock cdm

Let’s see an example of the previous functions. To start with, we will load essential packages and create a mock cdm using `mockOmopSketch()`.

    library(duckdb)
    library(OmopSketch)
    library(dplyr)

    cdm <- mockOmopSketch()

    cdm
    #>
    #> ── # OMOP CDM reference (duckdb) of mockOmopSketch ─────────────────────────────
    #> • omop tables: person, observation_period, cdm_source, concept, vocabulary,
    #> concept_relationship, concept_synonym, concept_ancestor, drug_strength,
    #> condition_occurrence, death, drug_exposure, measurement, observation,
    #> procedure_occurrence, visit_occurrence, device_exposure
    #> • cohort tables: -
    #> • achilles tables: -
    #> • other tables: -

# 3 Summarise concept id counts

We now use the `summariseConceptIdCounts()` function from the OmopSketch package to retrieve counts for each concept id and name, as well as for each source concept id and name, across the clinical tables.

    summariseConceptIdCounts(cdm, omopTableName = "drug_exposure") |>
      select(group_level, variable_name, variable_level, estimate_name, estimate_value, additional_name, additional_level) |>
      glimpse()
    #> Rows: 216
    #> Columns: 7
    #> $ group_level      <chr> "drug_exposure", "drug_exposure", "drug_exposure", "d…
    #> $ variable_name    <chr> "Diclofenac Sodium 75 MG Delayed Release Oral Tablet"…
    #> $ variable_level   <chr> "40162359", "40213227", "40213281", "782043", "111951…
    #> $ estimate_name    <chr> "count_records", "count_records", "count_records", "c…
    #> $ estimate_value   <chr> "100", "100", "100", "100", "100", "100", "100", "100…
    #> $ additional_name  <chr> "source_concept_id &&& source_concept_name", "source_…
    #> $ additional_level <chr> "0 &&& No matching concept", "0 &&& No matching conce…

By default, the function returns the number of records (`estimate_name == "count_records"`) for each concept_id. To include counts by person, you can set the `countBy` argument to `"person"` or to c`("record", "person")` to obtain both record and person counts.

    summariseConceptIdCounts(cdm,
      omopTableName = "drug_exposure",
      countBy = c("record", "person")
    ) |>
      select( variable_name, estimate_name, estimate_value)
    #> # A tibble: 432 × 3
    #>    variable_name                                    estimate_name estimate_value
    #>    <chr>                                            <chr>         <chr>
    #>  1 Diclofenac Sodium 75 MG Delayed Release Oral Ta… count_records 100
    #>  2 Diclofenac Sodium 75 MG Delayed Release Oral Ta… count_subjec… 65
    #>  3 tetanus and diphtheria toxoids, adsorbed, prese… count_records 100
    #>  4 tetanus and diphtheria toxoids, adsorbed, prese… count_subjec… 65
    #>  5 diphtheria, tetanus toxoids and acellular pertu… count_records 100
    #>  6 diphtheria, tetanus toxoids and acellular pertu… count_subjec… 66
    #>  7 Isoflurane                                       count_records 100
    #>  8 Isoflurane                                       count_subjec… 65
    #>  9 Dextromethorphan                                 count_records 100
    #> 10 Dextromethorphan                                 count_subjec… 64
    #> # ℹ 422 more rows

Further stratification can be applied using the `interval`, `sex`, and `ageGroup` arguments. The interval argument supports “overall” (no time stratification), “years”, “quarters”, or “months”.

    summariseConceptIdCounts(cdm,
      omopTableName = "condition_occurrence",
      countBy = "person",
      interval = "years",
      sex = TRUE,
      ageGroup = list("<=50" = c(0, 50), ">50" = c(51, Inf))
    ) |>
      select(group_level, strata_level, variable_name, estimate_name, additional_level) |>
      glimpse()
    #> Rows: 17,628
    #> Columns: 5
    #> $ group_level      <chr> "condition_occurrence", "condition_occurrence", "cond…
    #> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
    #> $ variable_name    <chr> "Diverticular disease", "Injury of medial collateral …
    #> $ estimate_name    <chr> "count_subjects", "count_subjects", "count_subjects",…
    #> $ additional_level <chr> "0 &&& No matching concept", "0 &&& No matching conce…

We can also filter the clinical table to a specific time window by setting the dateRange argument.

    summarisedResult <- summariseConceptIdCounts(cdm,
                                                 omopTableName = "condition_occurrence",
                                                 dateRange = as.Date(c("1990-01-01", "2010-01-01")))
    summarisedResult |>
      omopgenerics::settings()|>
      glimpse()
    #> Rows: 1
    #> Columns: 10
    #> $ result_id          <int> 1
    #> $ result_type        <chr> "summarise_concept_id_counts"
    #> $ package_name       <chr> "OmopSketch"
    #> $ package_version    <chr> "0.5.1"
    #> $ group              <chr> "omop_table"
    #> $ strata             <chr> ""
    #> $ additional         <chr> "source_concept_id &&& source_concept_name"
    #> $ min_cell_count     <chr> "0"
    #> $ study_period_end   <chr> "2010-01-01"
    #> $ study_period_start <chr> "1990-01-01"

Finally, you can summarise concept counts on a subset of records by specifying the `sample` argument.

    summariseConceptIdCounts(cdm,
                             omopTableName = "condition_occurrence",
                             sample = 50) |>
      select(group_level, variable_name, estimate_name) |>
      glimpse()
    #> Rows: 36
    #> Columns: 3
    #> $ group_level   <chr> "condition_occurrence", "condition_occurrence", "conditi…
    #> $ variable_name <chr> "Escherichia coli urinary tract infection", "First degre…
    #> $ estimate_name <chr> "count_records", "count_records", "count_records", "coun…

## 3.1 Display the results

Finally, concept counts can be visualised using `tableConceptIdCounts()`. By default, it generates an interactive reactable table, but DT datatables are also supported.

    result <- summariseConceptIdCounts(cdm,
      omopTableName = "measurement",
      countBy = "record"
    )
    tableConceptIdCounts(result, type = "reactable")

    tableConceptIdCounts(result, type = "datatable")

The `display` argument in tableConceptIdCounts() controls which concept counts are shown. Available options include `display = "overall"`. It is the default option and it shows both standard and source concept counts.

    tableConceptIdCounts(result, display = "overall")

If `display = "standard"` the table shows only standard concept_id and concept_name counts.

    tableConceptIdCounts(result, display = "standard")

If `display = "source"` the table shows only source concept_id and concept_name counts.

    tableConceptIdCounts(result, display = "source")
    #> Warning: Values from `estimate_value` are not uniquely identified; output will contain
    #> list-cols.
    #> • Use `values_fn = list` to suppress this warning.
    #> • Use `values_fn = {summary_fun}` to summarise duplicates.
    #> • Use the following dplyr code to identify duplicates.
    #>   {data} |>
    #>   dplyr::summarise(n = dplyr::n(), .by = c(cdm_name, group_level,
    #>   source_concept_name, source_concept_id, result_id, group_name, estimate_type,
    #>   estimate_name)) |>
    #>   dplyr::filter(n > 1L)

If `display = "missing source"` the table shows only counts for concept ids that are missing a corresponding source concept id.

    tableConceptIdCounts(result, display = "missing source")

If `display = "missing standard"` the table shows only counts for source concept ids that are missing a mapped standard concept id.

    tableConceptIdCounts(result, display = "missing standard")
    #> Warning: `result` does not contain any `summarise_concept_id_counts` data.

## 3.2 Display the most frequent concepts

You can use the `tableTopConceptCounts()` function to display the most frequent concepts in a OMOP CDM table in formatted table. By default, the function returns a gt table, but you can also choose from other output formats, including flextable, datatable, and reactable.

    result <- summariseConceptIdCounts(cdm,
      omopTableName = "drug_exposure",
      countBy = "record"
    )
    tableTopConceptCounts(result, type = "gt")

Top | Cdm name
--- | ---
mockOmopSketch
drug_exposure
1 | Standard: celecoxib 200 MG Oral Capsule [Celebrex] (1118088) Source: No matching concept (0) 100
2 | Standard: meningococcal polysaccharide (groups A, C, Y and W-135) diphtheria toxoid conjugate vaccine (MCV4P) (40213180) Source: No matching concept (0) 100
3 | Standard: hepatitis A vaccine, adult dosage (40213296) Source: No matching concept (0) 100
4 | Standard: Phenazopyridine (933724) Source: No matching concept (0) 100
5 | Standard: Meperidine (1102527) Source: No matching concept (0) 100
6 | Standard: Dornase Alfa (1125443) Source: No matching concept (0) 100
7 | Standard: salmeterol (1137529) Source: No matching concept (0) 100
8 | Standard: Galantamine (757627) Source: No matching concept (0) 100
9 | Standard: NITROFURANTOIN, MACROCRYSTALS 50 MG Oral Capsule (920334) Source: No matching concept (0) 100
10 | Standard: Amlodipine 5 MG Oral Tablet (1332419) Source: No matching concept (0) 100

### 3.2.1 Customising the number of top concepts

By default, the function shows the top 10 concepts. You can change this using the `top` argument:

    tableTopConceptCounts(result, top = 5)

Top | Cdm name
--- | ---
mockOmopSketch
drug_exposure
1 | Standard: celecoxib 200 MG Oral Capsule [Celebrex] (1118088) Source: No matching concept (0) 100
2 | Standard: meningococcal polysaccharide (groups A, C, Y and W-135) diphtheria toxoid conjugate vaccine (MCV4P) (40213180) Source: No matching concept (0) 100
3 | Standard: hepatitis A vaccine, adult dosage (40213296) Source: No matching concept (0) 100
4 | Standard: Phenazopyridine (933724) Source: No matching concept (0) 100
5 | Standard: Meperidine (1102527) Source: No matching concept (0) 100

### 3.2.2 Choosing the count type

If your summary includes both record and person counts, you must specify which type to display using the `countBy` argument:

    result <- summariseConceptIdCounts(cdm,
      omopTableName = "drug_exposure",
      countBy = c("record", "person")
    )
    tableTopConceptCounts(result, countBy = "person")

Top | Cdm name
--- | ---
mockOmopSketch
drug_exposure
1 | Standard: Amlodipine 5 MG Oral Tablet (1332419) Source: No matching concept (0) 72
2 | Standard: norelgestromin (1518198) Source: No matching concept (0) 72
3 | Standard: Warfarin Sodium 5 MG Oral Tablet (40163554) Source: No matching concept (0) 71
4 | Standard: Influenza, seasonal, injectable, preservative free (40213154) Source: No matching concept (0) 70
5 | Standard: 1 ML Epinephrine 1 MG/ML Injection (46275916) Source: No matching concept (0) 70
6 | Standard: celecoxib (1118084) Source: No matching concept (0) 70
7 | Standard: Albuterol (1154343) Source: No matching concept (0) 69
8 | Standard: sevoflurane (19039298) Source: No matching concept (0) 69
9 | Standard: Loratadine 5 MG Chewable Tablet (19125062) Source: No matching concept (0) 69
10 | Standard: Midazolam 1 MG/ML Injectable Solution (19078924) Source: No matching concept (0) 69