Skip to content
Permalink
Browse files

Minor updates to text

  • Loading branch information
jbednar committed Apr 14, 2017
1 parent 4fbd5ac commit edb172ec727d32c29bbeb9bb2b8a8858b4d5e4a9
Showing with 6 additions and 6 deletions.
  1. +6 −6 doc/Tutorials/Rich_Display.ipynb
@@ -83,7 +83,7 @@
"\n",
"What if the relevant aspects of that domain knowledge could be captured directly, making it possible to fully automate the subsequent process of turning the data + domain knowledge into a visible plot? If that automation could be achieved, we could have a natural, effortlessly visible representation for complex data, just as Python already automatically reveals small data structures consisting of scalar and string data. \n",
"\n",
"As you will see in the sections below, HoloViews is designed to allow precisely that sort of automation, by letting the user couple arbitrarily complex datasets (including NumPy arrays, xarray n-dimensional arrays, and Pandas or Dask dataframes) with a small amount of semantic metadata (hints) about what that data represents. If you then refer to the resulting object at a Jupyter notebook prompt, HoloViews will automatically run suitable plotting commands to render it, with the results revealed interactively using [IPython's rich display support](http://nbviewer.jupyter.org/github/ipython/ipython/blob/2.x/examples/Notebook/Custom%20Display%20Logic.ipynb). \n",
"As you will see in the sections below, HoloViews is designed to allow precisely that sort of automation, by letting the user couple arbitrarily complex datasets with a small amount of semantic metadata (hints) about what that data represents. Supported datatypes include Python data structures and any combination of NumPy or xarray n-dimensional arrays and Pandas or Dask columnar dataframes. If you then refer to the resulting object at a Jupyter notebook prompt, HoloViews will automatically run suitable plotting commands to render it, with the results revealed interactively using [IPython's rich display support](http://nbviewer.jupyter.org/github/ipython/ipython/blob/2.x/examples/Notebook/Custom%20Display%20Logic.ipynb). \n",
"\n",
"For instance, after capturing the relevant metadata about the ``s`` array above using the declarative ``Image`` object from HoloViews, the array can be visualized just by referring to it, as easily as if it were a number or a string:"
]
@@ -141,7 +141,7 @@
"source": [
"Because HoloViews knows that the ``sines`` object represents a continuous 2D surface, it can automatically deduce that a sample along one axis will be a continuous function of one dimension, i.e., an ``hv.Curve`` object (in **B** above). Because the bounds were declared, HoloViews can find the corresponding row of the ``s`` matrix that represents ``y=1.5`` to get the data for the curve. Which row in that matrix corresponds to ``y=1.5`` isn't encoded in the original ``s`` array, but it is easily computed from the declarations in ``sines``. HoloViews then automatically labels the vertical dimension of the curve as ``z``, because that is the default name for the value dimension in ``sines``. Other semantic declarations like custom dimension names and units will also propagate automatically where appropriate.\n",
"\n",
"In **A** we have also overlaid a horizontal line on the ``sines`` object using the ``*`` (``Overlay``) operator, and the resulting overlay is then laid out next to the sample curve using the ``+`` (``Layout``) operator. When typed at the prompt, the combined result is then effortlessly displayed as a figure with plots as subfigures, but it is still just data. The composite ``layout`` object reflects the relationships that these data items have to one another, allowing them to be grouped together, just as the small tuple of data ``g`` above is a composite object that expresses that there is a relationship between that set of Python literals.\n",
"In **A** we have also overlaid a horizontal line on the ``sines`` object using the ``*`` (``Overlay``) operator, and the resulting overlay is then laid out next to the sample curve using the ``+`` (``Layout``) operator. When typed at the prompt, the combined result is then effortlessly displayed as a figure with plots as subfigures, but it is still just data. The composite ``layout`` object reflects the relationships that these data items have to one another, allowing them to be grouped together, just as the small tuple of data ``g`` above is a composite object that expresses a relationship between that set of Python literals.\n",
"\n",
"The metadata in ``sines`` makes it simple to explore the properties of this data interactively:"
]
@@ -225,7 +225,7 @@
"\n",
"Behind the scenes, HoloViews will use the excellent lower-level Matplotlib or Bokeh packages to render the images or make an interactive web page. Rather than trying to replace these plotting libraries, HoloViews is a set of tools for working with complex datasets, annotating your data with just enough metadata to make it instantly visualizable. Of course, all the real work is done by the underlying plotting libraries, with HoloViews plotting backends making it possible for you to avoid worrying about all those details in day-to-day work.\n",
"\n",
"The key point is that unlike what you get when working with plotting libraries directly, the plots above are just the *representation* of your data, rendered into a figure only at the instant when your data needs to be displayed. The declarative HoloViews view objects are what you would keep, preserve, and modify over time, not the disposable and discardable plot (just as no one would curate the specific pixels representing 2.0 above, because they know they can always effortlessly regenerate them when needed), and not just the raw data alone (which doesn't capture enough of the domain knowledge to be interpretable directly). If you had built a plot directly using the underlying plotting program, then each time you wanted to do the above operations (sampling, slicing, faceting, animating, etc.), you would need to recapitulate all of the semantic metadata into the options for this new plot, which is time consuming, error prone, and would generate large amounts of domain-specific code that you would then need to maintain.\n",
"The key point is that unlike what you get when working with plotting libraries directly, the plots above are just the *representation* of your data, with a backend-specific figure object and eventual rendering as pixels or HTML created only at the instant when your data needs to be displayed. The declarative HoloViews view objects wrapping your data are what you would keep, preserve, and modify over time, not the disposable and discardable visible plot. No one would curate the specific pixels representing 2.0 above, because they know they can always effortlessly regenerate them when needed, and just storing the raw data alone isn't sufficient either, because it doesn't capture enough of the domain knowledge to be interpretable directly. If instead of using HoloViews you had built a plot directly using the underlying plotting program, then each time you wanted to do the above operations (sampling, slicing, faceting, animating, etc.), you would need to recapitulate all of the semantic metadata into the options for this new plot, which is time consuming, error prone, and would generate large amounts of domain-specific code that you would then need to maintain.\n",
"\n",
"Of course, the default settings used above are sufficient to generate *a* plot, but they may not generate precisely the plot you might want. In that case, you can give hints to the underlying plotting libraries about how you want to display this data, without complicating your actual data objects:"
]
@@ -245,7 +245,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Such [options](http://holoviews.org/Tutorials/Options.html) can be specified per type, per label, per group, per cell, per notebook, and/or per user account, so there should be a way to express plotting preferences without having to complicate the data itself.\n",
"Such options can be specified per type, per label, per group, per cell, per notebook, and/or per user account, so there should be a way to express plotting preferences without having to complicate the data itself. Here they are expressed using a special concise IPython syntax, but [options](http://holoviews.org/Tutorials/Options.html) can also be specified using (somewhat more verbose) Python syntax if preferred.\n",
"\n",
"Hopefully now you can see how HoloViews fits into a science, engineering, data-analysis, or data-science workflow: it helps you collect your data and capture what you know about its semantic properties at a high level, doing it once per type of data rather than again every time you need a different type of plot. HoloViews then aims to keep you working at that high (semantic) level as much as possible, while also giving you access to the low-level details of your data and its visual representation when you need them. \n",
"\n",
@@ -284,7 +284,7 @@
"Apart from this information, you also need some code:\n",
"- **make_obj()**: Construct a Python object holding the data and metadata (i.e., the Python integer 2, not just the bare bit pattern for 2)\n",
"- **make_str()**: Use the resulting obj and the str-options to create a string representation for the obj, which in Python is orchestrated by the integer ``__str__`` method. \n",
"- **render()**: Using code in your terminal program, OS, or web browser for taking a string and some rendering_options, turning it into visible pixels.\n",
"- **render()**: Using code in your terminal program, OS, or web browser for taking a string and some rendering_options, turn it into visible pixels.\n",
"\n",
"So the whole sequence of steps from constructing a Python scalar to seeing the result at the Python prompt will end up evaluating code like:\n",
"\n",
@@ -373,7 +373,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"If you use Jupyter, the only code bit you need to worry about is `make_obj`, where you attach the metadata to the data. The rest of the code should all be invoked for you at the right times automatically. If you don't use Jupyter, e.g. in an automated workflow, you can invoke each part separately if you like, as shown here, but even then you can usually let the renderer's `save` method look everything up as needed (as shown [here](https://github.com/ioam/holoviews-contrib/blob/master/scripts/matplotlib_export.py)).\n",
"If you use Jupyter, the only code bit you need to worry about is `make_obj` (the constructor for each HoloViews object), which is where you attach the metadata to the data. The rest of the code should all be invoked for you at the right times automatically. If you don't use Jupyter, e.g. in an automated workflow, you can invoke each part separately if you like, as shown above, but even then you can usually let the renderer's `save` method look everything up as needed (as shown [here](https://github.com/ioam/holoviews-contrib/blob/master/scripts/matplotlib_export.py)).\n",
"\n",
"However you invoke these commands, each of these categories of data, metadata, and options will be available to you for controlling what you want to see and how you would like to see it, while keeping your semantic information (data, metadata) clearly separated from the incidental display details.\n",
"\n",

0 comments on commit edb172e

Please sign in to comment.
You can’t perform that action at this time.