Historical Data Analysis
Relevant source files
The following files were used as context for generating this wiki page:The Historical Data Analysis feature provides a comprehensive "Analytics Command Center" for administrators. It transforms the basic historical view into an advanced dashboard with trending intelligence, context-aware filtering, integrated diagnostic tools, and enhanced data visualization. This system allows for deep analysis of a BMS's performance over time by correlating BMS screenshot data with external sources like hourly weather data.
The core of this feature is built around the AdminHistoricalAnalysis component, which integrates several specialized child components to create a unified and powerful analytics experience. It is designed to be backward-compatible, with admin-specific features enabled through optional props.
Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md, ADMIN_HISTORICAL_ANALYSIS_OVERHAUL.md
Architecture
The Historical Data Analysis system is a composite UI built from several distinct React components, orchestrated by the AdminHistoricalAnalysis container. Data fetching and state management are centralized in the useAnalyticsData hook, which provides processed and filtered data to the various UI components.
This diagram shows the high-level component architecture for the admin historical analysis view.
Key Components
| Component | Description | Source File |
|---|---|---|
AdminHistoricalAnalysis | The main container component that integrates all analytics elements, manages state like the visible time range, and coordinates data flow between child components. | components/admin/AdminHistoricalAnalysis.tsx |
useAnalyticsData | A custom React hook responsible for fetching system analytics, filtering history records, and processing alerts for display. | hooks/useAnalyticsData.ts |
TrendingOverview | A dashboard that displays high-level trending metrics like average charge/discharge rates and alert counts. | components/admin/analytics/TrendingOverview.tsx |
HistoricalChart | A highly configurable and interactive chart for visualizing time-series data with advanced features like statistical bands, annotations, and data source differentiation. | components/HistoricalChart.tsx |
ToolsPanel | A panel providing admin-specific actions like running diagnostics or triggering AI-powered analysis. | components/admin/analytics/ToolsPanel.tsx |
AlertAnalysis | A component that displays a list of alerts, dynamically filtered to match the visible time range of the HistoricalChart. | HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md |
Data Fetching and Processing
Data handling is centralized within the useAnalyticsData custom hook, which simplifies the logic in the main AdminHistoricalAnalysis component.
Sources: hooks/useAnalyticsData.ts
useAnalyticsData Hook
This hook is responsible for:
- Fetching system analytics from the
/system-analyticsendpoint. - Filtering the main history records to match the selected system.
- Extracting and deduplicating alerts from the analysis records.
- Filtering alerts based on the visible time range provided by the chart's zoom/pan events.
- Providing a
refreshAnalyticsfunction to re-fetch data on demand.
Sources: hooks/useAnalyticsData.ts:1-123
The hook returns a structured object containing all the necessary data and state for the UI.
This diagram illustrates the data structure returned by the useAnalyticsData hook.
Sources: hooks/useAnalyticsData.ts:109-116
Alert Deduplication
To prevent visual clutter from repeated alerts, a Set is used to track unique alerts based on a composite key of timestamp, type, and message.
// From hooks/useAnalyticsData.ts
const uniqueKey = `${record.timestamp}-${alert.type}-${alert.message}`;
if (!alertsSet.has(uniqueKey)) {
alertsSet.add(uniqueKey);
// ... add to alerts array
}
Sources: hooks/useAnalyticsData.ts:80-86, HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Data Visualization (HistoricalChart)
The HistoricalChart.tsx component is the centerpiece of the analysis view, offering several advanced features for administrators.
Sources: components/HistoricalChart.tsx
Deterministic Rendering
To prevent stale state and ensure the chart updates reliably when its data or configuration changes, a chartKey is generated from all relevant props. Changing this key forces React to unmount and remount the component, guaranteeing a fresh render.
// From components/HistoricalChart.tsx
const chartKey = useMemo(() => {
return JSON.stringify({
systemId: selectedSystemId,
startDate,
endDate,
metricConfig: Object.keys(metricConfig).sort(),
zoomPercentage,
chartView,
useMergedData
});
}, [/* dependencies */]);
// <div key={chartKey}>...chart content...</div>
Sources: ADMIN_HISTORICAL_ANALYSIS_OVERHAUL.md
Statistical Bands
Instead of simple min/max bands which can be noisy, the chart renders tolerance bands using a statistical approach: mean ± 1 standard deviation (1σ). This provides a clearer representation of the typical operating range. The opacity of these bands is also reduced to 0.05 to minimize visual clutter.
Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Merged Data and Source Differentiation
The chart can display merged data from both BMS screenshots and hourly cloud/weather data fetched from the /history?merged=true endpoint. To distinguish between data sources, path styling is applied:
- BMS Data: Solid line, 100% opacity.
- Cloud Data: Dashed line (
8 4), 80% opacity. - Interpolated Data: Dashed line (
8 4), 60% opacity.
Tooltips also display a badge indicating the data source for a given point: "📸 BMS Screenshot", "☁️ Hourly Weather", or "🔮 Interpolated".
Sources: ADMIN_HISTORICAL_ANALYSIS_OVERHAUL.md, HOURLY_CLOUD_SOLAR_INTEGRATION.md
Context-Aware Alert Filtering
The chart implements an onZoomDomainChange callback. As the user zooms or pans the chart, this callback fires with the start and end times of the visible domain. The parent AdminHistoricalAnalysis component uses this information to filter the list of displayed alerts, ensuring only relevant alerts are shown.
Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Other Features
- Alert Annotations: Displays vertical dashed lines and color-coded circles on the chart for critical, warning, or info alerts.
- Solar Overlay: An optional
showSolarOverlayprop can be used to render solar power generation data on the chart. - Reactive Configuration: Toggles for features like data averaging update the chart instantly without a full page reload.
Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Admin Tooling
The analysis view is augmented with panels providing at-a-glance metrics and actionable tools.
Trending Overview
The TrendingOverview component displays key performance indicators calculated from the historical data.
| Metric | Description |
|---|---|
| Avg Charge Rate | The mean charging current in Amperes (A). |
| Avg Load Current | The mean discharging current in Amperes (A). |
| Charge/Discharge Ratio | The balance between charge and discharge, with a color-coded health indicator (Green ≥1.0, Yellow 0.8-1.0, Red <0.8). |
| Total Alerts | A count of all alerts in the system's history, broken down by unique alert types. |
Sources: components/admin/analytics/TrendingOverview.tsx, HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Tools Panel
The ToolsPanel provides buttons for admins to trigger specific backend processes.
| Action | Description |
|---|---|
| Run Diagnostics | Executes a series of diagnostic tests via the runDiagnostics() client service and displays detailed results. |
| Analyze History (Guru) | Triggers an admin-specific AI insights generation process. |
| Predict Maintenance | A placeholder for a future predictive analytics feature. |
Sources: components/admin/analytics/ToolsPanel.tsx, HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
Overall Data Flow
The following sequence diagram illustrates the end-to-end data flow when an admin interacts with the Historical Analysis page.
Conclusion
The Historical Data Analysis overhaul transforms a simple data view into a powerful, multi-faceted "Analytics Command Center." By integrating data from multiple sources, providing advanced and context-aware visualizations, and embedding actionable admin tools, it provides a comprehensive platform for monitoring, diagnosing, and understanding BMS performance over time. The modular architecture, centered around the AdminHistoricalAnalysis component and the useAnalyticsData hook, ensures that the system is both powerful and maintainable.