Skip to content

Commit

Permalink
Updates to the getting started guide notebooks (#3279)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jlstevens @philippjfr
jlstevens authored and philippjfr committed Dec 14, 2018
1 parent b78116f commit b1e614b
Show file tree
Hide file tree
Showing 7 changed files with 187 additions and 155 deletions.
2 changes: 1 addition & 1 deletion doc/install.rst
View file
Expand Up @@ -53,7 +53,7 @@ for running unit tests, you can use::
Between releases, development snapshots are made available on conda and
can be installed using::

conda install -c ioam/label/dev holoviews
conda install -c pyviz/label/dev holoviews

To get the very latest development version using ``pip``, you can use::

Expand Down
41 changes: 22 additions & 19 deletions examples/getting_started/1-Introduction.ipynb
View file
Expand Up @@ -37,6 +37,7 @@
"import pandas as pd\n",
"import numpy as np\n",
"import holoviews as hv\n",
"from holoviews import opts\n",
"hv.extension('bokeh')"
]
},
Expand Down Expand Up @@ -91,7 +92,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Here we passed our dataframe to [``hv.Scatter``](../reference/elements/bokeh/Scatter.ipynb) to create an *object* called `scatter`, which is independent of any plotting library. HoloViews provides a wide range of Element types, all visible in the [Reference Gallery.](http://holoviews.org/reference/index.html)\n",
"Here we passed our dataframe to [``hv.Scatter``](../reference/elements/bokeh/Scatter.ipynb) to create an *object* called `scatter`, which is independent of any plotting library but here is visualized using bokeh. HoloViews provides a wide range of Element types, all visible in the [Reference Gallery.](http://holoviews.org/reference/index.html)\n",
"\n",
"In this example, `scatter` is a simple wrapper around our dataframe that knows that the 'services' column is the independent variable, normally plotted along the x-axis, and that the 'ridership' column is a dependent variable, plotted on the y-axis. These are our *dimensions* which we will describe in more detail a little later.\n",
"\n",
Expand Down Expand Up @@ -137,7 +138,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"In a single line using the ``+`` operator, we created a new, compositional object called a ``Layout`` built from our scatter visualizations and a ``Histogram`` that shows how many subway stations opened in Manhattan since 1900. Note that once again, all the plotting is happening behind the scenes. The ``layout`` is not a plot, it's a new object that exists independently of any given plotting system:"
"In a single line using the ``+`` operator, we created a new, compositional object called a ``Layout`` built from our scatter visualization and a ``Histogram`` that shows how many subway stations opened in Manhattan since 1900. Note that once again, all the plotting is happening behind the scenes. The ``layout`` is not a plot, it's a new object that exists independently of any given plotting system:"
]
},
{
Expand Down Expand Up @@ -183,7 +184,7 @@
"source": [
"## Compositional ``Overlays``\n",
"\n",
"Once again, we can easily visualize this data with HoloViews by passing our array to [``hv.Image``](../reference/elements/bokeh/Image.ipynb) to create the ``image`` object. This object has the spatial extent of the data declared as the ``bounds``, in terms of the corresponding range of latitudes and longitudes."
"Once again, we can easily visualize this data with HoloViews by passing our array to [``hv.Image``](../reference/elements/bokeh/Image.ipynb) to create an object named ``image``. This object has the spatial extent of the data declared as the ``bounds``, in terms of the corresponding range of latitudes and longitudes."
]
},
{
Expand All @@ -200,7 +201,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"HoloViews supports ``numpy``, ``xarray``, ``iris``, and ``dask`` arrays when working with array data (see [Gridded Datasets](../user_guide/Gridded_Datasets.ipynb)). We can also compose elements containing array data with those containing tabular data. To illustrate, let's pass our tabular station data to a [``Points``](../reference/elements/bokeh/Points.ipynb) element which is used to mark positions in two-dimensional space:"
"HoloViews supports ``numpy``, ``xarray``, and ``dask`` arrays when working with array data (see [Gridded Datasets](4-Gridded_Datasets.ipynb)). We can also compose elements containing array data with those containing tabular data. To illustrate, let's pass our tabular station data to a [``Points``](../reference/elements/bokeh/Points.ipynb) element, which is used to mark positions in two-dimensional space:"
]
},
{
Expand All @@ -218,7 +219,7 @@
"metadata": {},
"source": [
"\n",
"On the left, we have the visual representation of the ``image`` object we declared. Using ``+`` we put it into a ``Layout`` together with a new compositional object created with the ``*`` operator called an ``Overlay``. This particular overlay displays the station positions on top of our image which works correctly as both elements contain data that exist in the same space, namely New York City.\n",
"On the left, we have the visual representation of the ``image`` object we declared. Using ``+`` we put it into a ``Layout`` together with a new compositional object created with the ``*`` operator called an ``Overlay``. This particular overlay displays the station positions on top of our image, which works correctly because the data in both elements exists in the same space, namely New York City.\n",
"\n",
"This overlay on the right lets us see the location of all the subway stations in relation to our midnight taxi dropoffs. Of course, HoloViews allows you to visually express more of the available information with our points. For instance, you could represent the ridership of each subway by point color or point size. For more information see [Customizing Plots](../user_guide/03-Customizing_Plots.ipynb)."
]
Expand Down Expand Up @@ -247,7 +248,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This is yet another object which is rendered by the HoloViews plotting system with Bokeh behind the scenes:"
"This is yet another object that is rendered by the HoloViews plotting system with Bokeh behind the scenes:"
]
},
{
Expand All @@ -264,7 +265,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"As this a ``HoloMap`` is a container for our ``Image`` elements, we can use the methods it offers to return new containers. For instance, in the next cell we select three different hours of the morning from the ``HoloMap`` and display them as a ``Layout``:"
"As this ``HoloMap`` is a container for our ``Image`` elements, we can use the methods it offers to return new containers. For instance, in the next cell we select three different hours of the morning from the ``HoloMap`` and display them as a ``Layout``:"
]
},
{
Expand All @@ -280,9 +281,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Here the ``select`` method picks values from the specified 'Hour' dimension. The various Elements like ``Scatter`` and ``Image`` all accept two types of dimensions: *key dimensions* (i.e., indexing dimensions or independent variables), and *value dimensions* (resulting data or dependent variables). These attributes are named ``kdims`` and ``vdims``, respectively, and can be passed as the second and third positional argument for all Elements other than Histogram. As you can see above, the ``HoloMap`` of ``Image``s also has a ``kdims`` argument, allowing it to be indexed over those dimensions. The ``kdims`` and ``vdims`` accept either single dimensions or lists of dimensions, and let you express the space in which your data lives.\n",
"Here the ``select`` method picks values from the specified 'Hour' dimension. The various Elements like ``Scatter`` and ``Image`` all accept two types of dimensions: *key dimensions* (i.e., indexing dimensions or independent variables), and *value dimensions* (resulting data or dependent variables). These attributes are named ``kdims`` and ``vdims``, respectively, and can be passed as the second and third positional argument for all Elements other than Histogram. As you can see above, the ``HoloMap`` of ``Image``s also has a ``kdims`` argument, allowing it to be indexed over those dimensions. The ``kdims`` and ``vdims`` accept either single dimensions or lists of dimensions, and let you conveniently express the full space in which your data lives.\n",
"\n",
"Note how the ``Image`` elements where the holomap is constructed are declared using key dimensions of ``['lat','lon']`` which describes the fact that New York City is being viewed in terms of longitude and latitude. This semantic information is automatically mapped to our visualization by the HoloViews plotting system, which sets the x-axis and y-axis labels accordingly. In the case of the ``HoloMap`` we used a key dimension of ``'Hour'`` to declare that the interactive slider ranges over the hours of the day."
"Note how the ``Image`` elements where the holomap is constructed are declared using key dimensions of ``['lat','lon']``, which describes the fact that New York City is being viewed in terms of longitude and latitude. This semantic information is automatically mapped to our visualization by the HoloViews plotting system, which sets the x-axis and y-axis labels accordingly. In the case of the ``HoloMap`` we used a key dimension of ``'Hour'`` to declare that the interactive slider ranges over the hours of the day."
]
},
{
Expand All @@ -300,19 +301,21 @@
"metadata": {},
"outputs": [],
"source": [
"%%opts Image [xrotation=90] Points (color='deepskyblue' marker='v' size=6)\n",
"hotspot = points.select(lon=(-73.99, -73.96), lat=(40.75,40.765))\n",
"composition = holomap * hotspot\n",
"composition"
"\n",
"composition.opts(\n",
" opts.Image(xrotation=90),\n",
" opts.Points(color='deepskyblue', marker='v', size=6))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The line starting with ``%%opts`` used to specify the visual style is part of the HoloViews options system described in the next 'Getting started' section which also describes how to achieve the same effect with standard Python syntax.\n",
"The `.opts()` method call for specifying the visual style is part of the HoloViews options system, which is described in the next ['Getting started' section](2-Customization.ipynb).\n",
"\n",
"In the cell above we created and styled a composite object with a few short lines of code. Furthermore, this composite object relates tabular and array data and is immediately presented in a way that can be explored interactively. This way of working enables highly productive exploration, allowing new insights to be gained easily. For instance, after exploring with the slider we notice a hotspot of taxi dropoffs at 7am which we can select as follows:"
"In the cell above we created and styled a composite object with a few short lines of code. Furthermore, this composite object relates tabular and array data and is immediately presented in a way that can be explored interactively. This way of working enables highly productive exploration, allowing new insights to be gained easily. For instance, after exploring with the slider we notice a hotspot of taxi dropoffs at 7am, which we can select as follows:"
]
},
{
Expand All @@ -328,7 +331,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"We can now see that the slice of subway locations was chosen in relation to the hotspot in taxi dropoffs around 7am in the morning. This area of Manhattan just south of Central Park contains many popular tourist attractions, including Times Square, and we can infer that tourists often take short taxi rides from the subway stations into this area.\n",
"We can now see that the slice of subway locations was chosen in relation to the hotspot in taxi dropoffs around 7am in the morning. This area of Manhattan just south of Central Park contains many popular tourist attractions, including Times Square, and we can infer that tourists often take short taxi rides from the subway stations into this area. Notice how the customizations applied to this new plot, just as for the original one, which is only possible because of how HoloViews lets you capture the data and its attributes independently of any particular visualization.\n",
"\n",
"At this point it may appear that HoloViews is about easily generating explorative, interactive visualizations *from* your data. In fact, as we have been building these visualizations we have actually been working *with* our data, as we can show by examining the ``.data`` attribute of our sliced subway locations:"
]
Expand All @@ -355,7 +358,7 @@
"source": [
"## Saving and rendering objects\n",
"\n",
"HoloViews renders objects using a variety of backends making it easy to export plots to a variety of formats. The ``hv.save`` utility makes it trivial to save the rendered output of a HoloViews object to file, e.g. if we wanted to save the ``composition`` object from above (including the widgets) to a standalone HTML file, we would simply run:"
"HoloViews renders objects using a variety of backends, making it easy to export plots to a variety of formats. The ``hv.save`` utility makes it trivial to save the rendered output of a HoloViews object to a file. For instance, if we wanted to save the ``composition`` object from above (including the widgets) to a standalone HTML file, we would simply run:"
]
},
{
Expand All @@ -364,14 +367,14 @@
"metadata": {},
"outputs": [],
"source": [
"hv.save(composition, 'composition.html')"
"hv.save(composition, 'holomap.html')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If the necessary dependencies are installed this even allows saving bokeh plots to png:"
"Or to save a single frame with no widget:"
]
},
{
Expand All @@ -380,14 +383,14 @@
"metadata": {},
"outputs": [],
"source": [
"hv.save(composition.last, 'composition.png')"
"hv.save(composition.last, 'image.html')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"``hv.save`` defaults to the currently selected backend. As we will discover in the next section, the backend can be changed, allowing plots to be rendered to a wide range of data formats. To override the selected backend, simply supply ``backend='matplotlib'`` and you can render ``composition`` as a ``gif`` or ``mp4``)."
"``hv.save`` defaults to the currently selected backend, which can be overriden by adding an argument like ``backend='matplotlib'``. The Bokeh backend supports ``png`` output, and the Matplotlib backend supports ``png``, ``svg``, ``gif``, or ``mp4``, selected by using the appropriate extension instead of `.html`. In each case, rendering to a given format may require additional libraries to be installed."
]
},
{
Expand Down

0 comments on commit b1e614b

Please sign in to comment.