On this article, I will clarify how I constructed a dashboard to visualise the site visitors information for some documentation I keep as a technical author. I’ve few design abilities and restricted Python expertise, so I wanted a easy, low-code method to point out the affect and utilization of the documentation I keep. This turned out to be an open-source resolution: Vizro as a template for a low-code dashboard, and Vizro-AI to construct particular person charts with generative AI.
TL;DR?
If you wish to soar proper in, you could find the Jupyter Pocket book code for the dashboard in my GitHub repo.
A Learn the Docs Dashboard Undertaking
If, like me, you handle an open-source docs mission with Learn the Docs (RTD), you’ve got in all probability found you can obtain the final 90 days’ price of site visitors information in CSV format out of your mission dashboard. The dashboard additionally shows a each day pageview totals chart, just like the one under.
For extra visible output, you possibly can harness Google Analytics (GA). Nevertheless, some initiatives desire to not use GA as a result of its compliance with the Normal Information Safety Regulation (GDPR) is seen as controversial, notably within the European Union (EU).
Only a word that within the instance under, I’ve used a set of pretend CSV site visitors information that I generated, with assist from OpenAI, to maintain the site visitors to our mission non-public. The faux information has the identical fields as real RTD information so you may obtain and use the dashboard with the info downloaded out of your RTD dashboard.
Get the Code and Information
To run via the instance your self, you may want my faux information (or your personal obtain) and the Jupyter Pocket book code, saved in my GitHub repo. It is easy to step via at a primary degree, however a extra superior person can prolong it. Please let me know in the event you do create an enhanced model!
Vizro is a framework constructed on high of Plotly and Sprint that makes use of a configuration method to specify customized dashboard layouts. A Vizro dashboard might be populated with charts constructed by Vizro-AI, a package deal separate from Vizro that simplifies the visualization course of by leaning on generative AI.
On this instance, I provided the info and pure language directions, and Vizro-AI generated Python code and created my requested charts. This labored effectively for me as a author, since I’ve no front-end design abilities and I am unfamiliar with Plotly, however I am pleased to phrase an appropriate generative AI immediate and coax a chart from OpenAI.
Set Up Vizro-AI
Earlier than operating the Pocket book code, you’ll want to arrange Vizro-AI inside a digital surroundings with Python 3.9 or later. Set up the package deal with pip set up vizro_ai
.
Subsequent, you want an API key to entry OpenAI. When you do not have already got an account, create one, and purchase some credit to make use of a mannequin since you can not use the free model. Generate an API key and add it to your surroundings so the code you write within the subsequent step might be accessed to efficiently name OpenAI. There are some simple directions within the OpenAI docs, and the method can be coated within the Vizro-AI LLM setup information.
Construct a Chart
At this level, you may open a Jupyter Pocket book to make your first chart, or simply open the Pocket book from my repo to step via the code I created and cargo your RTD information (or the faux information I’ve supplied) right into a pandas DataFrame, named df
within the code under.
The next code reveals methods to submit a request to Vizro-AI to construct a chart that resembles the chart within the Learn the Docs mission dashboard, displaying views by date, however splitting the info into two traces, for the steady and newest variations of the documentation:
import vizro_ai
from vizro_ai import VizroAI
from dotenv import load_dotenv
load_dotenv()
vizro_ai = VizroAI(mannequin="gpt-4–0613")
compare_versions_fig = vizro_ai.plot(df, "Combine rows of Views for each Date for latest and stable Version. Draw a line graph comparing Views per Date for latest and stable", clarify=True)
compare_versions_fig.present()
Vizro-AI passes the pure language question, “Combine rows of Views for each Date for latest and stable Version. Draw a line graph comparing Views per Date for latest and stable,” and the dataframe to the mannequin. Word that within the instance above, I’ve specified a GPT-4 mannequin. Vizro-AI will default to make use of GPT-3.5-turbo as a result of it affords a lower cost level and better velocity for offering solutions, however it doesn’t supply essentially the most refined charting, so I opted to make an specific request to make use of a GPT-4 mannequin.
The chart output will rely in your information, and on the output acquired from OpenAI on the time the question was submitted. The parameter clarify=True
requests that Vizro-AI clarify how the ensuing chart was obtained, and the reason is proven as output within the Jupyter Pocket book, together with the chart which is displayed by the present()
command.
The Insights textual content returned by Vizro-AI explains methods to manipulate the site visitors information. The Code part describes the steps the code snippet follows to generate the road graph requested.
The chart returned appears as follows:
Construct Extra Charts
I created some further charts to additional illustrate the site visitors to our documentation, as follows:
# Complete views of the highest performing steady pages
top_performing_pages_fig = vizro_ai.plot(df, "Collate rows of data for Path where Version==stable. Create a horizontal bar chart describing the total Views for the top 5 pages. Add the numbers to each bar. Decrease font size of marks", clarify=True)
top_performing_pages_fig.present()
# Prime 5 performing pages on steady by date
top_pages_by_date_fig = vizro_ai.plot(df, "Collate rows of data for Path where Version==stable. Create a line graph for the total Views per Date for the top 5 Paths", clarify=True)
top_pages_by_date_fig.present()
“Collate rows of data for Path where Version==stable. Create a horizontal bar chart describing the total Views for the top 5 pages. Add the numbers to each bar and title ‘Total views for top 5 stable pages’. Decrease font size of marks” and “Collate rows of data for Path where Version==stable. Create a line graph for the total Views per Date for the top 5 Paths”
Vizro-AI has accomplished the heavy lifting for me by producing the code to control the info and generate a set of charts, that are helpful in themselves. Extra helpful nonetheless can be to group them collectively together to make a whole dashboard.
Create a Vizro Dashboard
You need to use Vizro in the identical Jupyter Pocket book because the Vizro-AI code above. Be certain to pip set up vizro
because the Vizro documentation describes. Right here is a few code for the skeleton of a easy dashboard with out the chart technology:
from vizro import Vizro
import vizro.fashions as vm
import vizro.plotly.categorical as px
first_page = vm.Web page(
title="Documentation traffic dashboard",
structure=vm.Format(
grid=[
[0, 2],
[1, 2],
],
),
parts=[
# TO DO
],
)
...
The # TO DO
part is the place we add every of the charts.
There are two choices at this level:
- Use Vizro-AI to generate the charts every time the dashboard is generated
- Use the Python code that Vizro-AI returned to name on to Plotly.
The primary choice requires much less code however can be slower to return and costlier as a result of it makes use of Vizro-AI, which calls OpenAI. The second choice is quicker however requires extra code manipulation.
This is a cell containing the dashboard code that demonstrates the primary choice with features that decision via to Vizro-AI (If you propose to run this for your self, be sure you’re utilizing the Pocket book in my repo, have loaded the info and stepped via the cells that arrange the calls to Vizro-AI):
# Dashboard utilizing Vizro-AI calls solely
from vizro import Vizro
import vizro.fashions as vm
import vizro.plotly.categorical as px
first_page = vm.Web page(
title="Documentation traffic dashboard",
structure=vm.Format(
grid=[
[0, 2],
[1, 2],
],
),
parts=[
# Latest and stable by date
vm.Graph(figure=compare_versions_fig),
# Top performing stable pages
vm.Graph(figure=top_performing_pages_fig),
# Top 5 stable pages by date
vm.Graph(figure=top_pages_by_date_fig),
],
)
dashboard = vm.Dashboard(pages=[first_page])
Vizro().construct(dashboard).run(port=8006)
This is a barely completely different model, which makes use of the second choice to generate one of many charts. I’ve taken the chance to tweak the Python code barely to vary the colours of the strains, which is about my restrict for Plotly manipulation! (Once more, in the event you plan to run this for your self, be sure you’re utilizing the Pocket book in my repo, have loaded the info, and stepped via the cells that arrange the chart creation features).
# Dashboard from Vizro-AI calls and utilizing Vizro-AI generated chart code
from vizro import Vizro
import vizro.fashions as vm
import vizro.plotly.categorical as px
from vizro.fashions.varieties import seize
import plotly.graph_objects as go
import pandas as pd
@seize('graph')
def compare_versions_custom_chart(data_frame=None):
if data_frame is None:
data_frame = pd.DataFrame()
data_frame['Date'] = pd.to_datetime(data_frame['Date'])
# Group by Date and Model and sum the Views
aggregated_df = data_frame.groupby(['Date', 'Version'])['Views'].sum().reset_index()
# Pivot the dataframe to have Variations as columns
pivot_df = aggregated_df.pivot(index='Date', columns="Version", values="Views")
# Fill NaN values with 0
pivot_df.fillna(0, inplace=True)
data_frame = pivot_df.reset_index()
# Create a line hint for every model
trace1 = go.Scatter(x=data_frame['Date'], y=data_frame['latest'], mode="lines", title="latest", line=dict(coloration="#689F38"))
trace2 = go.Scatter(x=data_frame['Date'], y=data_frame['stable'], mode="lines", title="stable", line=dict(coloration="#FDC935"))
# Outline the structure
structure = go.Format(title="Views per Date for latest and stable Version", xaxis=dict(title="Date"), yaxis=dict(title="Views"))
# Create a Determine and add the traces
fig = go.Determine(information=[trace1, trace2], structure=structure)
# Return the determine
return fig
compare_versions_custom_fig = compare_versions_custom_chart(data_frame=df)
first_page = vm.Web page(
title="Documentation traffic dashboard",
structure=vm.Format(
grid=[
[0, 2],
[1, 2],
],
),
parts=[
# Latest and stable by date
vm.Graph(figure=compare_versions_custom_fig),
# Top performing stable pages
vm.Graph(figure=top_performing_pages_fig),
# Top 5 stable pages by date
vm.Graph(figure=top_pages_by_date_fig),
],
)
dashboard = vm.Dashboard(pages=[first_page])
Vizro().construct(dashboard).run(jupyter_mode="external")
You possibly can obtain the Jupyter Pocket book to check out the dashboard with your personal Learn the Docs information. It appears as follows with the faux information I provided.
One in all my colleagues (thanks, Nadija!) gave me a tip you can run the dashboard within the Pocket book after which view it in a separate browser window by viewing the port you select as follows:
Vizro().construct(dashboard).run(port=8006) # localhost8006 within the browser
Alternatively (thanks, Antony!), as I’ve proven within the second dashboard instance above, you may generate a clickable hyperlink to view the dashboard as follows:
Vizro().construct(dashboard).run(jupyter_mode="external")
Wrapping Up
On this instance, I confirmed methods to use Vizro-AI to generate Plotly charts to visualise documentation site visitors, after which constructed these charts right into a Vizro dashboard.
If in case you have information science and Python abilities and a expertise for design, you might have considered trying the problem of constructing a dashboard with Plotly and Sprint. However, to somebody like me with out these abilities, it’s a recreation changer to have the ability to use OpenAI and obtain the output above. I now have a helpful visualization for Learn the Docs site visitors information in about 50 strains of code. It appears skilled and is definitely extensible and comparatively straightforward to share. With extra effort, I might enhance it additional by including customizations resembling filters, parameters, or separate navigable pages.
What’s extra, I can collaborate on the dashboard code with my colleagues to adapt it for different Learn the Docs initiatives. I’ve used a Jupyter Pocket book to make it straightforward to display the mission, however this method works equally effectively in a Python script, making it simply sharable and maintainable in model management. I also can deploy the dashboard so my colleagues can entry it straight with out operating the code.
Our staff now has a helpful and usable dashboard for monitoring documentation affect, put collectively by a technical author in a day. Who can ask for extra?
I’d wish to thank my colleagues, notably Nadija, Anna, and Joe, for a number of rounds of assessment suggestions as I used to be placing this put up collectively.