Add final app

.gitignore

@@ -0,0 +1,144 @@
+# npm node_modules
+node_modules/
+
+# Ipynb
+ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# macOS
+*.DS_Store
+.DS_Store
+.AppleDouble
+.LSOverride
+.Trashes
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask
+instance/
+.webassets-cache
+
+# Scrapy
+.scrapy
+
+# PyBuilder
+.pybuilder/
+target/
+
+# IntelliJ
+.idea/
+*.iml
+out/
+.idea_modules/
+
+# Vscode
+.vscode/
+
+# PEP 582
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder
+.spyderproject
+.spyproject
+
+# Rope
+.ropeproject
+
+# Mkdocs
+/site
+
+# Mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
+
+# Pytype
+.pytype/
+
+# Cython
+cython_debug/
+
+# Ruff
+.ruff_cache/

Dockerfile

@@ -0,0 +1,18 @@
+# read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+# you will also find guides on how best to write your Dockerfile
+
+FROM python:3.12
+
+RUN useradd -m -u 1000 user
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+
+EXPOSE 7860
+
+CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "app:server"]

README.md

@@ -1,11 +1,73 @@
 ---
-title: Dash Summer App 2024
-emoji: 😻
-colorFrom: green
-colorTo: indigo
+title: Dash summer app challenge 2024
+emoji: 📊
+colorFrom: blue
+colorTo: blue
 sdk: docker
 pinned: false
 license: apache-2.0
