From dee27c3d272325154ed5f37323dd084525b41100 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 20 Jan 2025 15:13:00 +0000 Subject: [PATCH] Update goodreads-tutorial.md --- .../pages/tutorials/goodreads-tutorial.md | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/vizro-ai/docs/pages/tutorials/goodreads-tutorial.md b/vizro-ai/docs/pages/tutorials/goodreads-tutorial.md index 1fbeebece..457980a61 100644 --- a/vizro-ai/docs/pages/tutorials/goodreads-tutorial.md +++ b/vizro-ai/docs/pages/tutorials/goodreads-tutorial.md @@ -1,10 +1,10 @@ # How to build a prototype dashboard with Vizro-AI -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. +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 show 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 explanation -The dataset for this project was a set of books data [exported from a personal Goodreads account](https://www.goodreads.com/review/import), which is provided with the project so you can run it. The dataset used can be downloaded from the [Vizro repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/filtered_books.csv). If you use Goodreads, you can export your own data in CSV format, substitute it for the dataset provided, and explore it with the code for this project. +The dataset for this project was a set of books data [exported from a personal Goodreads account](https://www.goodreads.com/review/import), which is provided with the project so you can run it. The dataset can be downloaded from the [Vizro repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/filtered_books.csv). If you use Goodreads, you can export your own data in CSV format, substitute it for the dataset provided, and explore it with the code for this project. The dataset was filtered to retain only books with an ISBN, which 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. @@ -17,7 +17,7 @@ This tutorial uses OpenAI models with Vizro-AI. To run through the steps, you mu ## Chart generation with Vizro-AI -In this step, we use a UI on a hosted version of Vizro-AI, found 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: +In this step, we use a hosted version of Vizro-AI, found at [https://py.cafe/app/vizro-official/vizro-ai-charts](https://py.cafe/app/vizro-official/vizro-ai-charts). Navigate with your browser to the site, which looks as follows: ![](../../assets/tutorials/project/user-interface-hosted-vizro-ai.png) @@ -27,7 +27,9 @@ The link will open with a settings pane where you can set the API key for your c ![](../../assets/tutorials/project/user-interface-settings-hosted-vizro-ai.png) -To return to these settings at any time, you'll notice a cog icon at the top right hand corner for access to them. Once the API key is set, return to the main screen and upload the data for the project. +To return to these settings at any time, you'll notice a cog icon at the top right hand corner for access to them. + +Once the API key is set, return to the main screen and [upload the data for the project](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/filtered_books.csv). We can now use Vizro-AI to build some charts by iterating text to form effective prompts. @@ -76,7 +78,7 @@ 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. The chart could be improved by bringing the line graph on top of the bar chart, but varying the prompt to make this explicit did not have the desired results: +The Plotly code generated when run with `gpt-4-turbo` was as follows. The chart could be improved by bringing the line graph on top of the bar chart, but varying the prompt to make this explicit did not generate the desired output: ??? example "Click to expand" === "Generated by Vizro-AI" @@ -190,7 +192,7 @@ The plot this code returns looks as follows: ![](../../assets/tutorials/project/ ### Set up a Jupyter Notebook -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 application hosted on PyCafe at the time of writing. We'll use a Jupyter Notebook instead. +Now we have prototypes for three plotly charts for the Goodreads data. To display these as an interactive dashboard, we need some additional code. Vizro-AI can generate this for us, but not through the application hosted on PyCafe at the time of writing. We'll use a Jupyter Notebook instead. Before running the Notebook code, [set up Vizro-AI](../user-guides/install.md) inside a virtual environment with Python 3.10 or later. Install the package with `pip install vizro_ai`. @@ -198,9 +200,9 @@ You need to give Vizro-AI your API key to access OpenAI by adding it to your env ### Build a dashboard -Now we can open a Jupyter Notebook to make the dashboard. We'll submit a single 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. +In the Jupyter Notebook we'll submit a single 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 shows the code to make the request to Vizro-AI to build and display the dashboard. The Notebook is available for download from [Vizro's GitHub repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/goodreads.ipynb): +The following shows the code to make the request to Vizro-AI to build and display the dashboardted, with the data handling code omit. The cp,[;ete Notebook is available for download from [Vizro's GitHub repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/goodreads.ipynb): ??? example "Click to expand" === "Generated by Vizro-AI" @@ -258,9 +260,9 @@ To make the Vizro dashboards more interactive, we can ask Vizro-AI to add the co ### Get the Notebook -You can see the code output in the [Notebook stored on the Vizro GitHub repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/goodreads.ipynb), and generate similar output by running it yourself, although it will not necessarily be identical because of the variability of restuls returned from generative AI. +You can see the code output in the [Notebook stored on the Vizro GitHub repository](https://raw.githubusercontent.com/mckinsey/vizro/834c8d9c198420e8b315c0dc045b7aa12534719d/vizro-ai/examples/goodreads_tutorial/goodreads.ipynb), and generate similar output by running it yourself, although it will not necessarily be identical because of the variability of results returned from generative AI. -The charts generated were similar to those created by the PyCafe host above, although the first chart was improved by spacing the books proportionate to the date read and the hover text included the book title as well as the date read, without an explicit request to do so. +The charts generated were similar to those created by the PyCafe host above, although the first chart was improved by spacing the books proportionate to the date read. The hover text included the book title as well as the date read, without needing an explicit request to do so. ![](../../assets/tutorials/project/chart1v2.png) @@ -272,7 +274,7 @@ As we've already seen, the code generated by Vizro-AI can vary from run to run, 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. -To share and iterate the prototype, we can transfer the generated code from the output of Vizro-AI in the Notebook into a PyCafe project. +To share and iterate the prototype, we can transfer the **generated** code from the output of Vizro-AI in the Notebook into a PyCafe project. There are three changes to the Notebook code needed for it to run on PyCafe: @@ -454,19 +456,19 @@ Follow the link at the bottom of the code snippet titled **☕️ Run and edit t Vizro().build(model).run() ``` -## Summary +## Prototype summary -In this tutorial, we first used Vizro-AI to generate a set of charts by iterating prompts, hosted in PyCafe. +In this tutorial, we used Vizro-AI to generate a set of charts by iterating prompts, hosted in PyCafe. We then converted the successful prompts to build a Vizro dashboard using Vizro-AI in a Notebook using a few lines of support code. -Finally, we converted the Vizro-AI generated Python to a PyCafe project with a few additional lines of support code. At this point, the Vizro project is not using generative AI, so it is easy to share and iterate. +Finally, we converted the generated Python to a PyCafe project with a few additional lines of support code. The resulting Vizro project is not using generative AI, so it is easy to share and iterate. The code generated by Vizro-AI does not make a perfect dashboard, but it has been very easy to get it to a good standard without a great deal of coding or design experience. There are a few improvements that are easily applied to the Plotly code to further improve the charts, as shown below in a separate PyCafe project. ### Improvements to generated Plotly code -In this version of the dashboard, the first chart that show the sequence of books read has been modified to improve the information supplied when hovering over a point, and the opacity of the points has been altered to make it more attractive. The control has been changed to a slider for the `Date Read` field. +In this version of the dashboard, the first chart that shows the sequence of books read has been modified to improve the information supplied when hovering over a point, and the opacity of the points has been altered to make it more attractive. The control has been changed to a slider for the `Date Read` field. In the second chart that shows the cumulative total of pages and books read, the line chart has been explicitly plotted on top of the bar chart.