Show Sidebar Hide Sidebar

Presentations API in Python

How to create and publish a spectacle-presentation with the Python API.

New to Plotly?¶

Plotly's Python library is free and open source! Get started by downloading the client and reading the primer.
You can set up Plotly to work in online or offline mode, or in jupyter notebooks.
We also have a quick-reference cheatsheet (new!) to help you get started!

Version Check¶

Note: The presentations API is available in version 2.2.1.+
Run pip install plotly --upgrade to update your Plotly version.

In [1]:
import plotly
plotly.__version__
Out[1]:
'2.2.1'

Plotly Presentations¶

To use Plotly's Presentations API you will write your presentation code in a string of markdown and then pass that through the Presentations API function pres.Presentation(). This creates a JSON version of your presentation. To upload the presentation online pass it through py.presentation_ops.upload().

In your string, use --- on a single line to seperate two slides. To put a title in your slide, put a line that starts with any number of #s. Only your first title will be appear in your slide. A title looks like:

# slide title

Anything that comes after the title will be put as text in your slide. Check out the example below to see this in action.

Current Limitations¶

Boldface, italics and hypertext are not supported features of the Presentation API.

Simple Example¶

In [2]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'simple-pres'
markdown_string = """
# slide 1
There is only one slide.

---
# slide 2
Again, another slide on this page.

"""

my_pres = pres.Presentation(markdown_string)
pres_url_0 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_0)
https://plot.ly/~AdamKulidjian/3700/simple-pres/
In [3]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_0 = url_to_iframe(pres_url_0, True)
IPython.display.HTML(iframe_0)
Out[3]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Insert Plotly Chart¶

If you want to insert a Plotly chart into your presentation, all you need to do is write a line in your presentation that takes the form:

Plotly(url)

where url is a Plotly url. For example:

Plotly(https://plot.ly/~AdamKulidjian/3564)

The Plotly url lines should be written on a separate line after your title line. You can put as many images in your slide as you want, as the API will arrange them on the slide automatically, but it is highly encouraged that you use 4 OR FEWER IMAGES PER SLIDE. This will produce the cleanest look.

Useful Tip:
For Plotly charts it is HIGHLY ADVISED that you use a chart that has layout['autosize'] set to True. If it is False the image may be cropped or only partially visible when it appears in the presentation slide.

In [4]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-plotly-chart'
markdown_string = """
# 3D scatterplots
3D Scatterplot are just a collection of balls in a 3D cartesian space each of which have assigned properties like color, size, and more.

---
# simple 3d scatterplot

Plotly(https://plot.ly/~AdamKulidjian/3698)
---
# different colorscales

There are various colorscales and colorschemes to try in Plotly. Check out plotly.colors to find a list of valid and available colorscales.

Plotly(https://plot.ly/~AdamKulidjian/3582)
Plotly(https://plot.ly/~AdamKulidjian/3698)
"""

my_pres = pres.Presentation(markdown_string)
pres_url_1 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_1)
https://plot.ly/~AdamKulidjian/3710/pres-with-plotly-chart/
In [5]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_1 = url_to_iframe(pres_url_1, True)
IPython.display.HTML(iframe_1)
Out[5]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Insert Web Images¶

To insert an image from the web, insert the a Image(url) where url is the image url.

