HTML Visualizations

Visualizations that benefit from limited interactivity, such as displaying tooltips on hover or zooming in / out and scrolling can be rendered within GitHub pages.

A folium map can be saved as a local HTML file and checked into GitHub (ipyleaflet must be rendered directly in the notebook). Many chart packages, including altair, matplotlib, and plotly allow you to export as HTML.

# altair
import altair as alt
chart.save("../my-visualization.html")

# matplotlib (by encoding it)
import matplotlib.pyplot as plt
import base64
from io import BytesIO

fig = plt.figure()

tmpfile = BytesIO()
fig.savefig(tmpfile, format='png')
encoded = base64.b64encode(tmpfile.getvalue()).decode('utf-8')

html = 'Some html head' + '<img src=\'data:image/png;base64,{}\'>'.format(encoded) + 'Some more html'

with open('test.html','w') as f:
    f.write(html)

# plotly
import plotly.express as px
fig.write_html("../my-visualization.html")

# folium
import folium
fig.save("../my-visualization.html")

Rendering Jupyter Notebook as HTML

A single notebook can be converted to HTML using nbconvert. If it’s a quick analysis in a standalone notebook, sometimes an analyst may choose not to go down the portfolio method.

• In the terminal: jupyter nbconvert --to html --no-input --no-prompt

  • --no-input: hide code cells

  • --no-prompt: hide prompts to have all cells vertically aligned

• A longer example of converting multiple notebooks into HTML pages and uploading to GitHub

Use GitHub pages to display these HTML pages

Analysts should use this only in case of emergencies (missing netlify credentials or analysts working outside of our data-analyses repo). We prefer launching through our portfolio, which can take single, unparameterized notebooks as well.

1. Go to the repo’s settings

2. Navigate to Pages on the left

3. Change the branch GH pages is sourcing from: main to my-current-branch

4. Embed the URL into the slides. Example URL: https://docs.calitp.org/data-analyses/PROJECT-FOLDER/MY-VISUALIZATION.html

5. Once a PR is ready and merged, the GH pages can be changed back to source from main. The URL is preserved within the slide deck.