Plotly's Python API User Guide

Section 7: Plotly's Streaming API

Welcome to Plotly's Python API User Guide.

Links to the other sections are on the User Guide's homepage
The Github repository is available here

Quickstart (initialize Plotly figure object and send 1 data point through a stream):

>>> import plotly.plotly as py
>>> from plotly.graph_objs import *
>>> # auto sign-in with credentials or use py.sign_in()
>>> trace1 = Scatter(
        x=[],
        y=[], 
        stream=dict(token='my_stream_id')
    )
>>> data = Data([trace1])
>>> py.plot(data)
>>> s = py.Stream('my_stream_id')
>>> s.open()
>>> s.write(dict(x=1, y=2))
>>> s.close()


Check which version is installed on your machine and please upgrade if needed.

In [1]:
# (*) Import plotly package
import plotly
 
# Check plolty version (if not latest, please upgrade)
plotly.__version__
Out[1]:
'1.6.6'

See the User Guide's homepage for more info on installation and upgrading.


Plotly's Streaming API enables your Plotly plots to update in real-time, without refreshing your browser. In other words, users can continuously send data to Plotly's servers and visualize this data in real-time.

For example, imagine that you have a thermometer (hooked to an Arduino for example) in your attic and you would like to monitor the temperature readings from your laptop. Plotly together with its streaming API makes this project easy to achieve.

With Ploly's Streaming API:

Everyone looking at a Plotly streaming plot sees the same data, updating at the same time. Like all Plotly plots, Plotly streaming plots are immediately shareable, by shortlink or as embedded in website or an IPython notebook. Owners of Plotly plot can edit their with the Plotly web GUI while all of the viewers of the plot will see the changes update live.

And for the skeptical among us, it's fast: plots update up to 20 times per second.

In this section, we present examples of how to make Plotly streaming plots. Readers looking for info about the nuts and bolts of Plotly's streaming API should refer to this link.

So, we first import a few modules and sign in to Plotly using our credentials file:

In [2]:
# (*) To communicate with Plotly's server, sign in with credentials file
import plotly.plotly as py  
 
# (*) Useful Python/Plotly tools
import plotly.tools as tls   
 
# (*) Graph objects to piece together plots
from plotly.graph_objs import *
 
import numpy as np  # (*) numpy for math functions and arrays

If you are not familiar with credentials files, refer to the User Guide's homepage.

What do Plotly streaming plots look like?

This

In [3]:
# Embed an existing Plotly streaming plot
tls.embed('streaming-demos','6')

# Note that the time point correspond to internal clock of the servers, 
# that is UTC time.
Out[3]:

Data is sent in real-time.
Plotly draws the data in real-time.
Plotly's interactibility happens in real-time.

Get your stream tokens

Making Plotly streaming plots requires no modifications to the sign in process; however, users must generate stream tokens or ids. To do so, first sign in on plot.ly. Once that is done, click on the Settings button in the upper-right corner of the page:

Under the *Stream Tokens* tab, click on the *Generate Token* button:

And there you go, you have generated a stream token. Please note that:

You must generate one stream token per trace to be plotted in each of your Plotly streaming plots.

If you are looking to run this notebook with you own account, please generate 4 unique stream tokens and add them to your credentials file by entering:

>>> tls.set_credentials_file(stream_ids=[
        "ab4kf5nfdn",
        "kdf5bn4dbn",
        "o72o2p08y5",
        "81dygs4lcy"
    ])

where the stream_ids keyword argument is filled in with your own stream ids.

Note that, in the above, tls.set_credentials() overwrites the existing stream tokens (if any) but does not clear the other keys in your credentials file such as username and api_key.

Once your credentials file is updated with your stream tokens (or stream ids, a synonym), retrieve them as a list:

In [4]:
stream_ids = tls.get_credentials_file()['stream_ids']

We are now ready to start making Plotly streaming plots!

The content of this section has been divided into separate IPython notebooks as loading multiple streaming at once can cause performance slow downs on some internet connections.

Here are the links to the subsections' notebooks:

In addition, here is a notebook of another Plotly streaming plot:


Go to [Section 8 --- 3D Plots](https://plot.ly/python/3d-plots-tutorial)

Go to [Section 6 --- Convert your Matplotlib plots to Plotly](https://plot.ly/python/matplotlib-to-plotly-tutorial)

Go to [top of page](#Plotly's-Python-API-User-Guide)

Go to User Guide's [homepage](https://plot.ly/python/user-guide)


Got Questions or Feedback?

About Plotly

About the User Guide

Notebook styling ideas

Big thanks to


In [5]:
# CSS styling within IPython notebook
from IPython.display import display, HTML
display(HTML(open('../custom.css').read()))