{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "#### Plotly Presentations\n", "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()`.\n", "\n", "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:\n", "\n", "`# slide title`\n", "\n", "Anything that comes after the title will be put as text in your slide. Check out the example below to see this in action." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Current Limitations\n", "`Boldface`, _italics_ and [hypertext](https://www.w3.org/WhatIs.html) are not supported features of the Presentation API." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Display in Jupyter\n", "The function below generates HTML code to display the presentation in an iframe directly in Jupyter." ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [], "source": [ "def url_to_iframe(url, text=True):\n", " html = ''\n", " # style\n", " html += '''\n", " \n", " '\n", " '''\n", " # iframe\n", " html += ''\n", " if text:\n", " html += '''\n", "
\n", "

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

\n", "
\n", " \n", " '''\n", " return html" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Simple Example" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [], "source": [ "import chart_studio.plotly as py\n", "import chart_studio.presentation_objs as pres\n", "\n", "filename = 'simple-pres'\n", "markdown_string = \"\"\"\n", "# slide 1\n", "There is only one slide.\n", "\n", "---\n", "# slide 2\n", "Again, another slide on this page.\n", "\n", "\"\"\"\n", "\n", "my_pres = pres.Presentation(markdown_string)\n", "pres_url_0 = py.presentation_ops.upload(my_pres, filename)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "https://plotly.com/~AdamKulidjian/3700/simple-pres/" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " '\n", " \n", "
\n", "

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

\n", "
\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import IPython\n", "\n", "iframe_0 = url_to_iframe(pres_url_0, True)\n", "IPython.display.HTML(iframe_0)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Insert Plotly Chart\n", "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:\n", "\n", "`Plotly(url)`\n", "\n", "where url is a Plotly url. For example:\n", "\n", "`Plotly(https://plotly.com/~AdamKulidjian/3564)`\n", "\n", "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.\n", "\n", "`Useful Tip`:
\n", "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." ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [], "source": [ "import chart_studio.plotly as py\n", "import chart_studio.presentation_objs as pres\n", "\n", "filename = 'pres-with-plotly-chart'\n", "markdown_string = \"\"\"\n", "# 3D scatterplots\n", "3D Scatterplot are just a collection of balls in a 3D cartesian space each of which have assigned properties like color, size, and more.\n", "\n", "---\n", "# simple 3d scatterplot\n", "\n", "Plotly(https://plotly.com/~AdamKulidjian/3698)\n", "---\n", "# different colorscales\n", "\n", "There are various colorscales and colorschemes to try in Plotly. Check out plotly.colors to find a list of valid and available colorscales.\n", "\n", "Plotly(https://plotly.com/~AdamKulidjian/3582)\n", "Plotly(https://plotly.com/~AdamKulidjian/3698)\n", "\"\"\"\n", "\n", "my_pres = pres.Presentation(markdown_string)\n", "pres_url_1 = py.presentation_ops.upload(my_pres, filename)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "https://plotly.com/~AdamKulidjian/3710/pres-with-plotly-chart/" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " '\n", " \n", "
\n", "

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

\n", "
\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import IPython\n", "\n", "iframe_1 = url_to_iframe(pres_url_1, True)\n", "IPython.display.HTML(iframe_1)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Insert Web Images\n", "To insert an image from the web, insert the a `Image(url)` where url is the image url." ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [], "source": [ "import chart_studio.plotly as py\n", "import chart_studio.presentation_objs as pres\n", "\n", "filename = 'pres-with-images'\n", "markdown_string = \"\"\"\n", "# Animals of the Wild\n", "---\n", "# The Lion\n", "\n", "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.\n", "\n", "Image(https://i.pinimg.com/736x/da/af/73/daaf73960eb5a21d6bca748195f12052--lion-photography-lion-kings.jpg)\n", "---\n", "# The Giraffe\n", "\n", "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.\n", "\n", "Image(https://img.purch.com/w/192/aHR0cDovL3d3dy5saXZlc2NpZW5jZS5jb20vaW1hZ2VzL2kvMDAwLzA2OC8wOTQvaTMwMC9naXJhZmZlLmpwZz8xNDA1MDA4NDQy)\n", "Image(https://upload.wikimedia.org/wikipedia/commons/9/9f/Giraffe_standing.jpg)\n", "\n", "\"\"\"\n", "\n", "my_pres = pres.Presentation(markdown_string)\n", "pres_url_2 = py.presentation_ops.upload(my_pres, filename)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "https://plotly.com/~AdamKulidjian/3702/pres-with-images/" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " '\n", " \n", "
\n", "

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

\n", "
\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 18, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import IPython\n", "\n", "iframe_2 = url_to_iframe(pres_url_2, True)\n", "IPython.display.HTML(iframe_2)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Image Stretch\n", "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." ] }, { "cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [], "source": [ "import chart_studio.plotly as py\n", "import chart_studio.presentation_objs as pres\n", "\n", "filename = 'pres-with-no-imgstretch'\n", "markdown_string = \"\"\"\n", "# images in native aspect ratio\n", "\n", "Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)\n", "Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)\n", "Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)\n", "Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)\n", "Image(https://raw.githubusercontent.com/jackparmer/gradient-backgrounds/master/moods1.png)\n", "\"\"\"\n", "\n", "my_pres = pres.Presentation(markdown_string, imgStretch=False)\n", "pres_url_3 = py.presentation_ops.upload(my_pres, filename)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "https://plotly.com/~AdamKulidjian/3703/pres-with-no-imgstretch/" ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " '\n", " " ], "text/plain": [ "" ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import IPython\n", "\n", "iframe_3 = url_to_iframe(pres_url_3, False)\n", "IPython.display.HTML(iframe_3)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Transitions\n", "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`.\n", "\n", "To apply any combination of these transition to a slide, just insert transitions at the top of the slide as follows:\n", "\n", "`transition: slide, zoom`\n", "\n", "Make sure that this line comes before any heading that you define in the slide, i.e. like this:\n", "\n", "```\n", "transition: slide, zoom\n", "# slide title\n", "```" ] }, { "cell_type": "code", "execution_count": 21, "metadata": {}, "outputs": [], "source": [ "import chart_studio.plotly as py\n", "import chart_studio.presentation_objs as pres\n", "\n", "filename = 'pres-with-transitions'\n", "markdown_string = \"\"\"\n", "transition: slide\n", "# slide\n", "---\n", "transition: zoom\n", "# zoom\n", "---\n", "transition: fade\n", "# fade\n", "---\n", "transition: spin\n", "# spin\n", "---\n", "transition: spin and slide\n", "# spin, slide\n", "---\n", "transition: fade zoom\n", "# fade, zoom\n", "---\n", "transition: slide, zoom, fade, spin, spin, spin, zoom, fade\n", "# slide, zoom, fade, spin\n", "\n", "\"\"\"\n", "\n", "my_pres = pres.Presentation(markdown_string, style='moods')\n", "pres_url_6 = py.presentation_ops.upload(my_pres, filename)" ] }, { "cell_type": "code", "execution_count": 22, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " '\n", " \n", "
\n", "

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

\n", "
\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 22, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import IPython\n", "\n", "iframe_6 = url_to_iframe(pres_url_6, True)\n", "IPython.display.HTML(iframe_6)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Reference" ] }, { "cell_type": "code", "execution_count": 23, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on class presentation_ops in module chart_studio.plotly.plotly:\n", "\n", "class presentation_ops(builtins.object)\n", " | Interface to Plotly's Spectacle-Presentations API.\n", " | \n", " | Class methods defined here:\n", " | \n", " | upload(presentation, filename, sharing='public', auto_open=True) from builtins.type\n", " | Function for uploading presentations to Plotly.\n", " | \n", " | :param (dict) presentation: the JSON presentation to be uploaded. Use\n", " | plotly.presentation_objs.Presentation to create presentations\n", " | from a Markdown-like string.\n", " | :param (str) filename: the name of the presentation to be saved in\n", " | your Plotly account. Will overwrite a presentation of the same\n", " | name if it already exists in your files.\n", " | :param (str) sharing: can be set to either 'public', 'private'\n", " | or 'secret'. If 'public', your presentation will be viewable by\n", " | all other users. If 'private' only you can see your presentation.\n", " | If it is set to 'secret', the url will be returned with a string\n", " | of random characters appended to the url which is called a\n", " | sharekey. The point of a sharekey is that it makes the url very\n", " | hard to guess, but anyone with the url can view the presentation.\n", " | :param (bool) auto_open: automatically opens the presentation in the\n", " | browser.\n", " | \n", " | See the documentation online for examples.\n", " | \n", " | ----------------------------------------------------------------------\n", " | Data descriptors defined here:\n", " | \n", " | __dict__\n", " | dictionary for instance variables (if defined)\n", " | \n", " | __weakref__\n", " | list of weak references to the object (if defined)\n", "\n" ] } ], "source": [ "help(py.presentation_ops)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "jupytext": { "notebook_metadata_filter": "all", "text_representation": { "extension": ".md", "format_name": "markdown", "format_version": "1.1", "jupytext_version": "1.1.7" } }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.5" }, "plotly": { "description": "How to create and publish a spectacle-presentation with the Python API.", "display_as": "chart_studio", "has_thumbnail": true, "language": "python", "layout": "base", "name": "Presentations Tool", "order": 0.6, "page_type": "u-guide", "permalink": "python/presentations-tool/", "thumbnail": "thumbnail/pres_api.jpg", "title": "Presentations Tool | plotly", "v4upgrade": true } }, "nbformat": 4, "nbformat_minor": 2 }