In [6]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-images'
markdown_string = """
# Animals of the Wild
---
# The Lion

Panthera leo is one of the big cats in the Felidae family and a member of genus Panthera. It has been listed as Vulnerable on the IUCN Red List since 1996, as populations in African range countries declined by about 43% since the early 1990s. Lion populations are untenable outside designated protected areas. Although the cause of the decline is not fully understood, habitat loss and conflicts with humans are the greatest causes of concern. The West African lion population is listed as Critically Endangered since 2016. The only lion population in Asia survives in and around India's Gir Forest National Park and is listed as Endangered since 1986.

Image(https://i.pinimg.com/736x/da/af/73/daaf73960eb5a21d6bca748195f12052--lion-photography-lion-kings.jpg)
---
# The Giraffe

The giraffe is a genus of African even-toed ungulate mammals, the tallest living terrestrial animals and the largest ruminants. The genus currently consists of one species, Giraffa camelopardalis, the type species. Seven other species are extinct, prehistoric species known from fossils. Taxonomic classifications of one to eight extant giraffe species have been described, based upon research into the mitochondrial and nuclear DNA, as well as morphological measurements of Giraffa, but the IUCN currently recognizes only one species with nine subspecies.

Image(https://img.purch.com/w/192/aHR0cDovL3d3dy5saXZlc2NpZW5jZS5jb20vaW1hZ2VzL2kvMDAwLzA2OC8wOTQvaTMwMC9naXJhZmZlLmpwZz8xNDA1MDA4NDQy)
Image(https://upload.wikimedia.org/wikipedia/commons/9/9f/Giraffe_standing.jpg)

"""

my_pres = pres.Presentation(markdown_string)
pres_url_2 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_2)
https://plot.ly/~AdamKulidjian/3702/pres-with-images/
In [7]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_2 = url_to_iframe(pres_url_2, True)
IPython.display.HTML(iframe_2)
Out[7]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Image Stretch¶

If you want to ensure that your image maintains its original width:height ratio, include the parameter imgStretch=False in your pres.Presentation() function call.

In [8]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-no-imgstretch'
markdown_string = """
# images in native aspect ratio

Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)
Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)
Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)
Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)
Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)
"""


my_pres = pres.Presentation(markdown_string, imgStretch=False)
pres_url_3 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_3)
https://plot.ly/~AdamKulidjian/3703/pres-with-no-imgstretch/
In [9]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_3 = url_to_iframe(pres_url_3, False)
IPython.display.HTML(iframe_3)
Out[9]:
'

Insert Code Blocks¶

The Presentations API also supports the insertion of blocks of code with various available langauges to choose from.

To instantiate a "code environment" in your string, place a ``` at the beginning of a line, followed by the name of the programming language you want your code block to be styled in. Then the next lines will be considered "code lines ". To close the "code environment" put another ``` at the end of the line For example:

```python
# code goes here
```

The valid languages to choose from are: arecpp, cs, css, fsharp, go, haskell, java, javascript, jsx, julia, xml, matlab, php, python, r, ruby, scala, sql and yaml.

In [10]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-code'
markdown_string = """
# Getting Started Using Code
A beginner's introduction to computer science.

---
# Python Functions
Functions are one of the most useful tools in Python. Intuitively, you select an input and get an output.

In order to set up a function use the key word "def" then the name of the function with open parentheses afterwards. Inside the parentheses, write variable names your function will use. These variables can then go into the body of your function and when you give a value to the variable in the call signature, it will pass through the guts of the function until it returns a value.

```python
def somePrintFunction():

    print("boo")

somePrintFunction()




>>>print(new_z)
10

def someAddFunction(a, b):

    print(a+b)




>>>someAddFunction(12,451)
463
```
---
# Use scala
You can write functions in other languages as well. For example, check out this scala code and notice how the print functions look different:

We write 'println()' as opposed to 'print()' as we do in Python.

```scala
/** Basic command line parsing. */
object Main {
  var verbose = false

  def main(args: Array[String]) {
    for (a <- args) a match {
      case "-h" | "-help"    =>
        println("Usage: scala Main [-help|-verbose]")
      case "-v" | "-verbose" =>
        verbose = true
      case x =>
        println("Unknown option: '" + x + "'")
    }
    if (verbose)
      println("How are you today?")
  }
}
```
---
# Under the Hood

There are many things to find when you look under the Plotly Hood. Of many things, one expected thing is the compliance and adherance to alphebetized and PEP-8'ed imports at the top of any module.

This is what the PEP-8 guide has more to say about Imports:

Wildcard imports (from <module> import *) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. There is one defensible use case for a wildcard import, which is to republish an internal interface as part of a public API (for example, overwriting a pure Python implementation of an interface with the definitions from an optional accelerator module and exactly which definitions will be overwritten isn't known in advance).

Image(https://help.plot.ly/images/dashboard-carousel.jpg)

```python
from __future__ import absolute_import

import copy
import json
import os
import time
import warnings
import webbrowser

import six
import six.moves
from requests.compat import json as _json

from plotly import exceptions, files, session, tools, utils
from plotly.api import v1, v2
from plotly.plotly import chunked_requests
from plotly.grid_objs import Grid, Column
from plotly.dashboard_objs import dashboard_objs as dashboard
```
"""

