Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update vizro-ai documentation #159

Merged
merged 10 commits into from
Nov 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions vizro-ai/changelog.d/20231110_151408_chiara_pullem_update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<!--
A new scriv changelog fragment.

Uncomment the section that is right (remove the HTML comment wrapper).
-->

<!--
### Highlights ✨

- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Removed

- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Added

- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Changed

- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Deprecated

- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Fixed

- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
<!--
### Security

- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))

-->
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified vizro-ai/docs/assets/tutorials/chart/GDP_Composition_Bar.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 13 additions & 1 deletion vizro-ai/docs/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,18 @@
# Vizro-AI

Vizro-AI is a tool for generating data visualizations.
Vizro-AI is a tool designed for generating data visualizations. It serves as an extension to Vizro, leveraging natural language capabilities to empower users in creating charts effortlessly.

## Why Vizro-AI?

### Easy-to-use
One of the key strengths of Vizro-AI lies in its natural language capabilities, making it accessible to coding novices. Vizro-AI provides a user-friendly interface that allows to create interactive charts while offering detailed explanations about the data and the generated code.

### Visually-optimized
Vizro-AI also caters data scientist who often spend more time on formatting than creating a visualization. Vizro-AI enables the user to speed up the formatting process and create a visually appealing chart, also leveraging the design library of Vizro.

### Dashboard-ready
Vizro-AI focuses currently on plotly and is used to create interactive chart. Thus, it is primarily aimed at dashboards, ensuring that the generated charts are well-suited for dashboard applications.

!!! notice "Notice"
Please review this [disclaimer](pages/explanation/disclaimer.md)
before using the `vizro-ai` package.
Expand Down
2 changes: 1 addition & 1 deletion vizro-ai/docs/pages/explanation/disclaimer.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Disclaimer

Users must select one of the [supported Large Language Models (LLMs)](../user_guides/model_config.md) in order to use the `vizro-ai` package,
Users must select one of the [supported Large Language Models (LLMs)](../user_guides/model_config.md) in order to use the `vizro_ai` package,
and are responsible for obtaining their own suitable API key for the relevant model.

## Third Party API
Expand Down
16 changes: 8 additions & 8 deletions vizro-ai/docs/pages/explanation/safety_in_vizro_ai.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Generative AI models, especially Large Language Models (LLMs) represent signific
Vizro-AI also leverages LLMs, however, as with any powerful tool, there are potential risks associated.

Users must connect to a generative AI model, specifically LLMs to use Vizro-AI.
We recommend users research and understand the selected model before using `vizro-ai` package.
We recommend users research and understand the selected model before using `vizro_ai` package.

Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**,
approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
Expand All @@ -13,7 +13,7 @@ approach with caution, review the relevant [disclaimer](disclaimer.md) page, and

Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
The vendor models might lack real-time knowledge or events beyond its last updates.
`vizro-ai` output may vary and please always verify critical information.
`vizro_ai` output may vary and please always verify critical information.
It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.

### 2. Unintended and Sensitive output
Expand Down Expand Up @@ -41,17 +41,17 @@ It's crucial for users to remain informed, cautious, and ethical in their applic

## Dependencies, Code Scanners and Infosec

It may occur that dependencies of `vizro-ai` get flagged by code scanners and other infosec tools. As a consequence it may happen that
`vizro-ai` also get flagged.
It may occur that dependencies of `vizro_ai` get flagged by code scanners and other infosec tools. As a consequence it may happen that
`vizro_ai` also get flagged.

While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a very dynamic environment such as generative AI. We encourage users to investigate if any flagged infosec issues are actually related
to any functionality used in our code base or if they only concern functionality outside the scope of `vizro-ai`.
to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.

