Skip to content

ADR-009: Matplotlib for Visualization

Status: SUPERSEDED - Originally implemented 2025-01-15; the visualization approach has changed.

[!IMPORTANT] This ADR proposed Matplotlib PNG charts generated by an analytics/ package. The current implementation does not use Matplotlib. Visualization is provided by a Streamlit dashboard (popupsim/frontend/dashboard.py) using Plotly for interactive charts. Matplotlib is not a project dependency, and the analytics/ package does not exist. The backend exports CSV/JSON results (via the Retrofit Workflow context), which the dashboard reads. The content below is retained for historical context only.

Context

Need visualization for simulation results. Full version will have web interface, but MVP needs simple charts.

Decision

Use Matplotlib for generating static charts (PNG files).

Rationale

  • Simple: Easy to use, well-known library
  • Offline: No web server required
  • Sufficient: Meets MVP visualization needs
  • Python native: Integrated in Python ecosystem
  • No frontend developer: Backend team can handle it
  • Fast development: Quick to implement basic charts

Alternatives Considered

  • Matplotlib — Chosen
  • Plotly: Interactive but requires web server
  • Bokeh: Overkill for static charts
  • Seaborn: Built on Matplotlib, no significant advantage
  • Custom web charts: Requires frontend development

Implementation in MVP

Visualization Components

# analytics/infrastructure/visualization/visualizer.py
class Visualizer:
    def create_throughput_chart(self, kpis: ThroughputKPI) -> Path:
        fig, ax = plt.subplots(figsize=(10, 6))
        ax.bar(['Wagons/Hour', 'Total Processed'], [kpis.wagons_per_hour, kpis.total_wagons])
        plt.savefig('throughput_chart.png')
        return Path('throughput_chart.png')

    def create_gantt_chart(self, events: list[Event]) -> Path:
        # Generate Gantt chart for locomotive and wagon activities
        return self._create_gantt_visualization(events)

Chart Types Generated

  • Throughput Charts: Wagons per hour, total processed
  • Utilization Charts: Workshop station usage over time
  • Gantt Charts: Locomotive and wagon activity timelines
  • Bottleneck Analysis: Resource utilization heatmaps

Consequences

Achieved

  • Fast Implementation: Charts generated in <1 second
  • No Web Complexity: Offline PNG files, no server required
  • Static Output: PNG charts suitable for reports
  • Multiple Chart Types: Throughput, utilization, Gantt, and bottleneck charts
  • Export Ready: PNG files easy to include in presentations

Files Implementing the Current (Superseded-By) Approach

  • popupsim/frontend/dashboard.py - Streamlit dashboard entry point
  • popupsim/frontend/dashboard_components/ - Plotly-based tabs and charts
  • contexts/retrofit_workflow/infrastructure/exporters/ - CSV/JSON result export consumed by the dashboard