my_pres = pres.Presentation(markdown_string)
pres_url_4 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_4)
https://plot.ly/~AdamKulidjian/3704/pres-with-code/
In [11]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_4 = url_to_iframe(pres_url_4, True)
IPython.display.HTML(iframe_4)
Out[11]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Style Your Presentation¶

The Presentations API currently has two styles to choose from: Martik and Moods. These themes are inspired by already existing PowerPoint Templates. Let's use the same markdown_string in the previous example but this time try the Martik style.

In [12]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'martik-style'
markdown_string = """
# Getting Started Using Code
A beginner's introduction to computer science.

---
# Python Functions
Functions are one of the most useful tools in Python. Intuitively, you select an input and get an output.

In order to set up a function use the key word "def" then the name of the function with open parentheses afterwards. Inside the parentheses, write variable names your function will use. These variables can then go into the body of your function and when you give a value to the variable in the call signature, it will pass through the guts of the function until it returns a value.

```python
def somePrintFunction():

    print("boo")

somePrintFunction()




>>>print(new_z)
10

def someAddFunction(a, b):

    print(a+b)




>>>someAddFunction(12,451)
463
```
---
# Use scala
You can write functions in other languages as well. For example, check out this scala code and notice how the print functions look different:

We write 'println()' as opposed to 'print()' as we do in Python.

```scala
/** Basic command line parsing. */
object Main {
  var verbose = false

  def main(args: Array[String]) {
    for (a <- args) a match {
      case "-h" | "-help"    =>
        println("Usage: scala Main [-help|-verbose]")
      case "-v" | "-verbose" =>
        verbose = true
      case x =>
        println("Unknown option: '" + x + "'")
    }
    if (verbose)
      println("How are you today?")
  }
}
```
---
# Under the Hood

There are many things to find when you look under the Plotly Hood. Of many things, one expected thing is the compliance and adherance to alphebetized and PEP-8'ed imports at the top of any module.

This is what the PEP-8 guide has more to say about Imports:

Wildcard imports (from <module> import *) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. There is one defensible use case for a wildcard import, which is to republish an internal interface as part of a public API (for example, overwriting a pure Python implementation of an interface with the definitions from an optional accelerator module and exactly which definitions will be overwritten isn't known in advance).

Image(https://help.plot.ly/images/dashboard-carousel.jpg)

```python
from __future__ import absolute_import

import copy
import json
import os
import time
import warnings
import webbrowser

import six
import six.moves
from requests.compat import json as _json

from plotly import exceptions, files, session, tools, utils
from plotly.api import v1, v2
from plotly.plotly import chunked_requests
from plotly.grid_objs import Grid, Column
from plotly.dashboard_objs import dashboard_objs as dashboard
```
"""

my_pres = pres.Presentation(markdown_string, style='martik')
pres_url_5 = py.presentation_ops.upload(my_pres, 'martik-style')

print(pres_url_5)
https://plot.ly/~AdamKulidjian/3707/martik-style/
In [13]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_5 = url_to_iframe(pres_url_5, True)
IPython.display.HTML(iframe_5)
Out[13]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Transitions¶

You can specify how your want your slides to transition to one another. Just like in the Plotly Presentation Application, there are 4 types of transitions: slide, zoom, fade and spin.

