dxpr: an R package for generating analysis-ready data from electronic health records—diagnoses and procedures

Code format transformation

The dxpr package first transforms ICD diagnostic codes into a uniform format before code grouping. ICD-9 and ICD-10 diagnostic codes (US Centers for Medicare & Medicaid Services, 2017a) have two formats, namely decimal (with a decimal place separating the code) and short formats. Different hospitals, grouping methods, or standards coded ICD into different formats. For example, studies using Clinical Classifications Software (CCS) (HCUP, 2017; HCUP, 2019a) and comorbidity measures, such as Elixhauser and Charlson (Elixhauser et al., 1998; Menendez et al., 2014; Moore et al., 2017), have coded the ICD in a short format, and a phenome-wide association study (PheWAS) (Denny et al., 2010) coded the ICD in a decimal format. Therefore, format transformation is required before code grouping, and the transformation type is decided by the chosen grouping method.

The transformation function (icdDxShortToDecimal) converts ICD-9 and ICD-10 codes into a uniform decimal format because a decimal format is needed for grouping diagnostic codes in PheWAS classification. Similar to icdDxShortToDecimal, icdDxDecimalToShort function converts diagnostic codes into a uniform short format, which can be used for grouping to CCS, Elixhauser, or other classifications. These transformative functions not only convert ICD codes into uniform format codes but also check for potential coding errors. We provide two types of warning messages: wrong ICD format and wrong ICD version. Additional suggestions are generated to help users adjust potential incorrect ICD codes if available.

Code grouping

The code grouping functions collapse clinical diagnostic data (ICD-9/ICD-10 codes) (US Centers for Medicare & Medicaid Services, 2017a) into a smaller number of clinically meaningful categories that are more useful for presenting descriptive statistics than using individual diagnostic codes (HCUP, 2019b). The dxpr package supports four strategies to group EHR diagnosis codes, namely CCS (US Centers for Medicare & Medicaid Services, 2017b), PheWAS (Denny et al., 2010) (icdDxToPheWAS), comorbidity measures (Elixhauser et al., 1998; Menendez et al., 2014; Moore et al., 2017), and self-defining grouping methods. The CCS grouping strategies includes single-level CCS (icdDxToCCS) and multiple-level CCS (icdDxToCCSLvl) (HCUP, 2017; HCUP, 2019a), comorbidity measures (icdDxToComorbid) includes Elixhauser, Agency for Healthcare Research and Quality (AHRQ) and Charlson (Elixhauser et al., 1998; Menendez et al., 2014; Moore et al., 2017), and self-defining grouping methods includes precise matching (icdDxToCustom) and searching for lines containing a match (icdDxToCustomGrep). The grouping functions return two tables of the dataset, one is data with the corresponding grouping categories of each ICD (Table 2), and the other is summarized data exhibiting the earliest/latest record date and diagnosis counts in the same grouping category for each patient (Table 3). For example, after executing function icdDxToCCS for the records of patients A and B, two output types are shown in Tables 2 and 3, respectively. Patient A has three diagnosis records (ICD codes: 78550, 78552, and 785.59), which are all in the “shock” category of the CCS classification, with the earliest record on September 1, 2013 and the latest one on October 1, 2014. The icdDxToCCS function mapped corresponding CCS categories for these ICD codes and returned the grouping results (Table 2). Similarly, patient B has two diagnosis records (ICD codes: 78552 and 250.00) in the “shock” category and “Diabetes mellitus without complication” category of CCS classification, and the grouping results are also shown in Table 2. According to these diagnosis records shown in Table 2, Table 3 shows that icdDxToCCS function can summarize the first and last dates of diagnosis, the total number of diagnoses, and the period between the first and last diagnoses for each category, which can be used for designing the analysis strategy. While icdDxToCCS groups codes into single-level CCS, icdDxToCCSLvl groups codes into multi-level CCS. Multi-level CCS expands single-level CCS into a four-level hierarchical system for diagnoses, which provide the opportunity to examine general aggregations or to assess specific conditions (HCUP, 2019a). For instance, if a user wishes to group codes into the second level of multi-level CCS, then this task can be performed through simply entering “ccslvl2” as the assigned grouping type. These grouping functions not only facilitate users to convert original diagnosis records from detailed levels into clinically meaningful diagnostic groups for further analysis but also provide aggregated information of each diagnostic group that can help research design and hypothesis generation, such as filtering out data based on specified criteria (e.g., first diagnosis dates of a specific chronic disease).

The usage of code classification function for CCS is as follows:

Case selection

