[Docs] Update docstrings and screenshots for KPI cards (#556)

vizro-core/changelog.d/20240701_084052_huong_li_nguyen_update_docs_kpi.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

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",
                     )
                 ),
             ],

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]

vizro-core/examples/_dev/app.py

@@ -1,50 +1,68 @@
 """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.actions import filter_interaction
+from vizro.figures import kpi_card
 from vizro.models.types import capture
 
-df = px.data.iris()
-
-
-@capture("graph")
-def my_graph(data_frame, custom_data=None):
-    """Custom graph function."""
-    return px.scatter(
-        data_frame,
-        title="Title",
-        x="sepal_width",
-        y="sepal_length",
-        color="species",
-        # This does not work
-        custom_data=["species"],
-        # This works
-        # custom_data=custom_data
+tips = px.data.tips
+
+
+@capture("figure")  # (1)!
+def custom_kpi_card(  # noqa: PLR0913
+    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)
+
+    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")
 
 
 page = vm.Page(
-    title="",
+    title="Create your own KPI card",
+    layout=vm.Layout(grid=[[0, 1, -1, -1]] + [[-1, -1, -1, -1]] * 3),  # (4)!
     components=[
-        vm.Graph(
-            id="graph_1",
-            figure=my_graph(
-                data_frame=df,
-                # custom_data has to be propagated to the custom graph function to make the filter_interaction to work.
-                # custom_data=["species"],
-            ),
-            actions=[vm.Action(function=filter_interaction(targets=["graph_2"]))],
+        vm.Figure(
+            figure=kpi_card(  # (5)!
+                data_frame=tips,
+                value_column="tip",
+                value_format="${value:.2f}",
+                icon="shopping_cart",
+                title="Default KPI card",
+            )
         ),
-        vm.Graph(
-            id="graph_2", figure=px.scatter(df, title="Title", x="sepal_width", y="sepal_length", color="species")
+        vm.Figure(
+            figure=custom_kpi_card(  # (6)!
+                data_frame=tips,
+                value_column="tip",
+                value_format="${value:.2f}",
+                icon="payment",
+                title="Custom KPI card",
+            )
         ),
     ],
-    controls=[vm.Filter(column="species")],
 )
 
-
 dashboard = vm.Dashboard(pages=[page])
 
 if __name__ == "__main__":

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"]

vizro-core/src/vizro/figures/kpi_cards.py

@@ -104,7 +104,7 @@ def kpi_card_reference(  # noqa: PLR0913
              - "{value:,}": Formats the value with comma as a thousands separator.
 
         reference_format: Format string to be applied to the reference. For more details on possible placeholders, see
-            docstring on `value_format`. Defaults to "{delta_relative:.1%} vs. reference ({reference})".
+            docstring on `value_format`. Defaults to "{delta_relative:+.1%} vs. reference ({reference})".
         agg_func: String function name to be used for aggregating the data. Common options include
             "sum", "mean" or "median". Default is "sum". For more information on possible functions, see
             https://stackoverflow.com/questions/65877567/passing-function-names-as-strings-to-pandas-groupby-aggregrate.