diff --git a/vizro-core/docs/assets/user_guides/figure/custom_kpi.png b/vizro-core/docs/assets/user_guides/figure/custom_kpi.png index b6d2f2727..be30ad740 100644 Binary files a/vizro-core/docs/assets/user_guides/figure/custom_kpi.png and b/vizro-core/docs/assets/user_guides/figure/custom_kpi.png differ diff --git a/vizro-core/docs/assets/user_guides/figure/figure.png b/vizro-core/docs/assets/user_guides/figure/figure.png index dad982f3e..2439c38da 100644 Binary files a/vizro-core/docs/assets/user_guides/figure/figure.png and b/vizro-core/docs/assets/user_guides/figure/figure.png differ diff --git a/vizro-core/docs/assets/user_guides/figure/kpi_cards.png b/vizro-core/docs/assets/user_guides/figure/kpi_cards.png index 2125be068..3ee57a727 100644 Binary files a/vizro-core/docs/assets/user_guides/figure/kpi_cards.png and b/vizro-core/docs/assets/user_guides/figure/kpi_cards.png differ diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md index 9d6dfa249..78e68bb04 100644 --- a/vizro-core/docs/pages/user-guides/custom-figures.md +++ b/vizro-core/docs/pages/user-guides/custom-figures.md @@ -63,7 +63,7 @@ adjust the return statement of the function. title: Optional[str] = None, icon: Optional[str] = None, ) -> dbc.Card: # (2)! - """Creates a custom KPI Card.""" + """Creates a custom KPI card.""" title = title or f"{agg_func} {value_column}".title() value = data_frame[value_column].agg(agg_func) @@ -78,7 +78,7 @@ adjust the return statement of the function. page = vm.Page( - title="Create your own KPI Card", + title="Create your own KPI card", layout=vm.Layout(grid=[[0, 1, -1, -1]] + [[-1, -1, -1, -1]] * 3), # (4)! components=[ vm.Figure( @@ -87,7 +87,7 @@ adjust the return statement of the function. value_column="tip", value_format="${value:.2f}", icon="shopping_cart", - title="Default KPI Card", + title="Default KPI card", ) ), vm.Figure( @@ -96,7 +96,7 @@ adjust the return statement of the function. value_column="tip", value_format="${value:.2f}", icon="payment", - title="Custom KPI Card", + title="Custom KPI card", ) ), ], diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md index 9d3e7656f..43e40191c 100644 --- a/vizro-core/docs/pages/user-guides/figure.md +++ b/vizro-core/docs/pages/user-guides/figure.md @@ -12,7 +12,7 @@ If these more specific models already achieve what you need then they should be the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`. -There are already a few figure functions you can reuse, see the section on [KPI Cards](#key-performance-indicator-kpi-cards) +There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details: - [`kpi_card`][vizro.figures.kpi_card] @@ -58,7 +58,7 @@ To add a `Figure` to your page: tips = px.data.tips page = vm.Page( - title="KPI Indicators", + title="KPI card", layout=vm.Layout(grid=[[0, -1, -1, -1]] + [[-1, -1, -1, -1]] * 4), # (1)! components=[ vm.Figure( @@ -67,7 +67,7 @@ To add a `Figure` to your page: value_column="tip", value_format="${value:.2f}", icon="shopping_cart", - title="KPI Card I", + title="KPI card I", ) ) ], @@ -93,7 +93,7 @@ To add a `Figure` to your page: value_column: tip value_format: ${value:.2f} icon: shopping_cart - title: KPI Card I + title: KPI card I type: figure controls: - column: day @@ -109,7 +109,7 @@ To add a `Figure` to your page: [-1, -1, -1, -1], [-1, -1, -1, -1], ] - title: KPI Indicators + title: KPI card ``` === "Result" [![Figure]][Figure] @@ -133,7 +133,7 @@ As described in the [API reference](../API-reference/figure-callables.md) and il functions have several arguments to customize your KPI cards. If you require a level of customization that is not possible with the built-in functions then you can create a [custom figure](custom-figures.md). -!!! example "KPI Card Variations" +!!! example "KPI card Variations" === "app.py" ```py @@ -180,8 +180,8 @@ possible with the built-in functions then you can create a [custom figure](custo value_column="Actual", reference_column="Reference", title="KPI reference with formatting", - value_format="{value:.2f}$", - reference_format="{delta:.2f}$ vs. last year ({reference:.2f}$)", + value_format="{value:.2f}€", + reference_format="{delta:+.2f}€ vs. last year ({reference:.2f}€)", ), kpi_card_reference( data_frame=df_kpi, @@ -193,7 +193,7 @@ possible with the built-in functions then you can create a [custom figure](custo ] page = vm.Page( - title="KPI Indicators", + title="KPI cards", layout=vm.Layout(grid=[[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]), # (3)! components=[vm.Figure(figure=figure) for figure in example_cards + example_reference_cards], controls=[vm.Filter(column="Category")], @@ -261,8 +261,8 @@ possible with the built-in functions then you can create a [custom figure](custo value_column: Actual reference_column: Reference title: KPI reference with formatting - value_format: "{value:.2f}$" - reference_format: "{delta:.2f}$ vs. last year ({reference:.2f}$)" + value_format: "{value:.2f}€" + reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)" type: figure - figure: _target_: kpi_card_reference @@ -277,7 +277,7 @@ possible with the built-in functions then you can create a [custom figure](custo type: filter layout: grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]] - title: KPI Indicators + title: KPI cards ``` === "Result" [![KPICards]][KPICards] diff --git a/vizro-core/examples/_dev/app.py b/vizro-core/examples/_dev/app.py index 05f568183..6beb079e8 100644 --- a/vizro-core/examples/_dev/app.py +++ b/vizro-core/examples/_dev/app.py @@ -1,65 +1,66 @@ """Dev app to try things out.""" +from typing import 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 import Vizro -from vizro.figures import kpi_card, kpi_card_reference +from vizro.figures import kpi_card +from vizro.models.types import capture + +tips = px.data.tips + -df_kpi = pd.DataFrame({"Actual": [100, 200, 700], "Reference": [100, 300, 500], "Category": ["A", "B", "C"]}) +@capture("figure") # (1)! +def custom_kpi_card( + data_frame: pd.DataFrame, + value_column: str, + *, + value_format: str = "{value}", + agg_func: str = "sum", + title: Optional[str] = None, + icon: Optional[str] = None, +) -> dbc.Card: # (2)! + """Creates a custom KPI card.""" + title = title or f"{agg_func} {value_column}".title() + value = data_frame[value_column].agg(agg_func) -example_cards = [ - kpi_card(data_frame=df_kpi, value_column="Actual", title="KPI with value"), - kpi_card(data_frame=df_kpi, value_column="Actual", title="KPI with aggregation", agg_func="median"), - kpi_card( - data_frame=df_kpi, - value_column="Actual", - title="KPI with formatting", - value_format="${value:.2f}", - ), - kpi_card( - data_frame=df_kpi, - value_column="Actual", - title="KPI with icon", - icon="shopping_cart", - ), -] + header = dbc.CardHeader( + [ + html.H2(title), + html.P(icon, className="material-symbols-outlined") if icon else None, # (3)! + ] + ) + body = dbc.CardBody([value_format.format(value=value)]) + return dbc.Card([header, body], className="card-kpi") -example_reference_cards = [ - kpi_card_reference( - data_frame=df_kpi, - value_column="Actual", - reference_column="Reference", - title="KPI reference (pos)", - ), - kpi_card_reference( - data_frame=df_kpi, - value_column="Actual", - reference_column="Reference", - agg_func="median", - title="KPI reference (neg)", - ), - kpi_card_reference( - data_frame=df_kpi, - value_column="Actual", - reference_column="Reference", - title="KPI reference with formatting", - value_format="{value:.2f}$", - reference_format="{delta:.2f}$ vs. last year ({reference:.2f}$)", - ), - kpi_card_reference( - data_frame=df_kpi, - value_column="Actual", - reference_column="Reference", - title="KPI reference with icon", - icon="shopping_cart", - ), -] page = vm.Page( - title="KPI Indicators", - layout=vm.Layout(grid=[[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]), - components=[vm.Figure(figure=figure) for figure in example_cards + example_reference_cards], - controls=[vm.Filter(column="Category")], + title="Create your own KPI card", + layout=vm.Layout(grid=[[0, 1, -1, -1]] + [[-1, -1, -1, -1]] * 3), # (4)! + components=[ + vm.Figure( + figure=kpi_card( # (5)! + data_frame=tips, + value_column="tip", + value_format="${value:.2f}", + icon="shopping_cart", + title="Default KPI card", + ) + ), + vm.Figure( + figure=custom_kpi_card( # (6)! + data_frame=tips, + value_column="tip", + value_format="${value:.2f}", + icon="payment", + title="Custom KPI card", + ) + ), + ], ) dashboard = vm.Dashboard(pages=[page]) diff --git a/vizro-core/pyproject.toml b/vizro-core/pyproject.toml index 8a5ae98af..83aafac7c 100644 --- a/vizro-core/pyproject.toml +++ b/vizro-core/pyproject.toml @@ -79,7 +79,7 @@ filterwarnings = [ "ignore:(?s).*Pyarrow will become a required dependency of pandas:DeprecationWarning", # Ignore until plotly fixes so the warning is no longer raised: "ignore:When grouping with a length-1 list-like, you will need to pass a length-1 tuple to get_group:FutureWarning", - # Ignore warning when providing a custom format string to the KPI Cards: + # Ignore warning when providing a custom format string to the KPI cards: "ignore:Custom format string detected." ] norecursedirs = ["tests/tests_utils", "tests/js"]