From 18150af8b86e19034ceaff995c84a961cdcaeddb Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 23 Feb 2024 13:59:27 +0000 Subject: [PATCH 01/32] Headings capitalisation and minor tweaks --- .../docs/pages/development/contributing.md | 2 +- .../pages/tutorials/explore-components.md | 14 ++++++------- vizro-core/docs/pages/user-guides/actions.md | 6 +++--- vizro-core/docs/pages/user-guides/assets.md | 12 +++++------ .../docs/pages/user-guides/card-button.md | 14 ++++++------- .../docs/pages/user-guides/components.md | 2 +- .../docs/pages/user-guides/container.md | 4 ++-- .../docs/pages/user-guides/custom-actions.md | 6 +++--- .../pages/user-guides/custom-components.md | 6 +++--- .../docs/pages/user-guides/dashboard.md | 4 ++-- vizro-core/docs/pages/user-guides/data.md | 14 ++++++------- vizro-core/docs/pages/user-guides/filters.md | 4 ++-- vizro-core/docs/pages/user-guides/install.md | 2 +- .../docs/pages/user-guides/integration.md | 15 +++++--------- vizro-core/docs/pages/user-guides/layouts.md | 4 ++-- .../docs/pages/user-guides/navigation.md | 6 +++--- .../docs/pages/user-guides/parameters.md | 4 ++-- .../docs/pages/user-guides/selectors.md | 4 ++-- vizro-core/docs/pages/user-guides/table.md | 2 +- vizro-core/mkdocs.yml | 20 +++++++++---------- 20 files changed, 70 insertions(+), 75 deletions(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index 229afbeb4..e57dae84d 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -2,7 +2,7 @@ Contributions of all experience levels are welcome! There are many ways to contribute, and we appreciate all of them. Please use our [issues page](https://github.com/mckinsey/vizro/issues) to discuss any contributions. Before opening a pull request, please ensure you've first opened an issue to discuss the contribution. -### Found a bug +### Found a bug? Great! We would appreciate if you could head to our [issues page](https://github.com/mckinsey/vizro/issues) and raise a ticket in the category `bug report`. It would greatly assist us if you could first check if there are any existing issues with a similar description before submitting a new ticket. We will promptly work on reproducing the bug you've reported and will follow up with the next steps. diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 791f5373e..415cecfca 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -18,7 +18,7 @@ In order to get started with this tutorial, you should have Vizro installed, and pasting it into a Jupyter notebook cell, or by running it from a python script. -### 2. Create first dashboard page +### 2. Create a first dashboard page At the core of every dashboard is a [`Page`][vizro.models.Page] object, which serves as its foundation. Think of it as a blank canvas where you can arrange and customize elements like charts and text. @@ -26,7 +26,7 @@ which serves as its foundation. Think of it as a blank canvas where you can arra In this first section, you will explore how to create a page with different elements and delve into the layout configuration. -#### 2.1. Add first component +#### 2.1. Add the first component First, let's define the structure of your dashboard page. Create a new [`Page`][vizro.models.Page] called `first_page` and assign a title. Each [`Page`][vizro.models.Page] allows you to define a list of `components`. These `components` are responsible for the content displayed on the page and can include a wide range of @@ -191,7 +191,7 @@ As you explore the added `components`, you may notice that the current layout could be further enhanced. The charts may appear cramped, while the text component has ample unused space. In the next section, we will learn how to configure the layout and effectively arrange the `components`. -#### 2.3. Configure layout +#### 2.3. Configure the layout To configure the appearance for your [`Page`][vizro.models.Page], the [`Layout`][vizro.models.Layout] object is utilized. It allows you to specify the placement and size of `components` on the grid. By default, each element is placed in the order they are added to the `components` list with equal space, as observed in the previous section. @@ -274,7 +274,7 @@ configure layouts, check out the [user guide](../user-guides/layouts.md) [FirstPage3]: ../../assets/tutorials/dashboard/dashboard23.png -#### 2.4. Configure filter +#### 2.4. Add and configure a filter The next thing you will learn is how to add functionality to your first dashboard page. This is achieved by adding `controls` to the [`Page`][vizro.models.Page]. `Controls` enable interaction with the `components` and empower users @@ -360,13 +360,13 @@ Fantastic job! By completing your first dashboard page, you have gained valuable [`Page`][vizro.models.Page] with multiple `components`, arranging them using layout configuration, and adding functionality to your dashboard. -### 3. Create second dashboard page +### 3. Create a second dashboard page Moving forward, you will add your second dashboard page to delve deeper into `controls` and explore different types of `selectors`. The structure is similar to the page you just created, and you configure two charts to visualize the iris data set. -#### 3.1. Configure parameter +#### 3.1. Configure parameters Next, you add two [`Parameters`][vizro.models.Parameter] to the `controls`. The first parameter will allow for changing the color of the virginica data, targeting both charts. The second parameter will adjust the opacity of the @@ -526,7 +526,7 @@ suit your specific needs. - [`RangeSlider`][vizro.models.RangeSlider] - [`Slider`][vizro.models.Slider] -### 4. Create final dashboard +### 4. Create the final dashboard Finally, it's time to put everything together and create a cohesive dashboard. In this section, we will focus on creating a homepage for your dashboard and provide seamless navigation to the previously built pages. diff --git a/vizro-core/docs/pages/user-guides/actions.md b/vizro-core/docs/pages/user-guides/actions.md index a6e577edb..f668a6a00 100644 --- a/vizro-core/docs/pages/user-guides/actions.md +++ b/vizro-core/docs/pages/user-guides/actions.md @@ -1,4 +1,4 @@ -# How to use Actions +# How to use actions This guide shows you how to use actions, a concept that is similar, but not identical, to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. Many components of a dashboard (e.g. [`Graph`][vizro.models.Graph] or [`Button`][vizro.models.Button]) have an optional `actions` argument, where you can enter the [`Action`][vizro.models.Action] model. @@ -279,11 +279,11 @@ Here is an example of how to configure a chart interaction when the source is a [Table]: ../../assets/user_guides/actions/actions_table_filter_interaction.png -## Pre-defined actions customization +## How to customize pre-defined actions Many pre-defined actions are customizable which helps to achieve more specific desired goal. For specific options, please refer to the [API reference][vizro.actions] on this topic. -## Actions chaining +### Chaining actions The `actions` parameter for the different screen components accepts a `List` of [`Action`][vizro.models.Action] models. This means that it's possible to set a list of actions that will be executed by triggering only one component. The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed. diff --git a/vizro-core/docs/pages/user-guides/assets.md b/vizro-core/docs/pages/user-guides/assets.md index 888f62a01..a45c79c82 100644 --- a/vizro-core/docs/pages/user-guides/assets.md +++ b/vizro-core/docs/pages/user-guides/assets.md @@ -25,11 +25,11 @@ The user-provided `assets` folder thus always takes precedence. Please note that Vizro is currently not compatible with [Dash Bootstrap Themes](https://dash-bootstrap-components.opensource.faculty.ai/docs/themes/). Adding a Bootstrap stylesheet will have no visual effect on the [components](https://vizro.readthedocs.io/en/stable/pages/user_guides/components/) included in Vizro. -## Changing the favicon +## How to change the favicon To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder. For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). -## Overwriting global CSS properties +## How to overwrite global CSS properties To overwrite any global CSS properties of existing components, target the right CSS property and place your CSS files in the `assets` folder. This will overwrite any existing defaults for that CSS property. For reference, see the [Vizro CSS files](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css). @@ -87,7 +87,7 @@ For reference, see the [Vizro CSS files](https://github.com/mckinsey/vizro/tree/ [AssetsCSS]: ../../assets/user_guides/assets/css_change.png -## Overwriting CSS properties in selective components +## How to overwrite CSS properties in selective components To overwrite CSS properties of selective components, provide an ID to the relevant component and target the right CSS property. For more information, see this [CSS selectors tutorial](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure). @@ -160,7 +160,7 @@ CSS properties will be applied with the last served file taking precedence. The Within each of these categories, individual files are served in alphanumerical order. -## Changing the `assets` folder path +## How to change the `assets` folder path If you do not want to place your `assets` folder in the root directory of your app, you can specify an alternative path through the `assets_folder` argument of the [`Vizro`][vizro.Vizro] class. @@ -179,7 +179,7 @@ Note that in the example above, you still need to configure your [`Page`][vizro. See more information in the [Pages User Guide](pages.md). -## Meta tags image +## How to include a meta tags image Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. To include an image in the preview, place an image file in the assets folder named `app.` or @@ -187,7 +187,7 @@ clients. To include an image in the preview, place an image file in the assets f Image types of `apng`, `avif`, `gif`, `jpeg`, `jpg`, `png`, `svg`, and `webp` are supported. -## Logo image +## How to add a logo image Vizro will automatically incorporate the dashboard logo in the top-left corner of each page if an image named `logo.` is present within the assets folder. diff --git a/vizro-core/docs/pages/user-guides/card-button.md b/vizro-core/docs/pages/user-guides/card-button.md index f67b80e85..9722fc97d 100755 --- a/vizro-core/docs/pages/user-guides/card-button.md +++ b/vizro-core/docs/pages/user-guides/card-button.md @@ -2,7 +2,7 @@ This guide shows you how to use cards and buttons to visualize and interact with your data in the dashboard. -## Card +## Cards The [`Card`][vizro.models.Card] is a flexible and extensible component, allowing for customization via Markdown text. For a basic guide on markdown text, please refer to the documentation [here](https://markdown-guide.readthedocs.io/en/latest/). @@ -49,7 +49,7 @@ You can add a [`Card`][vizro.models.Card] to your dashboard by inserting the [`C [Card]: ../../assets/user_guides/components/card.png -### Customizing text +### How to customize card text The [`Card`][vizro.models.Card] utilizes the `dcc.Markdown` component from Dash as its underlying text component. For more details on customizing the markdown text, refer to the `dcc.Markdown` component documentation [here](https://dash.plotly.com/dash-core-components/markdown). @@ -183,7 +183,7 @@ Based on the provided examples from Dash, the [`Card`][vizro.models.Card] model [CardText]: ../../assets/user_guides/components/card_text.png -### Placing images +### How to place an image on a card Images can be added to the `text` parameter by using the standard markdown syntax: @@ -255,7 +255,7 @@ accessibility of your app. Providing an image ALT text is optional. You might notice that the image is quite large, find out how to style images (e.g. position and size) in the next section! -### Styling images +### How to style a card image To change the styling of the image (e.g. size or position), add a URL hash to your image like this: @@ -395,7 +395,7 @@ and provide an attribute selector to select images with that matching URL hash. [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png -### Creating navigation +### How to create a navigation card !!! note @@ -497,7 +497,7 @@ If you now click on the card area, you should automatically be redirected to the - If the href provided is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to. - If the href provided is an absolute link, it should start with `https://` or an equivalent protocol. -### Adding an icon +### How to add an icon If you want to add an icon to your card, just add your image as described in the [previous section](#placing-images) If you use the image URL hash `icon-top`, the image will be styled according to our default icon styling. @@ -590,7 +590,7 @@ If you use the image URL hash `icon-top`, the image will be styled according to Note that in the above example the first [`Card`][vizro.models.Card] navigates to an existing [`Page`][vizro.models.Page] in the app with `path = filters-and-parameters` and the second one to an external link. -## Button +## Buttons To enhance dashboard interactions, you can use the [`Button`][vizro.models.Button] component to trigger any pre-defined action functions such as e.g. exporting chart data. Please refer to the [user guide][vizro.actions] on diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md index b32c4e1ae..de1a5c933 100755 --- a/vizro-core/docs/pages/user-guides/components.md +++ b/vizro-core/docs/pages/user-guides/components.md @@ -22,7 +22,7 @@ listed below to fill your dashboard with visuals. [:octicons-arrow-right-24: View User Guide](table.md) -- :material-cards-outline:{ .lg .middle } __Card & Button__ +- :material-cards-outline:{ .lg .middle } __Card & button__ --- diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md index 2b962cddf..5ef909dd0 100755 --- a/vizro-core/docs/pages/user-guides/container.md +++ b/vizro-core/docs/pages/user-guides/container.md @@ -35,7 +35,7 @@ Here are a few cases where you might want to use a `Container` instead of `Page. - If you want to apply controls to selected subgrids (will be supported soon) -## Basic Containers +## Basic containers To add a [`Container`][vizro.models.Container] to your page, do the following: 1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page] @@ -159,7 +159,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following: Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) e.g. by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`. -## Nested Containers +## Nested containers Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability allows users to create more complex layouts and manage related components at any level of granularity. diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md index aced0153c..8ec3d9bec 100644 --- a/vizro-core/docs/pages/user-guides/custom-actions.md +++ b/vizro-core/docs/pages/user-guides/custom-actions.md @@ -4,7 +4,7 @@ This guide demonstrates the usage of custom actions, a concept that shares simil If you want to use the [`Action`][vizro.models.Action] model to perform functions that are not available in the [pre-defined action functions][vizro.actions], you can create your own custom action. Like other [actions](actions.md), custom actions could also be added as an element inside the [actions chain](actions.md#actions-chaining), and it can be triggered with one of many dashboard components. -### Simple custom actions +## Simple custom actions Custom actions enable you to implement your own action function. Simply do the following: @@ -63,7 +63,7 @@ The following example shows how to create a custom action that postpones executi ``` -### Interacting with dashboard inputs and outputs +## Interacting with dashboard inputs and outputs When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action. - `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (e.g. `"scatter_chart.clickData`"). @@ -146,7 +146,7 @@ The following example shows how to create a custom action that shows the clicked [CustomAction]: ../../assets/user_guides/custom_actions/custom_action_inputs_outputs.png -### Multiple return values +## Multiple return values The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's normal flexibility in managing multiple return values. diff --git a/vizro-core/docs/pages/user-guides/custom-components.md b/vizro-core/docs/pages/user-guides/custom-components.md index 2c5665298..8408f9ca4 100644 --- a/vizro-core/docs/pages/user-guides/custom-components.md +++ b/vizro-core/docs/pages/user-guides/custom-components.md @@ -28,7 +28,7 @@ or if you would like to use additional `args` or `kwargs` of those components, t [^1]: You can easily check if your new component will be part of a discriminated union by consulting our [API reference on models](../API-reference/models.md). Check whether the relevant model field (e.g. `selectors` in [`Filter`][vizro.models.Filter] or [`Parameter`][vizro.models.Parameter]) is described as a discriminated union (in this case the [`SelectorType`][vizro.models.types.SelectorType] is, but for example [`OptionsType`][vizro.models.types.OptionsType] is not). -## Extend an existing component +## How to extend an existing component ??? info "When to choose this strategy" You may want to use this strategy to: @@ -147,7 +147,7 @@ vm.Parameter.add_type("selector", TooltipNonCrossRangeSlider) [CustomComponent1]: ../../assets/user_guides/custom_components/customcomponent_1.png -## Entirely new component +## Create a new component ??? info "When to choose this strategy" @@ -198,7 +198,7 @@ vm.Page.add_type("components", Jumbotron) ``` -??? example "Example of entirely new component" +??? example "Example of new component creation" === "app.py" ``` py diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md index 69936f26f..91a21b1f9 100644 --- a/vizro-core/docs/pages/user-guides/dashboard.md +++ b/vizro-core/docs/pages/user-guides/dashboard.md @@ -183,12 +183,12 @@ To create a dashboard: After running the dashboard, you can access the dashboard via `localhost:8050`. -## Adding a dashboard title +## How to add a dashboard title If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page. -## Adding a dashboard logo +## How to add a dashboard logo Vizro will automatically incorporate the dashboard [logo](assets.md/#logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder. diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md index 5046f2f4f..1fae01545 100644 --- a/vizro-core/docs/pages/user-guides/data.md +++ b/vizro-core/docs/pages/user-guides/data.md @@ -43,7 +43,7 @@ Here `px.data.iris()` returns a Pandas DataFrame. We then pass this DataFrame to -## Use a data connector +## How to use a data connector You can also connect your charts with a data connector. To use a data connector with Vizro, you need: @@ -56,7 +56,7 @@ Vizro, you need: This allows you to use this data connector in your dashboard. -!!! example "Use a Data Connector" +!!! example "Use a Data connector" === "app.py" ```py linenums="1" hl_lines="18" from vizro import Vizro @@ -116,14 +116,14 @@ Vizro, you need: how Vizro knows which data connector to use. -### Data connector with arguments +### How to use a data connector with arguments You can also define a data connector with arguments. This is useful when you want to use the same data connector to load different data. For example, when you want to retrieve data from different tables in a database, you can define a data connector that accepts different SQL queries as arguments. -!!! example "Use a Data Connector with Arguments" +!!! example "Use a Data Connector with arguments" === "app.py (use lambda)" ```py linenums="1" from vizro import Vizro @@ -188,11 +188,11 @@ that accepts different SQL queries as arguments. [DataConnector]: ../../assets/user_guides/data/data_selected_from_source.png -### Kedro data catalog +### Kedro integration If the data you are visualizing is a [`kedro_datasets.pandas`](https://docs.kedro. -org/en/stable/kedro_datasets.html) type from a Kedro data catalog, you can leverage -Vizro's [Kedro integration](integration.md#kedro) to connect your charts to the data catalog. +org/en/stable/kedro_datasets.html) type from a Kedro data catalog, you can use +Vizro's [Kedro integration](integration.md#kedro) to connect your charts to [Kedro's Data Catalog](https://docs.kedro.org/en/stable/data/index.html). If it is not a `kedro_datasets.pandas` type, you need to build a data connector to load the data from the data catalog and convert it to a Pandas diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md index a5d623fb8..7f51f4ce1 100644 --- a/vizro-core/docs/pages/user-guides/filters.md +++ b/vizro-core/docs/pages/user-guides/filters.md @@ -6,7 +6,7 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you 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. -## Basic Filters +## Basic filters To add a filter to your page, do the following: @@ -62,7 +62,7 @@ automatically based on the target column, e.g. a dropdown for categorical data o [Filter]: ../../assets/user_guides/control/control1.png -## Changing Selectors +## 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]. diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index b3654ee22..24339ef14 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -16,7 +16,7 @@ This guide shows you how to install Vizro. It will provide detailed explanation - install the [Anaconda Navigator](https://www.anaconda.com/download) - create a new environment as [outlined here](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/), choose a Python version `>=3.8` -## Install +## Installation To install Vizro from the Python Package Index (PyPI), use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: diff --git a/vizro-core/docs/pages/user-guides/integration.md b/vizro-core/docs/pages/user-guides/integration.md index faa0f4961..b60a35365 100644 --- a/vizro-core/docs/pages/user-guides/integration.md +++ b/vizro-core/docs/pages/user-guides/integration.md @@ -1,21 +1,16 @@ -# How to integrate Vizro with other tools +# How to integrate Vizro with Kedro -This page describes how to integrate Vizro with other tools. - -## Kedro - -[Kedro](https://docs.kedro.org/en/stable/index.html) is an open-source Python framework to create reproducible, maintainable, and -modular data science code. For Pandas datasets registered in a Kedro data catalog, +This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them. -### Installation +## Installation To install Vizro with Kedro support, run: ```bash pip install vizro[kedro] ``` -### Using datasets from the Kedro Data Catalog +## Using datasets from the Kedro Data Catalog `vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the [Vizro Data Manager][vizro.managers._data_manager] is: ```python from vizro.integrations import kedro as kedro_integration @@ -36,7 +31,7 @@ The `catalog` variable may have been created in a number of different ways: The full code for these different cases is given below. -!!! example "Import a Kedro Data Catalog to the Vizro Data Manager" +!!! example "Import a Kedro Data Catalog into the Vizro Data Manager" === "app.py (Kedro project path)" ```py from vizro.integrations import kedro as kedro_integration diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md index 0eab12f09..baa3b5af0 100644 --- a/vizro-core/docs/pages/user-guides/layouts.md +++ b/vizro-core/docs/pages/user-guides/layouts.md @@ -82,7 +82,7 @@ This defines a single row that occupies the entire width and height, divided int ![Stacking components](../../assets/user_guides/layout/stacking.png){ width="680" } -### Grid - Basic Example +### Grid - basic example !!! example "Grid Arrangement - Basic Example" === "app.py" ```py @@ -126,7 +126,7 @@ This defines a single row that occupies the entire width and height, divided int [Grid]: ../../assets/user_guides/layout/one_left_two_right.png -### Grid - Advanced Example +### Grid - advanced example Generally, the `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids. diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md index 42d141296..a9b768901 100644 --- a/vizro-core/docs/pages/user-guides/navigation.md +++ b/vizro-core/docs/pages/user-guides/navigation.md @@ -74,7 +74,7 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png -## Including only some pages +## Including a subset of pages If you wish to include only some of your dashboard pages in your navigation then list them in the `pages` argument of the `Navigation` model. To refer to a page inside the `Navigation` model, you should always use the page's `id`, which [defaults to the page `title`](pages.md#customizing-the-page-url), e.g. we specify `pages = ["My first page", "My second page"]` rather than `pages=[page_1, page_2]`. @@ -103,7 +103,7 @@ If you wish to include only some of your dashboard pages in your navigation then [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png -## Grouping your pages +## Grouping pages You can also group your pages together by specifying `pages` as a dictionary: @@ -137,7 +137,7 @@ You can also group your pages together by specifying `pages` as a dictionary: [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png -## Navigation bar with icons +## Using a navigation bar with icons Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]: diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md index bff419a80..073e5879c 100644 --- a/vizro-core/docs/pages/user-guides/parameters.md +++ b/vizro-core/docs/pages/user-guides/parameters.md @@ -4,7 +4,7 @@ This guide shows you how to add parameters to your dashboard. One main way to in The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Parameter`][vizro.models.Parameter] model. If e.g. the charting function has a `title` argument, you could configure a parameter that allows the user to select the chart title via e.g. a dropdown. -## Basic Parameters +## Basic parameters To add a parameter to your page, do the following: @@ -80,7 +80,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure !!! tip If you would like to pass `None` as a parameter, e.g. in order to make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field. -## Nested Parameters +## Nested parameters If you want to modify nested parameters, you can specify the `targets` argument with a dot separated string like `..`. diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md index 14aef61fc..55c2a1888 100644 --- a/vizro-core/docs/pages/user-guides/selectors.md +++ b/vizro-core/docs/pages/user-guides/selectors.md @@ -4,7 +4,7 @@ This guide highlights different selectors that can be used in a dashboard. Selec The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter] model accept the `selector` argument, where a selector model can be entered to choose how the user should input their choices for the respective models. -## Categorical Selectors +## Categorical selectors Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while @@ -28,7 +28,7 @@ For more details, kindly refer to the documentation of the underlying dash compo 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. -## Numerical Selectors +## Numerical selectors For more details, kindly refer to the documentation of the underlying dash components: diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md index aa5e17520..f7a3525b2 100755 --- a/vizro-core/docs/pages/user-guides/table.md +++ b/vizro-core/docs/pages/user-guides/table.md @@ -63,7 +63,7 @@ setting some defaults for some of the arguments to help with styling. [Table]: ../../assets/user_guides/table/table.png -#### Styling/Modifying the Dash DataTable +#### Styling and modifying the Dash DataTable As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase. diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index 4a61da730..feb30bfb2 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -5,17 +5,17 @@ nav: - Get started: - Quickstart: pages/tutorials/first-dashboard.md - Explore Vizro: pages/tutorials/explore-components.md - - User Guides: + - User guides: - FUNDAMENTALS: - Install: pages/user-guides/install.md - Dashboards: pages/user-guides/dashboard.md - Pages: pages/user-guides/pages.md - - Run Methods: pages/user-guides/run.md + - Run methods: pages/user-guides/run.md - COMPONENTS: - Overview: pages/user-guides/components.md - Graphs: pages/user-guides/graph.md - Tables: pages/user-guides/table.md - - Cards & Buttons: pages/user-guides/card-button.md + - Cards & buttons: pages/user-guides/card-button.md - Containers: pages/user-guides/container.md - Tabs: pages/user-guides/tabs.md - CONTROLS: @@ -34,19 +34,19 @@ nav: - Data: pages/user-guides/data.md - Integrations: pages/user-guides/integration.md - EXTENSIONS: - - Custom Charts: pages/user-guides/custom-charts.md - - Custom Tables: pages/user-guides/custom-tables.md - - Custom Components: pages/user-guides/custom-components.md - - Custom Actions: pages/user-guides/custom-actions.md + - Custom charts: pages/user-guides/custom-charts.md + - Custom tables: pages/user-guides/custom-tables.md + - Custom components: pages/user-guides/custom-components.md + - Custom actions: pages/user-guides/custom-actions.md - API Reference: - Vizro: pages/API-reference/vizro.md - Models: pages/API-reference/models.md - - Data Manager: pages/API-reference/manager.md + - Data manager: pages/API-reference/manager.md - Actions: pages/API-reference/actions.md - Explanation: - - Why Vizro: pages/explanation/why-vizro.md + - Why Vizro?: pages/explanation/why-vizro.md - Contribute: - - Contributing: pages/development/contributing.md + - Contribute to Vizro: pages/development/contributing.md - Documentation style: pages/development/documentation-style-guide.md - Authors: pages/development/authors.md From 6c905a8b8fc0866480156e9059485dbc9df73fc6 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 23 Feb 2024 13:59:33 +0000 Subject: [PATCH 02/32] Update authors.md --- vizro-core/docs/pages/development/authors.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/vizro-core/docs/pages/development/authors.md b/vizro-core/docs/pages/development/authors.md index 43d1c5f00..c687a66a6 100644 --- a/vizro-core/docs/pages/development/authors.md +++ b/vizro-core/docs/pages/development/authors.md @@ -1,16 +1,19 @@ ## Current team members -[Chiara Pullem](https://github.com/chiara-sophie), -[Antony Milne](https://github.com/antonymilne), +[Alexey Snigir](https://github.com/l0uden), [Anna Xiong](https://github.com/Anna-Xiong), +[Antony Milne](https://github.com/antonymilne), +[Chiara Pullem](https://github.com/chiara-sophie), +[Dan Dumitriu](https://github.com/dandumitriu1), +[Huong Li Nguyen](https://github.com/huong-li-nguyen), +[Jo Stichbury](https://github.com/stichbury), +[Joseph Perkins](https://github.com/Joseph-Perkins), [Lingyi Zhang](https://github.com/lingyielia), +[Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), [Petar Pejovic](https://github.com/petar-qb) -[Alexey Snigir](https://github.com/l0uden), -[Maximilian Schulz](https://github.com/maxschulz-COL), -[Huong Li Nguyen](https://github.com/huong-li-nguyen), -[Dan Dumitriu](https://github.com/dandumitriu1), -[Joseph Perkins](https://github.com/Joseph-Perkins), + + ## Previous team members and code contributors @@ -19,7 +22,6 @@ Natalia Kurakina, [Leon Nallamuthu](https://github.com/leonnallamuthu), [axa99](https://github.com/axa99), -[Jo Stichbury](https://github.com/stichbury), [Juan Luis Cano Rodríguez](https://github.com/astrojuanlu), [Denis Lebedev](https://github.com/DenisLebedevMcK), [Qiuyi Chen](https://github.com/Qiuyi-Chen), From 727775e17b5c5f5d4193e7f2bcfd9fa8e2bc4cfb Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 23 Feb 2024 15:09:13 +0000 Subject: [PATCH 03/32] Link fixes and word repetition --- vizro-core/docs/pages/development/contributing.md | 4 ++-- vizro-core/docs/pages/explanation/why-vizro.md | 2 +- vizro-core/docs/pages/tutorials/first-dashboard.md | 2 +- vizro-core/docs/pages/user-guides/card-button.md | 4 ++-- vizro-core/docs/pages/user-guides/container.md | 4 ++-- vizro-core/docs/pages/user-guides/custom-charts.md | 2 +- vizro-core/docs/pages/user-guides/themes.md | 2 +- 7 files changed, 10 insertions(+), 10 deletions(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index e57dae84d..641361b77 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -67,7 +67,7 @@ hatch run test To run only python unit tests, run `hatch run test-unit`, and for python integration tests only run `hatch run test-integration`. -For integration tests, all examples are executed in separate testing sessions due to [this](https://github.com/mckinsey/vizro/issues/10) issue by providing the `-k` tag per example. +For integration tests, [all examples are executed in separate testing sessions](https://github.com/mckinsey/vizro/issues/10) by providing the `-k` tag per example. Arguments are passed through to the underlying `pytest` command, e.g. @@ -180,7 +180,7 @@ To build the source distribution and wheel, run `hatch build`. The Vizro team pledges to foster and maintain a friendly community. We enforce a [Code of Conduct](https://github.com/mckinsey/vizro/tree/main/CODE_OF_CONDUCT.md) to ensure every Vizro contributor is welcomed and treated with respect. -## FAQ +## Frequently asked questions ### How do I add a dependency? diff --git a/vizro-core/docs/pages/explanation/why-vizro.md b/vizro-core/docs/pages/explanation/why-vizro.md index 7771da6e3..b7d96fd15 100644 --- a/vizro-core/docs/pages/explanation/why-vizro.md +++ b/vizro-core/docs/pages/explanation/why-vizro.md @@ -31,7 +31,7 @@ Users can configure Vizro dashboards without needing to know advanced software d This removes most of the "glue code" that would otherwise need to be written. Thousands of lines of code are reduced to tens of lines of configuration. Users can configure Vizro dashboards without needing to know any advanced software development principles of how to build front-end applications. -### 2) Extend & customize infinitely +### 2) Extend and customize infinitely Users benefit from the power of the Dash framework and the flexibility of React. diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index a531e2e1b..cc64dbffe 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -30,7 +30,7 @@ jupyter notebook The command opens a browser tab and you can navigate to your preferred folder for this new project. Create a new notebook `Python 3 (ipykernel)` notebook from the "New" dropdown. ??? tip "Beginners/Code novices" - If you followed the beginners steps in the the [installation guide](../user-guides/install.md), you should already be set, and you can continue below. + If you followed the beginners steps in the [installation guide](../user-guides/install.md), you should already be set, and you can continue below. Confirm that Vizro is installed by typing the following into a cell in the notebook and running it. diff --git a/vizro-core/docs/pages/user-guides/card-button.md b/vizro-core/docs/pages/user-guides/card-button.md index 9722fc97d..0be49793f 100755 --- a/vizro-core/docs/pages/user-guides/card-button.md +++ b/vizro-core/docs/pages/user-guides/card-button.md @@ -5,7 +5,7 @@ This guide shows you how to use cards and buttons to visualize and interact with ## Cards The [`Card`][vizro.models.Card] is a flexible and extensible component, allowing for customization via Markdown text. -For a basic guide on markdown text, please refer to the documentation [here](https://markdown-guide.readthedocs.io/en/latest/). +Refer to any online guide for [basic markdown usage](https://markdown-guide.readthedocs.io/en/latest/). You can add a [`Card`][vizro.models.Card] to your dashboard by inserting the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page]. @@ -52,7 +52,7 @@ You can add a [`Card`][vizro.models.Card] to your dashboard by inserting the [`C ### How to customize card text The [`Card`][vizro.models.Card] utilizes the `dcc.Markdown` component from Dash as its underlying text component. -For more details on customizing the markdown text, refer to the `dcc.Markdown` component documentation [here](https://dash.plotly.com/dash-core-components/markdown). +For more details on customizing the markdown text, refer to the [`dcc.Markdown` component documentation](https://dash.plotly.com/dash-core-components/markdown). Based on the provided examples from Dash, the [`Card`][vizro.models.Card] model supports the following: - Headers diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md index 5ef909dd0..efffb2fa8 100755 --- a/vizro-core/docs/pages/user-guides/container.md +++ b/vizro-core/docs/pages/user-guides/container.md @@ -40,8 +40,8 @@ To add a [`Container`][vizro.models.Container] to your page, do the following: 1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page] 2. Provide a `title` to your `Container` -3. Configure your `components`, see our overview page on the various options [here](components.md) -4. (optional) Configure your `layout` , see our guide on [`Layout`](layouts.md) +3. Configure your `components`, see [the overview page on the various options](components.md) +4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md) !!! example "Container" === "app.py" diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md index d2951c3b0..919441483 100644 --- a/vizro-core/docs/pages/user-guides/custom-charts.md +++ b/vizro-core/docs/pages/user-guides/custom-charts.md @@ -98,7 +98,7 @@ add a `Parameter` that allows the dashboard user to interact with the argument, ## New Waterfall chart based on `go.Figure()` -The below examples shows a more involved use-case. We create and style a waterfall chart, and add it alongside a filter to the dashboard. The example is based on [this](https://plotly.com/python/waterfall-charts/) tutorial. +The below examples shows a more involved use-case. We create and style a waterfall chart, and add it alongside a filter to the dashboard. The example is based on [a plotly waterfall chart tutorial](https://plotly.com/python/waterfall-charts/). !!! example "Custom `go.Figure()` waterfall chart with a `Parameter`" === "app.py" diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md index 7a4faeb32..ae36c3b96 100644 --- a/vizro-core/docs/pages/user-guides/themes.md +++ b/vizro-core/docs/pages/user-guides/themes.md @@ -64,7 +64,7 @@ you can still switch between the themes via the toggle button in the upper-right ## Themes in plotly charts You can also use our templates for plotly charts outside the dashboard. Our `vizro_dark` and `vizro_light` theme are automatically registered to `plotly.io.templates` when importing Vizro. -You can find more details on how templates work in plotly.express [here](https://plotly.com/python/templates/#theming-and-templates). +Consult the plotly documentation for [more details on how templates work in plotly.express](https://plotly.com/python/templates/#theming-and-templates). ### Set themes for all charts The default plotly.io template is set to be `vizro_dark` as soon as you `import vizro`: From 5ec83463138cd3902f4741639e591d60dfd529e1 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 23 Feb 2024 17:28:58 +0000 Subject: [PATCH 04/32] Update .gitignore --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 79a54175f..08f969bb4 100644 --- a/.gitignore +++ b/.gitignore @@ -85,7 +85,8 @@ instance/ # Scrapy .scrapy -# mkdocs +# mkdocs and docs +vizro-core/docs/.vale vizro-core/site vizro-ai/site From 059a5f49a8eb1b89e72202cc2f948221c2792a1f Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 10:39:02 +0000 Subject: [PATCH 05/32] Update installation guide --- vizro-core/docs/pages/user-guides/install.md | 139 +++++++++++++++---- vizro-core/mkdocs.yml | 4 +- 2 files changed, 113 insertions(+), 30 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 24339ef14..79c267fd4 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -1,46 +1,127 @@ # How to install Vizro -This guide shows you how to install Vizro. It will provide detailed explanation on how to install, update and verify the current version of vizro. +This guide shows you how to install Vizro, how to verify the installation succeeded and find the version of Vizro, and how to update Vizro. ## Prerequisites -- **Python**: Vizro supports macOS, Linux, and Windows. It is designed to work with Python 3.8 and above. The python - version can be specified when setting up your virtual environment. -- **Virtual environment**: We suggest to create a new virtual environment for each new Vizro project you work on to - isolate its Python dependencies from those of other projects. See the following references to learn more about [python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). +**Python**: Vizro supports macOS, Linux, and Windows. It is designed to work with Python 3.8 and above. You specify the version of Python to use with Vizro when you set up your virtual environment. -??? tip "Beginners/Code novices" - If you consider yourself a beginner or coding novice, you can follow the steps in these boxes to completely avoid the terminal usage +**Virtual environment**: You should create a virtual environment for each Vizro project you work on to + isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). - - install the [Anaconda Navigator](https://www.anaconda.com/download) - - create a new environment as [outlined here](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/), choose a Python version `>=3.8` +!!! tip "Prefer to use Vizro without opening a terminal window?" + + If you are a beginner or coding novice, you may prefer to avoid using a terminal to work with Vizro. Skip to the ["Use Vizro inside Anaconda" section](#use-vizro-inside-anaconda-navigator) below. -## Installation + -To install Vizro from the Python Package Index (PyPI), use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: +??? information "How to create a virtual environment for your Vizro project" + + ### Using `conda` + We strongly recommend [installing `conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/) if you don't already use it. Once installed, create a virtual environment from the terminal as follows: + + ```bash + conda create --name vizro-environment python=3.10 -y + ``` + + (The example above uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8 and <3.12), and name it anything you choose). + + Activate your virtual environment from any directory: + + ```bash + conda activate kedro-environment + ``` + + To confirm that a valid version of Python is installed in your virtual environment, type the following in your terminal (macOS and Linux): + + ```bash + python3 --version + ``` + + On Windows: + + ```bash + python --version + ``` + + ??? information "How to create a virtual environment without using conda" + + ### How to create a new virtual environment without using `conda` + + You can alternatively create virtual environments using `venv` or `pipenv` instead of `conda`. + + #### `venv` + + You should already have the `venv` module installed with the Python 3 standard library. Create a directory for working with your project and navigate to it. For example: + + ```bash + mkdir vizro-environment && cd vizro-environment + ``` + + Next, create a new virtual environment in this directory with `venv`: + + ```bash + python -m venv .venv + ``` + + To activate: + + ```bash + source .venv/bin/activate # macOS / Linux + .\.venv\Scripts\activate # Windows + ``` + + + ####`pipenv` + + From any directory: + + ```bash + pip install pipenv + ``` + + Create a directory for working with your project and navigate to it. For example: + + ```bash + mkdir vizro-environment && cd vizro-environment + ``` + + To start a session with the correct virtual environment activated: + + ```bash + pipenv shell + ``` + + + +## Install vizro + +To install Vizro, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: ```bash pip install vizro ``` -You can run any code from the tutorials and user guides using a python script, but it is arguably more convenient to use a Jupyter notebook. In this case you can optionally install `jupyter`: -```bash -pip install jupyter -``` +## Use Vizro inside Anaconda Navigator + +To completely avoid terminal usage, follow these steps to work with Vizro: + + +1. Install [Anaconda Navigator](https://www.anaconda.com/download). -??? tip "Beginners/Code novices" - If you consider yourself a beginner or coding novice, you can follow the steps in these boxes to completely avoid the terminal usage +2. Create a new environment as [outlined in the Anaconda documentation](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/). Choose a Python version `>=3.8`. - - search `vizro` and subsequently install it [using the Anaconda Navigator package manager](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/ ) - - search `jupyter` and subsequently install it following the same procedure - - it should now be easy to [launch a jupyter notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) - - you can paste any of the examples into a notebook cell, evaluate the cell and inspect the results - happy vizro'ing! +3. Search `vizro` and install it [using the Anaconda Navigator package manager](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/). + +4. Similarly, search `jupyter` and install it. +5. [Launch a Jupyter notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro. -## Verify version -Once Vizro is installed, if you would like to verify the version of Vizro or check if everything worked, simply run the following code from a python script or a Jupyter notebook cell: +## Confirm a successful installation + +To confirm the installation above was successful, and verify the version of Vizro installed, call the following from within a Jupyter notebook cell (or run the following as a Python script): ```py import vizro @@ -48,14 +129,16 @@ import vizro print(vizro.__version__) ``` -You should see a return output of the form `0.1.0`. +You should see a return output of the form `x.y.z`. ## Upgrade -To later upgrade Vizro to a different version, simply run: -``` +To change the version of Vizro installed: + +```bash pip install vizro -U ``` -The best way to safely upgrade is to check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-core/CHANGELOG.md) for any notable breaking changes before migrating an -existing project. +!!! tip Check the Vizro release notes + + To upgrade safely, check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-core/CHANGELOG.md) for any notable breaking changes before migrating an existing project. diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index feb30bfb2..f457a6f51 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -3,11 +3,11 @@ site_url: https://mckinsey.github.io/vizro/ nav: - Vizro: index.md - Get started: - - Quickstart: pages/tutorials/first-dashboard.md + - Install Vizro: pages/user-guides/install.md + - Dashboard quickstart: pages/tutorials/first-dashboard.md - Explore Vizro: pages/tutorials/explore-components.md - User guides: - FUNDAMENTALS: - - Install: pages/user-guides/install.md - Dashboards: pages/user-guides/dashboard.md - Pages: pages/user-guides/pages.md - Run methods: pages/user-guides/run.md From d28364235197ce078e7cdd8c04e730ca7dc899cc Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 10:39:09 +0000 Subject: [PATCH 06/32] Update documentation-style-guide.md --- .../docs/pages/development/documentation-style-guide.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/vizro-core/docs/pages/development/documentation-style-guide.md b/vizro-core/docs/pages/development/documentation-style-guide.md index 5755321d9..fc02cf2f8 100644 --- a/vizro-core/docs/pages/development/documentation-style-guide.md +++ b/vizro-core/docs/pages/development/documentation-style-guide.md @@ -94,8 +94,12 @@ This is less helpful: Don't write this: + + > To learn how to contribute to Vizro, see [here](https://vizro.readthedocs.io/en/stable/pages/development/contributing/). + + ### Internal cross-referencing We use internal cross-references as follows: From e0216942e884ced397e0dcd93db08ef0b99e1a3c Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 11:17:12 +0000 Subject: [PATCH 07/32] Update install.md --- vizro-core/docs/pages/user-guides/install.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 79c267fd4..8fe0601b2 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -4,7 +4,7 @@ This guide shows you how to install Vizro, how to verify the installation succee ## Prerequisites -**Python**: Vizro supports macOS, Linux, and Windows. It is designed to work with Python 3.8 and above. You specify the version of Python to use with Vizro when you set up your virtual environment. +**Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.8 and later. You can specify the version of Python to use with Vizro when you set up a virtual environment. **Virtual environment**: You should create a virtual environment for each Vizro project you work on to @@ -25,7 +25,7 @@ This guide shows you how to install Vizro, how to verify the installation succee conda create --name vizro-environment python=3.10 -y ``` - (The example above uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8 and <3.12), and name it anything you choose). + (This example uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8 and <3.12), and name it anything you choose). Activate your virtual environment from any directory: @@ -102,9 +102,11 @@ To install Vizro, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal w ```bash pip install vizro ``` + ## Use Vizro inside Anaconda Navigator + To completely avoid terminal usage, follow these steps to work with Vizro: @@ -121,7 +123,7 @@ To completely avoid terminal usage, follow these steps to work with Vizro: ## Confirm a successful installation -To confirm the installation above was successful, and verify the version of Vizro installed, call the following from within a Jupyter notebook cell (or run the following as a Python script): +To confirm the installation was successful, and verify the version of Vizro installed, call the following. You can do this from within a Jupyter notebook cell, or run the following as a Python script: ```py import vizro From d487ef44fe8936e89be87de55b1508b80298910e Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 11:39:09 +0000 Subject: [PATCH 08/32] Page updates --- .../docs/pages/tutorials/first-dashboard.md | 48 +++++++++---------- vizro-core/docs/pages/user-guides/install.md | 2 +- vizro-core/mkdocs.yml | 2 +- 3 files changed, 25 insertions(+), 27 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index cc64dbffe..c21b2d8fb 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -1,39 +1,40 @@ -# Get started with Vizro +# A first dashboard -This tutorial introduces Vizro. It is a step-by-step guide to create a first dashboard and is designed to equip you with the knowledge to explore the documentation further. +This is a quickstart guide to create your first dashboard and set you up to explore Vizro further. -If you want a more complete tutorial exploring more of the available features, please see the [Explore Vizro tutorial](../tutorials/explore-components.md). +The [Explore Vizro tutorial](../tutorials/explore-components.md) is a more complete exploration of Vizro's features. -## Let's get started! +## Get started ### 1. Install Vizro and its dependencies -If you haven't already installed Vizro, follow the [installation guide](../user-guides/install.md) to do so inside a virtual environment. - -If you consider yourself a beginner to python and/or virtual environments, there is also a section that avoids any use of terminals and relies only upon a graphical user interface. +If you haven't already installed Vizro, follow the [installation guide](../user-guides/install.md). ### 2. Open a Jupyter notebook -A good way to initially explore Vizro is from inside a Jupyter notebook. If you haven't used one of these before, you may need to install the Jupyter package: +A good way to initially explore Vizro is from inside a Jupyter Notebook. -```console -pip install jupyter -``` +??? "Install and run Jupyter" -From the terminal window, with the virtual environment you installed Vizro in active, start a new notebook as follows: + If you haven't used Jupyter before, you may need to install the Jupyter package. From the terminal window: + + ```bash + pip install jupyter + ``` -```console -jupyter notebook -``` + Alternatively, you can [work within Anaconda Navigator](../user-guides/install.md#use-vizro-inside-anaconda-navigator) as described in the Vizro installation guide. + -The command opens a browser tab and you can navigate to your preferred folder for this new project. Create a new notebook `Python 3 (ipykernel)` notebook from the "New" dropdown. +Activate the virtual environment you used to install Vizro, and start a new Notebook as follows: -??? tip "Beginners/Code novices" - If you followed the beginners steps in the [installation guide](../user-guides/install.md), you should already be set, and you can continue below. +```bash +jupyter notebook +``` +The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. -Confirm that Vizro is installed by typing the following into a cell in the notebook and running it. +Create a new notebook `Python 3 (ipykernel)` notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. ```py import vizro @@ -41,11 +42,11 @@ import vizro print(vizro.__version__) ``` -You should see a return output of the form `0.1.0`. +You should see a return output of the form `x.y.z`. ### 3. Create your first dashboard -You can now paste the below example into a jupyter notebook cell (or a python script), run it, and see the results. +Paste the following example into a notebook cell, run it, and view the generated dashboard by typing `localhost:8050` into your browser. !!! example "Dashboard Configuration Syntaxes" === "Code for the cell" @@ -76,10 +77,7 @@ You can now paste the below example into a jupyter notebook cell (or a python sc [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png -After running the dashboard, you can access the dashboard by typing `localhost:8050` in the browser of your choice. ### 4. Explore further -You are now ready to explore our documentation further, as you can now easily evaluate all examples. - -One place to start would be the more complete [Explore Vizro tutorial](../tutorials/explore-components.md). +You are now ready to explore Vizro further, by working through the [Explore Vizro tutorial](../tutorials/explore-components.md) or consulting the [user guide documentation](../first-dashboard/). diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 8fe0601b2..c9fb56e4b 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -95,7 +95,7 @@ This guide shows you how to install Vizro, how to verify the installation succee -## Install vizro +## Install `vizro` To install Vizro, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index f457a6f51..891b25363 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -4,7 +4,7 @@ nav: - Vizro: index.md - Get started: - Install Vizro: pages/user-guides/install.md - - Dashboard quickstart: pages/tutorials/first-dashboard.md + - A first dashboard: pages/tutorials/first-dashboard.md - Explore Vizro: pages/tutorials/explore-components.md - User guides: - FUNDAMENTALS: From dc26035a5dd28a92b500e5a8665f825895b8d1c8 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 17:04:38 +0000 Subject: [PATCH 09/32] Update explore-components.md --- .../pages/tutorials/explore-components.md | 160 ++++++++---------- 1 file changed, 69 insertions(+), 91 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 415cecfca..d35d06e91 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -1,41 +1,29 @@ -# Get started with your first dashboard +# Explore Vizro -This tutorial guides you step-by-step through the process of creating a dashboard. +This tutorial walks through the process of creating a sophisticated dashboard. It introduces Vizro components and explains how to configure a layout to suit the functionality you need. The example uses the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.data.html#plotly.data.gapminder). -By the end of this tutorial, you will have gained a deep understanding of Vizro dashboards: their structure, adding -functionality, and configuring layouts to suit your specific needs. +If you haven't yet done so, you may want to review the [first dashboard tutorial](../tutorials/first-dashboard.md) before starting on this one. -This step-by-step guide is designed to equip you -with the knowledge and skills required to create your own dashboards using Vizro. +## 1. Install Vizro and get ready to run your code -In case you are completely new, you may want to review our [Get started](../tutorials/first-dashboard.md) tutorial first. +To get started with this tutorial, make sure you have [installed Vizro](../user_guides/install.md), and can run the dashboard code [within a Jupyter Notebook cell](../first_dashboard/#2-open-a-jupyter-notebook), or from a Python script. -## Let's get started! +## 2. Create a first dashboard page -### 1. Install Vizro and get ready to run your code +In this section we create a new [`Page`][vizro.models.Page] called `first_page`. -In order to get started with this tutorial, you should have Vizro installed, and be ready to evaluate your code, either by -pasting it into a Jupyter notebook cell, or by running it from a python script. +The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. A page contains a set of component types to display the content of the page. Components can be objects such as [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table], [`Card`][vizro.models.Card], [`Button`][vizro.models.Button], [`Container`][vizro.models.Container], or [`Tabs`][vizro.models.Tabs]. +### 2.1. Add the first figure -### 2. Create a first dashboard page +Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions](https://plotly.com/python-api-reference/plotly.express.html) to build different types of [figures](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html). -At the core of every dashboard is a [`Page`][vizro.models.Page] object, -which serves as its foundation. Think of it as a blank canvas where you can arrange and customize elements like charts and text. +For example, to add a box plot to the page: -In this first section, you will explore how to create a page with different elements and delve into the layout -configuration. +1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. +2. Assign it a unique id (`box_cont`). +3. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. -#### 2.1. Add the first component -First, let's define the structure of your dashboard page. Create a new [`Page`][vizro.models.Page] called -`first_page` and assign a title. Each [`Page`][vizro.models.Page] allows you to define a list of -`components`. These `components` are responsible for the content displayed on the page and can include a wide range of -elements such as charts, text boxes, buttons, and more. - -Let's begin by adding a box plot showing the life expectancy per continent to the page. This can be done by including a -[`Graph`][vizro.models.Graph] in the `components` list and assigning it a unique id. -[`Graphs`][vizro.models.Graph] are utilized to incorporate charts to your page by specifying `figure` using the -plotly express standard. !!! example "First component" === "app.py" @@ -69,48 +57,42 @@ plotly express standard. [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png -Let's give it a try and see your dashboard in action! Either paste the above code into a Jupyter notebook cell and evaluate it, or create a new Python script called `app.py` and copy the code from -above into the script. Next, navigate to the directory where the `app.py` file is located using your terminal or command -prompt. Run the script by executing the command: - -```python -python app.py -``` - -Once the script is running, open your web browser and go to `localhost:8050`. You should now see your dashboard page -with the gapminder data displayed. +!!! tip "To see the dashboard in action" + + Paste the above code into a Notebook cell, run the Notebook, and evaluate it. + + ??? tip "Prefer Python scripts to Notebooks?" + + 1. Create a new script called `app.py`. + 2. Copy the code above into the script. + 3. Navigate to the directory where `app.py` file is located using your terminal + 4. Run the script by executing the command: + + ```python + python app.py + ``` -If everything worked correctly, you should be able to see your first dashboard page as shown in the `Result` tab above. Congratulations on creating your very first dashboard -page! +Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page +with the gapminder data displayed, as shown in the `Result` tab above. -You may notice a couple of additions in the `app.py` script: +!!! note "Note the following:" -1. The import statement -`import vizro.plotly.express as px` allows the use of plotly express and facilitates seamless integration into Vizro -by defining figures with px. + 1. The import statement `import vizro.plotly.express as px` integrates Plotly Express for building figures. -2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before -building and running it with `Vizro().build(dashboard).run()`. It's important to note that every -[`Page`][vizro.models.Page] that you want to display needs to be added to the -[`Dashboard`][vizro.models.Dashboard] object. + 2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. + It's important to note that every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. -#### 2.2. Add further components +### 2.2. Add further components -To further enhance your first dashboard page, let's add a [`Card`][vizro.models.Card] and another chart using -[`Graph`][vizro.models.Graph] to the `components` list. The [`Card`][vizro.models.Card] allows you to -insert text into your dashboard and can be configured using markdown syntax. For the second chart, we will incorporate a -bar chart that visualizes the GDP development per continent since 1952. +You can combine and arrange various types of `components` on a dashboard page. The `components` currently available are [`Card`][vizro.models.Card], [`Graph`][vizro.models.Graph], and [`Button`][vizro.models.Button]. For more information, refer to the [components](../user-guides/components.md) overview page to find the user guide for each type. -Remember, you can combine and arrange various types of `components` on a dashboard page. -To see which components are available, refer to our [components](../user-guides/components.md) overview page. -The user guides of the components serve as a detailed resource to learn how to make the most of them in your dashboards. +To further enhance the dashboard, add two further components to the page: -??? info "Further information for `components`" - Currently available types of `components`: +* A [`Card`][vizro.models.Card], used to insert text into the dashboard, which can be configured using Markdown syntax. +* A [`Graph`][vizro.models.Graph], which illusrates GDP development per continent since 1952 as a bar chart. - - [`Card`][vizro.models.Card] - - [`Graph`][vizro.models.Graph] - - [`Button`][vizro.models.Button] +!!! warning "Before you run this code in a Jupyter notebook" + If you are following this tutorial in a Jupyter notebook, you should restart the kernel before re-evaluating the code. This avoids error messages about components already existing in the `model_manager`. !!! example "Add components" === "Code first component" @@ -181,46 +163,42 @@ The user guides of the components serve as a detailed resource to learn how to m [FirstPage2]: ../../assets/tutorials/dashboard/dashboard22.png -Let's run the code and take a look at our dashboard. - -!!! note "If using a Jupyter notebook..." - If you are following this tutorial using a Jupyter notebook, we recommend restarting the kernel before re-evaluating your notebook. This avoids error messages about components already existing in the `model_manager`. +As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts may appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components. +### 2.3. Configure the layout +By default, each element is placed in the order it was added to `components` list with equal space, as observed in the previous section. -As you explore the added `components`, you may notice that the -current layout could be further enhanced. The charts may appear cramped, while the text component has ample unused -space. In the next section, we will learn how to configure the layout and effectively arrange the `components`. +The [`Layout`][vizro.models.Layout] object is used to specify the placement and size of components on the page. To learn more about how to +configure layouts, check out the [How to use layouts](../user-guides/layouts.md) in the user guide. -#### 2.3. Configure the layout -To configure the appearance for your [`Page`][vizro.models.Page], the [`Layout`][vizro.models.Layout] object is -utilized. It allows you to specify the placement and size of `components` on the grid. By default, each element is -placed in the order they are added to the `components` list with equal space, as observed in the previous section. +We can optimize the layout by positioning the text at the top and the two charts side +by side, giving them more space relative to the text component. This can be achieved using the following +configuration: -To improve the current layout, we aim to optimize the space by positioning the text at the top and the two charts side -by side while giving the charts more space relative to the text component. This can be achieved using the following -configuration: `grid=[[0, 0], [1, 2], [1, 2], [1, 2]]`. +```python +grid=[ [0, 0], + [1, 2], + [1, 2], + [1, 2] ] +``` -Let's go through one-by-one. Firstly, the configuration divides the available space into two columns and -four rows. Each element in the list represents one row of the grid layout. An example of the generated grid is shown in -below. +These values are interpreted as follows. First, the configuration divides the available space into two columns and +four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout: ![image1](../../assets/tutorials/dashboard/dashboard231.png) -Secondly, the `components` are placed on the grid as visualized with the white frames. The text -card, referenced by 0 as the first element in the `components` list, is placed in the first row and spans across both -columns (`[0, 0]`). The two charts, referenced by 1 and 2, are positioned next to each other and span across two columns -(`[1, 2]`). +Each element in the `components` list is reference with a unique number, and placed on the grid as visualized with the white frames. The `Card`, reference by 0 as the first element in the `components` list, is placed in the first row and spans across both +columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and span across two columns. ![image2](../../assets/tutorials/dashboard/dashboard233.png) -It's important to note that the charts span over three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the -text card only occupies one row `[0, 0]`. As a result, the charts occupy three-quarters of the vertical space, while the -text card occupies one-quarter of it. +The `Graph` objects occupy three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the +`Card` only occupies one row `[0, 0]`. As a result, the `Graph` objects occupy three-quarters of the vertical space, while the +`Card` occupies one-quarter of it. ![image3](../../assets/tutorials/dashboard/dashboard232.png) -Let's see how it is looks on the dashboard when applied to the three components. If you like to learn more about how to -configure layouts, check out the [user guide](../user-guides/layouts.md) +Run the code below to apply the layout to the dashboard page: !!! example "Configure layout" === "Code" @@ -274,7 +252,7 @@ configure layouts, check out the [user guide](../user-guides/layouts.md) [FirstPage3]: ../../assets/tutorials/dashboard/dashboard23.png -#### 2.4. Add and configure a filter +### 2.4. Add and configure a filter The next thing you will learn is how to add functionality to your first dashboard page. This is achieved by adding `controls` to the [`Page`][vizro.models.Page]. `Controls` enable interaction with the `components` and empower users @@ -360,13 +338,13 @@ Fantastic job! By completing your first dashboard page, you have gained valuable [`Page`][vizro.models.Page] with multiple `components`, arranging them using layout configuration, and adding functionality to your dashboard. -### 3. Create a second dashboard page +## 3. Create a second dashboard page Moving forward, you will add your second dashboard page to delve deeper into `controls` and explore different types of `selectors`. The structure is similar to the page you just created, and you configure two charts to visualize the iris data set. -#### 3.1. Configure parameters +### 3.1. Configure parameters Next, you add two [`Parameters`][vizro.models.Parameter] to the `controls`. The first parameter will allow for changing the color of the virginica data, targeting both charts. The second parameter will adjust the opacity of the @@ -501,7 +479,7 @@ for parameters](../user-guides/parameters.md). [SecondPage]: ../../assets/tutorials/dashboard/dashboard3.png -#### 3.2. Customize with selectors +### 3.2. Customize with selectors When examining the code, you will notice the usage of two different types of `selectors`, namely [`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider], within the @@ -526,7 +504,7 @@ suit your specific needs. - [`RangeSlider`][vizro.models.RangeSlider] - [`Slider`][vizro.models.Slider] -### 4. Create the final dashboard +## 4. Create the final dashboard Finally, it's time to put everything together and create a cohesive dashboard. In this section, we will focus on creating a homepage for your dashboard and provide seamless navigation to the previously built pages. @@ -701,7 +679,7 @@ Congratulations on completing this tutorial! You have acquired skills in configu implementing functionality in Vizro dashboards. By building your own dashboard with multiple pages, you have gained hands-on experience in creating dynamic and interactive data visualizations. -## Further reference +## Find out more After completing the tutorial you now have a solid understanding of the main elements required to build dashboard pages and how to bring them together. From 27942842b120f0c78fa8626af41794537aec3a62 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 26 Feb 2024 17:37:10 +0000 Subject: [PATCH 10/32] dashboard tutorial improvements --- .../pages/tutorials/explore-components.md | 95 +++++++++---------- .../docs/pages/tutorials/first-dashboard.md | 10 +- vizro-core/docs/pages/user-guides/install.md | 18 ++-- 3 files changed, 59 insertions(+), 64 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index d35d06e91..5580b0768 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -10,13 +10,13 @@ To get started with this tutorial, make sure you have [installed Vizro](../user_ ## 2. Create a first dashboard page -In this section we create a new [`Page`][vizro.models.Page] called `first_page`. +In this section we create a new [`Page`][vizro.models.Page] called `first_page`. -The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. A page contains a set of component types to display the content of the page. Components can be objects such as [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table], [`Card`][vizro.models.Card], [`Button`][vizro.models.Button], [`Container`][vizro.models.Container], or [`Tabs`][vizro.models.Tabs]. +The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. A page uses a set of component types to display the content of the page. These components can be objects such as [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table], [`Card`][vizro.models.Card], [`Button`][vizro.models.Button], [`Container`][vizro.models.Container], or [`Tabs`][vizro.models.Tabs]. ### 2.1. Add the first figure -Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions](https://plotly.com/python-api-reference/plotly.express.html) to build different types of [figures](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html). +Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions](https://plotly.com/python-api-reference/plotly.express.html) to build different types of [figures](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html). For example, to add a box plot to the page: @@ -58,13 +58,13 @@ For example, to add a box plot to the page: [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png !!! tip "To see the dashboard in action" - - Paste the above code into a Notebook cell, run the Notebook, and evaluate it. - + + Paste the above code into a Notebook cell, run the Notebook, and evaluate it. + ??? tip "Prefer Python scripts to Notebooks?" - - 1. Create a new script called `app.py`. - 2. Copy the code above into the script. + + 1. Create a new script called `app.py`. + 2. Copy the code above into the script. 3. Navigate to the directory where `app.py` file is located using your terminal 4. Run the script by executing the command: @@ -73,13 +73,13 @@ For example, to add a box plot to the page: ``` Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page -with the gapminder data displayed, as shown in the `Result` tab above. +with the gapminder data displayed, as shown in the `Result` tab above. !!! note "Note the following:" 1. The import statement `import vizro.plotly.express as px` integrates Plotly Express for building figures. - 2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. + 2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. It's important to note that every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. ### 2.2. Add further components @@ -88,11 +88,11 @@ You can combine and arrange various types of `components` on a dashboard page. T To further enhance the dashboard, add two further components to the page: -* A [`Card`][vizro.models.Card], used to insert text into the dashboard, which can be configured using Markdown syntax. -* A [`Graph`][vizro.models.Graph], which illusrates GDP development per continent since 1952 as a bar chart. +* A [`Card`][vizro.models.Card] to insert Markdown text into the dashboard. +* A [`Graph`][vizro.models.Graph] to illusrate GDP development per continent since 1952 as a bar chart. -!!! warning "Before you run this code in a Jupyter notebook" - If you are following this tutorial in a Jupyter notebook, you should restart the kernel before re-evaluating the code. This avoids error messages about components already existing in the `model_manager`. +!!! warning "Before you run this code in a Jupyter Notebook" + If you are following this tutorial in a Jupyter Notebook, you should restart the kernel before re-evaluating the code. This avoids error messages about components already existing in the `model_manager`. !!! example "Add components" === "Code first component" @@ -166,29 +166,30 @@ To further enhance the dashboard, add two further components to the page: As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts may appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components. ### 2.3. Configure the layout -By default, each element is placed in the order it was added to `components` list with equal space, as observed in the previous section. -The [`Layout`][vizro.models.Layout] object is used to specify the placement and size of components on the page. To learn more about how to +By default, Vizro places each element in the order it was added to `components` list, and spaces them equally. + +You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to configure layouts, check out the [How to use layouts](../user-guides/layouts.md) in the user guide. -We can optimize the layout by positioning the text at the top and the two charts side -by side, giving them more space relative to the text component. This can be achieved using the following -configuration: +You can optimize the layout by positioning the text at the top and the two charts side +by side, giving them more space relative to the text component. Use the following +configuration: ```python -grid=[ [0, 0], - [1, 2], - [1, 2], +grid=[ [0, 0], + [1, 2], + [1, 2], [1, 2] ] ``` -These values are interpreted as follows. First, the configuration divides the available space into two columns and +Vizro interprets these values as follows. First, the configuration divides the available space into two columns and four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout: ![image1](../../assets/tutorials/dashboard/dashboard231.png) -Each element in the `components` list is reference with a unique number, and placed on the grid as visualized with the white frames. The `Card`, reference by 0 as the first element in the `components` list, is placed in the first row and spans across both -columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and span across two columns. +Each element in the `components` list is referenced with a unique number, and placed on the grid as visualized with the white frames. The `Card`, is referenced by 0 as it is the first element in the `components` list. It is placed in the first row and spans across both +columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and occupy a column each. ![image2](../../assets/tutorials/dashboard/dashboard233.png) @@ -252,32 +253,26 @@ Run the code below to apply the layout to the dashboard page: [FirstPage3]: ../../assets/tutorials/dashboard/dashboard23.png -### 2.4. Add and configure a filter +### 2.4. Add a control for dashboard interactivity -The next thing you will learn is how to add functionality to your first dashboard page. This is achieved by adding -`controls` to the [`Page`][vizro.models.Page]. `Controls` enable interaction with the `components` and empower users -with functionality. In general, `controls` can be of two types. The first one are [`Filters`][vizro.models.Filter], -which allows users to filter a column of the underlying data. The second type is -[`Parameters`][vizro.models.Parameter], which enables users to modify arguments or properties of the `components` -themselves, such as adjusting colors. - -By incorporating `controls` into your dashboard, you enhance its interactivity and make it more dynamic, enabling users +Controls add interactivity to the dashboard page and make it more dynamic, enabling users to have greater control and customization over the displayed data and components. -??? info "Further information for `controls`" - The user guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) provide a comprehensive overview on how to apply - [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [user guide on selectors](../user-guides/selectors.md). +There are two types of control: + +* [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. +* [`Parameters`][vizro.models.Parameter] enable users to modify arguments or properties of the components, such as adjusting colors. + + +The user guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) provide a comprehensive overview on how to apply [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [user guide on selectors](../user-guides/selectors.md). -In order to link the `controls` to your two charts, it's important to understand the unique -id assigned to each `component`. This id is unique across all dashboard pages and serves as a reference for -targeting specific `components`. +To link a control to a component you use the id assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. -For your first dashboard page, a [`Filter`][vizro.models.Filter] is added to enable filtering on specific -continents of the underlying data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes -the target column to be filtered. Each `control` also has a `targets` parameter, which allows you to specify the -datasets and components that will be affected by the `control`. In the case of your first dashboard page, both charts -are listed in the `targets` parameter, meaning that the filter will be applied to both charts. However, you also have -the flexibility to apply the [`Filter`][vizro.models.Filter] to only one specific chart if desired. +To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific +continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes +the target column to be filtered. Each `control` also has a `targets` parameter, to specify the +datasets and components affected by the `control`. For this dashboard, both charts +are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. !!! example "Configure filter" === "Code" @@ -334,9 +329,9 @@ the flexibility to apply the [`Filter`][vizro.models.Filter] to only one specifi [FirstPage4]: ../../assets/tutorials/dashboard/dashboard24.png -Fantastic job! By completing your first dashboard page, you have gained valuable skills in creating a -[`Page`][vizro.models.Page] with multiple `components`, arranging them using layout configuration, and adding -functionality to your dashboard. +Fantastic job! You have completed first dashboard page and gained valuable skills to create a +[`Page`][vizro.models.Page] that contains several components, arrange them using a layout, then configure and add +interactive functionality to the page. ## 3. Create a second dashboard page diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index c21b2d8fb..e5dfadeab 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -13,18 +13,18 @@ If you haven't already installed Vizro, follow the [installation guide](../user- ### 2. Open a Jupyter notebook -A good way to initially explore Vizro is from inside a Jupyter Notebook. +A good way to initially explore Vizro is from inside a Jupyter Notebook. ??? "Install and run Jupyter" If you haven't used Jupyter before, you may need to install the Jupyter package. From the terminal window: - + ```bash pip install jupyter ``` Alternatively, you can [work within Anaconda Navigator](../user-guides/install.md#use-vizro-inside-anaconda-navigator) as described in the Vizro installation guide. - + Activate the virtual environment you used to install Vizro, and start a new Notebook as follows: @@ -32,7 +32,7 @@ Activate the virtual environment you used to install Vizro, and start a new Note jupyter notebook ``` -The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. +The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. Create a new notebook `Python 3 (ipykernel)` notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. @@ -80,4 +80,4 @@ Paste the following example into a notebook cell, run it, and view the generated ### 4. Explore further -You are now ready to explore Vizro further, by working through the [Explore Vizro tutorial](../tutorials/explore-components.md) or consulting the [user guide documentation](../first-dashboard/). +You are now ready to explore Vizro further, by working through the [Explore Vizro tutorial](../tutorials/explore-components.md) or consulting the [user guide documentation](../first-dashboard/). diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index c9fb56e4b..1505e5a98 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -8,13 +8,13 @@ This guide shows you how to install Vizro, how to verify the installation succee **Virtual environment**: You should create a virtual environment for each Vizro project you work on to - isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). + isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). !!! tip "Prefer to use Vizro without opening a terminal window?" - + If you are a beginner or coding novice, you may prefer to avoid using a terminal to work with Vizro. Skip to the ["Use Vizro inside Anaconda" section](#use-vizro-inside-anaconda-navigator) below. - + ??? information "How to create a virtual environment for your Vizro project" @@ -52,7 +52,7 @@ This guide shows you how to install Vizro, how to verify the installation succee You can alternatively create virtual environments using `venv` or `pipenv` instead of `conda`. #### `venv` - + You should already have the `venv` module installed with the Python 3 standard library. Create a directory for working with your project and navigate to it. For example: ```bash @@ -76,7 +76,7 @@ This guide shows you how to install Vizro, how to verify the installation succee ####`pipenv` From any directory: - + ```bash pip install pipenv ``` @@ -108,14 +108,14 @@ pip install vizro To completely avoid terminal usage, follow these steps to work with Vizro: - - + + 1. Install [Anaconda Navigator](https://www.anaconda.com/download). 2. Create a new environment as [outlined in the Anaconda documentation](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/). Choose a Python version `>=3.8`. 3. Search `vizro` and install it [using the Anaconda Navigator package manager](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/). - + 4. Similarly, search `jupyter` and install it. 5. [Launch a Jupyter notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro. @@ -142,5 +142,5 @@ pip install vizro -U ``` !!! tip Check the Vizro release notes - + To upgrade safely, check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-core/CHANGELOG.md) for any notable breaking changes before migrating an existing project. From b113dcb08e8fadc2f09d0d2f453498f701bcdd2d Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 12:20:03 +0000 Subject: [PATCH 11/32] Update explore-components.md --- .../pages/tutorials/explore-components.md | 121 ++++++++---------- 1 file changed, 52 insertions(+), 69 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 5580b0768..99e88ff4a 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -1,6 +1,6 @@ # Explore Vizro -This tutorial walks through the process of creating a sophisticated dashboard. It introduces Vizro components and explains how to configure a layout to suit the functionality you need. The example uses the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.data.html#plotly.data.gapminder). +This tutorial walks through the process of creating a sophisticated dashboard. It introduces Vizro components and explains how to configure a layout to suit the functionality you need. The example uses the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder). If you haven't yet done so, you may want to review the [first dashboard tutorial](../tutorials/first-dashboard.md) before starting on this one. @@ -18,7 +18,7 @@ The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions](https://plotly.com/python-api-reference/plotly.express.html) to build different types of [figures](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html). -For example, to add a box plot to the page: +The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. 2. Assign it a unique id (`box_cont`). @@ -86,7 +86,7 @@ with the gapminder data displayed, as shown in the `Result` tab above. You can combine and arrange various types of `components` on a dashboard page. The `components` currently available are [`Card`][vizro.models.Card], [`Graph`][vizro.models.Graph], and [`Button`][vizro.models.Button]. For more information, refer to the [components](../user-guides/components.md) overview page to find the user guide for each type. -To further enhance the dashboard, add two further components to the page: +To further enhance the dashboard, the code below adds two further components to the page: * A [`Card`][vizro.models.Card] to insert Markdown text into the dashboard. * A [`Graph`][vizro.models.Graph] to illusrate GDP development per continent since 1952 as a bar chart. @@ -172,9 +172,8 @@ By default, Vizro places each element in the order it was added to `components` You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to configure layouts, check out the [How to use layouts](../user-guides/layouts.md) in the user guide. -You can optimize the layout by positioning the text at the top and the two charts side -by side, giving them more space relative to the text component. Use the following -configuration: +The following layout configuration positions the text at the top and the two charts side +by side, giving them more space relative to the text component: ```python grid=[ [0, 0], @@ -264,7 +263,7 @@ There are two types of control: * [`Parameters`][vizro.models.Parameter] enable users to modify arguments or properties of the components, such as adjusting colors. -The user guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) provide a comprehensive overview on how to apply [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [user guide on selectors](../user-guides/selectors.md). +The user guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) give a comprehensive overview on how to apply [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [user guide on selectors](../user-guides/selectors.md). To link a control to a component you use the id assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. @@ -329,27 +328,23 @@ are listed in the `targets` parameter, meaning that the filter is be applied to [FirstPage4]: ../../assets/tutorials/dashboard/dashboard24.png -Fantastic job! You have completed first dashboard page and gained valuable skills to create a -[`Page`][vizro.models.Page] that contains several components, arrange them using a layout, then configure and add -interactive functionality to the page. +Fantastic job! You have completed first dashboard page and gained valuable skills to [create an initial figure on a dashboard page](#2-create-a-first-dashboard-page), [add extra components](#22-add-further-components), [arrange them in a layout configuration](/#23-configure-the-layout), and [set up an interactive dashboard control](#24-add-a-control-for-dashboard-interactivity). ## 3. Create a second dashboard page -Moving forward, you will add your second dashboard page to delve deeper into `controls` and explore different types -of `selectors`. The structure is similar to the page you just created, and you configure two charts to visualize -the iris data set. +This section adds a second dashboard page and explains how to use controls and selectors. The new page is structured similarly to the page you just created, but contains two charts that visualize the [iris dataset](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.iris). -### 3.1. Configure parameters +The code below illustrates how to add the page, titled `second_page` to the dashboard by calling `vm.Dashboard(pages=[first_page,second_page])`. There are two `Graph` objects added to the list of components. To enable interactivity on those components, we add two [`Parameters`][vizro.models.Parameter] to the list of `controls`. -Next, you add two [`Parameters`][vizro.models.Parameter] to the `controls`. The first parameter will allow for -changing the color of the virginica data, targeting both charts. The second parameter will adjust the opacity of the -first chart. Unlike [`Filters`][vizro.models.Filter] where you are required to set the `column`, -[`Parameters`][vizro.models.Parameter] require you to define the `targets`. +In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below: -For instance, the opacity of the scatter chart can be changed by defining `scatter_iris.opacity` in the `targets`. In -general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of +* The first parameter enables the user to change the color of the virginica data, targeting both charts. +* The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. + + +In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of `component_id.argument`. In certain cases, you may encounter a nested structure for the `targets`. An example of this is -`scatter_iris.color_discrete_map.virginica`. This nested structure allows you to target a specific attribute within a +`scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a component. In this particular example, it specifies that only the color of the virginica flower type should be changed. More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [user guide for parameters](../user-guides/parameters.md). @@ -460,7 +455,7 @@ for parameters](../user-guides/parameters.md). options=["#ff5267", "#3949ab"], multi=False, value="#3949ab", title="Color Virginica"), ), vm.Parameter( - targets=["scatter_iris.opacity", "hist_iris.opacity"], + targets=["scatter_iris.opacity"], selector=vm.Slider(min=0, max=1, value=0.8, title="Opacity"), ), ], @@ -474,51 +469,43 @@ for parameters](../user-guides/parameters.md). [SecondPage]: ../../assets/tutorials/dashboard/dashboard3.png -### 3.2. Customize with selectors +### 3.1. Customize with selectors -When examining the code, you will notice the usage of two different types of `selectors`, namely -[`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider], within the -[`Parameters`][vizro.models.Parameter]. These `selectors` provide additional configuration options for the `controls` -and allow you to customize their behavior and appearance. +The code in the example above uses two different types of [`selector` objects](../user-guides/selectors/), namely +[`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider] upon the +[`Parameters`][vizro.models.Parameter]. The `selectors` enable configuration of the controls to customize their behavior and appearance. -The first parameter of your page is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available -options, disables multi-selection and has a default `value` set to blue. This means users can choose a single option -from the dropdown. The second parameter is a [`Slider`][vizro.models.Slider] with a default value of 0.8. It allows -users to adjust a value within the specified range of `min=0` and `max=1`. As you can see, `selectors` offer -flexibility in configuring the controls and are applicable to both [`Filters`][vizro.models.Filter] and -[`Parameters`][vizro.models.Parameter]. They allow you to fine-tune the behavior and appearance of the controls to -suit your specific needs. +The first parameter is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available +options, disables multi-selection, and has a default `value` set to blue. Users can choose a single option +from the dropdown. -??? info "Further information for `selectors`" - Currently available `selectors` for [`Filter`][vizro.models.Filter] and - [`Parameter`][vizro.models.Parameter]: +The second parameter is a [`Slider`][vizro.models.Slider] with a default value of 0.8. Users can adjust a value within the specified range of `min=0` and `max=1`. - - [`Checklist`][vizro.models.Checklist] - - [`Dropdown`][vizro.models.Dropdown] - - [`RadioItems`][vizro.models.RadioItems] - - [`RangeSlider`][vizro.models.RangeSlider] - - [`Slider`][vizro.models.Slider] +You can apply selectors to configure [`Filters`][vizro.models.Filter] and +[`Parameters`][vizro.models.Parameter] to fine-tune the behavior and appearance of the controls. The selectors currently available are as follows: -## 4. Create the final dashboard +- [`Parameter`][vizro.models.Parameter]: +- [`Checklist`][vizro.models.Checklist] +- [`Dropdown`][vizro.models.Dropdown] +- [`RadioItems`][vizro.models.RadioItems] +- [`RangeSlider`][vizro.models.RangeSlider] +- [`Slider`][vizro.models.Slider] -Finally, it's time to put everything together and create a cohesive dashboard. In this section, we will focus on -creating a homepage for your dashboard and provide seamless navigation to the previously built pages. +## 4. The final touches -To enable easy navigation within your dashboard, we will create the homepage that serves as the entry point for the user. -For that, we will utilize two [`Cards`][vizro.models.Card] and include them in the `components` list. Each -[`Card`][vizro.models.Card] serves as a customizable tile that can be configured with a title, text, and an -image. These cards will act as links to the subpages within your dashboard. +This section puts everything together by adding a +homepage to the previous example that offers navigation between the two separate pages. -To bring everything together, you will now reference the two subpages within the [`Cards`][vizro.models.Card] -on the homepage by specifying their respective `href` attributes as `href="/first-page"` and `href="/second-page"`. This +To enable easy navigation within your dashboard, we create a page that serves as the entry point for the user. +On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an +image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This establishes the navigation links from the homepage to each of the subpages. -Furthermore, the created pages need to be added to the dashboard using the following line of code: -`vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible in the dashboard. +Each page is added to the dashboard using the following line of code: +`vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible. -Once everything is put together, you will have a functional dashboard where you can navigate from the homepage to each -of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages, -providing a seamless and interactive user experience. +The code below illustrates a functional dashboard where you can navigate from the homepage to each +of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages. !!! example "Final dashboard" === "Code" @@ -646,7 +633,7 @@ providing a seamless and interactive user experience. options=["#ff5267", "#3949ab"], multi=False, value="#3949ab", title="Color Virginica"), ), vm.Parameter( - targets=["scatter_iris.opacity", "hist_iris.opacity"], + targets=["scatter_iris.opacity"], selector=vm.Slider(min=0, max=1, value=0.8, title="Opacity"), ), ], @@ -670,24 +657,20 @@ providing a seamless and interactive user experience. [FinalPage2]: ../../assets/tutorials/dashboard/dashboard3.png -Congratulations on completing this tutorial! You have acquired skills in configuring layouts, adding components, and -implementing functionality in Vizro dashboards. By building your own dashboard with multiple pages, you have gained -hands-on experience in creating dynamic and interactive data visualizations. +Congratulations on completing this tutorial! You have acquired the knowledge to configure layouts, add components, and +implement interactivity in Vizro dashboards, working across two navigable pages. ## Find out more -After completing the tutorial you now have a solid understanding of the main elements required to build dashboard pages -and how to bring them together. +After completing the tutorial you now have a solid understanding of the main elements of Vizro and how to bring them together to create dynamic and interactive data visualizations. -For future dashboard creations, you can explore more about the available dashboard `components` by going through our overview page for -[components](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration -details of `controls`, check out the user guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) +You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the user guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head to [Navigation](../user-guides/navigation.md). Vizro doesn't end here, and we only covered the key features, but there is still much more to explore! You can learn: -- How to create you own components under [custom components](../user-guides/custom-components.md) -- How to add custom styling using [custom css](../user-guides/assets.md) -- How to use [Actions](../user-guides/actions.md) for e.g. chart interaction or custom controls -- How to create dashboards from `yaml`, `dict` or `json` following the [user guide](../user-guides/dashboard.md) +- How to create you own components under [custom components](../user-guides/custom-components.md). +- How to add custom styling using [custom css](../user-guides/assets.md). +- How to use [Actions](../user-guides/actions.md) for example, for chart interaction or custom controls. +- How to create dashboards from `yaml`, `dict` or `json` following the [user guide](../user-guides/dashboard.md). From e65a106ed9ec9a9f04451894c62df23b23c9edd5 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 12:39:23 +0000 Subject: [PATCH 12/32] Create 20240227_123915_jo_stichbury_light_edit_for_readability.md --- ...jo_stichbury_light_edit_for_readability.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 vizro-core/changelog.d/20240227_123915_jo_stichbury_light_edit_for_readability.md diff --git a/vizro-core/changelog.d/20240227_123915_jo_stichbury_light_edit_for_readability.md b/vizro-core/changelog.d/20240227_123915_jo_stichbury_light_edit_for_readability.md new file mode 100644 index 000000000..f1f65e73c --- /dev/null +++ b/vizro-core/changelog.d/20240227_123915_jo_stichbury_light_edit_for_readability.md @@ -0,0 +1,48 @@ + + + + + + + + + From e136eb6e84defa3f11c1b58b33539796a3002acf Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 14:38:52 +0000 Subject: [PATCH 13/32] Update vizro-core/docs/pages/user-guides/custom-components.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/user-guides/custom-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/custom-components.md b/vizro-core/docs/pages/user-guides/custom-components.md index 8408f9ca4..a1f90e16d 100644 --- a/vizro-core/docs/pages/user-guides/custom-components.md +++ b/vizro-core/docs/pages/user-guides/custom-components.md @@ -147,7 +147,7 @@ vm.Parameter.add_type("selector", TooltipNonCrossRangeSlider) [CustomComponent1]: ../../assets/user_guides/custom_components/customcomponent_1.png -## Create a new component +## How to create a new component ??? info "When to choose this strategy" From 9936b550be65a19add786bddaccf8da8b8eeb145 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 14:39:01 +0000 Subject: [PATCH 14/32] Update vizro-core/docs/pages/user-guides/data.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/user-guides/data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md index 1fae01545..4bda1ceb6 100644 --- a/vizro-core/docs/pages/user-guides/data.md +++ b/vizro-core/docs/pages/user-guides/data.md @@ -56,7 +56,7 @@ Vizro, you need: This allows you to use this data connector in your dashboard. -!!! example "Use a Data connector" +!!! example "Use a data connector" === "app.py" ```py linenums="1" hl_lines="18" from vizro import Vizro From 0c6362d31767d207b9749475e298d355ca701c48 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 14:39:09 +0000 Subject: [PATCH 15/32] Update vizro-core/docs/pages/user-guides/data.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/user-guides/data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md index 4bda1ceb6..d29a5c049 100644 --- a/vizro-core/docs/pages/user-guides/data.md +++ b/vizro-core/docs/pages/user-guides/data.md @@ -123,7 +123,7 @@ use the same data connector to load different data. For example, when you want t retrieve data from different tables in a database, you can define a data connector that accepts different SQL queries as arguments. -!!! example "Use a Data Connector with arguments" +!!! example "Use a data connector with arguments" === "app.py (use lambda)" ```py linenums="1" from vizro import Vizro From 35a76b4ad2c2e5725203928c4372bc85e2ff5873 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 14:39:59 +0000 Subject: [PATCH 16/32] Update vizro-core/docs/pages/user-guides/install.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/user-guides/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 1505e5a98..cee2787b9 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -30,7 +30,7 @@ This guide shows you how to install Vizro, how to verify the installation succee Activate your virtual environment from any directory: ```bash - conda activate kedro-environment + conda activate vizro-environment ``` To confirm that a valid version of Python is installed in your virtual environment, type the following in your terminal (macOS and Linux): From 113f43432f8d95b50a823cb7b77aa38c31fa5f5d Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 27 Feb 2024 17:40:47 +0000 Subject: [PATCH 17/32] some further changes per review comments --- .../docs/pages/tutorials/explore-components.md | 7 +++---- vizro-core/docs/pages/user-guides/install.md | 13 +++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 99e88ff4a..624513f30 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -6,13 +6,13 @@ If you haven't yet done so, you may want to review the [first dashboard tutorial ## 1. Install Vizro and get ready to run your code -To get started with this tutorial, make sure you have [installed Vizro](../user_guides/install.md), and can run the dashboard code [within a Jupyter Notebook cell](../first_dashboard/#2-open-a-jupyter-notebook), or from a Python script. +To get started with this tutorial, make sure you have [installed Vizro](../user-guides/install.md), and can run the dashboard code [within a Jupyter Notebook cell](../first-dashboard/#2-open-a-jupyter-notebook), or from a Python script. ## 2. Create a first dashboard page In this section we create a new [`Page`][vizro.models.Page] called `first_page`. -The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. A page uses a set of component types to display the content of the page. These components can be objects such as [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table], [`Card`][vizro.models.Card], [`Button`][vizro.models.Button], [`Container`][vizro.models.Container], or [`Tabs`][vizro.models.Tabs]. +The foundation of every Vizro dashboard is a [`Page`][vizro.models.Page] object. A page uses a set of [component types](../user-guides/components/) to display the content of the page. These components can be objects such as [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table], [`Card`][vizro.models.Card], [`Button`][vizro.models.Button], [`Container`][vizro.models.Container], or [`Tabs`][vizro.models.Tabs]. ### 2.1. Add the first figure @@ -21,8 +21,7 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. -2. Assign it a unique id (`box_cont`). -3. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. +2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 1505e5a98..a5de890cd 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -18,7 +18,7 @@ This guide shows you how to install Vizro, how to verify the installation succee ??? information "How to create a virtual environment for your Vizro project" - ### Using `conda` + **Using `conda`** We strongly recommend [installing `conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/) if you don't already use it. Once installed, create a virtual environment from the terminal as follows: ```bash @@ -47,11 +47,12 @@ This guide shows you how to install Vizro, how to verify the installation succee ??? information "How to create a virtual environment without using conda" - ### How to create a new virtual environment without using `conda` + **How to create a new virtual environment without using `conda`** You can alternatively create virtual environments using `venv` or `pipenv` instead of `conda`. - #### `venv` + --- + **`venv`** You should already have the `venv` module installed with the Python 3 standard library. Create a directory for working with your project and navigate to it. For example: @@ -72,8 +73,8 @@ This guide shows you how to install Vizro, how to verify the installation succee .\.venv\Scripts\activate # Windows ``` - - ####`pipenv` + --- + **`pipenv`** From any directory: @@ -95,7 +96,7 @@ This guide shows you how to install Vizro, how to verify the installation succee -## Install `vizro` +## Install Vizro To install Vizro, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: From e7f239c3df52f82c15dc92aa167506f4694aa53f Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 11:13:58 +0000 Subject: [PATCH 18/32] Another round of updates following feedback --- vizro-core/docs/index.md | 10 +++--- .../pages/tutorials/explore-components.md | 33 ++++++++++--------- .../docs/pages/tutorials/first-dashboard.md | 16 +++++---- vizro-core/mkdocs.yml | 2 +- 4 files changed, 33 insertions(+), 28 deletions(-) diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md index 982c5d2e2..f8e65c31c 100644 --- a/vizro-core/docs/index.md +++ b/vizro-core/docs/index.md @@ -20,9 +20,9 @@ Vizro is a toolkit for creating modular data visualization applications.
-
User Guides
+
How-to Guides

- Our user guides provide step-by-step instructions on how to leverage our core features. + These guides offer step-by-step instructions on how to use our core features.

@@ -31,7 +31,7 @@ Vizro is a toolkit for creating modular data visualization applications.
-
API reference
+
API Reference

The API reference contains a detailed description of the Vizro API and our pydantic models.

@@ -44,7 +44,7 @@ Vizro is a toolkit for creating modular data visualization applications.
Explanation

- Our explanation section contains background information and the answer to "why" questions. + Our explanation section contains background information and the answer to "why?" questions.

@@ -55,7 +55,7 @@ Vizro is a toolkit for creating modular data visualization applications.
Contribute

- Find our contribution guidelines and all our current and previous contributors here. + Find our contribution guidelines and all our current and past contributors.

diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 624513f30..849e9b8d3 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -1,6 +1,6 @@ # Explore Vizro -This tutorial walks through the process of creating a sophisticated dashboard. It introduces Vizro components and explains how to configure a layout to suit the functionality you need. The example uses the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder). +In this tutorial, we walk through the process of creating a sophisticated dashboard. You'll be introduced to some Vizro components and learn how to create a pair of dashboard pages and configure their layout to suit the functionality you need. The example uses the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder). If you haven't yet done so, you may want to review the [first dashboard tutorial](../tutorials/first-dashboard.md) before starting on this one. @@ -79,19 +79,20 @@ with the gapminder data displayed, as shown in the `Result` tab above. 1. The import statement `import vizro.plotly.express as px` integrates Plotly Express for building figures. 2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. - It's important to note that every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. + Every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. ### 2.2. Add further components -You can combine and arrange various types of `components` on a dashboard page. The `components` currently available are [`Card`][vizro.models.Card], [`Graph`][vizro.models.Graph], and [`Button`][vizro.models.Button]. For more information, refer to the [components](../user-guides/components.md) overview page to find the user guide for each type. +You can combine and arrange various types of `components` on a dashboard page. The `components` currently available are [`Card`][vizro.models.Card], [`Graph`][vizro.models.Graph], and [`Button`][vizro.models.Button]. For more information, refer to the [components](../user-guides/components.md) overview page to find the guide for each type. -To further enhance the dashboard, the code below adds two further components to the page: +The code below adds two components to the page: * A [`Card`][vizro.models.Card] to insert Markdown text into the dashboard. * A [`Graph`][vizro.models.Graph] to illusrate GDP development per continent since 1952 as a bar chart. !!! warning "Before you run this code in a Jupyter Notebook" - If you are following this tutorial in a Jupyter Notebook, you should restart the kernel before re-evaluating the code. This avoids error messages about components already existing in the `model_manager`. + + If you are following this tutorial in a Jupyter Notebook, you need to restart the kernel each time you evaluate the code. If you do not, you will see error messages such as "Components must uniquely map..." because those components already exist from the previous evaluation. !!! example "Add components" === "Code first component" @@ -169,7 +170,7 @@ As you explore the dashboard, you may notice that the current layout could be fu By default, Vizro places each element in the order it was added to `components` list, and spaces them equally. You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to -configure layouts, check out the [How to use layouts](../user-guides/layouts.md) in the user guide. +configure layouts, check out [How to use layouts](../user-guides/layouts.md). The following layout configuration positions the text at the top and the two charts side by side, giving them more space relative to the text component: @@ -259,17 +260,17 @@ to have greater control and customization over the displayed data and components There are two types of control: * [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. -* [`Parameters`][vizro.models.Parameter] enable users to modify arguments or properties of the components, such as adjusting colors. +* [`Parameters`][vizro.models.Parameter] enable users to change arguments or properties of the components, such as adjusting colors. -The user guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) give a comprehensive overview on how to apply [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [user guide on selectors](../user-guides/selectors.md). +The guides for [Filters](../user-guides/filters.md) and [Parameters](../user-guides/parameters.md) explain how to apply [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter]. For further customization, refer to the [guide on selectors](../user-guides/selectors.md). -To link a control to a component you use the id assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. +To link a control to a component, use the id assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes the target column to be filtered. Each `control` also has a `targets` parameter, to specify the -datasets and components affected by the `control`. For this dashboard, both charts +datasets and components targeted by the `control`. For this dashboard, both charts are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. !!! example "Configure filter" @@ -342,10 +343,10 @@ In creating a [`Parameter`][vizro.models.Parameter] object, you define the `targ In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of -`component_id.argument`. In certain cases, you may encounter a nested structure for the `targets`. An example of this is +`component_id.argument`. In certain cases, you may see a nested structure for the `targets`. An example of this is `scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a component. In this particular example, it specifies that only the color of the virginica flower type should be changed. -More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [user guide +More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [how-to guide for parameters](../user-guides/parameters.md). !!! example "Second page" @@ -493,9 +494,9 @@ You can apply selectors to configure [`Filters`][vizro.models.Filter] and ## 4. The final touches This section puts everything together by adding a -homepage to the previous example that offers navigation between the two separate pages. +homepage to the example for navigation between the two separate pages. -To enable easy navigation within your dashboard, we create a page that serves as the entry point for the user. +For easy navigation within your dashboard, we'll create a page that serves as the entry point for the user. On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This establishes the navigation links from the homepage to each of the subpages. @@ -663,7 +664,7 @@ implement interactivity in Vizro dashboards, working across two navigable pages. After completing the tutorial you now have a solid understanding of the main elements of Vizro and how to bring them together to create dynamic and interactive data visualizations. -You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the user guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) +You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head to [Navigation](../user-guides/navigation.md). @@ -672,4 +673,4 @@ Vizro doesn't end here, and we only covered the key features, but there is still - How to create you own components under [custom components](../user-guides/custom-components.md). - How to add custom styling using [custom css](../user-guides/assets.md). - How to use [Actions](../user-guides/actions.md) for example, for chart interaction or custom controls. -- How to create dashboards from `yaml`, `dict` or `json` following the [user guide](../user-guides/dashboard.md). +- How to create dashboards from `yaml`, `dict` or `json` following the [dashboard guide](../user-guides/dashboard.md). diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index e5dfadeab..61b477665 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -1,8 +1,8 @@ # A first dashboard -This is a quickstart guide to create your first dashboard and set you up to explore Vizro further. +This is a short tutorial for you to create your first dashboard, showing you the basic setup so you can explore Vizro further. -The [Explore Vizro tutorial](../tutorials/explore-components.md) is a more complete exploration of Vizro's features. +Once you've completed this tutorial, the following [Explore Vizro tutorial](../tutorials/explore-components.md) creates a more complex dashboard so you can explore Vizro's features. ## Get started @@ -11,7 +11,7 @@ The [Explore Vizro tutorial](../tutorials/explore-components.md) is a more compl If you haven't already installed Vizro, follow the [installation guide](../user-guides/install.md). -### 2. Open a Jupyter notebook +### 2. Open a Jupyter Notebook A good way to initially explore Vizro is from inside a Jupyter Notebook. @@ -34,7 +34,7 @@ jupyter notebook The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. -Create a new notebook `Python 3 (ipykernel)` notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. +Create a new `Python 3 (ipykernel)` Notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. ```py import vizro @@ -44,9 +44,13 @@ print(vizro.__version__) You should see a return output of the form `x.y.z`. +!!! warning "What could go wrong?" + + If you are following this tutorial in a Jupyter Notebook, you need to restart the kernel each time you evaluate the code. If you do not, you will see error messages such as "Components must uniquely map..." because those components already exist from the previous evaluation. + ### 3. Create your first dashboard -Paste the following example into a notebook cell, run it, and view the generated dashboard by typing `localhost:8050` into your browser. +Paste the following example into a Notebook cell, run it, and view the generated dashboard by typing `localhost:8050` into your browser. !!! example "Dashboard Configuration Syntaxes" === "Code for the cell" @@ -80,4 +84,4 @@ Paste the following example into a notebook cell, run it, and view the generated ### 4. Explore further -You are now ready to explore Vizro further, by working through the [Explore Vizro tutorial](../tutorials/explore-components.md) or consulting the [user guide documentation](../first-dashboard/). +You are now ready to explore Vizro further, by working through the [Explore Vizro tutorial](../tutorials/explore-components.md) or by consulting the [how-to guides](../first-dashboard/). diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index 891b25363..d92407d35 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -6,7 +6,7 @@ nav: - Install Vizro: pages/user-guides/install.md - A first dashboard: pages/tutorials/first-dashboard.md - Explore Vizro: pages/tutorials/explore-components.md - - User guides: + - How-to guides: - FUNDAMENTALS: - Dashboards: pages/user-guides/dashboard.md - Pages: pages/user-guides/pages.md From ddce1007f8007f45cc21afe65b75d183fe418ff9 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 11:48:50 +0000 Subject: [PATCH 19/32] Update index.md --- vizro-core/docs/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md index f8e65c31c..b02c77fe6 100644 --- a/vizro-core/docs/index.md +++ b/vizro-core/docs/index.md @@ -11,7 +11,7 @@ Vizro is a toolkit for creating modular data visualization applications.
Get Started

- New to Vizro? Take a look at our tutorials to get started and to explore our core features. + New to Vizro? Tutorials to get started and to explore the key features.

@@ -22,7 +22,7 @@ Vizro is a toolkit for creating modular data visualization applications.
How-to Guides

- These guides offer step-by-step instructions on how to use our core features. + Step-by-step instructions on how to use Vizro features.

@@ -33,7 +33,7 @@ Vizro is a toolkit for creating modular data visualization applications.
API Reference

- The API reference contains a detailed description of the Vizro API and our pydantic models. + Detailed reference of the Vizro API and our pydantic models.

@@ -44,7 +44,7 @@ Vizro is a toolkit for creating modular data visualization applications.
Explanation

- Our explanation section contains background information and the answer to "why?" questions. + Background information and answers to your "why..?" questions.

@@ -55,7 +55,7 @@ Vizro is a toolkit for creating modular data visualization applications.
Contribute

- Find our contribution guidelines and all our current and past contributors. + Contribution guidelines and all our current and past contributors.

From dff89074de537c1707218cbda529c0f2003f54ef Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 12:06:49 +0000 Subject: [PATCH 20/32] Update index.md --- vizro-core/docs/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md index b02c77fe6..705469a64 100644 --- a/vizro-core/docs/index.md +++ b/vizro-core/docs/index.md @@ -6,7 +6,7 @@ Vizro is a toolkit for creating modular data visualization applications.
- +
Get Started
@@ -17,7 +17,7 @@ Vizro is a toolkit for creating modular data visualization applications.
- +
How-to Guides
@@ -28,7 +28,7 @@ Vizro is a toolkit for creating modular data visualization applications.
- +
API Reference
@@ -39,7 +39,7 @@ Vizro is a toolkit for creating modular data visualization applications.
- +
Explanation
From 433636c69bc06ce3cb312beb0b71ea7db8918fac Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 12:15:11 +0000 Subject: [PATCH 21/32] Update vizro-core/docs/pages/development/contributing.md Co-authored-by: Antony Milne <49395058+antonymilne@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/development/contributing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index 641361b77..b7a6de863 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -67,7 +67,6 @@ hatch run test To run only python unit tests, run `hatch run test-unit`, and for python integration tests only run `hatch run test-integration`. -For integration tests, [all examples are executed in separate testing sessions](https://github.com/mckinsey/vizro/issues/10) by providing the `-k` tag per example. Arguments are passed through to the underlying `pytest` command, e.g. From 3e9c4ec6051331c6760ef2124e16995bb19f6a6c Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 12:18:59 +0000 Subject: [PATCH 22/32] Update vizro-core/docs/pages/user-guides/install.md Co-authored-by: Antony Milne <49395058+antonymilne@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/user-guides/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index d26182aa4..c55d5e693 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -25,7 +25,7 @@ This guide shows you how to install Vizro, how to verify the installation succee conda create --name vizro-environment python=3.10 -y ``` - (This example uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8 and <3.12), and name it anything you choose). + (This example uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8), and name it anything you choose). Activate your virtual environment from any directory: From 1906eda03002acb8ead7cd1277ddc36dd1de6f94 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 12:27:12 +0000 Subject: [PATCH 23/32] Remove nested admonition and pipenv/venv instructions --- vizro-core/docs/pages/user-guides/install.md | 51 +------------------- 1 file changed, 1 insertion(+), 50 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index c55d5e693..9ab9f6a38 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -45,54 +45,7 @@ This guide shows you how to install Vizro, how to verify the installation succee python --version ``` - ??? information "How to create a virtual environment without using conda" - - **How to create a new virtual environment without using `conda`** - - You can alternatively create virtual environments using `venv` or `pipenv` instead of `conda`. - - --- - **`venv`** - - You should already have the `venv` module installed with the Python 3 standard library. Create a directory for working with your project and navigate to it. For example: - - ```bash - mkdir vizro-environment && cd vizro-environment - ``` - - Next, create a new virtual environment in this directory with `venv`: - - ```bash - python -m venv .venv - ``` - - To activate: - - ```bash - source .venv/bin/activate # macOS / Linux - .\.venv\Scripts\activate # Windows - ``` - - --- - **`pipenv`** - - From any directory: - - ```bash - pip install pipenv - ``` - - Create a directory for working with your project and navigate to it. For example: - - ```bash - mkdir vizro-environment && cd vizro-environment - ``` - - To start a session with the correct virtual environment activated: - - ```bash - pipenv shell - ``` + You can alternatively create virtual environments using [`venv`](https://docs.python.org/3/library/venv.html) or [`pipenv`](https://pipenv.pypa.io/en/latest/) instead of `conda`. @@ -103,11 +56,9 @@ To install Vizro, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal w ```bash pip install vizro ``` - ## Use Vizro inside Anaconda Navigator - To completely avoid terminal usage, follow these steps to work with Vizro: From add9fe8049e7a625bc6e8e687000c5d948a279fc Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 14:27:25 +0000 Subject: [PATCH 24/32] Update vizro-core/docs/pages/tutorials/explore-components.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-core/docs/pages/tutorials/explore-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 849e9b8d3..bbda03e84 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -338,7 +338,7 @@ The code below illustrates how to add the page, titled `second_page` to the dash In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below: -* The first parameter enables the user to change the color of the virginica data, targeting both charts. +* The first parameter enables the user to change the color mapping for the `virginica` category of the iris data set , targeting both charts. * The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. From c60c610145f03a4b452b7550b78d3184d348dfb1 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 14:29:22 +0000 Subject: [PATCH 25/32] Update explore-components.md --- .../pages/tutorials/explore-components.md | 28 ++++++------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 849e9b8d3..00f72638d 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -21,8 +21,7 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. -2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. - +2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" === "app.py" @@ -60,26 +59,17 @@ The code below shows the steps necessary to add a box plot to the page: Paste the above code into a Notebook cell, run the Notebook, and evaluate it. - ??? tip "Prefer Python scripts to Notebooks?" - - 1. Create a new script called `app.py`. - 2. Copy the code above into the script. - 3. Navigate to the directory where `app.py` file is located using your terminal - 4. Run the script by executing the command: - - ```python - python app.py - ``` - -Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page -with the gapminder data displayed, as shown in the `Result` tab above. + --- + If you prefer to use Python scripts to Notebooks, here's how to try out the dashboard: -!!! note "Note the following:" + 1. Create a new script called `app.py`. + 2. Copy the code above into the script. + 3. Navigate to the directory where `app.py` file is located using your terminal. + 4. Run the script by executing the command `python app.py`. - 1. The import statement `import vizro.plotly.express as px` integrates Plotly Express for building figures. + Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page with the gapminder data displayed, as shown in the `Result` tab above. - 2. The `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. - Every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. +As you can see from the code, the `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. Every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. ### 2.2. Add further components From 375538c7513d438f5ec647ffa0d7a8437f238a08 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 28 Feb 2024 14:29:50 +0000 Subject: [PATCH 26/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- vizro-core/docs/pages/tutorials/explore-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 95a139b79..650a13a7b 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -21,7 +21,7 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. -2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. +2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" === "app.py" From 6c14d076a0002e9077be800e088936ad493626c6 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 14:44:48 +0000 Subject: [PATCH 27/32] Update explore-components.md --- vizro-core/docs/pages/tutorials/explore-components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 650a13a7b..cdb90a29c 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -328,7 +328,7 @@ The code below illustrates how to add the page, titled `second_page` to the dash In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below: -* The first parameter enables the user to change the color mapping for the `virginica` category of the iris data set , targeting both charts. +* The first parameter enables the user to change the color mapping for the `virginica` category of the iris data set, targeting both charts. * The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. @@ -371,7 +371,7 @@ for parameters](../user-guides/parameters.md). options=["#ff5267", "#3949ab"], multi=False, value="#3949ab", title="Color Virginica"), ), vm.Parameter( - targets=["scatter_iris.opacity", "hist_iris.opacity"], + targets=["scatter_iris.opacity"], selector=vm.Slider(min=0, max=1, value=0.8, title="Opacity"), ), ], From c848505cd85e21dd539ee76806a1b61fc8356a7a Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 15:27:53 +0000 Subject: [PATCH 28/32] Update explore-components.md --- vizro-core/docs/pages/tutorials/explore-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index cdb90a29c..8dc993c11 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -20,7 +20,7 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: -1. Add a Vizro [`Graph`](vizro.models.Graph) to the `components` list. +1. Add a Vizro [`Graph`][vizro.models.Graph] to the `components` list. 2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" From 677b342bc93dd65caa1aa8090caf45ad8900ded7 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 15:33:49 +0000 Subject: [PATCH 29/32] Update .gitignore Signed-off-by: Jo Stichbury --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 08f969bb4..393948979 100644 --- a/.gitignore +++ b/.gitignore @@ -85,7 +85,7 @@ instance/ # Scrapy .scrapy -# mkdocs and docs +# mkdocs vizro-core/docs/.vale vizro-core/site vizro-ai/site From 95023e035212aeeb52b2a3d49d8d229f6c8686b4 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 28 Feb 2024 15:34:07 +0000 Subject: [PATCH 30/32] Update .gitignore Signed-off-by: Jo Stichbury --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 393948979..79a54175f 100644 --- a/.gitignore +++ b/.gitignore @@ -86,7 +86,6 @@ instance/ .scrapy # mkdocs -vizro-core/docs/.vale vizro-core/site vizro-ai/site From 8e222fec1820102da33714c802ddcb2b893fbaec Mon Sep 17 00:00:00 2001 From: Antony Milne Date: Thu, 29 Feb 2024 10:21:46 +0000 Subject: [PATCH 31/32] Simplify and update virtual environment instructions --- vizro-core/docs/pages/user-guides/install.md | 45 +++++++++----------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index 9ab9f6a38..db87fc857 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -2,6 +2,11 @@ This guide shows you how to install Vizro, how to verify the installation succeeded and find the version of Vizro, and how to update Vizro. +If you already have a virtual environment setup in Python then you can skip this page and just install Vizro straight away by running: +```bash +pip install vizro +``` + ## Prerequisites **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.8 and later. You can specify the version of Python to use with Vizro when you set up a virtual environment. @@ -18,36 +23,26 @@ This guide shows you how to install Vizro, how to verify the installation succee ??? information "How to create a virtual environment for your Vizro project" - **Using `conda`** - We strongly recommend [installing `conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/) if you don't already use it. Once installed, create a virtual environment from the terminal as follows: - + The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example: + ```bash - conda create --name vizro-environment python=3.10 -y - ``` - - (This example uses Python 3.10, and creates a virtual environment called `vizro-environment`. You can opt for a different version of Python (any version >= 3.8), and name it anything you choose). - - Activate your virtual environment from any directory: - + mkdir vizro-project + cd vizro-project + ``` + + Next, create and activate a new virtual environment in this directory with `venv`: ```bash - conda activate vizro-environment + python3 -m venv .venv + source .venv/bin/activate ``` - - To confirm that a valid version of Python is installed in your virtual environment, type the following in your terminal (macOS and Linux): - + + Alternatively, you might like to use [`conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/). Once installed, you can create and activate a virtual environment from the terminal as follows: + ```bash - python3 --version - ``` - - On Windows: - - ```bash - python --version + conda create --name vizro-environment + conda activate vizro-environment ``` - You can alternatively create virtual environments using [`venv`](https://docs.python.org/3/library/venv.html) or [`pipenv`](https://pipenv.pypa.io/en/latest/) instead of `conda`. - - ## Install Vizro @@ -90,7 +85,7 @@ You should see a return output of the form `x.y.z`. To change the version of Vizro installed: ```bash -pip install vizro -U +pip install -U vizro ``` !!! tip Check the Vizro release notes From 038f0d8d7d5125640aee5dddebad8bc9b889b60f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 29 Feb 2024 10:22:12 +0000 Subject: [PATCH 32/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- vizro-core/docs/pages/user-guides/install.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md index db87fc857..46f195296 100644 --- a/vizro-core/docs/pages/user-guides/install.md +++ b/vizro-core/docs/pages/user-guides/install.md @@ -2,7 +2,7 @@ This guide shows you how to install Vizro, how to verify the installation succeeded and find the version of Vizro, and how to update Vizro. -If you already have a virtual environment setup in Python then you can skip this page and just install Vizro straight away by running: +If you already have a virtual environment setup in Python then you can skip this page and just install Vizro straight away by running: ```bash pip install vizro ``` @@ -24,20 +24,20 @@ pip install vizro ??? information "How to create a virtual environment for your Vizro project" The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example: - + ```bash mkdir vizro-project cd vizro-project - ``` - + ``` + Next, create and activate a new virtual environment in this directory with `venv`: ```bash python3 -m venv .venv source .venv/bin/activate ``` - + Alternatively, you might like to use [`conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/). Once installed, you can create and activate a virtual environment from the terminal as follows: - + ```bash conda create --name vizro-environment conda activate vizro-environment