/
Chapter 11. MassCPR-Major Query Status Redesign

Chapter 11. MassCPR-Major Query Status Redesign

May 15, 2026

Major Query Status Redesign

The i2b2 web client now includes a library of modular data visualizations that can be used with Query Status. A configuration file (`/js-i2b2/cells/CRC/QueryStatus/breakdowns.json`) maps each query breakdown to one or more of these visualizations. Users can switch between different visualizations using a drop-down menu on the top-right corner of each breakdown. Query Report has also been updated to use these new visualizations.

This new feature greatly expands how breakdowns can be used in i2b2. Previously, bar charts were the only way to view query breakdowns. This limited breakdowns to a small number of categories before the charts became unreadable. By pairing custom SQL breakdowns with the appropriate visualization(s), any type of breakdown data can be returned to the web client presented to the user in different ways.

Default Visualizations

By default, i2b2 1.8.3 includes several breakdowns and mapped data visualizations. These include demographic breakdowns mapped to bar charts, pie charts, and line graphs; an NIH-style enrollment table; a table summary of the data; and an option to download the breakdown as a comma-separated values (CSV) file.

Below is the standard Bar Chart showing a drop-down menu with additional visualization options.

The Line Chart visualization is useful for breakdowns where the categories are numbers or dates, such as patient age.

The Pie Chart visualization shows the proportion of patients in each category.

The NIH Enrollment Table visualization is based on forms used by the U.S. National Institutes of Health to collect demographic breakdowns (race, ethnicity, and sex) for clinical studies.

The Table Summary displays a simple table with each breakdown group and the corresponding number of patients.

The CSV Download option, rather than displaying the breakdown within the web client, exports the data to a CSV file that can be opened in other data analysis programs.



Optional Visualizations

The i2b2 1.8.3 web client includes several additional data visualizations, which by default, are not mapped to any breakdowns. The i2b2 software includes an optional database script to add new custom SQL breakdowns to the QT_QUERY_RESULT_TYPE and QT_BREAKDOWN_PATH tables. Once these have been installed, they can be mapped in the i2b2 web client file (via `js-i2b2/cells/CRC/QueryStatus/breakdowns.json`) to their corresponding visualizations.

The Table Bar Chart is similar to the Table Summary visualization, but adds a small horizontal bar chart in the rightmost column. This is useful for breakdowns with so many categories that they would not be easily readable in a standard vertical bar chart. An optional diagnosis category breakdown is included with i2b2 1.8.3 to demonstrate this new visualization. (Note that to improve performance of this breakdown, a new table is added to the database to pre-compute patients’ diagnosis categories.)

The ZIP Code visualization displays the geographic location of patients matching the query. It is interactive, allowing the user to quickly zoom to different configurable levels (e.g., city, state, region); select an aggregation level (e.g., 5-digit ZIP Code, 3-digit ZIP Code, or state); and select a normalization type (e.g., actual counts - no normalization, or dividing by the total number of patients in the region). (Note that 5-digit ZIP Codes cannot be used if the underlying i2b2 data has been de-identified by removing patient ZIP Codes or replacing them with 3-digit ZIP Codes. Also, shape files have only been included in i2b2 1.8.3 for regions in the United States. Though these can be replaced with any shape file that uses the standard GeoJSON format.)

The Pathogen Timeline displays counts by month or year of COVID-19, influenza, and RSV diagnoses in the patients who match a query. These three diagnoses are included as examples in the custom SQL breakdown. However, these can be changed to any type and number of temporal values. For example, this visualization can be used with an “Encounter Timeline” breakdown that returns the number of inpatient and outpatient visits over time. The visualization also supports overlays, with data from an external file or API. This is demonstrated with an example file containing COVID-19 wastewater pathogen levels in Boston, Massachusetts, from 2020-2025. (The data were obtained from the Massachusetts Water Resources Authority wastewater tracking website, https://www.mwra.com/biobot/biobotdata.htm.)

Mapping Visualizations to Breakdowns

Once a visualization is registered to the Query Status/Report subsystem (via `/js-i2b2/cells/CRC/QueryStatus/config.json`), it can then be mapped to one or more breakdowns that can be returned from the server (via `/js-i2b2/cells/CRC/QueryStatus/breakdowns.json`).  

The mapping JSON file is a simple nested dictionary with the first level being the code of the breakdown as returned from the server, and the second level being the code of one or more breakdown visualization modules that have been registered to the subsystem.

In some special instances a visualization can be created as a “Super Module” which will handle the rendering of multiple breakdown results within its individual area.  Currently this is only being done to display the status of data request submissions but is an option for you if you are developing new visualization modules.

For full configuration details see the README.md file within the QueryStatus directory for the most up-to-date information. [https://github.com/hms-dbmi/i2b2v2-webclient/blob/v1.8.3/js-i2b2/cells/CRC/QueryStatus/README.md]

Creating New Breakdown Visualizations

When developing a new breakdown visualization all related files should be placed in its own folder within the `/js-i2b2/cells/CRC/QueryStatus` directory.  Additionally, a registration entry needs to be placed within `/js-i2b2/cells/CRC/QueryStatus/config.json` so that the Query Status and Query Report subsystems are aware of your visualization module.  See the extensive documentation (`README.md` files) within the Query Status subsystem’s directories and other included visualization modules for examples of how to write your own module.

Configuring the Query Report

The Query Report subsystem exists within the `/js-i2b2/cells/CRC/QueryReport/` directory and is configured using the `ReportConfig.json` file to set which visualizations are displayed for each breakdown in the Query Report.  To change or style the text on the printed report you can edit the `QueryReport.html` file within the subsystem’s root directory.

Displaying Query Status in a Separate Tab

In previous versions of i2b2, Query Status appears in a fixed region below Find Patients. In 1.8.3, users can now move Query Status to a separate tab to provide more space to view the breakdown visualizations. The default location for Query Status can be changed using the tab configuration file found at `/js-i2b2/i2b2_tabs.json`.  The configuration file is a lightweight subset of the Item configuration options found in the Golden-Layout framework found at https://golden-layout.com/docs/ItemConfig.html.