To apply any combination of these transition to a slide, just insert transitions at the top of the slide as follows:

transition: slide, zoom

Make sure that this line comes before any heading that you define in the slide, i.e. like this:

transition: slide, zoom
# slide title
In [14]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-transitions'
markdown_string = """
transition: slide
# slide
---
transition: zoom
# zoom
---
transition: fade
# fade
---
transition: spin
# spin
---
transition: spin and slide
# spin, slide
---
transition: fade zoom
# fade, zoom
---
transition: slide, zoom, fade, spin, spin, spin, zoom, fade
# slide, zoom, fade, spin

"""

my_pres = pres.Presentation(markdown_string, style='moods')
pres_url_6 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_6)
https://plot.ly/~AdamKulidjian/3708/pres-with-transitions/
In [15]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_6 = url_to_iframe(pres_url_6, True)
IPython.display.HTML(iframe_6)
Out[15]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Add Thin Border Around Text Boxes¶

Every slide has children, and each of these children have a style attribute. This style property is derived from the CSS element of the same name. Since you have the power of CSS to work with, you could customize text borders in your presentation if you want.

In [16]:
import plotly.plotly as py
import plotly.presentation_objs as pres

filename = 'pres-with-custom-css'
markdown_string = """
# custom css
---
transition: zoom, slide, spin, fade
# fun with css

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
```python
x = 4

if x < 2:
    x = 2 * x
    if x >= 2:
        break
```

"""

my_pres = pres.Presentation(markdown_string)

# change text border style
my_pres['presentation']['slides'][1]['children'][0]['props']['style']['border'] = 'solid red'

pres_url_7 = py.presentation_ops.upload(my_pres, filename)

print(pres_url_7)
https://plot.ly/~AdamKulidjian/3709/pres-with-custom-css/
In [17]:
import IPython

def url_to_iframe(url, text=True):
    html = ''
    # style
    html += '''<head>
    <style>
    div.textbox {
        margin: 30px;
        font-weight: bold;   
    }
    </style>
    </head>'
    '''
    # iframe
    html += '<iframe src=' + url + '.embed#{} width=750 height=400 frameBorder="0"></iframe>'
    if text:
        html += '''<body>
        <div class="textbox">
            <p>Click on the presentation above and use left/right arrow keys to flip through the slides.</p>
        </div>
        </body>
        '''
    return html

iframe_7 = url_to_iframe(pres_url_7, True)
IPython.display.HTML(iframe_7)
Out[17]:
'

Click on the presentation above and use left/right arrow keys to flip through the slides.

Reference¶

In [18]:
help(py.presentation_ops)
Help on class presentation_ops in module plotly.plotly.plotly:

class presentation_ops
 |  Interface to Plotly's Spectacle-Presentations API.
 |  
 |  Class methods defined here:
 |  
 |  upload(cls, presentation, filename, sharing='public', auto_open=True) from __builtin__.classobj
 |      Function for uploading presentations to Plotly.
 |      
 |      :param (dict) presentation: the JSON presentation to be uploaded. Use
 |          plotly.presentation_objs.Presentation to create presentations
 |          from a Markdown-like string.
 |      :param (str) filename: the name of the presentation to be saved in
 |          your Plotly account. Will overwrite a presentation of the same
 |          name if it already exists in your files.
 |      :param (str) sharing: can be set to either 'public', 'private'
 |          or 'secret'. If 'public', your presentation will be viewable by
 |          all other users. If 'private' only you can see your presentation.
 |          If it is set to 'secret', the url will be returned with a string
 |          of random characters appended to the url which is called a
 |          sharekey. The point of a sharekey is that it makes the url very
 |          hard to guess, but anyone with the url can view the presentation.
 |      :param (bool) auto_open: automatically opens the presentation in the
 |          browser.
 |      
 |      See the documentation online for examples.

Still need help?
Contact Us

For guaranteed 24 hour response turnarounds, upgrade to a Developer Support Plan.