Analytics: Activity Heatmap

The Activity Heatmap is a data visualization feature that provides a graphical representation of messaging activity, distributed by the hour of the day and the day of the week. It allows users to quickly identify peak messaging times and activity patterns. The heatmap is one of several visualizations available within the ActivityChart component, which also includes column charts for activity by hour, day, and month.

This feature is part of the analytics suite displayed on the results page after a user searches their chat database. The heatmap uses color intensity to represent the volume of messages, with warmer colors indicating higher activity.

Architecture and Data Flow

The Activity Heatmap functionality is composed of several distinct components, from data processing to UI rendering. The flow begins with the main MessageDataProcessor orchestrating the data extraction, which is then passed through a series of React components to be rendered by the amCharts library.

The following diagram illustrates the high-level component architecture and data flow for generating the heatmap.

Data Processing

The core logic for preparing data for the heatmap resides in the HeatmapProcessor class. This processor transforms the raw list of messages into a structured format suitable for the amCharts heatmap component.

Sources: web/src/analytics/processors/heatmapProcessor.js

HeatmapProcessor Class

This class is responsible for generating the heatmap data. It is instantiated with the list of messages and the names of the chats being analyzed.

Sources: web/src/analytics/processors/heatmapProcessor.js:8-12

Heatmap Data Generation Flow

The processHeatmapHourPerDay method follows a clear sequence to generate the data:

1. A template data structure is created using generateHeatmapTemplate. This template is a nested array representing each hour of each day of the week.
2. It iterates through every message. For each message, it extracts the weekday and hour.
3. It finds the corresponding entry in the template and increments the message count for the specific chatName.
4. Finally, it flattens the nested structure into a single array of objects, ensuring that every chat has a value (defaulting to 0) for every hour slot.

The following flowchart visualizes this process:

Data Structure

The data processing results in an array of objects, where each object represents a specific hour of a specific day and contains the message count for the selected chat.

• weekday: The day of the week (e.g., 'Sun', 'Mon'). Sourced from DAYS_OF_WEEK in constants.js.
• hour: The hour of the day as a two-digit string (e.g., '00', '01'). Sourced from HOURS_IN_DAY in constants.js.
• [chatName]: A dynamic key matching the name of the chat, holding the integer message count for that time slot.

Example of a single data point object:

{
  "weekday": "Mon",
  "hour": "14",
  "John Doe": 25
}

Sources: web/src/analytics/utils/dataStructureHelpers.js:9-15, web/src/analytics/processors/heatmapProcessor.js:39-45, web/src/analytics/constants.js:21,29

UI Rendering

The user interface for the heatmap is managed by a hierarchy of React components, culminating in the HeatMapChart which uses the amCharts 5 library for the actual rendering.

Component Interaction

The user interaction to display the heatmap involves selecting an option from a dropdown, which triggers state changes and conditional rendering.

ActivityChart Component

This component acts as a container and controller for various activity-related charts. It uses a SelectPicker from the rsuite library to allow users to choose the desired visualization. When "Heat Map hour per day" is selected, it updates its internal state to conditionally render the HeatMapChart component, passing the processed data to it.

Sources: web/src/analytics/components/ActivityChart.jsx:10-18, 45-47

HeatMapChart Component

This is the core component responsible for rendering the heatmap visualization using amCharts 5.

Key implementation details inside its useEffect hook:

1. Root Element: An am5.Root is created, targeting a div with the ID chartDiv.
2. Chart Initialization: An am5xy.XYChart instance is created.
3. Axes Configuration:
   • A CategoryAxis (yAxis) is configured for the days of the week (weekday), with data like [{ weekday: 'Sun' }, ...]. The axis is inverted to show Sunday at the top.
   • Another CategoryAxis (xAxis) is configured for the hours of the day (hour), with data like [{ hour: '00' }, ...].
4. Series Creation:
   • A ColumnSeries is used to create the heatmap cells.
   • It maps hour to the x-axis, weekday to the y-axis, and the message count (from the dynamic chatName property) to the valueField.
5. Heat Rules: A heat rule is applied to the series' columns. This rule maps the value of each cell to a color gradient, from a minimum color (0xfffb77 - yellow) to a maximum color (0xfe131a - red).
6. Heat Legend: A HeatLegend is added to the bottom of the chart to provide a key for the color gradient.

Sources: web/src/analytics/components/charts/heatMapChart.jsx:15-101

Conclusion

The Activity Heatmap feature is a powerful tool for visualizing WhatsApp chat patterns. It effectively combines robust data processing via the HeatmapProcessor with a sophisticated rendering implementation using amCharts 5. The modular architecture, separating data logic from presentation, allows for clear maintenance and potential extension. The result is an intuitive, color-coded grid that gives users an immediate understanding of their messaging habits throughout the week.