Skip to content

Commit

Permalink
[pre-commit.ci] auto fixes from pre-commit.com hooks
Browse files Browse the repository at this point in the history 
for more information, see https://pre-commit.ci
  • Loading branch information
@pre-commit-ci
pre-commit-ci[bot] committed Jan 15, 2025
1 parent 6e5929a commit 9c8849e
Showing 1 changed file with 88 additions and 92 deletions.
180 changes: 88 additions & 92 deletions vizro-ai/docs/pages/tutorials/project-tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,50 +3,52 @@
This tutorial uses Vizro-AI to build a prototype dashboard with three charts that illustrate a simple dataset. We first show how to create individual charts with Vizro-AI and then move on to learn how to use Vizro-AI to build a dashboard. The tutorial concludes by moving the prototype code generated by Vizro-AI into a project on PyCafe, for others to use and extend.

## Project background and data

The dataset for this project was a set of books data [exported from a personal Goodreads account](https://www.goodreads.com/review/import). If you use Goodreads, you can export your own data in CSV format and use it with the code for this project.

The dataset was filtered to retain only books with an ISBN, since that can be used with [Google Books API](https://developers.google.com/books) to retrieve additional data about a book. The Books API wasn't used in this project, but by including ISBN data, there is scope to extend the prototype project in future. The dataset used can be downloaded from the [Vizro repository](filtered_books.csv).

## OpenAI
This tutorial uses OpenAI with Vizro-AI. To run through the steps, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the OpenAI models and pricing on their website](https://platform.openai.com/docs/models).

This tutorial uses OpenAI with Vizro-AI. To run through the steps, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the OpenAI models and pricing on their website](https://platform.openai.com/docs/models).

!!! note

Before using a model, please review OpenAI's guidelines on risk mitigation to understand potential model limitations and best practices. [See the OpenAI site for more details on responsible usage](https://platform.openai.com/docs/guides/safety-best-practices).


## Individual chart generation with Vizro-AI

In this step, we'll show a UI on a hosted version of Vizro-AI, at [https://py.cafe/app/vizro-official/vizro-ai-charts](https://py.cafe/app/vizro-official/vizro-ai-charts). Use your browser to navigate to the site which looks as follows:

![](../../assets/tutorials/project/user-interface-hosted-vizro-ai.png)

### Settings

You'll notice a cog icon at the top right hand corner for access to your settings, which look as follows:

![](../../assets/tutorials/project/user-interface-settings-hosted-vizro-ai.png)

Add the API key for your chosen vendor. At the time of writing, you can use OpenAI, Anthropic, Mistral, or xAI.
Add the API key for your chosen vendor. At the time of writing, you can use OpenAI, Anthropic, Mistral, or xAI.

Once the API key is set, return to the main screen and upload the data for the project.
Once the API key is set, return to the main screen and upload the data for the project.

We can now dive use Vizro-AI to build some charts by iterating text to write effective prompts.

### Chart 1: Books timeline

To ask Vizro-AI to build a chart, describe what you want to see. This chart should show an ordered horiontal timeline to illustrate the sequence of reading the books.

> Plot a chart with the title "Sequence of reading" . It is a scatter chart. Use the x axis to show the date a book was read. Plot it at y=1.
You can adjust the model used: the chart below was generated from `gpt-4o-mini`. The chart displays on the right hand side of the screen and the Plotly code to generate the chart is below the prompt.

The plot this code returns looks as follows. Hovering over each point gave the date the book was read, but not the title of the book. You'll also notice that the points are spaced evenly rather than proportionately:
![](../../assets/tutorials/project/chart1.png)
The plot this code returns looks as follows. Hovering over each point gave the date the book was read, but not the title of the book. You'll also notice that the points are spaced evenly rather than proportionately: ![](../../assets/tutorials/project/chart1.png)

??? example "Click to expand"
=== "Generated by Vizro-AI"
```
import plotly.graph_objects as go
from vizro.models.types import capture

@capture("graph")
def custom_chart(data_frame):
fig = go.Figure()
Expand All @@ -56,70 +58,69 @@ The plot this code returns looks as follows. Hovering over each point gave the d
```

### Chart 2: Reading velocity

The second chart should plot the cumulative total of pages read and the cumulative total of books read per year. The prompt took a few iterations to refine:

> Plot a chart with the title "Pages and Book totals" . It shows the cumulative total number of pages read by summing the Number of Pages of each book read in each year, using the Date Read data. Plot date on the x axis and the number of pages on the y axis using a scale on the left hand side of the chart.
> Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column. Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.
> Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column. Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.
The Plotly code generated when run with `gpt-4-turbo` was as follows:

??? example "Click to expand"
=== "Generated by Vizro-AI"
```python
import pandas as pd
import plotly.graph_objects as go
from plotly.subplots import make_subplots
from vizro.models.types import capture


@capture("graph")
def custom_chart(data_frame):
# Convert Date Read to datetime
data_frame["Date Read"] = pd.to_datetime(data_frame["Date Read"], dayfirst=True)

# Group by year and sum pages
pages_per_year = (
data_frame.groupby(data_frame["Date Read"].dt.year)["Number of Pages"].sum().cumsum()
)

# Count books per year
books_per_year = data_frame.groupby(data_frame["Date Read"].dt.year).size()

# Create subplot
fig = make_subplots(specs=[[{"secondary_y": True}]])

# Add line for cumulative pages
fig.add_trace(
go.Scatter(
x=pages_per_year.index,
y=pages_per_year,
mode="lines",
name="Cumulative Pages",
),
secondary_y=False,
)

# Add bar for books count
fig.add_trace(
go.Bar(x=books_per_year.index, y=books_per_year, name="Total Books"),
secondary_y=True,
)

# Set y-axes titles
fig.update_yaxes(title_text="Cumulative Pages", secondary_y=False)
fig.update_yaxes(title_text="Total Books", secondary_y=True)

# Set layout
fig.update_layout(title="Pages and Book totals", xaxis_title="Year", showlegend=True)

return fig
```

The plot this code returns looks as follows:
![](../../assets/tutorials/project/chart2.png)
```python
import pandas as pd
import plotly.graph_objects as go
from plotly.subplots import make_subplots
from vizro.models.types import capture


@capture("graph")
def custom_chart(data_frame):
# Convert Date Read to datetime
data_frame["Date Read"] = pd.to_datetime(data_frame["Date Read"], dayfirst=True)

# Group by year and sum pages
pages_per_year = data_frame.groupby(data_frame["Date Read"].dt.year)["Number of Pages"].sum().cumsum()

# Count books per year
books_per_year = data_frame.groupby(data_frame["Date Read"].dt.year).size()

# Create subplot
fig = make_subplots(specs=[[{"secondary_y": True}]])

# Add line for cumulative pages
fig.add_trace(
go.Scatter(
x=pages_per_year.index,
y=pages_per_year,
mode="lines",
name="Cumulative Pages",
),
secondary_y=False,
)

# Add bar for books count
fig.add_trace(
go.Bar(x=books_per_year.index, y=books_per_year, name="Total Books"),
secondary_y=True,
)

# Set y-axes titles
fig.update_yaxes(title_text="Cumulative Pages", secondary_y=False)
fig.update_yaxes(title_text="Total Books", secondary_y=True)

# Set layout
fig.update_layout(title="Pages and Book totals", xaxis_title="Year", showlegend=True)

return fig
```

The plot this code returns looks as follows: ![](../../assets/tutorials/project/chart2.png)

### Chart 3: Reviews comparison

The third chart should illustrate the difference between the rating the Goodreads reader assigned a book and the average rating across the Goodreads community. This prompt took a degree of iteration and needed us to specify how to draw the lines between the points. It was run several times before it colored each line differently, which is a key learning when using generative AI: your results will vary from run to run.

> For each row, create a dumbbell chart to show the difference between My Rating and Average Rating for each book - use shapes to add the horizontal lines between markers. Omit the legend. Don't show any row where My Rating is 0.
Expand Down Expand Up @@ -167,38 +168,38 @@ The third chart should illustrate the difference between the rating the Goodread
return fig
```

The plot this code returns looks as follows:
![](../../assets/tutorials/project/chart3.png)

The plot this code returns looks as follows: ![](../../assets/tutorials/project/chart3.png)

## Dashboard generation with Vizro-AI

### Set up a Jupyter Notebook in which to use Vizro-AI

At this point, we have prototypes for three plotly charts for the Goodreads data. To display these as an interactive dashboard, we need some additional code and Vizro-AI can generate this for us, but not through the PyCafe host at the time of writing. We'll use a Jupyter Notebook

Before running the Notebook code, you need to [set up Vizro-AI](https://vizro.readthedocs.io/projects/vizro-ai/en/latest/pages/user-guides/install/) inside a virtual environment with Python 3.10 or later. Install the package with `pip install vizro_ai`.

You need to give Vizro-AI your API key to access OpenAI by adding it to your environment so the code you write in the next step can access it to successfully call OpenAI. There are some [straightforward instructions in the OpenAI docs](https://platform.openai.com/docs/quickstart/step-2-set-up-your-api-key), and the process is also covered in the our [LLM setup guide](https://vizro.readthedocs.io/projects/vizro-ai/en/latest/pages/user-guides/install/#set-up-access-to-a-large-language-model).

### Build a dashboard

At this point you can open a Jupyter Notebook to make the dashboard. We'll submit a prompt that combines the three prompts listed above, with some small edits to ask for a dashboard that has three pages: one for each chart.

The following code shows the code to make the request to Vizro-AI to build and display the dashboard. The Notebook is available for download on [Vizro's GitHub repository](TO DO):
The following code shows the code to make the request to Vizro-AI to build and display the dashboard. The Notebook is available for download on \[Vizro's GitHub repository\](TO DO):

??? example "Click to expand"
=== "Generated by Vizro-AI"
```
user_question = """
Create a dashboard with 3 pages, one for each chart.
Create a dashboard with 3 pages, one for each chart.

On the first page, plot a chart with the title "Sequence of reading" .
On the first page, plot a chart with the title "Sequence of reading" .
It is a scatter chart. Use the x axis to show the date a book was read. Plot it at y=1.

On the second page, lot a chart with the title "Pages and Book totals" .
It shows the cumulative total number of pages read by summing the Number of Pages of each book read in each year, using the Date Read data.
On the second page, lot a chart with the title "Pages and Book totals" .
It shows the cumulative total number of pages read by summing the Number of Pages of each book read in each year, using the Date Read data.
Plot date on the x axis and the number of pages on the y axis using a scale on the left hand side of the chart.
Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column.
Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.
Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column.
Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.

On the third page, for each row, create a dumbbell chart to show the difference between My Rating and Average Rating for each book.
Use shapes to add the horizontal lines between markers. Omit the legend. Don't show any row where My Rating is 0.
Expand All @@ -218,25 +219,26 @@ The charts generated were similar to those created by the PyCafe host above, alt
![](../../assets/tutorials/project/chart1v2.png)

### Dashboard interactivity
To make the Vizro dashboards more interactive, we can ask Vizro-AI to add the code for a control. As a simple example, we can extend the prompt to ask for a filter to modify the time period displayed.

To make the Vizro dashboards more interactive, we can ask Vizro-AI to add the code for a control. As a simple example, we can extend the prompt to ask for a filter to modify the time period displayed.

??? example "Click to expand"
=== "Generated by Vizro-AI"
```diff
user_question = """
Create a dashboard with 3 pages, one for each chart.
Create a dashboard with 3 pages, one for each chart.

On the first page, plot a chart with the title "Sequence of reading" .
On the first page, plot a chart with the title "Sequence of reading" .
It is a scatter chart. Use the x axis to show the date a book was read. Plot it at y=1.

+ Add a filter so the user can adjust the range of dates by year on the x axis.

On the second page, plot a chart with the title "Pages and Book totals" .
It shows the cumulative total number of pages read by summing the Number of Pages of each book read in each year, using the Date Read data.
On the second page, plot a chart with the title "Pages and Book totals" .
It shows the cumulative total number of pages read by summing the Number of Pages of each book read in each year, using the Date Read data.
Plot date on the x axis and the number of pages on the y axis using a scale on the left hand side of the chart.
Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column.
Superimpose a bar chart showing the total books read for each year, taking data from the Date Read column.

Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.
Show the total books read using the right hand side of the chart which can be a different scale to the y axis shown on the left hand side.

+ Add a filter so the user can adjust the range of dates by year on the x axis.

Expand All @@ -247,9 +249,10 @@ To make the Vizro dashboards more interactive, we can ask Vizro-AI to add the co
```

## Interactive Vizro dashboards on PyCafe

At this point, we have a Notebook with code to call Vizro-AI to build a prototype Vizro dashboard with a set of three pages and three charts, plus a control to filter the view.

As we've already seen, the code generated by Vizro-AI can vary from run to run, and calling OpenAI each time a dashboard is needed can get costly.
As we've already seen, the code generated by Vizro-AI can vary from run to run, and calling OpenAI each time a dashboard is needed can get costly.

The project isn't particularly easy to share at present either: sharing a Notebook requires every user to have an OpenAI key and set up an environment.

Expand All @@ -258,14 +261,13 @@ At this point, to share and iterate the prototype the best course of action is t
There are three changes to the Notebook code needed for it to run on PyCafe:

1. Add `from vizro import Vizro` to the imports list
2. Add `Vizro().build(model).run()` at the end of the code block
3. Uncomment the data manager code and replace it with code needed to access the dataset:
1. Add `Vizro().build(model).run()` at the end of the code block
1. Uncomment the data manager code and replace it with code needed to access the dataset:
- If you are building your own PyCafe project, you can download the dataset from the Vizro GitHub repository and upload it to the PyCafe project.
- Alternatively, you can use the code added to the snippet below to read the dataset directly from online storage.

Follow the link at the bottom of the code snippet titled **☕️ Run and edit this code in PyCafe** to use and edit the dashboard.


Follow the link at the bottom of the code snippet titled **☕️ Run and edit this code in PyCafe** to use and edit the dashboard.

??? example "Click to expand"
=== "PyCafe project based on Notebook code"
```{.python pycafe-link}
Expand All @@ -275,7 +277,7 @@ Follow the link at the bottom of the code snippet titled **☕️ Run and edit
import pandas as pd
import plotly.graph_objects as go
from vizro.models.types import capture

####### Function definitions ######
@capture("graph")
def sequence_reading(data_frame):
Expand Down Expand Up @@ -437,13 +439,7 @@ Follow the link at the bottom of the code snippet titled **☕️ Run and edit
),
],
title="Book Reading Analysis Dashboard",
)
)

Vizro().build(model).run()
```






0 comments on commit 9c8849e

Please sign in to comment.