In clinical data analysis projects, the most crucial step is case definition and selection, such as defining Lyme disease cases from claims data (Tseng et al., 2015) or defining acute ischemic stroke from EHR (Tseng et al., 2020). The analysis results could change based on case definition and lead to a different conclusion. The query function selectCases can select cases matching case definitions. Users can select cases based on diagnosis (ICD) or diagnostic categories (CCS, PheWAS, comorbidities, or self-defined diagnostic categories). Moreover, the function provides an option to set the minimum number of diagnoses within a specific duration. For example, users can extract diabetes cases by assigning at least two diagnoses in ICD codes “250.xx” or “E10.x-E14.x” within 730 days when a user applies the validated diabetes case definition: “two physician claims within 2 years with diagnosis codes 250.xx or E10.x-E14.x” (Chen et al., 2010). The output dataset of this function provides the start and end dates of the cases, the number of days between them, and the most common ICD codes used in the case definition. Furthermore, a list of people who did not satisfy the required case conditions or practically match the case definition is appended in the returned output table, and these individuals can be defined as a control group or be removed.

Eligible period identification

In some clinical data, such as claims data, individuals can join or leave the program on different dates, and the length of available records might affect the analysis completeness. The dxpr package provides a function getEligiblePeriod for researchers to identify the first/last record date for each patient. These outputs can be used as an index date for case exclusion, such as cases without at least 6 months washout or follow-up period, or further data splitting.

Data splitting based on index date and moving window

In clinical data analysis projects, users usually need to extract data based on a specific clinical event (e.g., extracting data before the first Lyme disease diagnosis in the records (Tseng et al., 2017)). The date of the specific event (index date) can be the first/last record date of the events or patient record, and the table of the index date for each individual can be generated using selectCases or getEligiblePeriod function, respectively. The dxpr package provides a convenient function splitDataByDate that can split data through classifying the data recorded before or after the defined index date and calculating the period between the record date and index date based on a self-defined window. For example, if a user needs to aggregate the data by using a 30-day window, the data recorded on 15 and 45 days after the index date will be defined as window 1 and window 2, respectively. The output of splitDataByDate function helps users to split the data based on the study design, and this can be applied to further time-series multiple-measurement analysis with period information.

Condition era generation

Condition era is a means to apply consistent rules for medical conditions to infer distinct episodes in care, generated through integrating distributed clinical records into a single progression record (Reisinger et al., 2010). The concept of condition era is committed to the length of the persistence gap: when the time interval of any two consecutive admissions for certain conditions is smaller than the length of the persistence gap, then these two admission events will be aggregated into the same condition era. Each condition era consists of one or many events, and differences between any two consecutive admission events are all within the persistence gap. For example, an episode of influenza may include single or multiple outpatient visits, and the length of the influenza course should be the period between the first and last visits of the episode. getConditionEra function calculates condition era by using the grouped categories or self-defining groups of each patient and then generates a table with individual IDs, the first and last record of an era, and the sequence number of each episode. Users can easily convert scattered diagnoses into an episode of condition based on the chararistics of target disease progression with the proposed function.

Analysis-ready data generation

After data integration and wrangling, researchers often need to further analyze these processed data, and function groupedDataLongToWide converts the long format of grouped data into a wide format, which is fit for other analytical and plotting packages, such as tableone (Yoshida & Bartel, 2020) package.

Pareto chart of error ICD

When code transformation is implemented in the dxpr package, it generates unified data of diagnosis codes with potential errors. Function plotICDError visualizes codes with potential error by using the Pareto chart containing a bar plot where error ICD codes are arranged in descending order, and the cumulative total is represented by the line. Users can sort based on the counts of error ICD codes and set the top selected number of the ordered dataset. For instance, if a user chooses the top 10 ordinal rankings, then the Pareto chart shows a plot of the top 10 common error ICD codes and a list with details of these 10 and other error ICD codes.

Bar chart of diagnostic categories

Function plotDiagCat provides an overview of the grouping categories of the diagnoses and summarizes the proportion of individuals diagnosed with grouped diagnostic categories in the whole study population or case and control groups in a bar chart. Users can observe the number and percentage of diagnostic categories in their dataset through this function. Furthermore, this function compares the usage of significantly different diagnostic categories between case and control groups by using the chi-square test or Fisher’s exact test when the data does not match the assumptions of the chi-square test. The default level of statistical significance is considered at 5% (p = 0.05). Researchers can set a threshold of the top N significant grouped categories and the minimum prevalence of the diagnostic groups in the case or control group.

The “percentage” column shows the proportion of individuals diagnosed with the diagnostic category in the group. For example, there are 38 patients in the sample file, and “Renal Failure” defined in Elixhauser comorbidity accounts for 63.16% of the population (24/38).