+short_description: Entry for the dash summer app challenge 2024
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌞 Dash summer app challenge 2024
+
+This is my entry for the [Dash summer app challenge 2024](https://community.plotly.com/t/summer-dash-app-building-challenge-amazon-purchases/84396)
+where I have visualized Amazon purchase history data.
+
+**Note:** The dashboard focuses on data from 2021 only. Observations with missing product information have been removed for the purpose of the analysis.
+
+The dashboard showcases how purchase data can be visualized and is divided into four main pages:
+
+- **Purchase Overview:** Displays key metrics and top performers across four major categories (product category, product items, region, states), with year-to-year comparisons.
+- **Product Overview:** Highlights the top N best-performing products, allowing users to explore the product hierarchy and identify seasonal patterns. Users can also select the top N for more detailed analysis.
+- **Regional Overview:** Provides a regional comparison of key metrics and top performers across the four major categories. Users can drill down from region to states to analyze product performance regionally.
+- **Customer Overview:** Compares various key metrics across different socio-economic categories (e.g., age group, education, income group).
+
+**Created by:** [Huong Li Nguyen](https://github.com/huong-li-nguyen)
+
+---
+
+### 🗓️ Data
+
+A special thanks to the authors mentioned below for supplying the data set. The original data set can be accessed
+[here](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/YGLYDY#).
+
+- **Authors**: Alex Berke and Dan Calacci and Robert Mahari and Takahiro Yabe and Kent Larson and Sandy Pentland
+- **Publisher**: Harvard Dataverse
+- **Title**: Open e-commerce 1.0: Five years of crowdsourced U.S. Amazon purchase histories with user demographics
+- **Publisher**: Harvard Dataverse
+- **Year**: 2023
+- **Version**: V1
+- **URL**: https://doi.org/10.7910/DVN/YGLYDY
+
+### 📊 Plotly/Dash resources
+
+- [Bar charts](https://plotly.com/python/bar-charts/)
+- [Line charts](https://plotly.com/python/line-charts/)
+- [Density heatmap](https://plotly.com/python/heatmaps/)
+- [Choropleth maps](https://plotly.com/python/choropleth-maps/)
+- [Dash AgGrid](https://dash.plotly.com/dash-ag-grid)
+
+### 🚀 Vizro features applied
+
+- [Vizro tutorial on pages, layouts and dashboards](https://vizro.readthedocs.io/en/stable/pages/tutorials/explore-components/)
+- [Graphs](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph/)
+- [Tables](https://vizro.readthedocs.io/en/stable/pages/user-guides/table/)
+- [KPI cards](https://vizro.readthedocs.io/en/stable/pages/user-guides/figure/)
+- [Actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/)
+- [Custom components](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-components/)
+- [Custom charts](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts/)
+- [Custom CSS](https://vizro.readthedocs.io/en/stable/pages/user-guides/assets/)
+
+### 🖥️ App demo
+
+<img src="./images/dash-summer-app.gif" alt="Gif to app" width="600">
+
+---
+
+## How to run the example locally
+
+1. Install the `requirements.txt` in your environment.
+2. Download the data `survey.csv` and `amazon-purchases.csv` from [here](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/YGLYDY#) and place it in a folder called `data`.
+3. Run the `app.py` file with your environment activated.
+4. You should now be able to access the app locally via http://127.0.0.1:8050/.

app.py

@@ -0,0 +1,448 @@
+"""Contains Vizro app configuration."""
+
+import dash_bootstrap_components as dbc
+import pandas as pd
+import vizro.models as vm
+from dash import html
+from utils.charts import COLUMNDEFS, FlexContainer, bar_avg, bar_top_n, choropleth, line, product_seasonality_heatmap
+from utils.config import CURRENT_YEAR, LAST_YEAR, ORANGE_SEQUENTIAL_PALETTE
+from utils.helper import create_customer_df, create_kpi_container, create_kpi_data, tidy_orders_data
+from vizro import Vizro
+from vizro.actions import filter_interaction
+from vizro.tables import dash_ag_grid
+
+# TIDY AND CREATE RELEVANT DATA SETS ---------------------
+# Data set below was created by loading original `amazon-purchases.csv` and filtering data on CURRENT_YEAR and LAST_YEAR
+orders = pd.read_csv(f"data/amazon-purchases.csv")
+survey = pd.read_csv("data/survey.csv")
+
+# Tidy and filter the data set on CURRENT_YEAR and LAST_YEAR
+orders = tidy_orders_data(orders)
+orders = orders[orders["Year"].isin([str(CURRENT_YEAR), str(LAST_YEAR)])]
+
+orders_cy = orders[orders["Year"] == str(CURRENT_YEAR)]
+kpi_overall_df = create_kpi_data(orders)
+kpi_midwest_df = create_kpi_data(orders.query("Region=='Midwest'"))
+kpi_northeast_df = create_kpi_data(orders.query("Region=='Northeast'"))
+kpi_south_df = create_kpi_data(orders.query("Region=='South'"))
+kpi_west_df = create_kpi_data(orders.query("Region=='West'"))
+customer_df = create_customer_df(orders_cy, survey)
+
+# CONFIGURE BIGGER COMPONENTS FOR PAGES -------------------
+kpi_overall = create_kpi_container(kpi_overall_df, "overall", vm.Layout(grid=[[0, 1], [2, 3]]))
+kpi_northeast = create_kpi_container(
+    kpi_northeast_df,
+    "northeast",
+    vm.Layout(grid=[[0], [1], [2], [3]], row_gap="8px", col_gap="8px"),
+)
+kpi_midwest = create_kpi_container(
+    kpi_midwest_df,
+    "midwest",
+    vm.Layout(grid=[[0], [1], [2], [3]], row_gap="8px", col_gap="8px"),
+)
+kpi_south = create_kpi_container(
+    kpi_south_df,
+    "south",
+    vm.Layout(grid=[[0], [1], [2], [3]], row_gap="8px", col_gap="8px"),
+)
+kpi_west = create_kpi_container(
+    kpi_west_df,
+    "west",
+    vm.Layout(grid=[[0], [1], [2], [3]], row_gap="8px", col_gap="8px"),
+)
+
+
+tabs_overall = vm.Tabs(
+    tabs=[
+        vm.Container(
+            title="By Category",
+            components=[
+                vm.Graph(
+                    figure=bar_top_n(
+                        data_frame=orders_cy,
+                        y="Category",
+                        x="Order_Value",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By Product",
+            components=[
+                vm.Graph(
+                    figure=bar_top_n(
+                        data_frame=orders_cy,
+                        y="Short_Title",
+                        x="Order_Value",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By Region",
+            components=[
+                vm.Graph(
+                    figure=bar_top_n(
+                        data_frame=orders_cy,
+                        y="Region",
+                        x="Order_Value",
+                    ),
+                )
+            ],
+        ),
+        vm.Container(
+            title="By State",
+            components=[
+                vm.Graph(
+                    figure=bar_top_n(
+                        data_frame=orders_cy,
+                        y="Shipping Address State",
+                        x="Order_Value",
+                    ),
+                )
+            ],
+        ),
+    ],
+)
+
+
+# CONFIGURE PAGES -------------------
+page_orders = vm.Page(
+    title="Order summary",
+    layout=vm.Layout(grid=[[0, 1], [2, 1]], col_gap="40px", row_gap="40px"),
+    components=[
+        kpi_overall,
+        vm.Container(title="Top performers 🚀", components=[tabs_overall]),
+        vm.Graph(
+            figure=line(
+                data_frame=orders,
+                x="Month_Day",
+                y="Order_Value",
+                color="Year",
+                title="Performance vs. last year (LY) ⏳",
+            )
+        ),
+    ],
+)
+
+page_region_comparison = vm.Page(
+    title="Regional comparison",
+    layout=vm.Layout(grid=[[0, 1, 2, 3]], row_min_height="800px"),
+    components=[
+        FlexContainer(
+            title="Midwest",
+            components=[
+                vm.Graph(
+                    figure=choropleth(
+                        data_frame=orders_cy.query('Region=="Midwest"'),
+                        locations="Shipping Address State",
+                        color="Order_Value",
+                        custom_data=["Shipping Address State"],
+                        color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE,
+                        show_region_only=True,
+                    ),
+                ),
+                kpi_midwest,
+                vm.Graph(
+                    id="midwest-bar",
+                    figure=bar_top_n(
+                        data_frame=orders_cy.query('Region=="Midwest"'),
+                        y="Short_Title",
+                        x="Order_Value",
+                        top_n=6,
+                        x_visible=False,
+                        title="Top performers 🚀",
+                    ),
+                ),
+            ],
+            classname="flex-container-regional",
+        ),
+        FlexContainer(
+            title="Northeast",
+            components=[
+                vm.Graph(
+                    figure=choropleth(
+                        data_frame=orders_cy.query('Region=="Northeast"'),
+                        locations="Shipping Address State",
+                        color="Order_Value",
+                        custom_data=["Shipping Address State"],
+                        color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE,
+                        show_region_only=True,
+                    ),
+                ),
+                kpi_northeast,
+                vm.Graph(
+                    id="northeast-bar",
+                    figure=bar_top_n(
+                        data_frame=orders_cy.query('Region=="Northeast"'),
+                        y="Short_Title",
+                        x="Order_Value",
+                        top_n=6,
+                        x_visible=False,
+                        title="Top performers 🚀",
+                    ),
+                ),
+            ],
+            classname="flex-container-regional",
+        ),
+        FlexContainer(
+            title="South",
+            components=[
+                vm.Graph(
+                    figure=choropleth(
+                        data_frame=orders_cy.query('Region=="South"'),
+                        locations="Shipping Address State",
+                        color="Order_Value",
+                        custom_data=["Shipping Address State"],
+                        color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE,
+                        show_region_only=True,
+                    ),
+                ),
+                kpi_south,
+                vm.Graph(
+                    id="south-bar",
+                    figure=bar_top_n(
+                        data_frame=orders_cy.query('Region=="South"'),
+                        y="Short_Title",
+                        x="Order_Value",
+                        top_n=6,
+                        x_visible=False,
+                        title="Top performers 🚀",
+                    ),
+                ),
+            ],
+            classname="flex-container-regional",
+        ),
+        FlexContainer(
+            title="West",
+            components=[
+                vm.Graph(
+                    figure=choropleth(
+                        data_frame=orders_cy.query('Region=="West"'),
+                        locations="Shipping Address State",
+                        color="Order_Value",
+                        custom_data=["Shipping Address State"],
+                        color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE,
+                        show_region_only=True,
+                    ),
+                ),
+                kpi_west,
+                vm.Graph(
+                    id="west-bar",
+                    figure=bar_top_n(
+                        data_frame=orders_cy.query('Region=="West"'),
+                        y="Short_Title",
+                        x="Order_Value",
+                        top_n=6,
+                        x_visible=False,
+                        title="Top performers 🚀",
+                    ),
+                ),
+            ],
+            classname="flex-container-regional",
+        ),
+    ],
+    controls=[
+        vm.Parameter(
+            targets=["south-bar.y", "northeast-bar.y", "west-bar.y", "midwest-bar.y"],
+            selector=vm.Dropdown(
+                options=[
+                    {"value": "Shipping Address State", "label": "State"},
+                    {"value": "Category", "label": "Category"},
+                    {"value": "Short_Title", "label": "Product item"},
+                ],
+                title="Change y-axis on top performers:",
+                multi=False,
+                value="Shipping Address State",
+            ),
+        ),
+    ],
+)
+
+page_region_map = vm.Page(
+    title="Regional map",
+    layout=vm.Layout(grid=[[0, 1]]),
+    components=[
+        vm.Graph(
+            figure=choropleth(
+                data_frame=orders_cy,
+                locations="Shipping Address State",
+                color="Order_Value",
+                title="Total order value by shipping state <br><sup> ⤵ Click on a state to filter the "
+                "charts on the right. Refresh the page to deselect.</sup>",
+                custom_data=["Shipping Address State"],
+                color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE,
+            ),
+            actions=[
+                vm.Action(
+                    function=filter_interaction(targets=["regional-bar"]),
+                )
+            ],
+        ),
+        vm.Graph(
+            id="regional-bar",
+            figure=bar_top_n(data_frame=orders_cy, y="Category", x="Order_Value", title="Top performers 🚀"),
+        ),
+    ],
+    controls=[
+        vm.Filter(column="Region"),
+        vm.Filter(column="Shipping Address State"),
+        vm.Filter(column="Category"),
+        vm.Parameter(
+            targets=["regional-bar.y"],
+            selector=vm.Dropdown(
+                options=[
+                    {"value": "Shipping Address State", "label": "State"},
+                    {"value": "Category", "label": "Category"},
+                    {"value": "Short_Title", "label": "Product item"},
+                ],
+                title="Change y-axis on bar chart:",
+                multi=False,
+                value="Category",
+            ),
+        ),
+        vm.Parameter(
+            targets=["regional-bar.top_n"],
+            selector=vm.Slider(min=10, max=35, step=5, value=15, title="Display top N:"),
+        ),
+    ],
+)
+
+page_product = vm.Page(
+    title="Product overview",
+    layout=vm.Layout(grid=[[0, 0, 1, 1, 1]], col_gap="0px"),
+    components=[
+        vm.Graph(
+            id="product-bar",
+            figure=bar_top_n(
+                data_frame=orders_cy,
+                y="Category",
+                x="Order_Value",
+                title="Top categories / product items by total order value",
+            ),
+        ),
+        vm.Graph(
+            id="product-heatmap",
+            figure=product_seasonality_heatmap(
+                orders_cy, x="Month", y="Category", z="Order_Value", color_continuous_scale=ORANGE_SEQUENTIAL_PALETTE
+            ),
+        ),
+    ],
+    controls=[
+        vm.Filter(column="Category"),
+        vm.Parameter(
+            targets=["product-bar.y", "product-heatmap.y"],
+            selector=vm.Dropdown(
+                options=[{"value": "Category", "label": "Category"}, {"value": "Short_Title", "label": "Product item"}],
+                title="Change product level:",
+                multi=False,
+                value="Category",
+            ),
+        ),
+        vm.Parameter(
+            targets=["product-bar.top_n", "product-heatmap.top_n"],
+            selector=vm.Slider(min=10, max=35, step=5, value=15, title="Display top N:"),
+        ),
+        vm.Filter(column="Region"),
+        vm.Filter(column="Shipping Address State"),
+    ],
+)
+
+
+page_customer = vm.Page(
+    title="Customer overview",
+    components=[
+        vm.Graph(
+            id="average-bar",
+            figure=bar_avg(
+                customer_df,
+                x="Q-demos-age",
+                y="Total order value",
+                title="Average KPI numbers across selected categories 📊",
+            ),
+        ),
+        vm.AgGrid(figure=dash_ag_grid(customer_df, columnDefs=COLUMNDEFS, dashGridOptions={"pagination": True})),
+    ],
+    controls=[
+        vm.Parameter(
+            targets=["average-bar.x"],
+            selector=vm.Dropdown(
+                options=[
+                    {"value": "Q-demos-age", "label": "Age group"},
+                    {"value": "Q-demos-education", "label": "Education level"},
+                    {"value": "Q-demos-income", "label": "Income group"},
+                    {"value": "Q-demos-gender", "label": "Gender"},
+                ],
+                title="Change category on x-axis",
+                multi=False,
+                value="Q-demos-age",
+            ),
+        ),
+        vm.Parameter(
+            targets=["average-bar.y"],
+            selector=vm.Dropdown(
+                options=[
+                    "Total order value",
+                    "Number of unique categories",
+                    "Number of unique products",
+                    "Number of unique order dates",
+                    "Total units ordered",
+                    "Avg. unit price",
+                    "Avg. order value",
+                ],
+                title="Change KPI on y-axis",
+                multi=False,
+                value="Total order value",
+            ),
+        ),
+    ],
+)
+
+# CONFIGURE DASHBOARD WITH PAGES AND NAVIGATION -------------------
+dashboard = vm.Dashboard(
+    pages=[page_orders, page_product, page_region_comparison, page_region_map, page_customer],
+    navigation=vm.Navigation(
+        nav_selector=vm.NavBar(
+            items=[
+                vm.NavLink(label="Order summary", pages=["Order summary"], icon="Home"),
+                vm.NavLink(
+                    label="Product overview",
+                    pages=["Product overview"],
+                    icon="Shopping Cart",
+                ),
+                vm.NavLink(
+                    label="Regional overview",
+                    pages=["Regional comparison", "Regional map"],
+                    icon="South America",
+                ),
+                vm.NavLink(
+                    label="Customer overview",
+                    pages=["Customer overview"],
+                    icon="Groups",
+                ),
+            ]
+        )
+    ),
+    title=f"Purchase history dashboard: {CURRENT_YEAR}",
+)
+
+app = Vizro().build(dashboard)
+
+# Add footer
+app.dash.layout.children.append(
+    html.Div(
+        [
+            dbc.NavLink("🌸 Created by Li Nguyen", href="https://github.com/huong-li-nguyen"),
+            dbc.NavLink("💻 Code", href=""),
+            dbc.NavLink(
+                "💾 Data", href="https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/YGLYDY"
+            ),
+        ],
+        className="anchor-container",
+    )
+)
+server = app.dash.server
+
+
+if __name__ == "__main__":
+    app.run()

assets/css/custom.css

@@ -0,0 +1,73 @@
+#logo {
+  padding: 12px 0 8px;
+}
+
+#logo-and-title {
+  gap: 16px;
+}
+
+#dashboard-title {
+  margin-bottom: 0.5rem;
+}
+
+#left-main {
+  width: 300px;
+}
+
+.card-kpi .card-footer {
+  font-size: 1rem;
+}
+
+.card-kpi .card-footer .material-symbols-outlined {
+  font-size: 1.25rem;
+}
+
+.flex-container-regional {
+  background: var(--surfaces-bg-02);
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  padding: 12px;
+}
+
+.flex-container-regional .card-kpi .material-symbols-outlined {
+  font-size: 1.2rem;
+}
+
+.flex-container-regional .card-kpi .card-footer {
+  font-size: 0.8rem;
+}
+
+.flex-container-regional .card-kpi .card-footer .material-symbols-outlined {
+  font-size: 1rem;
+}
+
+.flex-container-regional .card-kpi,
+.flex-container-regional .card {
+  height: unset;
+  padding: 0.5rem;
+}
+
+.flex-container-regional .card-kpi .card-body {
+  font-size: 2vh;
+  padding: 0.25rem;
+}
+
+.flex-container-regional .card-kpi-title {
+  font-size: 1rem;
+}
+
+.anchor-container {
+  background: var(--main-container-bg-color);
+  border-top: 1px solid var(--border-subtleAlpha01);
+  bottom: 0;
+  display: flex;
+  font-size: 11px;
+  font-weight: 600;
+  gap: 2rem;
+  height: 24px;
+  padding: 2px 12px;
+  place-content: baseline right;
+  position: fixed;
+  right: 0;
+}

requirements.txt

@@ -0,0 +1,2 @@
+vizro
+gunicorn

utils/__init__.py

@@ -0,0 +1,8 @@
+"""Contains helper functions and custom chart/components configurations.
+
+For more information, see:
+
+- Custom charts: https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts/
+- Custom components: https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-components/
+
+"""

utils/charts.py

@@ -0,0 +1,273 @@
+"""Contains code for custom charts and table configurations."""
+
+from typing import List, Literal, Optional
+
+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
+
+from .config import PRIMARY_COLOR, SECONDARY_COLOR
+from .helper import shorten_product_name
+
+
+# CUSTOM CHARTS ---------------
+@capture("graph")
+def bar_top_n(
+    data_frame: pd.DataFrame,
+    x: str,
+    y: str,
+    top_n: int = 15,
+    custom_data: Optional[List[str]] = None,
+    title: Optional[str] = None,
+    x_visible: bool = True,
+):
+    """Custom bar chart implementation.
+
+    Based on [px.bar](https://plotly.com/python-api-reference/generated/plotly.express.bar).
+    """
+    df_agg = data_frame.groupby(y).agg({x: "sum"}).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_auto=".3s",
+        color_discrete_sequence=[SECONDARY_COLOR],
+        custom_data=custom_data,
+    )
+    fig.update_layout(
+        title=title,
+        xaxis={"title": "Total order value in USD", "visible": x_visible},
+        yaxis={"title": "", "autorange": "reversed"},
+        margin={"r": 0, "b": 16, "t": 32},
+        paper_bgcolor="rgba(0, 0, 0, 0)",
+        plot_bgcolor="rgba(0, 0, 0, 0)",
+    )
+    return fig
+
+
+@capture("graph")
+def line(data_frame: pd.DataFrame, x: str, y: str, color: str, title: Optional[str] = None):
+    """Custom line chart implementation.
+
+    Based on [px.line](https://plotly.com/python-api-reference/generated/plotly.express.line).
+    """
+    df_agg = data_frame.groupby([x, color]).agg({y: "sum"}).reset_index()
+
+    # Create full order date for correct sorting
+    df_agg["order_date_sort"] = pd.to_datetime(df_agg[x] + "-" + df_agg[color], format="%b-%d-%Y")
+    df_agg = df_agg.sort_values(by="order_date_sort")
+
+    fig = px.line(
+        data_frame=df_agg,
+        x=x,
+        y=y,
+        color=color,
+        color_discrete_sequence=[SECONDARY_COLOR, PRIMARY_COLOR],
+    )
+    fig.update_layout(
+        title=title,
+        xaxis={"title": "", "nticks": 12, "showgrid": False},
+        yaxis_title="Total order value in USD",
+        legend_title="",
+    )
+    return fig
+
+
+@capture("graph")
+def product_seasonality_heatmap(
+    data_frame: pd.DataFrame,
+    x: str,
+    y: str,
+    z: str,
+    top_n: int = 15,
+    color_continuous_scale: Optional[List[str]] = None,
+):
+    """Custom density heatmap implementation.
+
+    Based on [px.density_heatmap](https://plotly.com/python-api-reference/generated/plotly.express.density_heatmap).
+    """
+    # Filter for top n categories
+    top_products = (
+        data_frame.groupby([y]).agg({z: "sum"}).sort_values(by=z, ascending=False).reset_index().head(top_n)[y]
+    )
+    df_filtered = data_frame[data_frame[y].isin(top_products)]
+
+    # Get average order value per category and month
+    df_agg = df_filtered.groupby([x, y]).agg({z: "sum"}).sort_values(by=z, ascending=False).reset_index()
+
+    fig = px.density_heatmap(
+        data_frame=df_agg,
+        x=x,
+        y=y,
+        z=z,
+        text_auto=".2s",
+        nbinsx=12,
+        color_continuous_scale=color_continuous_scale,
+    )
+
+    fig.update_coloraxes(colorbar_title="")
+    fig.update_yaxes(categoryorder="array", categoryarray=top_products)
+    fig.update_layout(
+        title={"text": f"Seasonality of {top_n} categories / products", "pad_l": 0, "pad_r": 0},
+        yaxis={"title": "", "autorange": "reversed", "visible": False},
+        xaxis={
+            "title": "",
+            "showgrid": False,
+            "tickmode": "array",
+            "tickvals": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
+            "ticktext": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+        },
+        margin={"l": 0, "r": 0, "t": 32, "b": 0},
+    )
+    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,
+    color_continuous_scale: Optional[List[str]] = None,
+    show_region_only: bool = False,
+):
+    """Custom choropleth implementation.
+
+    Based on [px.choropleth](https://plotly.com/python-api-reference/generated/plotly.express.choropleth).
+    """
+    df_agg = data_frame.groupby(locations).agg({color: "sum"}).reset_index()
+    fig = px.choropleth(
+        data_frame=df_agg,
+        locations=locations,
+        color=color,
+        color_continuous_scale=color_continuous_scale,
+        scope="usa",
+        locationmode="USA-states",
+        title=title,
+        custom_data=custom_data,
+    )
+    fig.update_coloraxes(colorbar={"thickness": 10, "title": ""})
+    fig.update_layout(geo_bgcolor="rgba(0,0,0,0)")
+
+    if show_region_only:
+        fig.update_geos(
+            fitbounds="locations",
+            visible=False,
+            projection_scale=10,
+        )
+        fig.update_layout(
+            {
+                "coloraxis_showscale": False,
+                "margin": {"t": 0, "b": 0, "r": 0, "l": 0},
+                "title_pad": {"t": 0, "b": 0, "r": 0, "l": 0},
+                "height": 160,
+            }
+        )
+    return fig
+
+
+@capture("graph")
+def bar_avg(data_frame: pd.DataFrame, x: str, y: str, title: Optional[str] = None):
+    """Custom bar chart implementation.
+
+    Based on [px.bar](https://plotly.com/python-api-reference/generated/plotly.express.bar).
+    """
+    df_agg = data_frame.groupby(x).agg({y: "mean"}).sort_values(by=y, ascending=False).reset_index()
+    df_agg[x] = df_agg[x].apply(shorten_product_name)
+    fig = px.bar(
+        data_frame=df_agg,
+        x=x,
+        y=y,
+        text_auto=".0f",
+        color_discrete_sequence=[SECONDARY_COLOR],
+    )
+    fig.update_layout(
+        title=title,
+        xaxis={"title": ""},
+        yaxis={"title": f"{y}"},
+    )
+    if x == "Q-demos-income":
+        fig.update_xaxes(
+            categoryorder="array",
+            categoryarray=[
+                "Less than $25,000",
+                "$25,000 - $49,999",
+                "$50,000 - $74,999",
+                "$75,000 - $99,999",
+                "$100,000 - $149,999",
+                "$150,000 or more",
+                "Prefer not to say",
+            ],
+        )
+    else:
+        fig.update_xaxes(categoryorder="category ascending")
+    return fig
+
+
+# CUSTOM COMPONENTS -----------
+class FlexContainer(vm.Container):
+    """Custom flex `Container`."""
+
+    type: Literal["flex_container"] = "flex_container"
+    classname: Optional[str] = "d-flex"
+
+    def build(self):
+        """Returns a flex container."""
+        components_container = [component.build() for component in self.components]
+
+        return html.Div(
+            id=self.id,
+            children=[html.H3(children=self.title, className="container__title"), *components_container],
+            className=self.classname,
+        )
+
+
+vm.Page.add_type("components", FlexContainer)
+
+
+# TABLE SPECIFICATIONS ----
+CELL_STYLE = {
+    "styleConditions": [
+        {
+            "condition": "params.data.Quintiles == 0",
+            "style": {"backgroundColor": "#ffc495"},
+        },
+        {
+            "condition": "params.data.Quintiles == 1",
+            "style": {"backgroundColor": "#ffb276"},
+        },
+        {
+            "condition": "params.data.Quintiles == 2",
+            "style": {"backgroundColor": "#fe9f56"},
+        },
+        {
+            "condition": "params.data.Quintiles == 3",
+            "style": {"backgroundColor": "#fb8d35"},
+        },
+        {
+            "condition": "params.data.Quintiles == 4",
+            "style": {"backgroundColor": "#f77a00"},
+        },
+    ],
+}
+
+COLUMNDEFS = [
+    {"field": "Survey ResponseID", "cellDataType": "text"},
+    {"field": "Q-demos-age", "cellDataType": "text"},
+    {"field": "Q-demos-education", "cellDataType": "text"},
+    {"field": "Q-demos-income", "cellDataType": "text"},
+    {"field": "Q-demos-gender", "cellDataType": "text"},
+    {"field": "Total order value", "cellDataType": "dollar", "cellStyle": CELL_STYLE},
+    {"field": "Quintiles"},
+    {"field": "Avg unit price", "cellDataType": "dollar"},
+    {"field": "Avg order value", "cellDataType": "dollar"},
+    {"field": "Total units ordered"},
+    {"field": "Number of unique categories"},
+    {"field": "Number of unique products"},
+    {"field": "Number of unique order dates"},
+    {"field": "pop", "flex": 3},
+]

utils/config.py

@@ -0,0 +1,29 @@
+"""Contains configuration constants to be reused inside dashboard."""
+
+PRIMARY_COLOR = "#FF9900"
+SECONDARY_COLOR = "#bfbdc1"
+CURRENT_YEAR = 2021
+LAST_YEAR = CURRENT_YEAR - 1
+REGION_MAPPING = {
+    **dict.fromkeys(["CT", "ME", "MA", "NH", "RI", "VT", "NJ", "NY", "PA"], "Northeast"),
+    **dict.fromkeys(["IL", "IN", "MI", "OH", "WI", "IA", "KS", "MN", "MO", "NE", "ND", "SD"], "Midwest"),
+    **dict.fromkeys(
+        ["DE", "FL", "GA", "MD", "NC", "SC", "VA", "WV", "DC", "AL", "KY", "MS", "TN", "AR", "LA", "TX", "OK"], "South"
+    ),
+    **dict.fromkeys(["AZ", "NM", "CO", "ID", "MT", "NV", "UT", "WY", "CA", "OR", "WA"], "West"),
+    **dict.fromkeys(["UM", "PR", "AP", "VI", "AE", "AS", "GU", "FM", "PW", "MP"], "Other"),
+}
+NULL_VALUE = "Unknown"
+ORANGE_SEQUENTIAL_PALETTE = ["#ffffff", "#dedce0", "#f0c8aa", "#f9b578", "#fca14b", "#fb8e22", "#f77a00"]
+SELECTED_CUSTOMER_COLUMNS = [
+    "Survey ResponseID",
+    "Q-demos-age",
+    "Q-demos-education",
+    "Q-demos-income",
+    "Q-demos-gender",
+    "Order_Value",
+    "Category",
+    "ASIN/ISBN (Product Code)",
+    "Order Date",
+    "Quantity",
+]

utils/helper.py

@@ -0,0 +1,163 @@
+"""Contains helper functions to tidy/format data and refactor bigger components on screen."""
+
+import pandas as pd
+import vizro.models as vm
+from vizro.figures import kpi_card_reference
+
+from .config import NULL_VALUE, REGION_MAPPING, SELECTED_CUSTOMER_COLUMNS
+
+
+def shorten_product_name(name, n_words=4):
+    """Shortens product labels by reducing it to the first n words."""
+    words = str(name).split()
+    return " ".join(words[:n_words])
+
+
+def tidy_orders_data(orders: pd.DataFrame):
+    """Tidies and filters the data frame and creates additional columns."""
+    # Remove rows where 'Category' is missing
+    orders = orders[orders["Category"].notna()]
+    orders = orders.dropna(subset=["Order Date"])
+
+    # Convert to correct data types
+    orders["Order Date"] = pd.to_datetime(orders["Order Date"], format="%Y-%m-%d", errors="coerce")
+
+    # Create new columns
+    orders = orders.assign(
+        Region=orders["Shipping Address State"].map(REGION_MAPPING).fillna(NULL_VALUE),
+        Order_Value=orders["Purchase Price Per Unit"] * orders["Quantity"],
+        Short_Title=orders["Title"].apply(shorten_product_name),
+        Year=orders["Order Date"].dt.year.astype(str),
+        Month_Day=orders["Order Date"].dt.strftime("%b-%d"),
+        Month=orders["Order Date"].dt.month,
+    )
+
+    # Fill null values
+    orders["Shipping Address State"] = orders["Shipping Address State"].fillna(NULL_VALUE)
+    return orders
+
+
+def create_kpi_data(orders):
+    """Calculate KPIs and create correct data format."""
+    df_kpi = (
+        orders.groupby("Year")
+        .agg({"Order_Value": "sum", "Survey ResponseID": pd.Series.nunique, "Quantity": "sum"})
+        .reset_index()
+    )
+
+    df_kpi = df_kpi.rename(
+        columns={
+            "Order_Value": "Total order value",
+            "Survey ResponseID": "Number of customers",
+            "Quantity": "Total units ordered",
+        }
+    )
+
+    df_kpi["Avg product unit price"] = df_kpi["Total order value"] / df_kpi["Total units ordered"]
+    df_kpi["Total order value mil"] = df_kpi["Total order value"] / 1000000
+
+    df_kpi["index"] = 0
+    df_kpi = df_kpi.pivot(
+        index="index",
+        columns="Year",
+        values=[
+            "Total order value mil",
+            "Number of customers",
+            "Total units ordered",
+            "Avg product unit price",
+        ],
+    )
+    df_kpi.columns = [f"{kpi}_{year}" for kpi, year in df_kpi.columns]
+    return df_kpi
+
+
+def create_kpi_container(data_frame: pd.DataFrame, id: str, layout: vm.Layout):
+    """Creates reusable KPI container configuration."""
+    container = vm.Container(
+        id=f"kpi-container-{id}",
+        title="",
+        layout=layout if layout else None,
+        components=[
+            vm.Figure(
+                figure=kpi_card_reference(
+                    data_frame,
+                    value_column="Total order value mil_2021",
+                    reference_column="Total order value mil_2020",
+                    title="Total order value",
+                    value_format="${value:.2f}M",
+                    reference_format="{delta_relative:+.1%} vs. LY (${reference:.2f}M)",
+                    icon="payments",
+                ),
+            ),
+            vm.Figure(
+                figure=kpi_card_reference(
+                    data_frame,
+                    value_column="Number of customers_2021",
+                    reference_column="Number of customers_2020",
+                    title="No. of customers",
+                    value_format="{value:,.0f}",
+                    reference_format="{delta_relative:+.1%} vs. LY ({reference:,.0f})",
+                    icon="groups",
+                )
+            ),
+            vm.Figure(
+                figure=kpi_card_reference(
+                    data_frame,
+                    value_column="Total units ordered_2021",
+                    reference_column="Total units ordered_2020",
+                    title="Total units ordered",
+                    value_format="{value:,.0f}",
+                    reference_format="{delta_relative:+.1%} vs. LY ({reference:,.0f})",
+                    icon="production_quantity_limits",
+                )
+            ),
+            vm.Figure(
+                figure=kpi_card_reference(
+                    data_frame,
+                    value_column="Avg product unit price_2021",
+                    reference_column="Avg product unit price_2020",
+                    title="Avg. unit price",
+                    value_format="${value:.2f}",
+                    reference_format="{delta_relative:+.1%} vs. LY (${reference:.2f})",
+                    icon="price_change",
+                )
+            ),
+        ],
+    )
+    return container
+
+
+def create_customer_df(orders_cy: pd.DataFrame, survey: pd.DataFrame):
+    """Creates aggregated customer dataframe with socioeconomic columns added."""
+    df_customer = (
+        orders_cy.groupby(["Year", "Survey ResponseID", "Region", "Shipping Address State"])
+        .agg(
+            {
+                "Order_Value": "sum",
+                "Category": pd.Series.nunique,
+                "ASIN/ISBN (Product Code)": pd.Series.nunique,
+                "Order Date": pd.Series.nunique,
+                "Quantity": "sum",
+            }
+        )
+        .reset_index()
+    )
+    df_customer = df_customer.merge(survey, on="Survey ResponseID", how="left")
+
+    # Filter and rename columns for better understanding
+    df_customer = df_customer[SELECTED_CUSTOMER_COLUMNS]
+    df_customer = df_customer.rename(
+        columns={
+            "Order_Value": "Total order value",
+            "Category": "Number of unique categories",
+            "ASIN/ISBN (Product Code)": "Number of unique products",
+            "Order Date": "Number of unique order dates",
+            "Quantity": "Total units ordered",
+        }
+    )
+
+    # Create new metrics
+    df_customer["Avg unit price"] = df_customer["Total order value"] / df_customer["Total units ordered"]
+    df_customer["Avg order value"] = df_customer["Total order value"] / df_customer["Number of unique order dates"]
+    df_customer["Quintiles"] = pd.qcut(df_customer["Total order value"], 5, labels=False)
+    return df_customer