Add KPI dashboard (#1)

- Add KPI dashboard (d138a118efcae7c37d0252e751f583ef74ab093e)
- Create utils/_charts.py (398985a2ea54ca59d617a20eb1edc703cd6946f4)
- Create _helper.py (993dfd756372a636cd4da0c1ebde5dd1587011a1)
- Create __init__.py (adb97fe7bd1f51e6daf373a33febc131d0b0add9)
- Upload 5 files (863e41a76906a216a9b5baf1a1a97b71073a2ee6)
- Update README.md (e5a22b80bf44189137e80ee91f72041944ba4b1d)
- Update README.md (f2615c72a2e18403916426ec2a6fbbca35c0ca1b)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/images/kpi_dashboard.gif filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,11 +1,36 @@
 ---
 title: KPI Demo
-emoji: 🏃
-colorFrom: pink
-colorTo: yellow
+emoji: 📊
+colorFrom: blue
+colorTo: blue
 sdk: docker
 pinned: false
 license: mit
+short_description: Example of a Key Performance Indicator (KPI) dashboard
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# KPI dashboard
+
+This demo dashboard provides an example of a Key Performance Indicator (KPI) dashboard, designed to help users get started and extend further.
+It uses fictional budget data to demonstrate the capabilities of Vizro using real world applications.
+
+Special thanks to the [#RWFD Real World Fake Data initiative](https://opendatainitiative.io/), a community project that
+provides high-quality fake data for creating realistic dashboard examples for real-world applications.
+
+Note: The data has been additionally edited for the purpose of this example.
+
+<img src="./assets/images/kpi_dashboard.gif" alt="Gif to KPI dashboard">
+
+## Possible future iterations
+
+- Enable selection of year filter
+- Enable current year vs. past year comparison
+- Enable dynamic KPI Cards
+- Bar - Enable drill-downs from Issue to Sub-issue and Product to Sub-product
+- Bar - Reformat numbers with commas in bar chart
+- Bar - Left-align y-axis labels
+- Bar - Shorten labels
+- Line - Customize function to always show selected year vs. past year
+- Table-view - Check why date format does not work on `Date Received`
+- Table-view - Add icons to `On time?` column
+- Table-view - Improve speed by applying cache or overcome limitation that entire data set is loaded in

app.py

@@ -0,0 +1,248 @@
+"""Example to show dashboard configuration."""
+
+import pandas as pd
+import vizro.models as vm
+from utils._charts import COLUMN_DEFS, KPI, bar, choropleth, line, pie
+from utils._helper import clean_data_and_add_columns
+from vizro import Vizro
+from vizro.actions import filter_interaction
+from vizro.tables import dash_ag_grid
+
+# DATA --------------------------------------------------------------------------------------------
+df_complaints = pd.read_csv("https://query.data.world/s/glbdstahsuw3hjgunz3zssggk7dsfu?dws=00000")
+df_complaints = clean_data_and_add_columns(df_complaints)
+vm.Container.add_type("components", KPI)
+
+# SUB-SECTIONS ------------------------------------------------------------------------------------
+kpi_banner = vm.Container(
+    id="kpi-banner",
+    title="",
+    components=[
+        # Note: For some KPIs the icon/sign go in opposite directions as an increase e.g. in complaints is negative
+        KPI(
+            title="Total Complaints",
+            value="75.513",
+            icon="arrow_circle_up",
+            sign="delta-neg",
+            ref_value="6.8% vs. LY",
+        ),
+        KPI(
+            title="Closed Complaints",
+            value="99.6%",
+            icon="arrow_circle_up",
+            sign="delta-pos",
+            ref_value="+0.2% vs. LY",
+        ),
+        KPI(
+            title="Open Complaints",
+            value="0.4%",
+            icon="arrow_circle_down",
+            sign="delta-pos",
+            ref_value="-0.2% vs. LY",
+        ),
+        KPI(
+            title="Timely Response",
+            value="98.1%",
+            icon="arrow_circle_up",
+            sign="delta-pos",
+            ref_value="+10.5% vs. LY",
+        ),
+        KPI(
+            title="Closed w/o cost",
+            value="84.5%",
+            icon="arrow_circle_down",
+            sign="delta-neg",
+            ref_value="-8.5% vs. LY",
+        ),
+        KPI(
+            title="Consumer disputed",
+            value="9.5%",
+            icon="arrow_circle_up",
+            sign="delta-neg",
+            ref_value="+2.3% vs. LY",
+        ),
+    ],
+)
+
+bar_charts_tabbed = vm.Tabs(
+    tabs=[
+        vm.Container(
+            title="By Issue",
+            components=[
+                vm.Graph(
+                    figure=bar(
+                        data_frame=df_complaints,
+                        y="Issue",
+                        x="Complaint ID",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By Product",
+            components=[
+                vm.Graph(
+                    figure=bar(
+                        data_frame=df_complaints,
+                        y="Product",
+                        x="Complaint ID",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By Channel",
+            components=[
+                vm.Graph(
+                    figure=bar(
+                        data_frame=df_complaints,
+                        y="Channel",
+                        x="Complaint ID",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By Region",
+            components=[
+                vm.Graph(
+                    figure=bar(
+                        data_frame=df_complaints,
+                        y="Region",
+                        x="Complaint ID",
+                    ),
+                )
+            ],
+        ),
+    ],
+)
+
+# PAGES --------------------------------------------------------------------------------------
+page_exec = vm.Page(
+    title="Executive View",
+    layout=vm.Layout(
+        grid=[
+            [0, 0],
+            [1, 2],
+            [1, 2],
+            [1, 3],
+            [1, 3],
+        ],
+    ),
+    components=[
+        kpi_banner,
+        bar_charts_tabbed,
+        vm.Graph(figure=line(data_frame=df_complaints, y="Complaint ID", x="Year-Month Received")),
+        vm.Graph(
+            figure=pie(
+                data_frame=df_complaints[df_complaints["Company response - Closed"] != "Not closed"],
+                custom_order=[
+                    "Closed with explanation",
+                    "Closed without relief",
+                    "Closed with non-monetary relief",
+                    "Closed with relief",
+                    "Closed with monetary relief",
+                ],
+                values="Complaint ID",
+                names="Company response - Closed",
+                title="Closed company responses",
+            )
+        ),
+    ],
+)
+
+page_region = vm.Page(
+    title="Regional View",
+    layout=vm.Layout(grid=[[0, 0]] + [[1, 2]] * 4),
+    components=[
+        vm.Card(
+            text="""
+        ##### Click on a state inside the map to filter the bar charts on the right.
+
+        - Which state has the most complaints?
+        - What are the three biggest issues in California?
+        - What is the product with the most complaints in Texas?
+        """
+        ),
+        vm.Graph(
+            figure=choropleth(
+                data_frame=df_complaints,
+                locations="State",
+                color="Complaint ID",
+                title="Complaints by State",
+                custom_data=["State"],
+            ),
+            actions=[
+                vm.Action(
+                    function=filter_interaction(targets=["regional-issue", "regional-product"]),
+                )
+            ],
+        ),
+        vm.Tabs(
+            tabs=[
+                vm.Container(
+                    title="By Issue",
+                    components=[
+                        vm.Graph(
+                            id="regional-issue",
+                            figure=bar(
+                                data_frame=df_complaints,
+                                y="Issue",
+                                x="Complaint ID",
+                            ),
+                        )
+                    ],
+                ),
+                vm.Container(
+                    title="By Product",
+                    components=[
+                        vm.Graph(
+                            id="regional-product",
+                            figure=bar(
+                                data_frame=df_complaints,
+                                y="Product",
+                                x="Complaint ID",
+                            ),
+                        )
+                    ],
+                ),
+            ],
+        ),
+    ],
+    controls=[
+        vm.Filter(column="Region", selector=vm.Checklist()),
+        vm.Filter(column="State"),
+        vm.Filter(column="Product"),
+        vm.Filter(column="Issue"),
+    ],
+)
+
+page_table = vm.Page(
+    title="List of complaints",
+    components=[
+        vm.AgGrid(
+            figure=dash_ag_grid(
+                data_frame=df_complaints,
+                columnDefs=COLUMN_DEFS,
+                dashGridOptions={"pagination": True},
+            )
+        )
+    ],
+)
+
+dashboard = vm.Dashboard(
+    pages=[page_exec, page_region, page_table],
+    title="Cumulus Financial Corporation",
+    navigation=vm.Navigation(
+        nav_selector=vm.NavBar(
+            items=[
+                vm.NavLink(label="Executive View", icon="Leaderboard", pages=["Executive View"]),
+                vm.NavLink(label="Regional View", icon="South America", pages=["Regional View"]),
+                vm.NavLink(label="Table View", icon="Table View", pages=["List of complaints"]),
+            ]
+        )
+    ),
+)
+
+if __name__ == "__main__":
+    Vizro().build(dashboard).run()

assets/css/custom.css

@@ -0,0 +1,79 @@
+#page-header {
+  padding-left: 4px;
+}
+
+.card {
+  padding: 8px;
+}
+
+.kpi-card-ref {
+  min-width: 168px;
+}
+
+.kpi-card-ref h4 {
+  margin: 0;
+}
+
+.kpi-card-ref > span {
+  display: flex;
+  font-weight: 600;
+  gap: 4px;
+}
+
+.kpi-card-ref .delta-pos {
+  color: #1a85ff;
+}
+
+.kpi-card-ref .delta-neg {
+  color: #d41159;
+}
+
+.kpi-card-ref .material-symbols-outlined {
+  font-size: 16px;
+  line-height: 20px;
+}
+
+.kpi-card-ref > div {
+  display: flex;
+  flex-direction: row;
+  gap: 8px;
+  margin: 0;
+}
+
+.kpi-card-ref > p {
+  align-items: center;
+  color: var(--text-secondary);
+  display: flex;
+  flex-grow: 1;
+  font-size: 1rem;
+  font-size: 3.6vh;
+  font-weight: 600;
+  line-height: unset;
+}
+
+.kpi-card-ref:has(.delta-pos) {
+  border-left: 4px solid #1a85ff;
+}
+
+.kpi-card-ref:has(.delta-neg) {
+  border-left: 4px solid #d41159;
+}
+
+.card ul {
+  margin-bottom: 0;
+}
+
+#kpi-banner .container__title {
+  display: none;
+}
+
+#kpi-banner .grid-layout {
+  display: flex;
+  flex-direction: row;
+  overflow: auto;
+}
+
+#kpi-banner > ::-webkit-scrollbar-thumb {
+  border: 6px solid;
+  border-color: var(--main-container-bg-color);
+}

utils/__init__.py

@@ -0,0 +1 @@
+"""Utils folder to contain helper functions and custom charts/components."""

utils/_charts.py

@@ -0,0 +1,193 @@
+"""Contains custom components and charts used inside the dashboard."""
+
+from typing import List, Literal, Optional
+
+import dash_bootstrap_components as dbc
+import pandas as pd
+import vizro.models as vm
+import vizro.plotly.express as px
+from dash import html
+from vizro.models.types import capture
+
+
+# CUSTOM COMPONENTS -------------------------------------------------------------
+# Note: This is a static KPI Card only (it will not be reactive to controls). A new dynamic KPI Card component
+# is currently in development.
+class KPI(vm.VizroBaseModel):
+    """Static custom `KPI` Card."""
+
+    type: Literal["kpi"] = "kpi"
+    title: str
+    value: str
+    icon: str
+    sign: Literal["delta-pos", "delta-neg"]
+    ref_value: str
+
+    def build(self):
+        return dbc.Card(
+            [
+                html.H4(self.title),
+                html.P(self.value),
+                html.Span(
+                    [
+                        html.Span(self.icon, className="material-symbols-outlined"),
+                        html.Span(self.ref_value),
+                    ],
+                    className=self.sign,
+                ),
+            ],
+            className="kpi-card-ref",
+        )
+
+
+# CUSTOM CHARTS ----------------------------------------------------------------
+@capture("graph")
+def bar(
+    x: str,
+    y: str,
+    data_frame: pd.DataFrame,
+    top_n: int = 15,
+    custom_data: Optional[List[str]] = None,
+):
+    df_agg = data_frame.groupby(y).agg({x: "count"}).sort_values(by=x, ascending=False).reset_index()
+
+    fig = px.bar(
+        data_frame=df_agg.head(top_n),
+        x=x,
+        y=y,
+        orientation="h",
+        text=x,
+        color_discrete_sequence=["#1A85FF"],
+        custom_data=custom_data,
+    )
+    fig.update_layout(xaxis_title="# of Complaints", yaxis=dict(title="", autorange="reversed"))  # noqa: C408
+    return fig
+
+
+@capture("graph")
+def line(x: str, y: str, data_frame: pd.DataFrame):
+    df_agg = data_frame.groupby(x).agg({y: "count"}).reset_index()
+    fig = px.area(
+        data_frame=df_agg,
+        x=x,
+        y=y,
+        color_discrete_sequence=["#1A85FF"],
+        title="Complaints over time",
+    )
+    fig.update_layout(xaxis_title="Date Received", yaxis_title="# of Complaints", title_pad_t=4)
+    return fig
+
+
+@capture("graph")
+def pie(
+    names: str,
+    values: str,
+    data_frame: pd.DataFrame = None,
+    title: Optional[str] = None,
+    custom_order: Optional[List[str]] = None,
+):
+    df_agg = data_frame.groupby(names).agg({values: "count"}).reset_index()
+
+    # Apply custom order so colors are applied correctly to the pie chart
+    order_mapping = {category: index for index, category in enumerate(custom_order)}
+    df_sorted = df_agg.sort_values(by=names, key=lambda names: names.map(order_mapping))
+
+    fig = px.pie(
+        data_frame=df_sorted,
+        names=names,
+        values=values,
+        color_discrete_sequence=["#1a85ff", "#7ea1ee", "#adbedc", "#df658c", "#d41159"],
+        title=title,
+        hole=0.4,
+    )
+
+    fig.update_layout(legend_x=1, legend_y=1, title_pad_t=2, margin=dict(l=0, r=0, t=60, b=0))  # noqa: C408
+    fig.update_traces(sort=False)
+    return fig
+
+
+@capture("graph")
+def choropleth(
+    locations: str,
+    color: str,
+    data_frame: pd.DataFrame = None,
+    title: Optional[str] = None,
+    custom_data: Optional[List[str]] = None,
+):
+    df_agg = data_frame.groupby(locations).agg({color: "count"}).reset_index()
+
+    fig = px.choropleth(
+        data_frame=df_agg,
+        locations=locations,
+        color=color,
+        color_continuous_scale=[
+            "#ded6d8",
+            "#f3bdcb",
+            "#f7a9be",
+            "#f894b1",
+            "#f780a3",
+            "#f46b94",
+            "#ee517f",
+            "#e94777",
+            "#e43d70",
+            "#df3168",
+            "#d92460",
+            "#d41159",
+        ],
+        scope="usa",
+        locationmode="USA-states",
+        title=title,
+        custom_data=custom_data,
+    )
+
+    fig.update_coloraxes(colorbar={"thickness": 10, "title": {"side": "right"}})
+    return fig
+
+
+# TABLE CONFIGURATIONS ---------------------------------------------------------
+CELL_STYLE = {
+    "styleConditions": [
+        {
+            "condition": "params.value == 'Closed with explanation'",
+            "style": {"backgroundColor": "#1a85ff"},
+        },
+        {
+            "condition": "params.value == 'Closed with monetary relief'",
+            "style": {"backgroundColor": "#d41159"},
+        },
+        {
+            "condition": "params.value == 'Closed with non-monetary relief'",
+            "style": {"backgroundColor": "#adbedc"},
+        },
+        {
+            "condition": "params.value == 'Closed without relief'",
+            "style": {"backgroundColor": "#7ea1ee"},
+        },
+        {
+            "condition": "params.value == 'Closed with relief'",
+            "style": {"backgroundColor": "#df658c"},
+        },
+        {
+            "condition": "params.value == 'Closed'",
+            "style": {"backgroundColor": "#1a85ff"},
+        },
+    ]
+}
+
+
+COLUMN_DEFS = [
+    {"field": "Complaint ID", "cellDataType": "text", "headerName": "ID", "flex": 3},
+    {"field": "Date Received", "cellDataType": "text", "headerName": "Date", "flex": 3},
+    {"field": "Channel", "cellDataType": "text", "flex": 3},
+    {"field": "State", "cellDataType": "text", "flex": 2},
+    {"field": "Product", "cellDataType": "text", "flex": 5},
+    {"field": "Issue", "cellDataType": "text", "flex": 5},
+    {
+        "field": "Company response - detailed",
+        "cellDataType": "text",
+        "cellStyle": CELL_STYLE,
+        "headerName": "Company response",
+        "flex": 6,
+    },
+    {"field": "Timely response?", "cellRenderer": "markdown", "headerName": "On time?", "flex": 3},
+]

utils/_helper.py

@@ -0,0 +1,55 @@
+"""Contains helper functions and variables."""
+
+import numpy as np
+import pandas as pd
+
+REGION_MAPPING = {
+    **dict.fromkeys(["CT", "ME", "MA", "NH", "RI", "VT", "NJ", "NY", "PA"], "North East"),
+    **dict.fromkeys(
+        ["IL", "IN", "MI", "OH", "WI", "IA", "KS", "MN", "MO", "NE", "ND", "SD"], "Mid West"  # codespell:ignore
+    ),
+    **dict.fromkeys(
+        ["DE", "FL", "GA", "MD", "NC", "SC", "VA", "WV", "DC", "AL", "KY", "MS", "TN", "AR", "LA"], "South"
+    ),
+    **dict.fromkeys(["AZ", "NM", "OK", "TX"], "South West"),
+    **dict.fromkeys(["CO", "ID", "MT", "NV", "UT", "WY", "AK", "CA", "HI", "OR", "WA"], "West"),
+    **dict.fromkeys(["UM", "PR", "AP", "VI", "AE", "AS", "GU", "FM", "PW", "MP"], "Other"),
+}
+
+
+def fill_na_with_random(df, column):
+    """Fills missing values in a column with random values from the same column."""
+    non_na_values = df[column].dropna().values
+    df[column] = df[column].apply(lambda x: np.random.choice(non_na_values) if pd.isna(x) else x)
+    return df[column]
+
+
+def clean_data_and_add_columns(data: pd.DataFrame):
+    """Tidies the original data set, adds new columns, and changes cell values for the purpose of this example."""
+    data = data.rename(
+        columns={
+            "Date Sumbited": "Date Submitted",
+            "Submitted via": "Channel",
+            "Company response to consumer": "Company response - detailed",
+        },
+    )
+
+    # Clean cell values and/or assign different values for the purpose of this example
+    data["Company response - detailed"] = data["Company response - detailed"].replace("Closed", "Closed without relief")
+    data["State"] = data["State"].replace("UNITED STATES MINOR OUTLYING ISLANDS", "UM")
+    data["State"] = fill_na_with_random(data, "State")
+
+    # Convert to correct data type
+    data["Date Received"] = pd.to_datetime(data["Date Received"], format="%m/%d/%y").dt.strftime("%Y-%m-%d")
+    data["Date Submitted"] = pd.to_datetime(data["Date Submitted"], format="%m/%d/%y").dt.strftime("%Y-%m-%d")
+
+    # Create additional columns
+    data["Year-Month Received"] = pd.to_datetime(data["Date Received"], format="%Y-%m-%d").dt.strftime("%Y-%m")
+    data["Region"] = data["State"].map(REGION_MAPPING)
+    data["Company response"] = np.where(
+        data["Company response - detailed"].str.contains("Closed"), "Closed", data["Company response - detailed"]
+    )
+    data["Company response - Closed"] = np.where(
+        data["Company response - detailed"].str.contains("Closed"), data["Company response - detailed"], "Not closed"
+    )
+    return data