In case those issues are related to code execution, note that `vizro-ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so.
In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so.

## Execution of Dynamic Code in Vizro-AI

The `exec()` statement is used in `vizro-ai`. It allows for dynamic execution of Python programs which can be powerful, but can also pose security risk
The `exec()` statement is used in `vizro_ai`. It allows for dynamic execution of Python programs which can be powerful, but can also pose security risk
if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.

Users must exercise caution when executing code generated by or influenced by AI models. It's essential to:
Expand All @@ -60,6 +60,6 @@ Users must exercise caution when executing code generated by or influenced by AI
- Always consider using controlled environments, such as virtual machines or containers, to execute uncertain code
- Always be aware of potential risks when executing dynamically generated code in environments with access to sensitive data or systems
- Always be aware that malicious code execution cannot be mitigated with 100% certainty
- Always review and understand the selected model before connecting with `vizro-ai`
- Always review and understand the selected model before connecting with `vizro_ai`

If you would like to learn more about our efforts in safeguarding code execution, please refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information.
131 changes: 131 additions & 0 deletions vizro-ai/docs/pages/tutorials/explore_vizro_ai.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Explore Vizro-AI
This tutorial serves as an exploration of the extended applications offered by Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md).

By the end of this tutorial, you will have gained an understanding of different language options and leveraging Vizro-AI to enhance the formatting your visualizations.

## Let's get started!
### 1. Install Vizro-AI and get ready to run your code
Before proceeding, ensure the installation of the `vizro_ai` package by following the steps outlined in the [installation guide](../user_guides/install.md). Once installed, you can execute your code either by pasting it into a Jupyter notebook cell or running it from a Python script.


??? tip "Beginners/Code novices"
For those new to Python or virtual environments, a user-friendly alternative is available in the [installation guide](../user_guides/install.md), offering a graphical user interface without the need for terminal commands.

A prerequisite for this tutorial is access to one of the supported large language models. Please refer to the [api setup](../user_guides/api_setup.md) for instructions on setting up the API.

Upon successful setup, load your API key with the following two lines:

```py
from dotenv import load_dotenv
load_dotenv()
```

### 2. Create your visualization using different languages

Vizro-AI is versatile, supporting prompts and chart visualizations in multiple languages. Let's explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time.

!!! example "Vizro-AI Chinese"
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "请画一个世界年均GDP的趋势图")
```
=== "Result"
[![ChineseChart]][ChineseChart]

[ChineseChart]: ../../assets/tutorials/chart/ChineseExample.png

Subsequently, we'll switch to German and prompt the visualization of life expectancy in the United States over time, comparing it to the global life expectancy trend. For this example, we'll include `explain=True` to obtain comprehensive insights into both the data and the generated code.

!!! example "Vizro-AI German"
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "Visualiere den Trend von der Lebenserwartung in USA über die Jahre im Vergleich zur Veränderung der weltweiten Lebenserwartung über die Jahre und kreiere eine deutsche Visualisierung", explain=True)
```
=== "Result"
[![GermanChart]][GermanChart]

[GermanChart]: ../../assets/tutorials/chart/GermanExample.png

### 3. Create advanced charts and formatting
Now, let's explore more advanced visualizations and leverage Vizro-AI for enhanced formatting.

To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Let's run the code below and look at the result.

!!! example "Vizro-AI animated chart"
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "The chart should be an animated stacked bar chart with popoluation on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years.")
```
=== "Result"
[![AnimatedChart1]][AnimatedChart1]

[AnimatedChart1]: ../../assets/tutorials/chart/animated_bar_chart_1.png

Having unveiled our animated bar chart showcasing population development per country, it's apparent that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout.

!!! example "Vizro-AI animated chart"
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "The chart should be an animated stacked bar chart with popoluation on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Please improve layout.")
```
=== "Result"
[![AnimatedChart2]][AnimatedChart2]

[AnimatedChart2]: ../../assets/tutorials/chart/animated_bar_chart_2.png


Great, by incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result.

Now, upon closer inspection, two challenges emerge. Firstly, the legend overlaps the x-axis. Secondly, the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below and see how we can improve and finalize our chart.

!!! example "Vizro-AI animated chart"
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Make sure that y axis range fits entire data. Please improve layout and optimize layout of legend.")
```
=== "Result"
[![AnimatedChart3]][AnimatedChart3]

[AnimatedChart3]: ../../assets/tutorials/chart/animated_bar_chart_3.png

Congratulations! You've now gained insights into harnessing the power of Vizro-AI for crafting advanced charts and elevating formatting. Don't forget, enabling `explain=True` is a good way of learning more about how a chart can be further improved and formatted.
23 changes: 14 additions & 9 deletions vizro-ai/docs/pages/tutorials/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ This tutorial serves as an introduction to Vizro-AI.
It is a step-by-step guide to help you experiment and create your initial Vizro chart using Vizro-AI, our English-to-visualization package. The goal is to provide you with the necessary knowledge to explore further into our documentation.

## Let's get started!
### 1. Install vizro-ai and its dependencies
If you haven't already installed `vizro-ai` package, follow the [installation guide](../user_guides/install.md)
### 1. Install Vizro-AI and its dependencies
If you haven't already installed `vizro_ai` package, follow the [installation guide](../user_guides/install.md)
to do so inside a virtual environment.

