Introduction

Today’s setup

Point your browser to https://jupyter.cass.vastcloud.org, log in with your username and password (supplied by the instructor), specify the runtime of at least 2 hours (and leave all other settings at their default values), and start a Jupyter notebook.

Installation on your own computer

If you are brave enough to try today’s examples on your own computer, you will need Python 3 and a Python package manager. Then, use your favourite installer to install Plotly, ideally inside a dedicated virtual environment:

$ pip install plotly
$ uv pip install plotly
$ conda install -c conda-forge plotly

Other recommended libraries to install for today’s session:

  • numpy
  • pandas
  • jupyter
  • nbformat to plot inside Jupyter notebooks
  • kaleido to save plots to PNG
  • networkx to work with networks
  • scikit-image to create an isosurface with Marching Cubes algorithm

Displaying Plotly figures

Renderers

With Plotly, you can:

  1. work inside a Python shell in the terminal,
  2. save your script into a *.py file and then run it, or
  3. run your script inside a Jupyter notebook.

Plotly supports a number of renderers, and it will attempt to choose an appropriate renderer automatically – in my experience, often not very successfully. You can examine the selected default renderer with:

import plotly.io as pio
pio.renderers   # show default and available renderers

You can overwrite the default by setting it manually inside your session or inside your code, e.g.

pio.renderers.default = 'browser'          # open each plot in a new browser tab
pio.renderers.default = 'notebook'         # plot inside a Jupyter notebook
pio.renderers.default = 'plotly_mimetype'  # default for Jupyter, fails with remote JH

If you want to have this setting persistent across interactive sessions (and not set it manually or in the code), you can create a file ~/.plotly_startup.py with the following:

try:
    import plotly.io as pio
    pio.renderers.default = "browser"
except ImportError:
    pass

and set export PYTHONSTARTUP=~/.plotly_startup.py in your ~/.bashrc file. Note that $PYTHONSTARTUP can be used to customize only your interactive Python sessions (in the terminal or Jupyter), i.e. it does not execute when you run a script. When running a script, you could insert

import plotly.io as pio
pio.renderers.default = "browser"

directly into the script.

Working in a Jupyter notebook

Let me demonstrate this using a renderer with a simple plot. Inside a Jupyter notebook, set the renderer and then create a basic line plot:

import plotly.io as pio
pio.renderers.default = 'notebook'
import plotly.graph_objs as go
from numpy import linspace, sin
x = linspace(0.01,1,100)
y = sin(1/x)
line = go.Scatter(x=x, y=y, mode='lines+markers', name='sin(1/x)')
   # this is a trace = fundamental building block of a plot;
   # think of it as a single set of data and the instructions on how to draw it
# Option 1
go.Figure([line])   # pass data = a list of trace instances
                    # plot should automatically dispay inside the notebook
# Option 2
fig = go.Figure([line])   # no plot displayed at this point
fig.show()                # plot should dispay inside the notebook

If you want to save your figure, you can mouse over the plot and select “Download plot as a PNG”. Alternatively, you can do this from the code:

fig.write_html("lines.html")            # interactive HTML file
fig.write_image("lines.png", scale=2)   # static, supports svg, png, jpg/jpeg, webp, pdf
                                        # requires 'kaleido' library and Chromium engine library
                                        # will take a while in Jupyter

The last command is meant for the Python shell, not for Jupyter. If run in Jupyter, it’ll use an external library kaleido which in turn will the Chromium engine system library, and the whole process will take minutes – something to keep in mind.

Working in a Python shell

Now, let me switch briefly to running Plotly on my computer:

import plotly.io as pio
pio.renderers.default   # 'browser'
import plotly.graph_objs as go
from numpy import linspace, sin
x = linspace(0.01,1,100)
y = sin(1/x)
line = go.Scatter(x=x, y=y, mode='lines+markers', name='sin(1/x)')
fig = go.Figure([line])   # no plot displayed at this point
fig.show()                # plot should dispay inside a new browser tab

fig.write_html("lines.html")            # interactive HTML file
fig.write_image("lines.png", scale=2)   # static, supports svg, png, jpg/jpeg, webp, pdf
ImportantKey point

In general, use fig.show() to enforce displaying the plot (shell or Jupyter). Depending on your setup, this command might not be necessary inside a Jupyter notebook if you create a figure with go.Figure(...) without saving it to a variable – then your plot should be displayed automatically.

Running a local script

Let me save the following as a local file test.py:

import plotly.io as pio
pio.renderers.default = "browser"
import plotly.graph_objs as go

from numpy import linspace, sin
x = linspace(0.01,1,100)
y = sin(1/x)
line = go.Scatter(x=x, y=y, mode='lines+markers', name='sin(1/x)')
fig = go.Figure([line])   # no plot displayed at this point
fig.show()

and then run it:

python test.py

This should open a new local browser tab with the plot.

Running a remote script

On a remote system, there is no browser in which we could open a new tab. To run this script from the command line on the training cluster, we need to change the last line fig.show() to fig.write_image("lines.png") to write directly into a file.

You can find more details at https://plotly.com/python/renderers.

Two plotting interfaces

At the moment, Plotly offers two plotting interfaces:

  1. original Graph Objects library plotly.graph_objs (GO) for total control
    • most capable, lower-level plotting interface – you saw its example few minutes ago
    • can combine multiple traces (building blocks) from different sources in a single plot
    • more flexible, deeper access to various plot properties, great for detailed customization
  2. newer Plotly Express (PX) library plotly.express for rapid data exploration
    • high-level interface
    • built on top of Graph Objects
    • provides 30+ functions for creating different types of figures in a single function call

Both interfaces can work with data from NumPy arrays, Xarrays, Pandas dataframes, basic Python iterables, etc. And you can mix the two interfaces in a single script, e.g. create a simple figure with Plotly Express and then customize it with Graph Objects controls – you will see many examples of this in the section on Dash.