{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Section 7.0: Introduction to Plotly's Streaming API" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Welcome to Plotly's Python API User Guide. \n", "\n", "> Links to the other sections can be found on the User Guide's [homepage](https://plotly.com/python/userguide)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Section 7 is divided, into separate notebooks, as follows:\n", "\n", "* [7.0 Streaming API introduction](https://plotly.com/python/intro_streaming)\n", "\n", "* [7.1 A first Plotly streaming plot](https://plotly.com/python/streaming_part1)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Quickstart (initialize Plotly figure object and send 1 data point through a stream):\n", "\n", " >>> import plotly.plotly as py\n", " >>> from plotly.graph_objs import *\n", " >>> # auto sign-in with credentials or use py.sign_in()\n", " >>> trace1 = Scatter(\n", " x=[],\n", " y=[], \n", " stream=dict(token='my_stream_id')\n", " )\n", " >>> data = Data([trace1])\n", " >>> py.plot(data)\n", " >>> s = py.Stream('my_stream_id')\n", " >>> s.open()\n", " >>> s.write(dict(x=1, y=2))\n", " >>> s.close()\n", " \n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Check which version is installed on your machine and please upgrade if needed. " ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'1.9.5'" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# (*) Import plotly package\n", "import plotly\n", " \n", "# Check plolty version (if not latest, please upgrade)\n", "plotly.__version__" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\n", "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*.\n", "\n", "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.\n", "\n", "With Ploly's Streaming API:\n", "\n", "> 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, embedded in website, or in an IPython notebook. Owners of the Plotly plot can edit the plot with the Plotly web GUI and all viewers will see these changes live. \n", "\n", "And for the skeptical among us, *it's fast*: plots update up to 20 times per second.\n", "\n", "In this section, we present examples of how to make Plotly streaming plots.\n", "Readers looking for info about the nuts and bolts of Plotly's streaming API should refer to this link." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "So, we first import a few modules and sign in to Plotly using our credentials file:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": false }, "outputs": [], "source": [ "# (*) To communicate with Plotly's server, sign in with credentials file\n", "import plotly.plotly as py \n", " \n", "# (*) Useful Python/Plotly tools\n", "import plotly.tools as tls \n", " \n", "# (*) Graph objects\n", "from plotly.graph_objs import *\n", " \n", "import numpy as np # (*) numpy for math functions and arrays" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### What do Plotly streaming plots look like?" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/html": [ "" ], "text/plain": [ "" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Embed an existing Plotly streaming plot\n", "tls.embed('streaming-demos','6')\n", "\n", "# Note that the time point correspond to internal clock of the servers, \n", "# that is UTC time." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Data is sent in real-time.
\n", "Plotly draws the data in real-time.
\n", "Plotly's interactibility happens in real-time." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Get your stream tokens" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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 to plot.ly. Once that is done, click on the *Settings* button in the upper-right corner of the page:\n", "\n", " \n", "\n", "

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

\n", "\n", "\n", "\n", "And there you go, you have generated a stream token. Please note that:\n", "\n", "> You must generate one stream token per **trace** in your Plotly streaming plot.\n", "\n", "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:\n", "\n", " >>> tls.set_credentials_file(stream_ids=[\n", " \"ab4kf5nfdn\",\n", " \"kdf5bn4dbn\",\n", " \"o72o2p08y5\",\n", " \"81dygs4lcy\"\n", " ])\n", "\n", "where the `stream_ids` keyword argument is filled in with your own stream ids.\n", "\n", "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`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once your credentials file is updated with your stream tokens (or stream ids, a synonym), retrieve them as a list:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "collapsed": false }, "outputs": [], "source": [ "stream_ids = tls.get_credentials_file()['stream_ids']" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We are now ready to start making Plotly streaming plots!\n", "\n", "The content of this section has been divided into separate IPython notebooks as loading multiple streaming plots at once can cause performance slow downs on some internet connections.\n", "\n", "Here are the links to the subsections' notebooks:\n", "\n", "* [7.0 Streaming API introduction](https://plotly.com/python/intro_streaming)\n", "* [7.1 A first Plotly streaming plot](https://plotly.com/python/streaming_part1)\n", "\n", "In addition, here is a notebook of another Plotly streaming plot:\n", "\n", "* Streaming the Poisson Pareto Burst Process by \n", "Emilia Petrisor\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", " \n", "
\n", "\n", "

Got Questions or Feedback?

\n", "\n", "Reach us here at: Plotly Community\n", "\n", "

What's going on at Plotly?

\n", "Check out our twitter: \n", "@plotlygraphs\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/html": [ "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "Requirement already up-to-date: publisher in /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages\r\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/IPython/nbconvert.py:13: ShimWarning: The `IPython.nbconvert` package has been deprecated. You should import from nbconvert instead.\n", " \"You should import from nbconvert instead.\", ShimWarning)\n", "/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/publisher/publisher.py:53: UserWarning: Did you \"Save\" this notebook before running this command? Remember to save, always save.\n", " warnings.warn('Did you \"Save\" this notebook before running this command? '\n", "/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/publisher/publisher.py:58: UserWarning: Your URL has more than 2 parts... are you sure?\n", " warnings.warn('Your URL has more than 2 parts... are you sure?')\n" ] } ], "source": [ "from IPython.display import display, HTML\n", "\n", "display(HTML(''))\n", "display(HTML(''))\n", "\n", "! pip install publisher --upgrade\n", "import publisher\n", "publisher.publish(\n", " 's7_streaming.ipynb', 'python/intro_streaming//', 'Getting Started with Plotly Streaming',\n", " 'Getting Started with Plotly Streaming',\n", " title = 'Getting Started with Plotly Streaming',\n", " thumbnail='', language='python',\n", " layout='user-guide', has_thumbnail='false') " ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 2", "language": "python", "name": "python2" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 2 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython2", "version": "2.7.9" } }, "nbformat": 4, "nbformat_minor": 0 }