D3 Visualizations & Heatmaps

Relevant source files

The following files were used as context for generating this wiki page:

• public/js/p3/widget/D3StackedBarChart.js
• public/js/p3/widget/D3BarLineChart.js
• public/js/p3/widget/SubsystemMapHeatmapContainer.js
• public/js/p3/widget/D3HorizontalBarChart.js
• public/js/p3/widget/D3HistogramChart.js
• public/js/p3/widget/D3StackedAreaChart.js
• public/js/p3/widget/SubSystemsOverviewMemoryGrid.js

The D3 Visualizations and Heatmaps module provides a robust set of data-driven components used to render biological and genomic data across the dxkb-web platform. These components leverage the D3.js library (primarily versions 3 and 5) to manipulate the Document Object Model (DOM) and create interactive SVG graphics, including stacked bar charts, histograms, area charts, and complex heatmaps.

The module is designed to handle high-dimensional biological data, such as subsystem distribution, gene counts, and functional profiles. Most visualization widgets are integrated with Dojo-based stores, allowing them to react to state changes (e.g., changes in genome or taxonomy selection) and update their visual representation dynamically.
Sources: public/js/d3.v5/README.md, public/js/p3/widget/SubSystemsOverviewMemoryGrid.js:40-65

Heatmap Architecture and Components

The heatmap system is primarily implemented through the SubsystemMapHeatmapContainer, which utilizes the Hotmap library to render high-performance, interactive heatmaps. This component allows for the visualization of protein families or roles across multiple genomes.

Key Functional Features

• Axis Flipping: Users can transpose the heatmap axes (switching genomes and protein families between rows and columns).
• Clustering: Integration with backend API endpoints to perform hierarchical clustering on genomic data.
• Interactive Selection: Support for cell-level clicks and multi-cell area selection to retrieve specific feature details.
• Export Capabilities: Options to download data as SVG snapshots, TSV, or JSON.

Heatmap Data Flow

The heatmap follows a specific sequence for data updates and rendering:

1. State Update: The container subscribes to updatePmState topics.
2. Data Request: A requestHeatmapData message is published to fetch fresh data from the store.
3. Rendering: Upon receiving updateHeatmapData, the hmapUpdate function formats the raw Solr/JSON response into a matrix compatible with Hotmap.

Sources: public/js/p3/widget/SubsystemMapHeatmapContainer.js:130-160, public/js/p3/widget/SubsystemMapHeatmapContainer.js:425-450

D3 Charting Widgets

The platform includes several specialized D3 charting widgets, each inheriting from Dojo's declare system but utilizing D3 for SVG rendering.

Comparison of Chart Widgets

Widget	File Path	D3 Version	Primary Use Case
Stacked Bar Chart	D3StackedBarChart.js	v3	Visualizing genomic feature distributions with normalization options.
Stacked Area Chart	D3StackedAreaChart.js	v5	Temporal data trends (e.g., variants per year/month).
Bar-Line Chart	D3BarLineChart.js	v5	Dual-axis visualization for count vs. percentage trends.
Horizontal Bar Chart	D3HorizontalBarChart.js	v3	Functional profiles and taxonomy gene counts.
Histogram Chart	D3HistogramChart.js	v3	Frequency distribution of genomic attributes.

Sources: public/js/p3/widget/D3StackedBarChart.js, public/js/p3/widget/D3StackedAreaChart.js, public/js/p3/widget/D3BarLineChart.js

Interaction and Tooltips

All D3 widgets implement a standard tooltip layer. When a user hovers over a chart element (rect, path, or circle), a transition is triggered on a div.tooltip element.

// Typical tooltip implementation in D3 widgets
.on('mouseover', function (d) {
  self.tooltipLayer.transition()
    .duration(200)
    .style('opacity', 0.95);
  var content = (d.tooltip) ? d.tooltip.apply(this, arguments) : lang.replace('{label} ({count})', d);
  self.tooltipLayer.html(content)
    .style('left', d3.event.pageX + 'px')
    .style('top', d3.event.pageY + 'px');
})

Sources: public/js/p3/widget/D3StackedBarChart.js:145-160, public/js/p3/widget/D3HistogramChart.js:105-115

Subsystem Overview Visualization

The SubSystemsOverviewMemoryGrid component specifically handles the visualization of Subsystem Super Classes. It utilizes a combination of a Pie Chart and a vertical Coverage Bar.

Pie Chart Logic

The pie chart visualizes the distribution of gene counts across different functional categories. It includes a custom legend that allows users to expand super-classes into sub-classes.

• D3 Layout: Uses d3.layout.pie() and d3.svg.arc().
• Color Coding: Maps categories to specific colors defined in DataVisualizationTheme.
• State Management: Listens for changes in genome or taxonomy state to re-draw the graph.

Coverage Bar Chart

In genome views, a specialized bar chart is rendered next to the pie chart to show "Subsystem Coverage"—the proportion of genes assigned to a subsystem versus those that are not.

• Proportion Calculation: Calculated as totalSubsystems / totalGenomes.
• Visuals: Uses standard SVG rect elements with tooltips providing specific counts for hypothetical vs. non-hypothetical proteins.

Sources: public/js/p3/widget/SubSystemsOverviewMemoryGrid.js:365-420

Data Rendering and Updating

Widgets typically implement render(data) and update(data) methods. The render method initializes axes, scales, and SVG elements, while the update method uses D3 transitions to smoothly morph elements to new data states.

Scales and Axis Handling

Widgets utilize ordinal scales for categorical data (e.g., labels) and linear or log scales for quantitative data.

• X-Scale: Often handles bar positioning via rangeRoundBands.
• Y-Scale: Typically maps data values to the canvas height, often inverted for SVG coordinate systems.

Sources: public/js/p3/widget/D3HistogramChart.js:65-85, public/js/p3/widget/D3VerticalBarChart.js:45-60

Sorting and Normalization

The D3StackedBarChart includes advanced controls for visual presentation:

• Normalization: Toggles between raw counts and percentage-based stacking (scaling to 100).
• Sorting: Allows re-ordering bars based on 'label' (alphabetical) or 'value' (magnitude).

Sources: public/js/p3/widget/D3StackedBarChart.js:285-330, public/js/p3/widget/D3StackedBarChart.js:335-380

The visualization module ensures that complex genomic datasets are accessible through interactive, state-aware components that provide both high-level overviews and detailed, filtered data views.