In rmgpanw/codemapper: Functions for Mapping Between Clinical Coding Systems

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(codemapper)

Introduction

The goal of codemapper is to simplify working with clinical codes for research using electronic health records. The workflow is as follows:

1. Create a local resource containing lookup and mapping tables for various clinical codings systems (e.g. ICD10 and Read codes)
2. Build clinical code lists for conditions of interest by querying this resource

This vignette demonstrates the above using dummy data included with the package. You can try out the steps either locally by installing codemapper on your own machine, or online by clicking on the following link to RStudio Cloud[^1] and navigating to this Rmd file in the 'vignettes' directory:

[^1]: You will be asked to sign up for a free account if you do not have one already.

Also included are functions for mapping between different clinical coding systems, and using CALIBER code lists[@kuan2019] and Phecodes[@denny2016; @wu2019] with UK Biobank data. See vignettes vignette('map_codes') vignette('caliber') and vignette('phecodes') for further information.

Build a local clinical codes lookup and mappings resource

The first step is to create a local database containing lookup and mapping tables for various clinical coding systems using build_all_lkps_maps().

By default this will download the following resources:

• UK Biobank resource 592 (Clinical coding classification systems and maps)

• UK Biobank data codings file

• Phecode lookup and mapping files (for ICD9 and ICD10 to phecode)

The tables are imported into R, reformatted, and stored as a named list of data frames:

# build dummy all_lkps_maps resource (supressing warning messages)
all_lkps_maps_dummy <- build_all_lkps_maps_dummy()

# view first few rows of ICD10 lookup table
head(all_lkps_maps_dummy$icd10_lkp)

Many of the functions in this package will require this object (supplied to argument all_lkps_maps).

Instead of re-running build_all_lkps_maps() in each new R session, the output can be saved to a SQLite database file:

# write to SQLite database file
db_path <- suppressMessages(all_lkps_maps_to_db(all_lkps_maps = all_lkps_maps_dummy, 
                               db_path = tempfile()))

Connect to this and create a named list of dbplyr::tbl_dbi[^2] objects:

[^2]: If you have not used SQL with R before, I recommend reading the Get started vignette from the dbplyr package.

# connect to SQLite database
con <- DBI::dbConnect(RSQLite::SQLite(), db_path)

# create named list of tbl_db objects
all_lkps_maps_dummy_db <- ukbwranglr::db_tables_to_list(con)

# view first few rows of ICD10 lookup table
head(all_lkps_maps_dummy_db$icd10_lkp)

Either will work with the functions described in the remainder of this vignette, but the SQLite database option is recommended. For convenience, record the path to your SQLite database in a .Renviron file:

ALL_LKPS_MAPS_DB=/PATH/TO/all_lkps_maps.db

Assuming you are using a RStudio project, this will set an environmental variable called ALL_LKPS_MAPS_DB when you start a new R session. Functions with an all_lkps_maps argument will automatically search for this variable and attempt to connect with the database file at that path, meaning you will not need to repeatedly type this in your self.

Build a clinical code list

Explore codes

Codes may be explored with:

• lookup_codes():

```r
lookup_codes(codes = c("E10", "E11"),
             code_type = "icd10",
             all_lkps_maps = all_lkps_maps_dummy_db)
```

• codes_starting_with():

```r
codes_starting_with(codes = "E1",
             code_type = "icd10",
             all_lkps_maps = all_lkps_maps_dummy_db)
```

• code_descriptions_like():

```r
code_descriptions_like(
  reg_expr = "cyst",
  code_type = "icd10",
  all_lkps_maps = all_lkps_maps_dummy_db
)
```

R Shiny app

Use RunCodelistBuilder() to launch a R Shiny app for building a clinical code list.[^3] The aim is to develop a broad search strategy that captures all clinincal codes that might possibly be included, then download the search results and manually select and sub-categorise the final set of codes:

[^3]: This is still quite experimental, but should hopefully work for the basic workflow described here.

{width="100%"}

Microsoft excel auto-formatting can cause problems with certain codes e.g. Read 3 '.7944' (Creation of permanent gastrostomy) may be reformatted to '7944'. Ideally use a different text editor.

rmgpanw/codemapper documentation built on Aug. 30, 2023, 4:07 p.m.