Streamlit OOP Charting Framework

A maintainable, object-oriented framework for creating consistent Streamlit charts using Plotly.

Overview

This repository demonstrates a design pattern for Streamlit applications where:

1. Charts are Objects: Defined as classes inheriting from BaseStreamlitChart.
2. Logic is Encapsulated: Data filtering, aggregation, and styling happen inside the class.
3. Styles are Consistent: A central ChartStyles configuration ensures specific design systems (fonts, colors) are applied globally, while allowing specific overrides.
4. Backend: Uses Plotly for rich interactivity.

Key Components

src/base_chart.py

The Abstract Base Class (ABC). It handles:

• Filtering: Automatically renders Streamlit widgets for registered filters.
• Aggregation: (Optional) Groups and aggregates raw data (e.g., Sum Cost by Date) before plotting.
• Styling: Applies Plotly layout templates.

src/chart_styles.py

Defines the default "Look and Feel".

• Edit DEFAULTS to change the global theme (font, margins, templates).

src/examples/

Contains concrete chart implementations (e.g., CostBarChart, TimeSeriesChart).

• Implement the generate_chart() method to return a go.Figure.

Usage

1. Installation

pip install -r requirements.txt

2. Running the Demo

streamlit run app.py

3. Semantic Model + PowerBI-style authoring

• The advanced demo loads a semantic model from models/star_schema.yaml that declares fact, dimensions, joins, measures, and default filter fields.
• Shared filters in the sidebar apply across all charts; field wells let you choose dimension fields for X/Color and a measure for Y without touching code.
• Joins are cached and will run through DuckDB when available for faster star-schema workflows; otherwise pandas merges are used.

4. Creating a New Chart

Subclass BaseStreamlitChart and implement generate_chart:

from src.base_chart import BaseStreamlitChart
import plotly.express as px

class MyChart(BaseStreamlitChart):
    def generate_chart(self):
        # self.get_data() returns the Filtered & Aggregated dataframe
        return px.bar(self.get_data(), x="category", y="value")

4. Using Aggregation (PowerBI-style)

Pass raw data and let the chart aggregate it:

# Raw data has many rows per date
chart = MyChart(
    data=raw_df, 
    group_by=["date"], 
    agg_funcs={"value": "sum"}
)
chart.render()

Plotly vs. Altair

This framework was originally designed with Altair but switched to Plotly for better interactivity and mutable object handling. See plotly_vs_altair.md for a detailed comparison.