Merge branch 'main' into docs/revise-vizro-ai-docs

vizro-core/changelog.d/20240219_132602_nadija_ratkusic_graca_datepicker.md

@@ -0,0 +1,46 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+### Highlights ✨
+
+- Introduce `DatePicker` model as a new `Filter` and `Parameter` selector. Visit the [user guide on selectors](https://vizro.readthedocs.io/en/stable/pages/user-guides/selectors/) for more details. ([#309](https://github.com/mckinsey/vizro/pull/309))
+
+<!--
+### 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/filters.md

@@ -3,7 +3,7 @@
 This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
 
 The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model allows the automatic creation of selectors (e.g. Dropdown, RadioItems, Slider, ...) that let a dashboard user filter with the charts/components on the screen.
+This model allows the automatic creation of [selectors](../user-guides/selectors.md) (e.g. Dropdown, RadioItems, Slider, ...) that operate upon the charts/components on the screen.
 
 
 ## Basic filters
@@ -14,7 +14,7 @@ To add a filter to your page, do the following:
 - configure the `column` argument, which denotes the target column to be filtered
 
 By default, all components on a page with such a `column` present will be filtered. The selector type will be chosen
-automatically based on the target column, e.g. a dropdown for categorical data or a range slider for numerical data.
+automatically based on the target column, e.g. a dropdown for categorical data, a range slider for numerical data, or a date picker for temporal data.
 
 !!! example "Basic Filter"
     === "app.py"
@@ -65,7 +65,7 @@ automatically based on the target column, e.g. a dropdown for categorical data o
 ## Changing selectors
 
 If you want to have a different selector for your filter, you can provide the `selector` argument of the [`Filter`][vizro.models.Filter] with a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider] and [`Slider`][vizro.models.Slider].
+Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
 
 !!! example "Filter with custom Selector"
     === "app.py"

vizro-core/docs/pages/user-guides/selectors.md

@@ -11,13 +11,13 @@ For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-opt
 the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
 [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
 
-For more details, kindly refer to the documentation of the underlying dash components:
+For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
 
-- [dcc.Dropdown](https://dash.plotly.com/dash-core-components/dropdown)
-- [dcc.Checklist](https://dash.plotly.com/dash-core-components/checklist)
-- [dcc.RadioItems](https://dash.plotly.com/dash-core-components/radioitems)
+- [`Dropdown`][vizro.models.Dropdown] based on [`dcc.Dropdown`](https://dash.plotly.com/dash-core-components/dropdown)
+- [`Checklist`][vizro.models.Checklist] based on [`dcc.Checklist`](https://dash.plotly.com/dash-core-components/checklist)
+- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
 
-???+ note
+!!! note
 
     When configuring the `options` of the categorical selectors, you can either provide:
 
@@ -26,20 +26,121 @@ For more details, kindly refer to the documentation of the underlying dash compo
 
     The later is required if you want to provide different display labels to your option values or in case you want to
     provide boolean values as options. In this case, you need to provide a string label for your boolean values as
-    boolean values cannot be displayed properly as labels in the underlying dash components.
+    boolean values cannot be displayed properly as labels in the underlying Dash components.
 
 ## Numerical selectors
 
-For more details, kindly refer to the documentation of the underlying dash components:
+For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
 
-- [dcc.Slider](https://dash.plotly.com/dash-core-components/slider])
-- [dcc.RangeSlider](https://dash.plotly.com/dash-core-components/rangeslider])
+- [`Slider`][vizro.models.Slider] based on [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider)
+- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
 
-???+ note
+!!! note
 
     When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
     unexpected behavior, such as the drag value being outside its indicated marks.
     To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
     [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
 
-To enhance existing selectors, please see our How-to-guide on creating [custom components](custom-components.md)
+## Temporal Selectors
+
+For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
+
+- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
+
+!!! note
+
+    When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
+
+    When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (e.g. `datetime.datetime(2024, 01, 01)`).
+
+## Default selectors
+
+If you don't specify a selector, a default selector is applied based on the data type of the provided column.
+
+Default selectors for:
+
+ - categorical data: [`Dropdown`][vizro.models.Dropdown]
+ - numerical data: [`RangeSlider`][vizro.models.RangeSlider]
+ - temporal data: [`DatePicker(range=True)`][vizro.models.DatePicker]
+
+Categorical selectors can be used independently of the data type of the column being filtered.
+
+To use numerical [`Filter`][vizro.models.Filter] selectors, the filtered column must be of `numeric` format,
+indicating that [pandas.api.types.is_numeric_dtype()](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) must return `True` for the filtered column.
+
+To use temporal [`Filter`][vizro.models.Filter] selectors, the filtered column must be of `datetime` format,
+indicating that [pandas.api.types.is_datetime64_any_dtype()](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) must return `True` for the filtered column.
+
+!!! tip
+
+    `pd.DataFrame` column types can be changed to `datetime` using [pandas.to_datetime()](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html) or
+
+
+### Example of default Filter selectors
+
+!!! example "Default Filter selectors"
+    === "app.py"
+        ```py
+        import pandas as pd
+        from vizro import Vizro
+        import vizro.plotly.express as px
+        import vizro.models as vm
+
+        df_stocks = px.data.stocks(datetimes=True)
+
+        df_stocks_long = pd.melt(
+            df_stocks,
+            id_vars='date',
+            value_vars=['GOOG', 'AAPL', 'AMZN', 'FB', 'NFLX', 'MSFT'],
+            var_name='stocks',
+            value_name='value'
+        )
+
+        df_stocks_long['value'] = df_stocks_long['value'].round(3)
+
+        page = vm.Page(
+            title="My first page",
+            components=[
+                vm.Graph(figure=px.line(df_stocks_long, x="date", y="value", color="stocks")),
+            ],
+            controls=[
+                vm.Filter(column="stocks"),
+                vm.Filter(column="value"),
+                vm.Filter(column="date"),
+            ],
+        )
+
+        dashboard = vm.Dashboard(pages=[page])
+
+        Vizro().build(dashboard).run()
+        ```
+    === "app.yaml"
+        ```yaml
+        # Still requires a .py to register data connector in Data Manager and parse yaml configuration
+        # See yaml_version example
+        pages:
+          - components:
+              - figure:
+                  _target_: line
+                  data_frame: df_stocks_long
+                  x: date
+                  y: value
+                  color: stocks
+                type: graph
+            controls:
+              - column: stocks
+                type: filter
+              - column: value
+                type: filter
+              - column: date
+                type: filter
+            title: My first page
+        ```
+    === "Result"
+        [![Filter]][Filter]
+
+    [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+
+
+To enhance existing selectors, please see our How-to-guide on creating [custom components](custom_components.md).