{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "#### Creating a Plotly Grid\n", "You can instantiate a grid with data by either uploading tabular data to Plotly or by creating a Plotly `grid` using the API. To upload the grid we will use `plotly.plotly.grid_ops.upload()`. It takes the following arguments:\n", "- `grid` (Grid Object): the actual grid object that you are uploading.\n", "- `filename` (str): name of the grid in your plotly account,\n", "- `world_readable` (bool): if `True`, the grid is `public` and can be viewed by anyone in your files. If `False`, it is private and can only be viewed by you.\n", "- `auto_open` (bool): if determines if the grid is opened in the browser or not.\n", "\n", "You can run `help(py.grid_ops.upload)` for a more detailed description of these and all the arguments." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "https://plotly.com/~PythonPlotBot/3534/\n" ] } ], "source": [ "import chart_studio\n", "import chart_studio.plotly as py\n", "import chart_studio.tools as tls\n", "import plotly.graph_objects as go\n", "from chart_studio.grid_objs import Column, Grid\n", "\n", "from datetime import datetime as dt\n", "import numpy as np\n", "from IPython.display import IFrame\n", "\n", "column_1 = Column(['a', 'b', 'c'], 'column 1')\n", "column_2 = Column([1, 2, 3], 'column 2') # Tabular data can be numbers, strings, or dates\n", "grid = Grid([column_1, column_2])\n", "url = py.grid_ops.upload(grid,\n", " filename='grid_ex_'+str(dt.now()),\n", " world_readable=True,\n", " auto_open=False)\n", "print(url)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### View and Share your Grid\n", "You can view your newly created grid at the `url`:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "IFrame(src= url.rstrip('/') + \".embed\", width=\"100%\",height=\"200px\", frameBorder=\"0\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You are also able to view the grid in your list of files inside your [organize folder](https://plotly.com/organize)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Upload Dataframes to Plotly\n", "Along with uploading a grid, you can upload a Dataframe as well as convert it to raw data as a grid:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import chart_studio.plotly as py\n", "import plotly.figure_factory as ff\n", "\n", "import pandas as pd\n", "\n", "df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_apple_stock.csv')\n", "df_head = df.head()\n", "table = ff.create_table(df_head)\n", "py.iplot(table, filename='dataframe_ex_preview')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Making Graphs from Grids\n", "Plotly graphs are usually described with data embedded in them. For example, here we place `x` and `y` data directly into our `Histogram2dContour` object:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "x = np.random.randn(1000)\n", "y = np.random.randn(1000) + 1\n", "\n", "data = [\n", " go.Histogram2dContour(\n", " x=x,\n", " y=y\n", " )\n", "]\n", "\n", "py.iplot(data, filename='Example 2D Histogram Contour')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can also create graphs based off of references to columns of grids. Here, we'll upload several `column`s to our Plotly account:" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "https://plotly.com/~PythonPlotBot/3537/\n" ] } ], "source": [ "column_1 = Column(np.random.randn(1000), 'column 1')\n", "column_2 = Column(np.random.randn(1000)+1, 'column 2')\n", "column_3 = Column(np.random.randn(1000)+2, 'column 3')\n", "column_4 = Column(np.random.randn(1000)+3, 'column 4')\n", "\n", "grid = Grid([column_1, column_2, column_3, column_4])\n", "url = py.grid_ops.upload(grid, filename='randn_int_offset_'+str(dt.now()))\n", "print(url)" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "IFrame(src= url.rstrip('/') + \".embed\", width=\"100%\",height=\"200px\", frameBorder=\"0\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Make Graph from Raw Data\n", "Instead of placing data into `x` and `y`, we'll place our Grid columns into `xsrc` and `ysrc`:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "data = [\n", " go.Histogram2dContour(\n", " xsrc=grid[0],\n", " ysrc=grid[1]\n", " )\n", "]\n", "\n", "py.iplot(data, filename='2D Contour from Grid Data')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "So, when you view the data, you'll see your original grid, not just the columns that compose this graph:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Attaching Meta Data to Grids\n", "In [Chart Studio Enterprise](https://plotly.com/product/enterprise/), you can upload and assign free-form JSON `metadata` to any grid object. This means that you can keep all of your raw data in one place, under one grid.\n", "\n", "If you update the original data source, in the workspace or with our API, all of the graphs that are sourced from it will be updated as well. You can make multiple graphs from a single Grid and you can make a graph from multiple grids. You can also add rows and columns to existing grids programatically." ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "https://plotly.com/~PythonPlotBot/3537/\n" ] } ], "source": [ "meta = {\n", " \"Month\": \"November\",\n", " \"Experiment ID\": \"d3kbd\",\n", " \"Operator\": \"James Murphy\",\n", " \"Initial Conditions\": {\n", " \"Voltage\": 5.5\n", " }\n", "}\n", "\n", "grid_url = py.grid_ops.upload(grid, filename='grid_with_metadata_'+str(dt.now()), meta=meta)\n", "print(url)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Reference" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on class grid_ops in module chart_studio.plotly.plotly:\n", "\n", "class grid_ops(builtins.object)\n", " | Interface to Plotly's Grid API.\n", " | Plotly Grids are Plotly's tabular data object, rendered\n", " | in an online spreadsheet. Plotly graphs can be made from\n", " | references of columns of Plotly grid objects. Free-form\n", " | JSON Metadata can be saved with Plotly grids.\n", " | \n", " | To create a Plotly grid in your Plotly account from Python,\n", " | see `grid_ops.upload`.\n", " | \n", " | To add rows or columns to an existing Plotly grid, see\n", " | `grid_ops.append_rows` and `grid_ops.append_columns`\n", " | respectively.\n", " | \n", " | To delete one of your grid objects, see `grid_ops.delete`.\n", " | \n", " | Class methods defined here:\n", " | \n", " | append_columns(columns, grid=None, grid_url=None) from builtins.type\n", " | Append columns to a Plotly grid.\n", " | \n", " | `columns` is an iterable of plotly.grid_objs.Column objects\n", " | and only one of `grid` and `grid_url` needs to specified.\n", " | \n", " | `grid` is a ploty.grid_objs.Grid object that has already been\n", " | uploaded to plotly with the grid_ops.upload method.\n", " | \n", " | `grid_url` is a unique URL of a `grid` in your plotly account.\n", " | \n", " | Usage example 1: Upload a grid to Plotly, and then append a column\n", " | ```\n", " | from plotly.grid_objs import Grid, Column\n", " | import plotly.plotly as py\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | grid = Grid([column_1])\n", " | py.grid_ops.upload(grid, 'time vs voltage')\n", " | \n", " | # append a column to the grid\n", " | column_2 = Column([4, 2, 5], 'voltage')\n", " | py.grid_ops.append_columns([column_2], grid=grid)\n", " | ```\n", " | \n", " | Usage example 2: Append a column to a grid that already exists on\n", " | Plotly\n", " | ```\n", " | from plotly.grid_objs import Grid, Column\n", " | import plotly.plotly as py\n", " | \n", " | grid_url = 'https://plotly.com/~chris/3143'\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | py.grid_ops.append_columns([column_1], grid_url=grid_url)\n", " | ```\n", " | \n", " | append_rows(rows, grid=None, grid_url=None) from builtins.type\n", " | Append rows to a Plotly grid.\n", " | \n", " | `rows` is an iterable of rows, where each row is a\n", " | list of numbers, strings, or dates. The number of items\n", " | in each row must be equal to the number of columns\n", " | in the grid. If appending rows to a grid with columns of\n", " | unequal length, Plotly will fill the columns with shorter\n", " | length with empty strings.\n", " | \n", " | Only one of `grid` and `grid_url` needs to specified.\n", " | \n", " | `grid` is a ploty.grid_objs.Grid object that has already been\n", " | uploaded to plotly with the grid_ops.upload method.\n", " | \n", " | `grid_url` is a unique URL of a `grid` in your plotly account.\n", " | \n", " | Usage example 1: Upload a grid to Plotly, and then append rows\n", " | ```\n", " | from plotly.grid_objs import Grid, Column\n", " | import plotly.plotly as py\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | column_2 = Column([5, 2, 7], 'voltage')\n", " | grid = Grid([column_1, column_2])\n", " | py.grid_ops.upload(grid, 'time vs voltage')\n", " | \n", " | # append a row to the grid\n", " | row = [1, 5]\n", " | py.grid_ops.append_rows([row], grid=grid)\n", " | ```\n", " | \n", " | Usage example 2: Append a row to a grid that already exists on Plotly\n", " | ```\n", " | from plotly.grid_objs import Grid\n", " | import plotly.plotly as py\n", " | \n", " | grid_url = 'https://plotly.com/~chris/3143'\n", " | \n", " | row = [1, 5]\n", " | py.grid_ops.append_rows([row], grid=grid_url)\n", " | ```\n", " | \n", " | delete(grid=None, grid_url=None) from builtins.type\n", " | Delete a grid from your Plotly account.\n", " | \n", " | Only one of `grid` or `grid_url` needs to be specified.\n", " | \n", " | `grid` is a plotly.grid_objs.Grid object that has already\n", " | been uploaded to Plotly.\n", " | \n", " | `grid_url` is the URL of the Plotly grid to delete\n", " | \n", " | Usage example 1: Upload a grid to plotly, then delete it\n", " | ```\n", " | from plotly.grid_objs import Grid, Column\n", " | import plotly.plotly as py\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | column_2 = Column([4, 2, 5], 'voltage')\n", " | grid = Grid([column_1, column_2])\n", " | py.grid_ops.upload(grid, 'time vs voltage')\n", " | \n", " | # now delete it, and free up that filename\n", " | py.grid_ops.delete(grid)\n", " | ```\n", " | \n", " | Usage example 2: Delete a plotly grid by url\n", " | ```\n", " | import plotly.plotly as py\n", " | \n", " | grid_url = 'https://plotly.com/~chris/3'\n", " | py.grid_ops.delete(grid_url=grid_url)\n", " | ```\n", " | \n", " | upload(grid, filename=None, world_readable=True, auto_open=True, meta=None) from builtins.type\n", " | Upload a grid to your Plotly account with the specified filename.\n", " | \n", " | Positional arguments:\n", " | - grid: A plotly.grid_objs.Grid object,\n", " | call `help(plotly.grid_ops.Grid)` for more info.\n", " | - filename: Name of the grid to be saved in your Plotly account.\n", " | To save a grid in a folder in your Plotly account,\n", " | separate specify a filename with folders and filename\n", " | separated by backslashes (`/`).\n", " | If a grid, plot, or folder already exists with the same\n", " | filename, a `plotly.exceptions.RequestError` will be\n", " | thrown with status_code 409. If filename is None,\n", " | and randomly generated filename will be used.\n", " | \n", " | Optional keyword arguments:\n", " | - world_readable (default=True): make this grid publically (True)\n", " | or privately (False) viewable.\n", " | - auto_open (default=True): Automatically open this grid in\n", " | the browser (True)\n", " | - meta (default=None): Optional Metadata to associate with\n", " | this grid.\n", " | Metadata is any arbitrary\n", " | JSON-encodable object, for example:\n", " | `{\"experiment name\": \"GaAs\"}`\n", " | \n", " | Filenames must be unique. To overwrite a grid with the same filename,\n", " | you'll first have to delete the grid with the blocking name. See\n", " | `plotly.plotly.grid_ops.delete`.\n", " | \n", " | Usage example 1: Upload a plotly grid\n", " | ```\n", " | from plotly.grid_objs import Grid, Column\n", " | import plotly.plotly as py\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | column_2 = Column([4, 2, 5], 'voltage')\n", " | grid = Grid([column_1, column_2])\n", " | py.grid_ops.upload(grid, 'time vs voltage')\n", " | ```\n", " | \n", " | Usage example 2: Make a graph based with data that is sourced\n", " | from a newly uploaded Plotly grid\n", " | ```\n", " | import plotly.plotly as py\n", " | from plotly.grid_objs import Grid, Column\n", " | from plotly.graph_objs import Scatter\n", " | # Upload a grid\n", " | column_1 = Column([1, 2, 3], 'time')\n", " | column_2 = Column([4, 2, 5], 'voltage')\n", " | grid = Grid([column_1, column_2])\n", " | py.grid_ops.upload(grid, 'time vs voltage')\n", " | \n", " | # Build a Plotly graph object sourced from the\n", " | # grid's columns\n", " | trace = Scatter(xsrc=grid[0], ysrc=grid[1])\n", " | py.plot([trace], filename='graph from grid')\n", " | ```\n", " | \n", " | ----------------------------------------------------------------------\n", " | Static methods defined here:\n", " | \n", " | ensure_uploaded(fid)\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.grid_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 upload data to Plotly from Python with the Plotly Grid API.", "display_as": "chart_studio", "has_thumbnail": true, "language": "python", "layout": "base", "name": "Plots from Grids", "order": 5, "page_type": "u-guide", "permalink": "python/data-api/", "thumbnail": "thumbnail/table.jpg", "title": "Plotly Data API", "v4upgrade": true } }, "nbformat": 4, "nbformat_minor": 2 }