??? tip "Beginners/Code novices"
Expand All @@ -28,7 +28,7 @@ This opens a browser tab, and you can navigate to your preferred folder for this
??? 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.

Confirm that vizro-ai is installed by typing the following into a jupyter cell in your notebook and running it.
Confirm that `vizro_ai` is installed by typing the following into a jupyter cell in your notebook and running it.

```py
import vizro_ai
Expand All @@ -48,7 +48,7 @@ from dotenv import load_dotenv
load_dotenv()
```

### 4. Ask your first question using vizro-ai
### 4. Ask your first question using Vizro-AI

For your first visualization, we will create a chart illustrating the GDP of various continents while including a reference line for the average.

Expand All @@ -60,22 +60,27 @@ By passing your prepared data and your written visualization request to this met
=== "Code for the cell"
```py
from vizro_ai import VizroAI
import plotly.express as px
import vizro.plotly.express as px

from dotenv import load_dotenv
load_dotenv()

df = px.data.gapminder()
vizro_ai = VizroAI()
vizro_ai.plot(df, "describe the composition of gdp in continent, and add horizontal line for avg gdp")
vizro_ai.plot(df, "describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp")
```
=== "Result"
[![BarChart]][BarChart]

[BarChart]: ../../assets/tutorials/chart/GDP_Composition_Bar.png

You can also pass `explain=True` to `plot()` method which will provide
additional insights in addition to the rendered chart.
The created chart is interactive, and you can hover over the data for additional information.

### 5. Get an explanation with your chart

By passing `explain=True` to the `plot()` method will provide additional insights in addition to the rendered chart.

Let's create another example and read through the additional information.

!!! example "Specify `explain=True`"
=== "Code for the cell"
Expand All @@ -87,7 +92,7 @@ additional insights in addition to the rendered chart.

[GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png

### 5. Explore further
### 6. Explore further

Now, you have created your first charts with Vizro-AI and are ready to explore the documentation further.

Expand Down
10 changes: 5 additions & 5 deletions vizro-ai/docs/pages/user_guides/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ More details can be found in the [environment setup guide](../user_guides/api_se
To install Vizro-AI from the Python Package Index (PyPI), utilize [`pip`](https://pip.pypa.io/en/stable/) in your terminal with the following command:

```bash
pip install vizro-ai
pip install vizro_ai
```

While you can execute code from the tutorials and user guides using a Python script, using a Jupyter notebook is often considered more convenient. You can install `jupyter` with the following command:
Expand All @@ -40,7 +40,7 @@ pip install jupyter
??? tip "Beginners/Code novices"
If you're new to coding or consider yourself a beginner, you can follow these following steps to avoid using the terminal:

- Search `vizro-ai` and install it using the Anaconda Navigator package manager. You can find instructions [here](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/)
- Search `vizro_ai` and install it using the Anaconda Navigator package manager. You can find instructions [here](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/)
- Similarly, search `jupyter` and install it through the same procedure
- Once installed, launching a Jupyter notebook becomes straightforward; you can find guidance [here](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator)
- With Jupyter, you can easily copy and paste any of the provided examples into a notebook cell, evaluate the cell, and examine the results
Expand All @@ -50,9 +50,9 @@ pip install jupyter
After successfully installing Vizro-AI, to verify the version or confirm the installation, you can run the following code from a Python script or a Jupyter notebook cell:

```py
import vizro-ai
import vizro_ai

print(vizro-ai.__version__)
print(vizro_ai.__version__)
```

You should see a return output of the current version.
Expand All @@ -61,7 +61,7 @@ You should see a return output of the current version.

If you want to upgrade Vizro-AI to a different version later on, you can do so by running the following command:
```
pip install vizro-ai -U
pip install vizro_ai -U
```

The best way to safely upgrade is to check the [release notes]() for any notable breaking changes before migrating an
Expand Down
2 changes: 1 addition & 1 deletion vizro-ai/docs/pages/user_guides/model_config.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

!!! Warning

Users are recommended to exercise caution and to research and understand the selected Large Language Model (LLM) before using `vizro-ai`.
Users are recommended to exercise caution and to research and understand the selected Large Language Model (LLM) before using `vizro_ai`.
Users should be cautious about sharing or inputting any personal or sensitive information.

**Data is sent to model vendors if you connect to LLMs via their APIs.**
Expand Down
Loading
Loading