Upload 52 files

hvplot_docs/01-Annotating_Data.md

@@ -0,0 +1,135 @@
+# Annotating Your Data
+
+
+```python
+import holoviews as hv
+hv.extension('bokeh')
+```
+
+As introduced in the [Getting Started guide](../getting_started/1-Introduction.ipynb), HoloViews relies heavily on semantic *annotations*, i.e., metadata you declare that lets HoloViews interpret what your data represents.  With these annotations, HoloViews can perform complex tasks like visualization automatically.
+
+There are three main kinds of annotation that can be associated with each element:
+  1. **Type**, used to declare the sort of data you have, which is required before it can be visualized,
+  2. **Dimensions**, used to specify the abstract space in which the data resides, allowing axis labeling and indexing, and
+  3. **Group/Label**, used to declare a meaningful category and human-readable description of the element, allowing plot labeling and selecting related sets of elements.
+
+This user guide explains each of these three types of annotation, describing why you would need or want to use them. 
+
+## 1. Specifying element type
+
+Basic Python data structures like dataframes, arrays, lists, and dictionaries can be used to represent an infinite variety of different types of data, and thus they cannot be visualized as any particular type of graphical representation without some additional information from the user that says what sort of data it is meant to be.  The user can declare this information by selecting a suitable HoloViews element type from the many different ones available (see the [Reference Gallery](http://holoviews.org/reference/index.html)).  
+
+For instance, let's say you have two lists of numbers:
+
+
+```python
+xs = range(-10,11)
+ys = [100-x**2 for x in xs]
+```
+
+As far as Python is concerned, ``xs`` and ``ys`` are just two arbitrary lists, which could represent nearly anything imaginable. But we as humans can see that each of the ``ys`` is a value computed from one of the ``xs`` by evaluating the function $y=100-x^2$.  We can convey some of that information to HoloViews by choosing a ``Curve`` element type, which is a convenient shorthand for "a discrete set of real-valued samples from a continuous function of one real-valued variable":
+
+
+```python
+curve = hv.Curve((xs, ys))
+curve
+```
+
+As you can see, declaring the element type is the only *required* bit of annotation, instantly making your data visualizable.  However, this initial visualization relies on various defaults that may not be appropriate for your data, and you can override these defaults by declaring additional annotations as described below.
+
+## 2. Specifying element dimensionality
+
+Each element type can process a certain number and type of *dimensions*, i.e., ways in which the data can vary.  For instance, the ``Curve`` object above has two dimensions, $x$ and $y$. If you look at how we generated the data, you can see that these two dimensions are semantically different -- we chose an arbitrary set of values for the ``xs``, and then calculated a corresponding value to make each of the ``ys``.  In mathematical terms, $x$ is thus an independent variable (selected by the creator of the data), and $y$ is a dependent variable (typically measured or calculated from the independent variable(s)).
+
+HoloViews elements call these two different types of variables *key dimensions* (``kdims``) and *value dimensions* (``vdims``). The *key dimensions* are the dimensions you can index *by* to get the values corresponding to the *value* dimensions. You can learn more about indexing data in the later [Indexing and Selecting Data](./10-Indexing_and_Selecting_Data.ipynb) user guide.
+
+Different elements have different numbers of required key dimensions and value dimensions. For instance, a ``Curve`` always has one key dimension and one value dimension. As we did not explicitly specify anything regarding dimensions when declaring the curve above, the ``kdims`` and ``vidms`` use their default names 'x' and 'y':
+
+
+```python
+"Object 'curve' has kdims {kdims} and vdims {vdims}".format(kdims=curve.kdims, vdims=curve.vdims)
+```
+
+The easiest way to override the default dimension names is to provide strings for the dimensions, where the second argument in the Element constructor will always be the ``kdims``, and the third will always be the ``vdims``:
+
+
+```python
+trajectory = hv.Curve((xs, ys), 'distance', 'height')
+trajectory
+```
+
+
+```python
+"Object 'trajectory' has kdims {kdims} and vdims {vdims} ".format(kdims=trajectory.kdims, vdims=trajectory.vdims)
+```
+
+We can see that the strings we provided have been  'promoted' to dimension objects.  The ``kdims`` and ``vdims`` *always* contain instances of the ``Dimension`` class, described in the following section.  Here, the immediate effect is to use the new names for the displayed axis labels.
+
+### Dimension parameters
+
+``Dimensions`` are not just names, they are rich objects with numerous parameters that can be used to describe the space in which the data resides. Only two of these are considered *core* parameters that uniquely identify the dimension object; the rest are auxiliary metadata. The most important parameters are:
+
+<br>
+<dl class="dl-horizontal">
+  <dt>name</dt><dd>(core) A concise name for the dimension, which for convenient usage as a keyword argument should usually be a legal Python identifier.</dd>
+  <dt>label <dd>(core) A optional longer description of the dimension, which is convenient if you want the displayed label to contain arbitrary spaces, symbols, or unicode.</dd>
+  <dt>range <dd>The minimum and maximum allowable values for the dimension, for error checking and generating widgets when needed.</dd>
+  <dt>soft_range <dd>Suggested minimum and maximum values within the allowed range, used to specify a useful portion of the range for widgets and animations.</dd>
+  <dt>step <dd>Suggested interval for sampling a continuous range, if needed for a widget or animation.</dd>
+  <dt>unit <dd>The name of the unit to be associated with the dimension, if any, for labelling.</dd>
+  <dt>values <dd>Explicit list of allowed dimension values, for error checking, widgets, and animations.</dd>
+</dl>
+
+
+For the full list of parameters, you can call ``hv.help(hv.Dimension)``.
+
+Similar to how you can just use a string if all you want to specify is the name, you can provide a ``(name,label)`` tuple if you want to specify the ``name`` and the ``label`` to ``kdims`` and ``vdims`` without building an explicit ``Dimension``:
+
+
+```python
+wo_unit = hv.Curve((xs, ys), 
+                   ('distance','Horizontal distance'), 
+                   ('height','Height above sea level'))
+
+distance = hv.Dimension('distance', label='Horizontal distance', unit='m')
+height = hv.Dimension(('height','Height above sea level'), unit='m')
+with_unit = hv.Curve((xs, ys), distance, height)
+
+# (using + to compose elements is described in the next guide)
+wo_unit + with_unit
+```
+
+Note that after supplying the longer labels, you can still use the short name to specify the dimension in keyword arguments. For instance, try using ``with_unit.select(distance=(5,8))`` in the cell above.
+
+### Setting properties with redim
+
+Declaring dimension objects with appropriate parameters can be awkward and verbose if you only want to set a few specific parameters. You can often avoid declaring explicit dimension objects using the ``redim`` method, which returns a *clone* of the element: the same data, wrapped in a new instance of the same element type with the new dimension settings.
+
+Let's use ``redim`` to swap out the 'height' dimension for an 'altitude' dimension:
+
+
+```python
+renamed_height = trajectory.redim(height='altitude')
+renamed_height
+```
+
+The ``redim`` "method" is actually a utility that can be used to set any of the dimension parameters, such as the label, unit, range, or values.  For instance, the label can be updated on an existing object by specifying the dimension name and then the new value for that parameter:
+
+
+```python
+renamed_height.redim.label(altitude='Altitude above sea-level', distance='Horizontal distance')
+```
+
+## 3. Organizing your elements with groups and labels
+
+A complex visualization you build with HoloViews may include many instances of the same element type, each built from different bits of data and potentially representing categorically distinct types of information to you.  To help you keep track of these distinctions when you need to, HoloViews provides a ``group`` parameter you can use to declare semantically distinct categories for elements, and a ``label`` parameter you can use to identify which specific item the element represents within that category:
+
+
+```python
+low_ys = [25-(0.5*el)**2 for el in xs]
+shallow = hv.Curve((xs, low_ys), group='Trajectory', label='Shallow')
+medium = hv.Curve((xs, ys), group='Trajectory', label='Medium')
+shallow + medium
+```
+
+As you can see, the ``group`` and ``label`` information will be used to generate sensible titles, here indicating that both sets of data represent trajectories, and that there are two different specific trajectories being shown.  Once the group and/or label have been specified, they can be used for [Applying Customization](./03-Applying_Customizations.ipynb) (e.g. to make all trajectories have the same line width and style, or to customize one particular plot out of many of the same type).  The group and label are also used for indexing, as we will see in the following [Composing_Elements](./02-Composing_Elements.ipynb) guide.

hvplot_docs/05-Dimensioned_Containers.md

@@ -0,0 +1,162 @@
+# Dimensioned Containers
+
+So far we've seen how to [wrap data in elements](./01-Annotating_Data.ipynb) and [compose](./02-Composing_Elements.ipynb) those Elements into Overlays and Layout. In this guide will see how we can use containers to hold Elements and declare parameter spaces to explore multi-dimensional parameter spaces visually. These containers allow faceting your data by one or more variables and exploring the resulting parameter space with widgets, positioning plots on a grid or simply laying them out consecutively.  Here we will introduce the ``HoloMap``, ``NdOverlay``, ``NdLayout`` and ``GridSpace``, which make all this possible.
+
+
+```python
+import numpy as np
+import holoviews as hv
+
+from holoviews import opts
+
+hv.extension('bokeh')
+
+opts.defaults(opts.Curve(line_width=1))
+```
+
+### Declaring n-dimensional collections
+
+Python users will be familiar with dictionaries as a way to collect data together in a conveniently accessible manner. Unlike NumPy arrays, dictionaries are sparse and do not have to be declared with a fixed size. The dimensioned types are therefore closely modeled on dictionaries but support n-dimensional keys.
+
+Therefore they allow you to express a mapping between a multi-variable key and other viewable objects, letting you structure your multi-dimensional data to facilitate exploration. The key here can represent anything from an ID, a filename, a parameter controlling some custom processing to some category representing a subset of your data.
+
+As a simple example we will use a function which varies with multiple parameters, in this case a function which generates a simple frequency modulation signal, with two main parameters a carrier frequency and a modulation frequency (see [Wikipedia](https://en.wikipedia.org/wiki/Frequency_modulation)). All we have to know here is that the function generates a ``Curve`` based on the parameters that we give it.
+
+
+```python
+def fm_modulation(f_carrier=220, f_mod=220, mod_index=1, length=0.1, sampleRate=2000):
+    sampleInc = 1.0/sampleRate
+    x = np.arange(0,length, sampleInc)
+    y = np.sin(2*np.pi*f_carrier*x + mod_index*np.sin(2*np.pi*f_mod*x))
+    return hv.Curve((x, y), 'Time', 'Amplitude')
+```
+
+Next we have to declare the parameter space we want to explore. Combinatorial parameter spaces can quickly get very large so here we will declare just 5 carrier frequencies and 5 modulation frequencies. If we have many more parameters or a larger set of values we could instead use a ``DynamicMap``, which does lazy evaluation and is introduced in the next section on [Live Data](./07-Live_Data.ipynb).
+
+However when working with relatively small datasets a ``HoloMap`` is preferred as ``HoloMap``s can be exported to static HTML. To declare the data we use a dictionary comprehension to compute an FM modulation curve for each combination of carrier and modulation frequencies and then pass that dictionary to a newly declared ``HoloMap``, which declares our two parameters as key dimensions. If we want to customize the starting value of the widgets a ``default`` value may be supplied on the ``Dimension`` objects:
+
+
+```python
+f_carrier = np.linspace(20, 60, 3)
+f_mod = np.linspace(20, 100, 5)
+
+curve_dict = {(fc, fm): fm_modulation(fc, fm) for fc in f_carrier for fm in f_mod}
+
+kdims = [hv.Dimension(('f_carrier', 'Carrier frequency'), default=40),
+         hv.Dimension(('f_mod', 'Modulation frequency'), default=60)]
+holomap = hv.HoloMap(curve_dict, kdims=kdims)
+holomap.opts(opts.Curve(width=600))
+```
+
+Any numeric key dimension values will automatically generate sliders while any non-numeric value will present you with a dropdown widget to select between the values. A HoloMap is therefore an easy way to quickly explore a parameter space. Since only one ``Curve`` is on the screen at the same time it is difficult to compare the data, we can however easily facet the data in other ways.
+
+## Casting between n-dimensional containers
+
+Exploring a parameter space using widgets is one of the most flexible approaches but as we noted above it also makes it difficult to compare between different parameter values. HoloViews therefore supplies several container objects, which behave similarly to a ``HoloMap`` but have a different visual representation:
+
+* NdOverlay - An n-dimensional container which overlays the elements
+* NdLayout  - An n-dimensional container which displays the data in separate plot axes and adds titles for each value
+* GridSpace - A 1D or 2D container which lays out up to two dimensions on a grid.
+
+Since all these classes share the same baseclass we can trivially cast between them, e.g. we can cast the ``HoloMap`` to a ``GridSpace``.
+
+
+```python
+grid = hv.GridSpace(holomap)
+grid.opts(
+    opts.GridSpace(plot_size=75),
+    opts.Curve(width=100))
+```
+
+Similarly we can select just a few values and lay the data out in an ``NdLayout``:
+
+
+```python
+ndlayout = hv.NdLayout(grid[20, 20:81])
+ndlayout.opts(opts.Curve(width=500, height=200)).cols(2)
+```
+
+## Faceting by dimension
+
+Casting between container types as we did above allows us to facet all dimensions but often it is more desirable to facet a specific dimension in some way. We may for example want to overlay the carrier frequencies, while still having a slider vary the modulation frequencies. For this purpose ``HoloMap`` and ``DynamicMap`` have ``.overlay``, ``.grid`` and ``.layout`` methods, which accept one or more dimensions as input, e.g. here we overlay the carrier frequencies:
+
+
+```python
+holomap.overlay('f_carrier').opts(width=600)
+```
+
+We can chain these faceting operations but we have to be careful about the order. We should always ``overlay`` first and only then use ``.grid`` or ``.layout`` . To better understand why that is, look at the [Building Composite objects](./06-Building_Composite_Objects.ipynb) guide, for now it suffices to say that objects are built to nest in a specific order. Here we will ``overlay`` the carrier frequencies and ``grid`` the modulation frequency:
+
+
+```python
+gridspace = holomap.overlay('f_carrier').grid('f_mod')
+gridspace.opts(opts.Curve(width=200,height=200))
+```
+
+This ability to facet data in different ways becomes incredibly useful when working with [tabular](./08-Tabular_Datasets.ipynb) and [gridded](./09-Gridded_Datasets.ipynb) datasets, which vary by multiple dimensions. By faceting the data by one or more dimensions and utilizing the wide range of elements we can quickly explore huge and complex datasets particularly when working with using ``DynamicMap``, which allows you to define dynamic and lazy [data processing pipelines](./14-Data_Pipelines.ipynb), which visualize themselves and allow you to build complex interactive dashboards.
+
+## Methods
+
+### Selecting by value
+
+Just like ``Elements`` dimensioned containers can be sliced and indexed by value using the regular indexing syntax and the ``select`` method. As a simple example we can index the carrier frequency 20 and modulation frequency 40 using both the indexing and select syntax:
+
+
+```python
+layout = holomap[20, 40] + holomap.select(f_carrier=20, f_mod=40)
+layout.opts(opts.Curve(width=400))
+```
+
+For more detail on indexing both Elements and containers see the [Indexing and Selecting user guide](./10-Indexing_and_Selecting_Data.ipynb).
+
+### Collapsing an n-dimensional container
+
+If we inspect one of the containers we created in the examples above we can clearly see the structure and the dimensionality of each container and the underlying ``Curve`` elements:
+
+
+```python
+print(grid)
+```
+
+Since this simply represents a multi-dimensional parameter space we can collapse this datastructure into a single `Dataset` containing columns for each of the dimensions we have declared:
+
+
+```python
+ds = grid.collapse()
+ds.data.head()
+```
+
+A ``Dataset`` is an element type which does not itself have a visual representation and may contain any type of data supported by HoloViews interfaces.
+
+### Reindexing containers
+
+Something we might want to do quite frequently is to change the order of dimensions in a dimensioned container. Let us inspect the key dimensions on our HoloMap from above:
+
+
+```python
+holomap.kdims
+```
+
+Using the ``reindex`` method we can easily change the order of dimensions:
+
+
+```python
+reindexed = holomap.reindex(['f_mod', 'f_carrier'])
+reindexed.kdims
+```
+
+### Add dimensions to a container
+
+Another common operation is adding a new dimension to a HoloMap, which can be useful when you want to merge two HoloMaps which vary by yet another dimension. The ``add_dimension`` method takes the new dimension name, the position in the list of key dimensions and the actual value as arguments:
+
+
+```python
+new_holomap = holomap.add_dimension('New dimension', dim_pos=0, dim_val=1)
+new_holomap.kdims
+```
+
+As you can see the 'New dimension' was added at position zero.
+
+## Onwards
+
+As we have seen Dimensioned containers make it easy to explore multi-dimensional datasets by mapping the dimensions onto visual layers (`NdOverlay`), 2D grid axes (`GridSpace`), widgets (`HoloMap`) or an arbitrary layout (`NdLayout`). In the [next section](06-Building_Composite_Objects.ipynb) we will discover how to construct composite objects of heterogeneous data.

hvplot_docs/06-Building_Composite_Objects.md

@@ -0,0 +1,191 @@
+# Building Composite Objects
+
+The [reference gallery](http://holoviews.org/reference/index.html) shows examples of each of the container types in HoloViews. As you work through this guide, it will be useful to look at the description of each type there.  
+
+This guide shows you how to combine the various container types, in order to build data structures that can contain all of the data that you want to visualize or analyze, in an extremely flexible way.  For instance, you may have a large set of measurements of different types of data (numerical, image, textual notations, etc.) from different experiments done on different days, with various different parameter values associated with each one.  HoloViews can store all of this data together, which will allow you to select just the right bit of data "on the fly" for any particular analysis or visualization, by indexing, slicing, selecting, and sampling in this data structure.
+
+## Nesting hierarchy <a id='NestingHierarchy'></a>
+
+To illustrate the full functionality provided, we will create an example of the maximally nested object structure currently possible with HoloViews:
+
+
+```python
+import numpy as np
+import holoviews as hv
+hv.extension('bokeh')
+np.random.seed(10)
+
+def sine_curve(phase, freq, amp, power, samples=102):
+    xvals = [0.1* i for i in range(samples)]
+    return [(x, amp*np.sin(phase+freq*x)**power) for x in xvals]
+
+phases =      [0, np.pi/2, np.pi, 3*np.pi/2]
+powers =      [1,2,3]
+amplitudes =  [0.5,0.75, 1.0]
+frequencies = [0.5, 0.75, 1.0, 1.25, 1.5, 1.75]
+
+
+gridspace = hv.GridSpace(kdims=['Amplitude', 'Power'], group='Parameters', label='Sines')
+
+for power in powers:
+    for amplitude in amplitudes:
+        holomap = hv.HoloMap(kdims='Frequency')
+        for frequency in frequencies:
+            sines = {phase : hv.Curve(sine_curve(phase, frequency, amplitude, power))
+                     for phase in phases}
+            ndoverlay = hv.NdOverlay(sines, kdims='Phase').relabel(group='Phases',
+                                                                   label='Sines', depth=1)
+            overlay = ndoverlay * hv.Points([(i,0) for i in range(0,10)], group='Markers', label='Dots')
+            holomap[frequency] = overlay
+        gridspace[amplitude, power] = holomap
+
+penguins = hv.RGB.load_image('../reference/elements/assets/penguins.png').relabel(group="Family", label="Penguin")
+
+layout = gridspace + penguins.opts(axiswise=True)
+```
+
+This code produces what looks like a relatively simple animation of two side-by-side figures, but is actually a deeply nested data structure:
+
+
+```python
+layout
+```
+
+To help us understand this structure, here is a schematic for us to refer to as we unpack this object, level by level:
+
+<center><img src="https://assets.holoviews.org/nesting-diagram.png"></center>
+
+Everything that is *displayable* in HoloViews has this same basic hierarchical structure, although any of the levels can be omitted in simpler cases, and many different Element types (not containers) can be substituted for any other.  
+
+Since HoloViews 1.3.0, you are allowed to build data-structures that violate this hierarchy (e.g., you can put ``Layout`` objects into ``HoloMaps``) but the resulting object cannot be displayed. Instead, you will be prompted with a message to call the ``collate`` method. Using the ``collate`` method will allow you to generate the appropriate object that correctly obeys the hierarchy shown above, so that it can be displayed.
+
+As shown in the diagram, there are three different types of container involved:
+
+- Basic Element: elementary HoloViews object containing raw data in an external format like Numpy or pandas.
+- Homogeneous container (UniformNdMapping): collections of Elements or other HoloViews components that are all the same type.  These are indexed using array-style key access with values sorted along some dimension(s), e.g. ``[0.50]`` or ``["a",7.6]``.
+- Heterogeneous container (AttrTree): collections of data of different types, e.g. different types of Element.  These are accessed by categories using attributes, e.g. ``.Parameters.Sines``, which does not assume any ordering of a dimension.
+
+We will now go through each of the containers of these different types, at each level.
+
+### ``Layout`` Level
+
+Above, we have already viewed the highest level of our data structure as a Layout. Here is the representation of the entire Layout object, which reflects all the levels shown in the diagram:
+
+
+```python
+print(layout)
+```
+
+In the examples below, we will unpack this data structure using attribute access (explained in the [Annotating Data](./01-Annotating_Data.ipynb) user guide) as well as indexing and slicing (explained in the [Indexing and Selecting Data](./10-Indexing_and_Selecting_Data.ipynb) user guide).
+
+### ``GridSpace`` Level
+
+Elements within a ``Layout``, such as the ``GridSpace`` in this example, are reached via attribute access:
+
+
+```python
+layout.Parameters.Sines
+```
+
+### ``HoloMap`` Level
+
+This ``GridSpace`` consists of nine ``HoloMap``s arranged in a two-dimensional space.  Let's now select one of these ``HoloMap`` objects by indexing to retrieve the one at [Amplitude,Power] ``[0.5,1.0]``, i.e. the lowest amplitude and power:
+
+
+```python
+layout.Parameters.Sines[0.5, 1]
+```
+
+As shown in the schematic above, a ``HoloMap`` contains many elements with associated keys. In this example, these keys are indexed with a dimension ``Frequency``, which is why the ``Frequency`` varies when you play the animation here.
+
+### ``Overlay`` Level
+
+The printed representation showed us that the ``HoloMap`` is composed of ``Overlay`` objects, six in this case (giving six frames to the animation above).  Let us access one of these elements, i.e. one frame of the animation above, by indexing to retrieve an ``Overlay`` associated with the key with a ``Frequency`` of *1.0*:
+
+
+```python
+layout.Parameters.Sines[0.5, 1][1.0]
+```
+
+### NdOverlay Level
+
+As the representation shows, the ``Overlay`` contains a ``Points`` object and an ``NdOverlay`` object.  We can access either one of these using the attribute access supported by ``Overlay``:
+
+
+```python
+(layout.Parameters.Sines[0.5, 1][1].Phases.Sines +
+ layout.Parameters.Sines[0.5, 1][1].Markers.Dots)
+```
+
+### ``Curve`` Level
+
+The ``NdOverlay`` is so named because it is an overlay of items indexed by dimensions, unlike the regular attribute-access overlay types.  In this case it is indexed by ``Phase``, with four values.  If we index to select one of these values, we will get an individual ``Curve``, e.g. the one with zero phase:
+
+
+```python
+l=layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0]
+l
+```
+
+
+```python
+print(l)
+```
+
+### Data Level
+
+At this point, we have reached the end of the HoloViews objects; below this object is only the raw data stored in one of the supported formats (e.g. NumPy arrays or Pandas DataFrames):
+
+
+```python
+type(layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0].data)
+```
+
+Actually, HoloViews will let you go even further down, accessing data inside the Numpy array using the continuous (floating-point) coordinate systems declared in HoloViews. E.g. here we can ask for a single datapoint, such as the value at x=5.2:
+
+
+```python
+layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0][5.2]
+```
+
+Indexing into 1D Elements like Curve and higher-dimensional but regularly gridded Elements like Image, Surface, and HeatMap will return the nearest defined value (i.e., the results "snap" to the nearest data item):
+
+
+```python
+layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0][5.23], layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0][5.27]
+```
+
+For other Element types, such as Points, snapping is not supported and thus indexing down into the .data array will be less useful, because it will only succeed for a perfect floating-point match on the key dimensions.  In those cases, you can still use all of the access methods provided by the numpy array itself, via ``.data``, e.g. ``.data[52]``, but note that such native operations force you to use the native indexing scheme of the array, i.e. integer access starting at zero, not the more convenient and semantically meaningful [continuous coordinate systems](./Continuous_Coordinates.ipynb) we provide through HoloViews.
+
+### Indexing using ``.select``
+
+The curve displayed immediately above shows the final, deepest Element access possible in HoloViews for this object:
+
+```python
+layout.Parameters.Sines[0.5, 1][1].Phases.Sines[0.0]
+```
+This is the curve with an amplitude of *0.5*, raised to a power of *1.0* with frequency of *1.0* and *0* phase. These are all the numbers, in order, used in the access shown above.
+
+The ``.select`` method is a more explicit way to use key access, with both of these equivalent to each other:
+
+
+```python
+o1 = layout.Parameters.Sines.select(Amplitude=0.5, Power=1.0).select(Frequency=1.0)
+o2 = layout.Parameters.Sines.select(Amplitude=0.5, Power=1.0, Frequency=1.0)
+o1 + o2
+```
+
+The second form demonstrates HoloViews' **deep indexing** feature, which allows indices to cross nested container boundaries. The above is as far as we can index before reaching a heterogeneous type (the ``Overlay``), where we need to use attribute access. Here is the more explicit method of indexing down to a curve, using ``.select`` to specify dimensions by name instead of bracket-based indexing by position:
+
+
+```python
+layout.Parameters.Sines.select(Amplitude=0.5,Power=1.0, Frequency=1.0, Phase=0.0).Phases.Sines
+```
+
+## Summary
+
+As you can see, HoloViews lets you compose objects of heterogeneous types, and objects covering many different numerical or other dimensions, laying them out spatially, temporally, or overlaid.  The resulting data structures are complex, but they are composed of simple elements with well-defined interactions, making it feasible to express nearly any relationship that will characterize your data.  In practice, you will probably not need this many levels, but given this complete example, you should be able to construct an appropriate hierarchy for whatever type of data that you want to represent or visualize. 
+
+As emphasized above, it is not recommended to combine these objects in other orderings.  Of course, any ``Element`` can be substituted for any other, which doesn't change the structure. But you should not e.g. display an ``Overlay`` of ``Layout`` objects. The display system will generally attempt to figure out the correct arrangement and warn you to call the `.collate` method to reorganize the objects in the recommended format.
+
+Another important thing to observe is that ``Layout`` and ``Overlay`` types may not be nested, e.g. using the ``+`` operator on two `Layout` objects will not create a nested `Layout` instead combining the contents of the two objects. The same applies to the ``*`` operator and combining of `Overlay` objects. 

hvplot_docs/07-Live_Data.md

@@ -0,0 +1,354 @@
+# Live Data
+
+The [HoloMap](../reference/containers/bokeh/HoloMap.ipynb) is a core HoloViews data structure that allows easy exploration of parameter spaces. The essence of a HoloMap is that it contains a collection of [Elements](http://holoviews.org/reference/index.html) (e.g. ``Image``s and ``Curve``s) that you can easily select and visualize.
+
+HoloMaps hold fully constructed Elements at specifically sampled points in a multidimensional space. Although HoloMaps are useful for exploring high-dimensional parameter spaces, they can very quickly consume huge amounts of memory to store all these Elements. For instance, a hundred samples along four orthogonal dimensions would need a HoloMap containing a hundred *million* Elements, each of which could be a substantial object that takes time to create and costs memory to store. Thus ``HoloMaps`` have some clear limitations:
+
+* HoloMaps may require the generation of millions of Elements before the first element can be viewed.
+* HoloMaps can easily exhaust all the memory available to Python.
+* HoloMaps can even more easily exhaust all the memory in the browser when displayed.
+* Static export of a notebook containing HoloMaps can result in impractically large HTML files.
+
+The ``DynamicMap`` addresses these issues by computing and displaying elements dynamically, allowing exploration of much larger datasets:
+
+* DynamicMaps generate elements on the fly, allowing the process of exploration to begin immediately.
+* DynamicMaps do not require fixed sampling, allowing exploration of parameters with arbitrary resolution.
+* DynamicMaps are lazy in the sense they only compute as much data as the user wishes to explore.
+
+Of course, these advantages come with some limitations:
+
+* DynamicMaps require a live notebook server and cannot be fully exported to static HTML.
+* DynamicMaps store only a portion of the underlying data, in the form of an Element cache and their output is dependent on the particular version of the executed code.   
+* DynamicMaps (and particularly their element caches) are typically stateful (with values that depend on patterns of user interaction), which can make them more difficult to reason about.
+
+In addition to the different computational requirements of ``DynamicMaps``, they can be used to build sophisticated, interactive visualisations that cannot be achieved using only ``HoloMaps``. This notebook demonstrates some basic examples and the [Responding to Events](./12-Responding_to_Events.ipynb) guide follows on by introducing the streams system. The [Custom Interactivity](./13-Custom_Interactivity.ipynb) shows how you can directly interact with your plots when using the Bokeh backend.
+
+When DynamicMap was introduced in version 1.6, it supported multiple different 'modes' which have now been deprecated. This notebook demonstrates the simpler, more flexible and more powerful DynamicMap introduced in version 1.7. Users who have been using the previous version of DynamicMap should be unaffected as backwards compatibility has been preserved for the most common cases.
+
+All this will make much more sense once we've tried out some ``DynamicMaps`` and showed how they work, so let's create one!
+
+
+<center><div class="alert alert-info" role="alert">To use visualize and use a <b>DynamicMap</b> you need to be running a live Jupyter server.<br>When viewing this user guide as part of the documentation DynamicMaps will be sampled with a limited number of states.<br>
+It's also best to run this notebook one cell at a time, not via "Run All",<br> so that subsequent cells can reflect your dynamic interaction with widgets in previous cells.</div></center>
+
+## ``DynamicMap``  <a id='DynamicMap'></a>
+
+Let's start by importing HoloViews and loading the extension:
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('matplotlib')
+```
+
+We will now create  ``DynamicMap`` similar to the  ``HoloMap`` introduced in the [Introductory guide](../getting_started/1-Introduction.ipynb). The ``HoloMap`` in that introduction consisted of ``Image`` elements defined by a function returning NumPy arrays called ``sine_array``. Here we will define a ``waves_image`` function that returns an array pattern parameterized by arbitrary ``alpha`` and ``beta`` parameters inside a HoloViews 
+[``Image``](../reference/elements/bokeh/Image.ipynb) element:
+
+
+```python
+xvals  = np.linspace(-4, 0, 202)
+yvals  = np.linspace(4, 0, 202)
+xs, ys = np.meshgrid(xvals, yvals)
+
+def waves_image(alpha, beta):
+    return hv.Image(np.sin(((ys/alpha)**alpha+beta)*xs))
+
+waves_image(1,0) + waves_image(1,4)
+```
+
+Now we can demonstrate the possibilities for exploration enabled by the simplest declaration of a ``DynamicMap``.
+
+### Basic ``DynamicMap`` declaration<a id='BasicDeclaration'></a>
+
+A simple ``DynamicMap`` declaration looks identical to that needed to declare a ``HoloMap``. Instead of supplying some initial data, we will supply the ``waves_image`` function with key dimensions simply declaring the arguments of that function:
+
+
+```python
+dmap = hv.DynamicMap(waves_image, kdims=['alpha', 'beta'])
+dmap
+```
+
+This object is created instantly, but because it doesn't generate any `hv.Image` objects initially it only shows the printed representation of this object along with some information about how to display it. We will refer to a ``DynamicMap`` that doesn't have enough information to display itself as 'unbounded'.
+
+The textual representation of all ``DynamicMaps`` look similar, differing only in the listed dimensions until they have been evaluated at least once.
+
+#### Explicit indexing
+
+Unlike a corresponding ``HoloMap`` declaration, this simple unbounded ``DynamicMap`` cannot yet visualize itself. To view it, we can follow the advice in the warning message. First we will explicitly index into our ``DynamicMap`` in the same way you would access a key on a ``HoloMap``:
+
+
+```python
+dmap[1,2] + dmap.select(alpha=1, beta=2)
+```
+
+Note that the declared kdims are specifying the arguments *by position* as they do not match the argument names of the ``waves_image`` function. If you *do* match the argument names *exactly*, you can map a kdim position to any argument position of the callable. For instance, the declaration ``kdims=['freq', 'phase']`` would index first by frequency, then phase without mixing up the arguments to ``waves_image`` when indexing.
+
+#### Setting dimension ranges
+
+The second suggestion in the warning message was to supply dimension ranges using the ``redim.range`` method:
+
+
+```python
+dmap.redim.range(alpha=(1, 5.0), beta=(1, 6.0))
+```
+
+Here each `hv.Image` object visualizing a particular sine ring pattern with the given parameters is created dynamically, whenever the slider is set to a new value.  Any value in the allowable range can be requested by dragging the sliders or by tweaking the values using the left and right arrow keys.
+
+Of course, we didn't have to use the ``redim.range`` method and we could have simply declared the ranges right away using explicit ``hv.Dimension`` objects. This would allow us to declare other dimension properties such as the step size used by the sliders: by default each slider can select around a thousand distinct values along its range but you can specify your own step value via the dimension ``step`` parameter. If you use integers in your range declarations, integer stepping will be assumed with a step size of one.
+
+Note that whenever the ``redim`` method is used, a new ``DynamicMap`` is returned with the updated dimensions. In other words, the original ``dmap`` remains unbounded with default dimension objects.
+
+
+#### Setting dimension values
+
+The ``DynamicMap`` above allows exploration of *any* phase and frequency within the declared range unlike an equivalent ``HoloMap`` which would have to be composed of a finite set of samples. We can achieve a similar discrete sampling using ``DynamicMap`` by setting the ``values`` parameter on the dimensions:
+
+
+```python
+dmap.redim.values(alpha=[1, 2, 3], beta=[0.1, 1.0, 2.5])
+```
+
+The sliders now snap to the specified dimension values and if you are running this live, the above cell should look like a [HoloMap](../reference/containers/bokeh/HoloMap.ipynb). ``DynamicMap`` is in fact a subclass of ``HoloMap`` with some crucial differences:
+
+* You can now pick as many values of **alpha** or **beta** as allowed by the slider.
+* What you see in the cell above will not be exported in any HTML snapshot of the notebook
+
+#### Getting the current key
+
+The ``current_key`` property returns the current key of the ``DynamicMap``, i.e. either a value (one-dimensional) or a tuple (multi-dimensional) that represents the current state of the widgets. If you move the sliders above and re-execute the cell below you will see that the tuple returned reflects the values of *alpha* and *beta*.
+
+
+```python
+dmap.current_key
+```
+
+We will now explore how ``DynamicMaps`` relate to ``HoloMaps`` including conversion operations between the two types. As we will see, there are other ways to display a ``DynamicMap`` without using explicit indexing or redim.
+
+## Interaction with ``HoloMap``s
+
+To explore the relationship between ``DynamicMap`` and ``HoloMap``, let's declare another callable to draw some shapes we will use in a new ``DynamicMap``:
+
+
+```python
+def shapes(N, radius=0.5): # Positional keyword arguments are fine
+    paths = [hv.Path([[(radius*np.sin(a), radius*np.cos(a)) 
+                        for a in np.linspace(-np.pi, np.pi, n+2)]], 
+                     extents=(-1,-1,1,1)) 
+             for n in range(N,N+3)]
+    return hv.Overlay(paths)
+```
+
+#### Sampling  ``DynamicMap`` from a ``HoloMap``
+
+When combining a ``HoloMap`` with a ``DynamicMap``, it would be very awkward to have to match the declared dimension ``values`` of the DynamicMap with the keys of the ``HoloMap``. Fortunately you don't have to:
+
+
+```python
+holomap = hv.HoloMap({(N,r):shapes(N, r) for N in [3,4,5] for r in [0.5,0.75]},  kdims=['N', 'radius'])
+dmap = hv.DynamicMap(shapes, kdims=['N','radius'])
+holomap + dmap
+```
+
+Here we declared a ``DynamicMap`` without using ``redim``, but we can view its output because it is presented alongside a ``HoloMap`` which defines the available keys. This convenience is subject to three particular restrictions:
+
+
+* You cannot display a layout consisting of unbounded ``DynamicMaps`` only, because at least one HoloMap is needed to define the samples.
+* The HoloMaps provide the necessary information required to sample the DynamicMap. 
+
+Note that there is one way ``DynamicMap`` is less restricted than ``HoloMap``: you can freely combine bounded ``DynamicMaps`` together in a ``Layout``, even if they don't share key dimensions.
+
+#### Converting from ``DynamicMap`` to ``HoloMap``
+
+Above we mentioned that ``DynamicMap`` is an instance of ``HoloMap``. Does this mean it has a ``.data`` attribute?
+
+
+```python
+dtype = type(dmap.data).__name__
+length = len(dmap.data)
+print("DynamicMap 'dmap' has an {dtype} .data attribute of length {length}".format(dtype=dtype, length=length))
+```
+
+This is exactly the same sort of ``.data`` as the equivalent ``HoloMap``, except that its values will vary according to how much you explored the parameter space of ``dmap`` using the sliders above. In a ``HoloMap``, ``.data`` contains a defined sampling along the different dimensions, whereas in a ``DynamicMap``, the ``.data`` is simply the *cache*.
+
+The cache serves two purposes:
+
+* Avoids recomputation of an element should we revisit a particular point in the parameter space. This works well for categorical or integer dimensions, but doesn't help much when using continuous sliders for real-valued dimensions.
+* Records the space that has been explored with the ``DynamicMap`` for any later conversion to a ``HoloMap`` up to the allowed cache size.
+
+We can always convert *any* ``DynamicMap`` directly to a ``HoloMap`` as follows:
+
+
+```python
+hv.HoloMap(dmap)
+```
+
+This is in fact equivalent to declaring a HoloMap with the same parameters (dimensions, etc.) using ``dmap.data`` as input, but is more convenient. Note that the slider positions reflect those we sampled from the ``HoloMap`` in the previous section.
+
+Although creating a HoloMap this way is easy, the result is poorly controlled, as the keys in the DynamicMap cache are usually defined by how you moved the sliders around. If you instead want to specify a specific set of samples, you can easily do so by using the same key-selection semantics as for a ``HoloMap`` to define exactly which elements are to be sampled and put into the cache:
+
+
+```python
+hv.HoloMap(dmap[{(2,0.3), (2,0.6), (3,0.3), (3,0.6)}])
+```
+
+Here we index the ``dmap`` with specified keys to return a *new* DynamicMap with those keys in its cache, which we then cast to a ``HoloMap``. This allows us to export specific contents of  ``DynamicMap`` to static HTML which will display the data at the sampled slider positions.
+
+The key selection above happens to define a Cartesian product, which is one of the most common ways to sample across dimensions. Because the list of such dimension values can quickly get very large when enumerated as above, we provide a way to specify a Cartesian product directly, which also works with ``HoloMaps``. Here is an equivalent way of defining the same set of four points in that two-dimensional space:
+
+
+```python
+samples = hv.HoloMap(dmap[{2,3},{0.5,1.0}])
+samples
+```
+
+
+```python
+samples.data.keys()
+```
+
+The default cache size of 500 Elements is relatively high so that interactive exploration will work smoothly, but you can reduce it using the ``cache_size`` parameter if you find you are running into issues with memory consumption. A bounded ``DynamicMap`` with ``cache_size=1`` requires the least memory, but will recompute a new Element every time the sliders are moved, making it less responsive.
+
+#### Converting from ``HoloMap`` to ``DynamicMap``
+
+We have now seen how to convert from a ``DynamicMap`` to a ``HoloMap`` for the purposes of static export, but why would you ever want to do the inverse?
+
+Although having a ``HoloMap`` to start with means it will not save you memory, converting to a ``DynamicMap`` does mean that the rendering process can be deferred until a new slider value requests an update. You can achieve this conversion using the ``Dynamic`` utility as demonstrated here by applying it to the previously defined ``HoloMap`` called ``samples``:
+
+
+```python
+from holoviews.util import Dynamic
+dynamic = Dynamic(samples)
+print('After apply Dynamic, the type is a {dtype}'.format(dtype=type(dynamic).__name__))
+dynamic
+```
+
+In this particular example, there is no real need to use ``Dynamic`` as each frame renders quickly enough. For visualizations that are slow to render, using ``Dynamic`` can result in more responsive visualizations. 
+
+The ``Dynamic`` utility is very versatile and is discussed in more detail in the [Transforming Elements](./11-Transforming_Elements.ipynb) guide.
+
+###  Slicing ``DynamicMaps``
+
+As we have seen we can either declare dimension ranges directly in the kdims or use the ``redim.range`` convenience method:
+
+
+```python
+dmap = hv.DynamicMap(shapes, kdims=['N','radius']).redim.range(N=(2,20), radius=(0.5,1.0))
+```
+
+The declared dimension ranges define the absolute limits allowed for exploration in this continuous, bounded DynamicMap . That said, you can use the soft_range parameter to view subregions within that range. Setting the soft_range parameter on dimensions can be done conveniently using slicing:
+
+
+```python
+sliced = dmap[4:8, :]
+sliced
+```
+
+
+Notice that N is now restricted to the range 4:8.  Open slices are used to release any ``soft_range`` values, which resets the limits back to those defined by the full range:
+
+
+```python
+sliced[:, 0.8:1.0]
+```
+
+The ``[:]`` slice leaves the soft_range values alone and can be used as a convenient way to clone a ``DynamicMap``. Note that mixing slices with any other object type is not supported. In other words, once you use a single slice, you can only use slices in that indexing operation.
+
+## Using groupby to discretize a DynamicMap
+
+A DynamicMap also makes it easy to partially or completely discretize a function to evaluate in a complex plot. By grouping over specific dimensions that define a fixed sampling via the Dimension values parameter, the DynamicMap can be viewed as a ``GridSpace``, ``NdLayout``, or ``NdOverlay``. If a dimension specifies only a continuous range it can't be grouped over, but it may still be explored using the widgets. This means we can plot partial or completely discretized views of a parameter space easily.
+
+#### Partially discretize
+
+The implementation for all the groupby operations uses the ``.groupby`` method internally, but we also provide three higher-level convenience methods to group dimensions into an ``NdOverlay`` (``.overlay``), ``GridSpace`` (``.grid``), or ``NdLayout`` (``.layout``).
+
+Here we will evaluate a simple sine function with three dimensions, the phase, frequency, and amplitude. We assign the frequency and amplitude discrete samples, while defining a continuous range for the phase:
+
+
+```python
+xs = np.linspace(0, 2*np.pi,100)
+
+def sin(ph, f, amp):
+    return hv.Curve((xs, np.sin(xs*f+ph)*amp))
+
+kdims=[hv.Dimension('phase', range=(0, np.pi)),
+       hv.Dimension('frequency', values=[0.1, 1, 2, 5, 10]),
+       hv.Dimension('amplitude', values=[0.5, 5, 10])]
+
+waves_dmap = hv.DynamicMap(sin, kdims=kdims)
+```
+
+Next we define the amplitude dimension to be overlaid and the frequency dimension to be gridded:
+
+
+```python
+wave_grid = waves_dmap.overlay('amplitude').grid('frequency')
+wave_grid.opts(fig_size=200, show_legend=True)
+```
+
+As you can see, instead of having three sliders (one per dimension), we've now laid out the frequency dimension as a discrete set of values in a grid, and the amplitude dimension as a discrete set of values in an overlay, leaving one slider for the remaining dimension (phase).  This approach can help you visualize a large, multi-dimensional space efficiently, with full control over how each dimension is made visible.
+
+
+#### Fully discretize
+
+Given a continuous function defined over a space, we could sample it manually, but here we'll look at an example of evaluating it using the groupby method. Let's look at a spiral function with a frequency and first- and second-order phase terms. Then we define the dimension values for all the parameters and declare the DynamicMap:
+
+
+```python
+opts.defaults(opts.Path(color=hv.Palette('Blues')))
+
+def spiral_equation(f, ph, ph2):
+    r = np.arange(0, 1, 0.005)
+    xs, ys = (r * fn(f*np.pi*np.sin(r+ph)+ph2) for fn in (np.cos, np.sin))
+    return hv.Path((xs, ys))
+
+spiral_dmap = hv.DynamicMap(spiral_equation, kdims=['f','ph','ph2'])
+spiral_dmap = spiral_dmap.redim.values(
+    f=np.linspace(1, 10, 10),
+    ph=np.linspace(0, np.pi, 10),
+    ph2=np.linspace(0, np.pi, 4))
+```
+
+Now we can make use of the ``.groupby`` method to group over the frequency and phase dimensions, which we will display as part of a GridSpace by setting the ``container_type``. This leaves the second phase variable, which we assign to an NdOverlay by setting the ``group_type``:
+
+
+```python
+spiral_grid = spiral_dmap.groupby(['f', 'ph'], group_type=hv.NdOverlay, container_type=hv.GridSpace)
+spiral_grid.opts(
+    opts.GridSpace(xaxis=None, yaxis=None),
+    opts.Path(bgcolor='white', xaxis=None, yaxis=None))
+```
+
+This grid shows a range of frequencies `f` on the x axis, a range of the first phase variable `ph` on the `y` axis, and a range of different `ph2` phases as overlays within each location in the grid.  As you can see, these techniques can help you visualize multidimensional parameter spaces compactly and conveniently.
+
+
+## DynamicMaps and normalization
+
+By default, a ``HoloMap`` normalizes the display of elements using the minimum and maximum values found across the ``HoloMap``. This automatic behavior is not possible in a ``DynamicMap``, where arbitrary new elements are being generated on the fly. Consider the following examples where the arrays contained within the returned ``Image`` objects are scaled with time:
+
+
+```python
+ls = np.linspace(0, 10, 200)
+xx, yy = np.meshgrid(ls, ls)
+
+def cells(time):
+    return hv.Image(time*np.sin(xx+time)*np.cos(yy+time), vdims='Intensity')
+
+dmap = hv.DynamicMap(cells, kdims='time').redim.range(time=(1,20))
+(dmap + dmap.redim.range(Intensity=(0,10))).opts(
+    opts.Image(axiswise=True))
+```
+
+Here we use ``axiswise=True`` to see the behavior of the two cases independently. We see in **A** that when only the time dimension is given a range, no automatic normalization occurs (unlike a ``HoloMap``). In **B** we see that normalization is applied, but only when the value dimension ('Intensity') range has been specified. 
+
+In other words, ``DynamicMaps`` cannot support automatic normalization across their elements, but do support the same explicit normalization behavior as ``HoloMaps``. Values that are generated outside this range are simply clipped in accord with the usual semantics of explicit value dimension ranges. 
+
+Note that we always have the option of casting a ``DynamicMap`` to a ``HoloMap`` in order to automatically normalize across the cached values, without needing explicit value dimension ranges.
+
+## Using DynamicMaps in your code
+
+As you can see, ``DynamicMaps`` let you use HoloViews with a very wide range of dynamic data formats and sources, making it simple to visualize ongoing processes or very large data spaces. 
+
+Given unlimited computational resources, the functionality covered in this guide would match that offered by ``HoloMap`` but with fewer normalization options. ``DynamicMap`` actually enables a vast range of new possibilities for dynamic, interactive visualizations as covered in the [Responding to Events](./Responding_to_Events.ipynb) guide. Following on from that, the [Custom Interactivity](./13-Custom_Interactivity.ipynb) guide shows how you can directly interact with your plots when using the Bokeh backend.

hvplot_docs/08-Tabular_Datasets.md

@@ -0,0 +1,297 @@
+# Tabular Datasets
+
+In this guide we will explore how to work with tabular data in HoloViews. Tabular data has a fixed list of column headings, with values stored in an arbitrarily long list of rows.  Spreadsheets, relational databases, CSV files, and many other typical data sources fit naturally into this format.  HoloViews defines an extensible system of interfaces to load, manipulate, and visualize this kind of data, as well as allowing conversion of any of the non-tabular data types into tabular data for analysis or data interchange.
+
+By default HoloViews will use one of these data storage formats for tabular data:
+
+* A pure Python dictionary containing 1D NumPy-arrays for each column.
+
+    ``{'x': np.array([0, 1, 2]), 'y': np.array([0, 1, 2])}``
+
+* A purely NumPy array format for numeric data.
+
+    ``np.array([[0, 0], [1, 1], [2, 3]])``
+
+* Pandas DataFrames
+
+    ``pd.DataFrame(np.array([[0, 0], [1, 1], [2, 3]]), columns=['x', 'y'])``
+
+* Dask DataFrames
+
+* cuDF Dataframes
+
+A number of additional standard constructors are supported:
+
+* A tuple of array (or array-like) objects
+
+    ``([0, 1, 2], [0, 1, 2])``
+
+* A list of tuples:
+
+    ``[(0, 0), (1, 1), (2, 2)]``
+
+
+
+```python
+import numpy as np
+import pandas as pd
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh', 'matplotlib')
+
+opts.defaults(opts.Scatter(size=10))
+```
+
+# A simple Dataset
+
+Usually when working with data we have one or more independent variables, taking the form of categories, labels, discrete sample coordinates, or bins.  We refer to these independent variables as key dimensions (or ``kdims`` for short) in HoloViews. The observer or dependent variables, on the other hand, are referred to as value dimensions (``vdims``), and are ordinarily measured or calculated given the independent variables. The simplest useful form of a ``Dataset`` object is therefore a column 'x' and a column 'y' corresponding to the key dimensions and value dimensions respectively. An obvious visual representation of this data is a ``Table``:
+
+
+```python
+xs = np.linspace(0, 10, 11)
+ys = np.sin(xs)
+
+table = hv.Table((xs, ys), 'x', 'y')
+table
+```
+
+However, this data has many more meaningful visual representations, and therefore the first important concept is that ``Dataset`` objects can be converted to other objects as long as their dimensionality allows it, meaning that you can easily create the different objects from the same data (and cast between the objects once created):
+
+
+```python
+(hv.Scatter(table) + hv.Curve(table) + hv.Area(table) + hv.Bars(table)).cols(2)
+```
+
+Each of these three plots uses the same data, but represents a different assumption about the semantic meaning of that data -- the ``Scatter`` plot is appropriate if that data consists of independent samples, the ``Curve`` plot is appropriate for samples chosen from an underlying smooth function, and the ``Bars`` plot is appropriate for independent categories of data.  Since all these plots have the same dimensionality, they can easily be converted to each other, but there is normally only one of these representations that is semantically appropriate for the underlying data.  For this particular data, the semantically appropriate choice is ``Curve``, since the *y* values are samples from the continuous function ``exp``.
+
+As a guide to which Elements can be converted to each other, those of the same dimensionality here should be interchangeable, because of the underlying similarity of their columnar representation:
+
+* 0D: BoxWhisker, Spikes, Distribution
+* 1D: Area, Bars, BoxWhisker, Curve, ErrorBars, Scatter, Spread
+* 2D: Bars, Bivariate, BoxWhisker, HeatMap, Points, VectorField 
+* 3D: Scatter3D, TriSurface, VectorField
+
+This categorization is based only on the ``kdims``, which define the space in which the data has been sampled or defined. An Element can also have any number of value dimensions (``vdims``), which may be mapped onto various attributes of a plot such as the color, size, and orientation of the plotted items.  For a reference of how to use these various Element types, see the [Elements Reference](http://holoviews.org/reference/index.html#elements).
+
+## Data types and Constructors
+
+As discussed above, ``Dataset`` provides an extensible interface to store and operate on data in different formats. All interfaces support a number of standard constructors.
+
+#### Storage formats
+
+Dataset types can be constructed using one of three supported formats, (a) a dictionary of columns, (b) an NxD array with N rows and D columns, or (c) pandas dataframes:
+
+
+```python
+print(hv.Scatter({'x': xs, 'y': ys}) +
+      hv.Scatter(np.column_stack([xs, ys])) +
+      hv.Scatter(pd.DataFrame({'x': xs, 'y': ys})))
+```
+
+#### Literals
+
+In addition to the main storage formats, Dataset Elements support construction from three Python literal formats: (a) An iterator of y-values, (b) a tuple of columns, and (c) an iterator of row tuples.
+
+
+```python
+print(hv.Scatter(ys) + hv.Scatter((xs, ys)) + hv.Scatter(zip(xs, ys)))
+```
+
+For these inputs, the data will need to be copied to a new data structure, having one of the three storage formats above.  By default Dataset will try to construct a simple array, falling back to either pandas dataframes (if available) or the dictionary-based format if the data is not purely numeric. Additionally, the interfaces will try to maintain the provided data's type, so numpy arrays and pandas DataFrames will always be parsed first by their respective array and dataframe interfaces.
+
+
+```python
+df = pd.DataFrame({'x': xs, 'y': ys, 'z': ys*2})
+print(type(hv.Scatter(df).data))
+```
+
+Dataset will attempt to parse the supplied data, falling back to each consecutive interface if the previous could not interpret the data. The default list of fallbacks and simultaneously the list of allowed datatypes is:
+
+
+```python
+hv.Dataset.datatype
+```
+
+Note these include grid based datatypes, which are covered in [Gridded Datasets](http://holoviews.org/user_guide/Gridded_Datasets.html). To select a particular storage format explicitly, supply one or more allowed datatypes (note that the 'array' interface only supports data with matching types):
+
+
+```python
+print(type(hv.Scatter((xs.astype('float64'), ys), datatype=['array']).data))
+print(type(hv.Scatter((xs, ys), datatype=['dictionary']).data))
+print(type(hv.Scatter((xs, ys), datatype=['dataframe']).data))
+```
+
+#### Sharing Data
+
+Since the formats with labelled columns do not require any specific order, each Element can effectively become a view into a single set of data. By specifying different key and value dimensions, many Elements can show different values, while sharing the same underlying data source.
+
+
+```python
+overlay = hv.Scatter(df, 'x', 'y') * hv.Scatter(df, 'x', 'z')
+overlay
+```
+
+We can quickly confirm that the data is actually shared:
+
+
+```python
+overlay.Scatter.I.data is overlay.Scatter.II.data
+```
+
+For columnar data, this approach is much more efficient than creating copies of the data for each Element, and allows for some advanced features like linked brushing in the [Bokeh backend](./Plotting_with_Bokeh.ipynb).
+
+#### Converting to raw data
+
+Column types make it easy to export the data to the three basic formats: arrays, dataframes, and a dictionary of columns.
+
+###### Array
+
+
+```python
+table.array()
+```
+
+###### Pandas DataFrame
+
+
+```python
+table.dframe().head()
+```
+
+###### Dataset dictionary
+
+
+```python
+table.columns()
+```
+
+# Creating tabular data from Elements using the .table and .dframe methods
+
+If you have data in some other HoloViews element and would like to use the columnar data features, you can easily tabularize any of the core Element types into a ``Table`` Element.  Similarly, the ``.dframe()`` method will convert an Element into a pandas DataFrame. These methods are very useful if you want to then transform the data into a different Element type, or to perform different types of analysis.
+
+## Tabularizing simple Elements
+
+For a simple example, we can create a ``Curve`` of an exponential function and cast it to a ``Table``, with the same result as creating the Table directly from the data as done earlier in this user guide:
+
+
+```python
+xs = np.arange(10)
+curve = hv.Curve(zip(xs, np.sin(xs)))
+curve * hv.Scatter(curve) + hv.Table(curve)
+```
+
+Similarly, we can get a pandas dataframe of the Curve using ``curve.dframe()``:
+
+
+```python
+curve.dframe()
+```
+
+## Collapsing dimensioned containers
+
+Even deeply nested objects can be deconstructed in this way, serializing them to make it easier to get your raw data out of a collection of specialized ``Element`` types. Let's say we want to make multiple observations of a noisy signal. We can collect the data into a ``HoloMap`` to visualize it and then call ``.collapse()`` to get a ``Dataset`` object to which we can apply operations or transformations to other ``Element`` types. Deconstructing nested data in this way only works if the data is homogeneous. In practical terms this requires that your data structure contains Elements (of any type) held in these Container types: ``NdLayout``, ``GridSpace``, ``HoloMap``, and ``NdOverlay``, with all dimensions consistent throughout (so that they can all fit into the same set of columns). To read more about these containers see the [Dimensioned Containers](./Dimensioned_Containers.ipynb) guide.
+
+Let's now go back to the ``Image`` example. We will collect a number of observations of some noisy data into a ``HoloMap`` and display it:
+
+
+```python
+obs_hmap = hv.HoloMap({i: hv.Image(np.random.randn(10, 10), bounds=(0,0,3,3))
+                       for i in range(3)}, kdims='Observation')
+obs_hmap
+```
+
+Now we can serialize this data just as before, where this time we get a four-column (4D) table. The key dimensions of both the HoloMap and the Images, as well as the z-values of each ``Image``, are all merged into a single table. We can visualize the samples we have collected by converting it to a ``Scatter3D`` object.
+
+
+```python
+hv.output(backend='matplotlib', size=150)
+
+collapsed = obs_hmap.collapse()
+scatter_layout = collapsed.to.scatter3d() + hv.Table(collapsed)
+scatter_layout.opts(
+    opts.Scatter3D(color='z', cmap='hot', edgecolor='black', s=50))
+```
+
+Here the `z` dimension is shown by color, as in the original images, and the other three dimensions determine where the datapoint is shown in 3D. This way of deconstructing objects will work for any data structure that satisfies the conditions described above, no matter how nested. If we vary the amount of noise while continuing to performing multiple observations, we can create an ``NdLayout`` of HoloMaps, one for each noise level, and animated by the observation number.
+
+
+```python
+extents = (0, 0, 3, 3)
+
+error_hmap = hv.HoloMap({
+    (i, j): hv.Image(j*np.random.randn(3, 3), bounds=extents)
+    for i in range(3) for j in np.linspace(0, 1, 3)},
+    ['Observation', 'noise'])
+
+noise_layout = error_hmap.layout('noise')
+noise_layout
+```
+
+And again, we can easily convert the object to a ``Table``:
+
+
+```python
+hv.Table(noise_layout.collapse())
+```
+
+# Applying operations to the data
+
+#### Sorting by columns
+
+Once data is in columnar form, it is simple to apply a variety of operations.  For instance, Dataset can be sorted by their dimensions using the ``.sort()`` method.  By default, this method will sort by the key dimensions in an ascending order, but any other dimension(s) can be sorted by providing them as an argument list to the sort method. The ``reverse`` argument also allows sorting in descending order:
+
+
+```python
+hv.output(backend='bokeh')
+
+bars = hv.Bars((['C', 'A', 'B', 'D'], [2, 7, 3, 4]))
+(bars +
+ bars.sort().relabel('sorted') +
+ bars.sort(['y']).relabel('y-sorted') +
+ bars.sort(reverse=True).relabel('reverse sorted')
+).opts(shared_axes=False).cols(2)
+```
+
+#### Working with categorical or grouped data
+
+Data is often grouped in various ways, and the Dataset interface provides various means to easily compare between groups and apply statistical aggregates. We'll start by generating some synthetic data with two groups along the x axis and 4 groups along the y axis.
+
+
+```python
+n = np.arange(1000)
+xs = np.repeat(range(2), 500)
+ys = n%4
+zs = np.random.randn(1000)
+table = hv.Table((xs, ys, zs), ['x', 'y'], 'z')
+table
+```
+
+Since there are repeat observations of the same x- and y-values, we may want to reduce the data before we display it or else use a datatype that supports plotting distributions in this way. The ``BoxWhisker`` type allows doing exactly that:
+
+
+```python
+hv.BoxWhisker(table)
+```
+
+### Aggregating/Reducing dimensions
+
+Most types require the data to be non-duplicated before being displayed.  For this purpose, HoloViews makes it easy to ``aggregate`` and ``reduce`` the data. These two operations are simple complements of each other--aggregate computes a statistic for each group in the supplied dimensions, while reduce combines all the groups except the supplied dimensions. Supplying only a function and no dimensions will simply aggregate or reduce all available key dimensions.
+
+
+```python
+hv.Bars(table).aggregate('x', function=np.mean) + hv.Bars(table).reduce(x=np.mean)
+```
+
+(**A**) aggregates over both the x and y dimension, computing the mean for each x/y group, while (**B**) reduces the x dimension leaving just the mean for each group along y.
+
+##### Collapsing multiple Dataset Elements
+
+When multiple observations are broken out into a ``HoloMap`` they can easily be combined using the ``collapse`` method. Here we create a number of Curves with increasingly larger y-values. By collapsing them with a ``function`` and a ``spreadfn`` we can compute the mean curve with a confidence interval. We then simply cast the collapsed ``Curve`` to a ``Spread`` and ``Curve`` Element to visualize them.
+
+
+```python
+hmap = hv.HoloMap({i: hv.Curve(np.arange(10)*i) for i in range(10)})
+collapsed = hmap.collapse(function=np.mean, spreadfn=np.std)
+hv.Spread(collapsed) * hv.Curve(collapsed) + hv.Table(collapsed)
+```

hvplot_docs/09-Gridded_Datasets.md

@@ -0,0 +1,294 @@
+# Gridded Datasets
+
+
+```python
+import xarray as xr
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+hv.extension('matplotlib')
+
+opts.defaults(opts.Scatter3D(color='Value', cmap='fire', edgecolor='black', s=50))
+```
+
+In the [Tabular Data](./08-Tabular_Datasets.ipynb) guide we covered how to work with columnar data in HoloViews. Apart from tabular or column based data there is another data format that is particularly common in the science and engineering contexts, namely multi-dimensional arrays. The gridded data interfaces allow working with grid-based datasets directly.
+
+Grid-based datasets have two types of dimensions:
+
+* they have coordinate or key dimensions, which describe the sampling of each dimension in the value arrays
+* they have value dimensions which describe the quantity of the multi-dimensional value arrays
+
+There are many different types of gridded datasets, which each approximate or measure a surface or space at discretely specified coordinates.  In HoloViews, gridded datasets are typically one of three possible types: Regular rectilinear grids, irregular rectilinear grids, and curvilinear grids.  Regular rectilinear grids can be defined by 1D coordinate arrays specifying the spacing along each dimension, while the other types require grid coordinates with the same dimensionality as the underlying value arrays, specifying the full n-dimensional coordinates of the corresponding array value. HoloViews provides many different elements supporting regularly spaced rectilinear grids, but currently only QuadMesh supports irregularly spaced rectilinear and curvilinear grids.
+
+The difference between uniform, rectilinear and curvilinear grids is best illustrated by the figure below:
+
+<figure>
+  <img src="http://earthsystemmodeling.org/docs/release/ESMF_8_1_1/ESMC_crefdoc/img11.png" alt="grid-types">
+  <figcaption>Types of logically rectangular grid tiles. Red circles show the values needed to specify grid coordinates for each type. Reproduced from <a href="http://earthsystemmodeling.org/docs/release/ESMF_8_1_1/ESMC_crefdoc/node5.html">ESMF documentation</a></figcaption>
+</figure>
+
+
+In this section we will first discuss how to work with the simpler rectilinear grids and then describe how to define a curvilinear grid with 2D coordinate arrays.
+
+## Declaring gridded data
+
+All Elements that support a ColumnInterface also support the GridInterface. The simplest example of a multi-dimensional (or more precisely 2D) gridded dataset is an image, which has implicit or explicit x-coordinates, y-coordinates and an array representing the values for each combination of these coordinates. Let us start by declaring an Image with explicit x- and y-coordinates:
+
+
+```python
+img = hv.Image((range(10), range(5), np.random.rand(5, 10)), datatype=['grid'])
+img
+```
+
+In the above example we defined that there would be 10 samples along the x-axis, 5 samples along the y-axis and then defined a random ``5x10`` array, matching those dimensions. This follows the NumPy (row, column) indexing convention. When passing a tuple HoloViews will use the first gridded data interface, which stores the coordinates and value arrays as a dictionary mapping the dimension name to a NumPy array representing the data:
+
+
+```python
+img.data
+```
+
+However HoloViews also ships with an interface for ``xarray`` and the [GeoViews](https://geoviews.org) library ships with an interface for ``iris`` objects, which are two common libraries for working with multi-dimensional datasets:
+
+
+```python
+arr_img = img.clone(datatype=['image'])
+print(type(arr_img.data))
+
+try: 
+    xr_img = img.clone(datatype=['xarray'])
+
+    print(type(xr_img.data))    
+except:
+    print('xarray interface could not be imported.')
+```
+
+In the case of an Image HoloViews also has a simple image representation which stores the data as a single array and converts the x- and y-coordinates to a set of bounds:
+
+
+```python
+print("Array type: %s with bounds %s" % (type(arr_img.data), arr_img.bounds))
+```
+
+To summarize the constructor accepts a number of formats where the value arrays should always match the shape of the coordinate arrays:
+
+    1. A simple np.ndarray along with (l, b, r, t) bounds
+    2. A tuple of the coordinate and value arrays
+    3. A dictionary of the coordinate and value arrays indexed by their dimension names
+    3. XArray DataArray or XArray Dataset
+    4. An Iris cube
+
+# Working with a multi-dimensional dataset
+
+A gridded Dataset may have as many dimensions as desired, however individual Element types only support data of a certain dimensionality. Therefore we usually declare a ``Dataset`` to hold our multi-dimensional data and take it from there.
+
+
+```python
+dataset3d = hv.Dataset((range(3), range(5), range(7), np.random.randn(7, 5, 3)),
+                       ['x', 'y', 'z'], 'Value')
+dataset3d
+```
+
+This is because even a 3D multi-dimensional array represents volumetric data which we can display easily only if it contains few samples. In this simple case we can get an overview of what this data looks like by casting it to a ``Scatter3D`` Element (which will help us visualize the operations we are applying to the data:
+
+
+```python
+hv.Scatter3D(dataset3d)
+```
+
+### Indexing
+
+In order to explore the dataset we therefore often want to define a lower dimensional slice into the array and then convert the dataset:
+
+
+```python
+dataset3d.select(x=1).to(hv.Image, ['y', 'z']) + hv.Scatter3D(dataset3d.select(x=1))
+```
+
+### Groupby
+
+Another common method to apply to our data is to facet or animate the data using ``groupby`` operations. HoloViews provides a convenient interface to apply ``groupby`` operations and select which dimensions to visualize. 
+
+
+```python
+(dataset3d.to(hv.Image, ['y', 'z'], 'Value', ['x']) +
+hv.HoloMap({x: hv.Scatter3D(dataset3d.select(x=x)) for x in range(3)}, kdims='x'))
+```
+
+### Aggregating
+
+Another common operation is to aggregate the data with a function thereby reducing a dimension. You can either ``aggregate`` the data by passing the dimensions to aggregate or ``reduce`` a specific dimension. Both have the same function:
+
+
+```python
+hv.Image(dataset3d.aggregate(['x', 'y'], np.mean)) + hv.Image(dataset3d.reduce(z=np.mean))
+```
+
+By aggregating the data we can reduce it to any number of dimensions we want. We can for example compute the spread of values for each z-coordinate and plot it using a ``Spread`` and ``Curve`` Element. We simply aggregate by that dimension and pass the aggregation functions we want to apply:
+
+
+```python
+hv.Spread(dataset3d.aggregate('z', np.mean, np.std)) * hv.Curve(dataset3d.aggregate('z', np.mean))
+```
+
+It is also possible to generate lower-dimensional views into the dataset which can be useful to summarize the statistics of the data along a particular dimension. A simple example is a box-whisker of the ``Value`` for each x-coordinate. Using the ``.to`` conversion interface we declare that we want a ``BoxWhisker`` Element indexed by the ``x`` dimension showing the ``Value`` dimension. Additionally we have to ensure to set ``groupby`` to an empty list because by default the interface will group over any remaining dimension.
+
+
+```python
+dataset3d.to(hv.BoxWhisker, 'x', 'Value', groupby=[])
+```
+
+Similarly we can generate a ``Distribution`` Element showing the ``Value`` dimension, group by the 'x' dimension and then overlay the distributions, giving us another statistical summary of the data:
+
+
+```python
+dataset3d.to(hv.Distribution, 'Value', [], groupby='x').overlay()
+```
+
+## Categorical dimensions
+
+The key dimensions of the multi-dimensional arrays do not have to represent continuous values, we can display datasets with categorical variables as a ``HeatMap`` Element:
+
+
+```python
+heatmap = hv.HeatMap((['A', 'B', 'C'], ['a', 'b', 'c', 'd', 'e'], np.random.rand(5, 3)))
+heatmap + hv.Table(heatmap)
+```
+
+## Non-uniform rectilinear grids
+
+As discussed above, there are two main types of grids handled by HoloViews.  So far, we have mainly dealt with uniform, rectilinear grids, but we can use the ``QuadMesh`` element to work with non-uniform rectilinear grids and curvilinear grids.
+
+In order to define a non-uniform, rectilinear grid we can declare explicit irregularly spaced x- and y-coordinates. In the example below we specify the x/y-coordinate bin edges of the grid as arrays of shape ``M+1`` and ``N+1`` and a value array (``zs``) of shape ``NxM``:
+
+
+```python
+n = 8  # Number of bins in each direction
+xs = np.logspace(1, 3, n)
+ys = np.linspace(1, 10, n)
+zs = np.arange((n-1)**2).reshape(n-1, n-1)
+print('Shape of x-coordinates:', xs.shape)
+print('Shape of y-coordinates:', ys.shape)
+print('Shape of value array:', zs.shape)
+hv.QuadMesh((xs, ys, zs))
+```
+
+## Curvilinear grids
+
+To define a curvilinear grid the x/y-coordinates of the grid should be defined as 2D arrays of shape ``NxM`` or ``N+1xM+1``, i.e. either as the bin centers or the bin edges of each 2D bin.
+
+
+```python
+n=20
+coords = np.linspace(-1.5,1.5,n)
+X,Y = np.meshgrid(coords, coords);
+Qx = np.cos(Y) - np.cos(X)
+Qy = np.sin(Y) + np.sin(X)
+Z = np.sqrt(X**2 + Y**2)
+
+print('Shape of x-coordinates:', Qx.shape)
+print('Shape of y-coordinates:', Qy.shape)
+print('Shape of value array:', Z.shape)
+
+qmesh = hv.QuadMesh((Qx, Qy, Z))
+qmesh
+```
+
+## Working with xarray data types
+As demonstrated previously, `Dataset` comes with support for the `xarray` library, which offers a powerful way to work with multi-dimensional, regularly spaced data. In this example, we'll load an example dataset, turn it into a HoloViews `Dataset` and visualize it. First, let's have a look at the xarray dataset's contents:
+
+
+```python
+xr_ds = xr.tutorial.open_dataset("air_temperature").load()
+xr_ds
+```
+
+It is trivial to turn this xarray Dataset into a Holoviews `Dataset` (the same also works for DataArray):
+
+
+```python
+hv_ds = hv.Dataset(xr_ds)[:, :, "2013-01-01"]
+print(hv_ds)
+```
+
+We have used the usual slice notation in order to select one single day in the rather large dataset. Finally, let's visualize the dataset by converting it to a `HoloMap` of `Images` using the `to()` method. We need to specify which of the dataset's key dimensions will be consumed by the images (in this case "lat" and "lon"), where the remaining key dimensions will be associated with the HoloMap (here: "time"). We'll use the slice notation again to clip the longitude.
+
+
+```python
+airtemp = hv_ds.to(hv.Image, kdims=["lon", "lat"], dynamic=False)
+airtemp[:, 220:320, :].opts(colorbar=True, fig_size=200)
+```
+
+Here, we have explicitly specified the default behaviour `dynamic=False`, which returns a HoloMap. Note, that this approach immediately converts all available data to images, which will take up a lot of RAM for large datasets. For these situations, use `dynamic=True` to generate a [DynamicMap](./07-Live_Data.ipynb) instead. Additionally, [xarray features dask support](http://xarray.pydata.org/en/stable/dask.html), which is helpful when dealing with large amounts of data.
+
+It is also possible to render curvilinear grids with xarray, and here we will load one such example. The dataset below defines a curvilinear grid of air temperatures varying over time. The curvilinear grid can be identified by the fact that the ``xc`` and ``yc`` coordinates are defined as two-dimensional arrays:
+
+
+```python
+rasm = xr.tutorial.open_dataset("rasm").load()
+rasm.coords
+```
+
+To simplify the example we will select a single timepoint and add explicit coordinates for the x and y dimensions:
+
+
+```python
+rasm = rasm.isel(time=0, x=slice(0, 200)).assign_coords(x=np.arange(200), y=np.arange(205))
+rasm.coords
+```
+
+Now that we have defined both rectilinear and curvilinear coordinates we can visualize the difference between the two by explicitly defining which set of coordinates to use:
+
+
+```python
+hv.QuadMesh(rasm, ['x', 'y']) + hv.QuadMesh(rasm, ['xc', 'yc'])
+```
+
+
+
+Additional examples of visualizing xarrays in the context of geographical data can be found in the GeoViews documentation: [Gridded Datasets I](http://geoviews.org/user_guide/Gridded_Datasets_I.html) and
+[Gridded Datasets II](http://geoviews.org/user_guide/Gridded_Datasets_II.html). These guides also contain useful information on the interaction between xarray data structures and HoloViews Datasets in general.
+
+# API
+
+## Accessing the data
+
+In order to be able to work with data in different formats Holoviews defines a general interface to access the data. The dimension_values method allows returning underlying arrays.
+
+#### Key dimensions (coordinates)
+
+By default ``dimension_values`` will return the expanded columnar format of the data:
+
+
+```python
+heatmap.dimension_values('x')
+```
+
+To access just the unique coordinates along a dimension simply supply the ``expanded=False`` keyword:
+
+
+```python
+heatmap.dimension_values('x', expanded=False)
+```
+
+Finally we can also get a non-flattened, expanded coordinate array returning a coordinate array of the same shape as the value arrays
+
+
+```python
+heatmap.dimension_values('x', flat=False)
+```
+
+#### Value dimensions
+
+When accessing a value dimension the method will similarly return a flat view of the data:
+
+
+```python
+heatmap.dimension_values('z')
+```
+
+We can pass the ``flat=False`` argument to access the multi-dimensional array:
+
+
+```python
+heatmap.dimension_values('z', flat=False)
+```

hvplot_docs/10-Indexing_and_Selecting_Data.md

@@ -0,0 +1,268 @@
+# Indexing and Selecting data
+
+As explained in the [Building composite objects](./06-Building_Composite_Objects.ipynb) and [Dimensioned Containers](./05-Dimensioned_Containers.ipynb) guides, HoloViews allows building up hierarchical containers that express the natural relationships between data items, in whatever multidimensional space best characterizes the application domain.  Once your data is in such containers, individual visualizations are then made by choosing subregions of this multidimensional space, either smaller numeric ranges (as in cropping of photographic images), or lower-dimensional subsets (as in selecting frames from a movie, or a specific movie from a large library), or both (as in selecting a cropped version of a frame from a specific movie from a large library).  
+
+In this user guide, we show how to specify such selections, using five different (but related) operations that can act on an element ``e``:
+
+| Operation      | Example syntax   |  Description |
+|:---------------|:----------------:|:-------------|
+| **indexing**   | e[5.5], e[3,5.5] | Selecting a single data value, returning one actual numerical value from the existing data
+| **slice**      | e[3:5.5], e[3:5.5,0:1] | Selecting a contiguous portion from an Element, returning the same type of Element
+| **sample**     | e.sample(y=5.5),<br>e.sample((3,3)) |  Selecting one or more regularly spaced data values, returning a new type of Element
+| **select**     | e.select(y=5.5),<br>e.select(y=(3,5.5)) | More verbose notation covering all supported slice and index operations by dimension name.
+| **iloc**       | e[2, :],<br>e[2:5, :]  | Indexes and slices by row and column tabular index supporting integer indexes, slices, lists and boolean indices.
+
+These operations are all concerned with selecting some subset of the data values, without combining across data values (e.g. averaging) or otherwise transforming the actual data. In the [Tabular Data](./08-Tabular_Datasets.ipynb) user guide we will look at additional operations on the data that reduce, summarize, or transform the data in other ways, in addition to the selections covered here.
+
+We'll be going through each operation in detail and provide a visual illustration to help make the semantics of each operation clear. This user guide assumes that you are familiar with continuous and discrete coordinate systems, so please review our [Continuous Coordinates](Continuous_Coordinates.ipynb) guide if you have not done so already.
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh', 'matplotlib')
+
+opts.defaults(
+    opts.Bounds(line_width=2, color='red', axiswise=True),
+    opts.Image(cmap='Blues'),
+    opts.Points(size=8, padding=0.1),
+    opts.Text(text_font_size='16pt'), opts.Scatter(size=5))
+```
+
+# Indexing and slicing Elements
+
+In the [Dimensioned Containers](./05-Dimensioned_Containers.ipynb) guide we saw examples of how to select individual elements embedded in a multi-dimensional space.  The [Continuous Coordinates](Continuous_Coordinates.ipynb) user guide covered slicing and indexing in Elements representing continuous coordinate coordinate systems such as ``Image`` types. Here we'll be going through each operation in full detail, providing a visual illustration to help make the semantics of each operation clear.
+
+How the ``Element`` may be indexed depends on the key dimensions (or ``kdims``) of the ``Element``. It is thus important to consider the nature and dimensionality of your data when choosing the ``Element`` type for it.
+
+## 1D Elements: Slicing and indexing
+
+Certain Chart elements support both single-dimensional indexing and slicing: ``Scatter``, ``Curve``, ``Histogram``, and ``ErrorBars``. Here we'll look at how we can easily slice a ``Histogram`` to select a subregion of it:
+
+
+```python
+np.random.seed(42)
+edges, data = np.histogram(np.random.randn(100))
+hist = hv.Histogram((edges, data))
+subregion = hist[0:1]
+hist * subregion
+```
+
+The two bins in a different color show the selected region, overlaid on top of the full histogram.  We can also access the value for a specific bin in the ``Histogram``. A continuous-valued index that falls inside a particular bin will return the corresponding value or frequency.
+
+
+```python
+hist[0.25], hist[0.5], hist[0.55]
+```
+
+We can slice a ``Curve`` the same way:
+
+
+```python
+xs = np.linspace(0, np.pi*2, 21)
+curve = hv.Curve((xs, np.sin(xs)))
+subregion = curve[np.pi/2:np.pi*1.5]
+curve * subregion * hv.Scatter(curve)
+```
+
+Here again the region in a different color is the specified subregion. We've also marked each discrete point with a dot using the ``Scatter`` ``Element``.  As before we can also get the value for a specific sample point; whatever x-index is provided will snap to the closest sample point and return the dependent value:
+
+
+```python
+curve[4.05], curve[4.1], curve[4.17], curve[4.3]
+```
+
+It is important to note that an index (or a list of indices, as for the 2D and 3D cases below) will always return the raw indexed (dependent) value, i.e. a number.  A slice (indicated with `:`), on the other hand, will retain the Element type even in cases where the plot might not be useful, such as having only a single value, two values, or no value at all in that range:
+
+
+```python
+curve[4:4.5]
+```
+
+## 2D and 3D Elements: slicing
+
+For data defined in a 2D space, there are 2D equivalents of the 1D ``Curve`` and ``Scatter`` types. ``Points``, for example, can be thought of as a number of points in a 2D space.
+
+
+```python
+r = np.arange(0, 1, 0.005)
+xs, ys = (r * fn(85*np.pi*r) for fn in (np.cos, np.sin))
+paths = hv.Points((xs, ys))
+paths + paths[0:1, 0:1]
+```
+
+However, indexing is not supported in this space, because there could be many possible points near a given set of coordinates, and finding the nearest one would require a search across potentially incommensurable dimensions, which is poorly defined and difficult to support.
+
+Slicing in 3D works much like slicing in 2D, but indexing is not supported for the same reason as in 2D:
+
+
+```python
+xs = np.linspace(0, np.pi*8, 201)
+scatter = hv.Scatter3D((xs, np.sin(xs), np.cos(xs)))
+layout = scatter + scatter[5:10, :, 0:]
+hv.output(layout, backend='matplotlib')
+```
+
+## 2D Raster and Image: slicing and indexing
+
+Raster and the various other image-like objects (Images, RGB, HSV, etc.) can all be sliced and indexed, as can Surface, because they all have an underlying regular grid of key dimension values:
+
+
+```python
+np.random.seed(0)
+extents = (0, 0, 10, 10)
+img = hv.Image(np.random.rand(10, 10), bounds=extents)
+img_slice = img[1:9,4:5]
+box = hv.Bounds((1,4,9,5))
+img*box + img_slice
+```
+
+
+```python
+img[4.2,4.2], img[4.3,4.2], img[5.0,4.2]
+```
+
+# Tabular indexing and slicing
+
+While most indexing in HoloViews works by selecting the values along a dimension it is also frequently useful to index and slice using integer row and column indices. For this purpose most HoloViews objects have a ``.iloc`` indexing interface (mirroring the [pandas](http://pandas.pydata.org/pandas-docs/stable/indexing.html#different-choices-for-indexing) API), which supports all the usual indexing semantics. Supported iloc arguments include:
+
+* An integer e.g. 5
+
+* A list or array of integers [4, 3, 0]
+
+* A slice object with ints 1:7
+
+* A boolean array
+
+#### Indexing
+
+In this way we can for example select the x- and y-values in the 8th row of our ``Curve``:
+
+
+```python
+xs = np.linspace(0, np.pi*2, 21)
+curve = hv.Curve((xs, np.sin(xs)))
+print('x: %s, y: %s' % (curve.iloc[8, 0], curve.iloc[8, 1]))
+curve * hv.Scatter(curve.iloc[8])
+```
+
+#### Slicing
+
+Alternatively we can select every second sample between indices 5 and 16 of a ``Curve``:
+
+
+```python
+curve + curve.iloc[5:16:2]
+```
+
+#### Lists of integers and boolean indices
+
+Finally we may also pass a list of the integer samples to select, or use boolean indices. This mode of indexing can be very useful for randomly sampling an Element or picking a specific set of rows or (columns):
+
+
+```python
+curve.iloc[[0, 5, 10, 15, 20]] + curve.iloc[xs>3]
+```
+
+# Sampling
+
+Sampling is essentially a process of indexing an Element at multiple index locations, and collecting the results.  Thus any Element that can be indexed can also be sampled.  Compared to regular indexing, sampling is different in that  multiple indices may be supplied at the same time.  Also, indexing will only return the value at that location, whereas the return type from a sampling operation is another ``Element`` type, usually either a ``Table`` or a ``Curve``, to allow both key and value dimensions to be returned.
+
+### Sampling Elements
+
+Sampling can use either an explicit list of indexes, or pass an index value for each dimension keyword argument.
+
+We'll start by taking a single sample of an Image object, to make clear how sampling and indexing are similar operations yet different in their results:
+
+
+```python
+img_coords = hv.Points(img, extents=extents)
+labeled_img = img * img_coords * hv.Points([img.closest([(4.1,4.3)])]).opts(color='r')
+img + labeled_img + img.sample([(4.1,4.3)])
+```
+
+
+```python
+img[4.1,4.3]
+```
+
+Here, the output of the indexing operation is the value (0.20887675609483469) from the location closest to the specified indexes, whereas ``.sample()`` returns a Table that lists both the coordinates *and* the value, and slicing (in previous section) returns an Element of the same type, not a Table.
+
+
+Next we can try sampling along only one Dimension on our 2D Image, leaving us with a 1D Element (in this case a ``Curve``):
+
+
+```python
+sampled = img.sample(y=5)
+labeled_img = img * img_coords * hv.Points(zip(sampled['x'], [img.closest(y=5)]*10))
+img + labeled_img + sampled
+```
+
+Sampling works on any regularly sampled Element type.  For example, we can select multiple samples along the x-axis of a Curve.
+
+
+```python
+xs = np.arange(10)
+samples = [2, 4, 6, 8]
+curve = hv.Curve(zip(xs, np.sin(xs)))
+curve_samples = hv.Scatter(zip(xs, [0] * 10)) * hv.Scatter(zip(samples, [0]*len(samples))) 
+curve + curve_samples + curve.sample(samples)
+```
+
+### Sampling HoloMaps
+
+Sampling is often useful when you have more data than you wish to visualize or analyze at one time. First, let's create a HoloMap containing a number of observations of some noisy data.
+
+
+```python
+obs_hmap = hv.HoloMap({i: hv.Image(np.random.randn(10, 10), bounds=extents)
+                       for i in range(3)}, kdims='Observation')
+```
+
+A `HoloMap` may not be sampled directly, instead we can use the `.apply` method to sample each element in the HoloMap and consequently use the `.collapse` method to produce a single `Dataset`. In this case we'll take 3x3 subsamples of each of the Images:
+
+
+```python
+hv.output(backend='matplotlib', size=120)
+
+sample_style = dict(edgecolors='k', alpha=1)
+all_samples = obs_hmap.collapse().to.scatter3d().opts(alpha=0.15, xticks=4)
+sampled = obs_hmap.apply.sample((3,3)).collapse()
+subsamples = sampled.to.scatter3d().opts(**sample_style)
+all_samples * subsamples + hv.Table(sampled)
+```
+
+By supplying bounds in as a (left, bottom, right, top) tuple we can also sample a subregion of our images:
+
+
+```python
+sampled = obs_hmap.apply.sample((3,3), bounds=(2,5,5,10)).collapse()
+subsamples = sampled.to.scatter3d().opts(xticks=4, **sample_style)
+all_samples * subsamples + hv.Table(sampled)
+```
+
+Since this kind of sampling is only well supported for continuous coordinate systems, we can only apply this kind of sampling to Image types for now.
+
+### Sampling Charts
+
+Sampling Chart-type Elements like Curve, Scatter, Histogram is only supported by providing an explicit list of samples, since those Elements have no underlying regular grid.
+
+
+```python
+hv.output(backend='bokeh')
+
+xs = np.arange(10)
+extents = (0, 0, 2, 10)
+curve = hv.HoloMap({(i) : hv.Curve(zip(xs, np.sin(xs)*i))
+                    for i in np.linspace(0.5, 1.5, 3)},
+                   kdims='Observation')
+all_samples = curve.collapse().to.points()
+sampled = curve.apply.sample([0, 2, 4, 6, 8]).collapse()
+sample_points = sampled.to.points(extents=extents)
+sampling = all_samples * sample_points.opts(color='red')
+sampling + hv.Table(sampled)
+```
+
+These tools should help you index, slice, sample, and select your data with ease.  The [Tabular Data](./07-Tabular_Data.ipynb) guide explains how to do other types of operations, such as averaging and other reduction operations.

hvplot_docs/11-Transforming_Elements.md

@@ -0,0 +1,336 @@
+# Applying Transformations
+
+
+```python
+import param
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh', 'matplotlib')
+```
+
+HoloViews objects provide a convenient way of wrapping your data along with some metadata for exploration and visualization. For the simplest visualizations, you can simply declare a small collection of elements which can then be composed or placed in an appropriate container. As soon as the task becomes more complex, it is natural to write functions that output HoloViews objects.
+
+In this user guide, we will introduce to related concepts to express transforms of some data, first we will cover `dim` transforms to express simple transforms of some data and then ``Operation`` classes to express more complex transformations. Operations provide a consistent structure for such code, making it possible to write general functions that can process HoloViews objects. This enables powerful new ways of specifying HoloViews objects computed from existing data, allowing the construction of flexible data processing pipelines. Examples of such operations are ``histogram``, ``rolling``, ``datashade`` or ``decimate``, which apply some computation on certain types of Element and return a new Element with the transformed data.
+
+In this user guide we will discover how transforms and operations work, how to control their parameters and how to chain them. The [Data Processing Pipelines](./14-Data_Pipelines.ipynb) guide extends what we will have learned to demonstrate how operations can be applied lazily by using the ``dynamic`` flag, letting us define deferred processing pipelines that can drive highly complex visualizations and dashboards.
+
+## Transforms
+
+A transform is expressed using a `dim` expression, which we originally introduced in the context of the [Style Mapping](./04-Style_Mapping.ipynb) user guide. It allows expressing some deferred computation on a HoloViews Element. This can be a powerful way to transform some 
+data quickly and easily. Let us start by declaring a `Dataset` with a single dimension `x`:
+
+
+```python
+ds = hv.Dataset(np.linspace(0, np.pi), 'x')
+ds
+```
+
+The `Dataset` x values consist of an array of monotonically increasing values from 0 to np.pi. We can now define a transform which takes these values and transform them:
+
+
+```python
+expr = np.sin(hv.dim('x')*10+5)
+expr
+```
+
+This expression takes these values multiplies them by 10, adds 5 and then calculates the `sine`. Using the `.transform` method we can now apply this expression to the `Dataset` and assign the values to a newly created `y` dimension by supplying it as a keyword (in the same way we could override the `x` dimension):
+
+
+```python
+transformed = ds.transform(y=expr)
+transformed
+```
+
+We can see the result of this by casting it to a `Curve`:
+
+
+```python
+hv.Curve(transformed)
+```
+
+This allows almost any mathematical transformation to be expressed and applied on a `Dataset` in a deferred way. The regular `dim` expression supports all the  standard mathematical operators and NumPy array methods. However if we want to use methods which exist only on specific datatypes we can invoke them using `.df` or `.xr`, which let you make (pandas) dataframe and xarray API (method and accessor) calls respectively. Let us for example load an XArray Dataset, which has a number of custom methods to perform complex computations on the data, e.g. the quantile method:
+
+
+```python
+import xarray as xr
+
+air_temp = xr.tutorial.load_dataset('air_temperature')
+print(air_temp.quantile.__doc__)
+```
+
+We can construct an expression to apply this method on the data and compute the 95th percentile of air temperatures along the 'time' dimension:
+
+
+```python
+quantile_expr = hv.dim('air').xr.quantile(0.95, dim='time')
+quantile_expr
+```
+
+Now we can apply this to the `Dataset` using the `transform` method, in the resulting dataset we can see that the time dimension has been dropped:
+
+
+```python
+temp_ds = hv.Dataset(air_temp, ['lon', 'lat', 'time'])
+
+transformed_ds = temp_ds.transform(air=quantile_expr)
+
+transformed_ds
+```
+
+To visualize this data we will cast it to an `Image`:
+
+
+```python
+hv.Image(transformed_ds)
+```
+
+The real power of `dim` transforms comes in when combining them with parameters. We will look at this in more detail later as part of the [Pipeline user guide](14-Data_Pipelines.ipynb) but let's quickly see what this looks like. We will create a [Panel](https://panel.holoviz.org) slider to control the `q` value in the call to the `quantile` method:
+
+
+```python
+import panel as pn
+
+q = pn.widgets.FloatSlider(name='quantile')
+
+quantile_expr = hv.dim('air').xr.quantile(q, dim='time')
+quantile_expr
+```
+
+Now that we have expressed this dynamic `dim` transform let us apply it using `.apply.transform`:
+
+
+```python
+temp_ds = hv.Dataset(air_temp, ['lon', 'lat'])
+transformed = temp_ds.apply.transform(air=quantile_expr).apply(hv.Image)
+
+pn.Column(q, transformed.opts(colorbar=True, width=400))
+```
+
+`dim` expressions provide a very powerful way to apply transforms on your data either statically or controlled by some external parameter, e.g. one driven by a Panel widget.
+
+## Operations are parameterized
+
+In cases a simple transform is not sufficient or you want to encapsulate some transformation in a more rigorous way an `Operation` allows encapsulating the parameters of a transform on a function-like object. Operations in HoloViews are subclasses of ``Operation``, which transform one Element or ``Overlay`` of Elements by returning a new Element that may be a transformation of the original. All operations are parameterized using the [param](https://github.com/holoviz/param) library which allows easy validation and documentation of the operation arguments. In particular, operations are instances of ``param.ParameterizedFunction`` which allows operations to be used in the same way as normal python functions.
+
+This approach has several advantages, one of which is that we can manipulate the parameters of operations at several different levels: at the class-level, at the instance-level or when it is called. Another advantage is that using parameterizing operations allows them to be inspected just like any other HoloViews object using ``hv.help``. We will now do this for the ``histogram`` operation:
+
+
+```python
+from holoviews.operation import histogram
+hv.help(histogram)
+```
+
+## Applying operations
+
+Above we can see a listing of all the parameters of the operation, with the defaults, the expected types and detailed docstrings for each one. The ``histogram`` operation can be applied to any Element and will by default generate a histogram for the first value dimension defined on the object it is applied to. As a simple example we can create an ``BoxWhisker`` Element containing samples from a normal distribution, and then apply the ``histogram`` operation to those samples in two ways: 1) by creating an instance on which we will change the ``num_bins`` and 2) by passing ``bin_range`` directly when calling the operation:
+
+
+```python
+boxw = hv.BoxWhisker(np.random.randn(10000))
+histop_instance = histogram.instance(num_bins=50)
+
+boxw + histop_instance(boxw).relabel('num_bins=50') + histogram(boxw, bin_range=(0, 3)).relabel('bin_range=(0, 3)')
+```
+
+We can see that these two ways of using operations gives us convenient control over how the parameters are applied. An instance allows us to persist some defaults which will be used in all subsequent calls, while passing keyword arguments to the operations applies the parameters for just that particular call.
+
+The third way to manipulate parameters is to set them at the class level. If we always want to use ``num_bins=30`` instead of the default of ``num_bins=20`` shown in the help output above, we can simply set ``histogram.num_bins=30``. 
+
+## Operations on containers
+
+``Operations`` in HoloViews are applied to individual elements, which means that when you apply an operation to a container object (such as ``NdLayout``, ``GridSpace`` and ``HoloMap``) the operation is applied once per element. For an operation to work, all the elements must be of the same type which means the operation effectively acts to map the operation over all the contained elements. As a simple example we can define a HoloMap of ``BoxWhisker`` Elements by varying the width of the distribution via the ``Sigma`` value and then apply the histogram operation to it:
+
+
+```python
+holomap = hv.HoloMap({(i*0.1+0.1): hv.BoxWhisker(np.random.randn(10000)*(i*0.1+0.1)) for i in range(5)},
+                     kdims='Sigma')
+holomap + histogram(holomap)
+```
+
+As you can see the operation has generated a ``Histogram`` for each value of ``Sigma`` in the ``HoloMap``. In this way we can apply the operation to the entire parameter space defined by a ``HoloMap``, ``GridSpace``, and ``NdLayout``.
+
+## Combining operations
+
+Since operations take a HoloViews object as input and return another HoloViews object we can very easily chain and combine multiple operations to perform complex analyses quickly and easily, while instantly visualizing the output.
+
+In this example we'll work with operations on timeseries. We first define a small function to generate a random, noisy timeseries:
+
+
+```python
+from holoviews.operation import timeseries
+
+def time_series(T = 1, N = 100, mu = 0.1, sigma = 0.1, S0 = 20):  
+    """Parameterized noisy time series"""
+    dt = float(T)/N
+    t = np.linspace(0, T, N)
+    W = np.random.standard_normal(size = N) 
+    W = np.cumsum(W)*np.sqrt(dt)       # standard brownian motion
+    X = (mu-0.5*sigma**2)*t + sigma*W 
+    S = S0*np.exp(X)                   # geometric brownian motion
+    return S
+
+curve = hv.Curve(time_series(N=1000)).opts(width=600)
+```
+
+Now we will start applying some operations to this data. HoloViews ships with two ready-to-use timeseries operations: the ``rolling`` operation, which applies a function over a rolling window, and a ``rolling_outlier_std`` operation that computes outlier points in a timeseries by excluding points less than ``sigma`` standard deviation removed from the rolling mean:
+
+
+```python
+smoothed = curve * timeseries.rolling(curve) * timeseries.rolling_outlier_std(curve)
+smoothed.opts(opts.Scatter(color='black'))
+```
+
+In the next section we will define a custom operation that will compose with the ``smoothed`` operation output above to form a short operation pipeline.
+
+## Defining custom operations
+
+We can now define our own custom ``Operation`` which as you may recall can process either elements and overlays. This means we can define a simple operation that takes our ``smoothed`` overlay and computes the difference between the raw and smoothed curves that it contains. Such a subtraction will give us the residual between the smoothed and unsmoothed ``Curve`` elements, removing long-term trends and leaving the short-term variation.
+
+Defining an operation is very simple. An ``Operation`` subclass should define a ``_process`` method, which simply accepts an ``element`` argument. Optionally we can also define parameters on the operation, which we can access using the ``self.p`` attribute on the operation. In this case we define a ``String`` parameter, which specifies the name of the subtracted value dimension on the returned Element.
+
+
+```python
+from holoviews.operation import Operation
+
+class residual(Operation):
+    """
+    Subtracts two curves from one another.
+    """
+    
+    label = param.String(default='Residual', doc="""
+        Defines the label of the returned Element.""")
+    
+    def _process(self, element, key=None):
+        # Get first and second Element in overlay
+        el1, el2 = element.get(0), element.get(1)
+        
+        # Get x-values and y-values of curves
+        xvals  = el1.dimension_values(0)
+        yvals  = el1.dimension_values(1)
+        yvals2 = el2.dimension_values(1)
+        
+        # Return new Element with subtracted y-values
+        # and new label
+        return el1.clone((xvals, yvals-yvals2),
+                         vdims=self.p.label)
+```
+
+Having defined the residual operation let's try it out right away by applying it to our original and smoothed ``Curve``. We'll place the two objects on top of each other so they can share an x-axis and we can compare them directly:
+
+
+```python
+(smoothed + residual(smoothed).opts(xaxis=None)).cols(1)
+```
+
+In this view we can immediately see that only a very small residual is left when applying this level of smoothing. However we have only tried one particular ``rolling_window`` value, the default value of ``10``. To assess how this parameter affects the residual we can evaluate the operation over a number different parameter settings, as we will see in the next section.
+
+## Evaluating operation parameters
+
+When applying an operation there are often parameters to vary. Using traditional plotting approaches it's often difficult to evaluate them interactively to get a detailed understanding of what they do. Here we will apply the ``rolling`` operations with varying ``rolling_window`` widths and ``window_type``s across a ``HoloMap``:
+
+
+```python
+rolled = hv.HoloMap({(w, str(wt)): timeseries.rolling(curve, rolling_window=w, window_type=wt)
+                     for w in [10, 25, 50, 100, 200] for wt in [None, 'hamming', 'triang']},
+                    kdims=['Window', 'Window Type'])
+rolled
+```
+
+This visualization is already useful since we can compare the effect of various parameter values by moving the slider and trying different window options. However since we can also chain operations we can easily compute the residual and view the two together. 
+
+To do this we simply overlay the ``HoloMap`` of smoothed curves on top of the original curve and pass it to our new ``residual`` function. Then we can combine the smoothed view with the original and see how the smoothing and residual curves vary across parameter values:
+
+
+```python
+(curve * rolled + residual(curve * rolled)).cols(1)
+```
+
+Using a few additional lines we have now evaluated the operation over a number of different parameters values, allowing us to process the data with different smoothing parameters. In addition, by interacting with this visualization we can gain a better understanding of the operation parameters as well as gain insights into the structure of the underlying data.
+
+## Operations on 2D elements
+
+Let's look at another example of operations in action, this time applying a simple filter to an `Image`. The basic idea is the same as above, although accessing the values to be transformed is a bit more complicated. First, we prepare an example image:
+
+
+```python
+hv.output(backend='matplotlib', size=200)
+
+from scipy.misc import ascent
+
+stairs_image = hv.Image(ascent()[200:500, :], bounds=[0, 0, ascent().shape[1], 300], label="stairs")
+stairs_image
+```
+
+We'll define a simple ``Operation``, which takes an ``Image`` and applies a high-pass or low-pass filter. We then use this to build a ``HoloMap`` of images filtered with different sigma values:
+
+
+```python
+from scipy import ndimage
+
+class image_filter(hv.Operation):
+    
+    sigma = param.Number(default=5)
+    
+    type_ = param.String(default="low-pass")
+
+    def _process(self, element, key=None):
+        xs = element.dimension_values(0, expanded=False)
+        ys = element.dimension_values(1, expanded=False)
+        
+        # setting flat=False will preserve the matrix shape
+        data = element.dimension_values(2, flat=False)
+        
+        if self.p.type_ == "high-pass":
+            new_data = data - ndimage.gaussian_filter(data, self.p.sigma)
+        else:
+            new_data = ndimage.gaussian_filter(data, self.p.sigma)
+        
+        label = element.label + " ({} filtered)".format(self.p.type_)
+        # make an exact copy of the element with all settings, just with different data and label:
+        element = element.clone((xs, ys, new_data), label=label)
+        return element
+
+stairs_map = hv.HoloMap({sigma: image_filter(stairs_image, sigma=sigma)
+                         for sigma in range(0, 12, 1)}, kdims="sigma")
+
+stairs_map.opts(framewise=True)
+```
+
+Just as in the previous example, it is quite straight-forward to build a HoloMap containing results for different parameter values. Inside the ``_process()`` method, the given parameters can be accessed as ``self.p.<parameter-name>`` (note that ``self.<parameter_name>`` always contains the default value!). Since we did not specify the ``type_`` parameter, it defaulted to "low-pass".
+
+There are some peculiarities when applying operations to two-dimensional elements:
+
+- Understanding the ``dimension_values()`` method: In principle, one could use ``element.data`` to access the element's data, however, since HoloViews can wrap a wide range of data formats, ``dimension_values()`` provides an API that lets you access the data without having to worry about the type of the data. The first parameter specifies the dimension to be returned. On a 2D element like an Image or Raster the first two dimensions reference the key dimensions, so passing an index of 0 or 1 will return the x- and y-axis values respectively. Any subsequent dimensions will be value dimensions, e.g. on an Image index value 2 will refer to the intensity values and on an RGB index values 2, 3, and 4 will return the Red, Green and Blue intensities instead. Setting ``expanded=False`` yields only the axis, while the default setting ``expanded=True`` returns a value for every pixel. Specifying ``flat=False`` means that the data's matrix shape will be preserved, which is what we need for this kind of filter.
+- ``Image`` and related classes come with convenient methods to convert between matrix indices and data coordinates and vice versa: ``matrix2sheet()`` and ``sheet2matrix()``. This is useful when searching for features such as peaks.
+
+A very powerful aspect of operations is the fact that they understand Holoviews data structures. This means it is very straight-forward to apply an operation to every element in a container. As an example, let's apply an additional high-pass filter to our HoloMap:
+
+
+```python
+image_filter(stairs_map, type_="high-pass").opts(framewise=True)
+```
+
+Note, that the sigma value for the high-pass filter has defaulted to 5, and the sigma value in the HoloMap still corresponds to the original low-pass filter.
+
+
+## Benefits of using ``Operation``
+
+Now that we have seen some operations in action we can get some appreciation of what makes them useful. When working with data interactively we often end up applying a lot of ad-hoc data transforms, which provides maximum flexibility but is neither reproducible nor maintainable. Operations allow us to encapsulate analysis code using a well defined interface that is well suited for building complex analysis pipelines:
+
+1. ``Operation`` parameters are well defined by declaring parameters on the class. These parameters can be easily documented and automatically carry out validation on the types and ranges of the inputs. These parameters are documented using ``hv.help``.
+
+2. Both inputs and outputs of an operation are instantly visualizable, because the data **is** the visualization. This means you're not constantly context switching between data processing and visualization --- visualization comes for free as you build your data processing pipeline.
+
+3. Operations understand HoloViews datastructures and can be immediately applied to any appropriate collection of elements, allowing you to evaluate the operation with permutations of parameter values. This flexibility makes it easy to assess the effect of operation parameters and their effect on your data.
+
+4. As we will discover in the [Data processing pipelines](./14-Data_Pipelines.ipynb) guide, operations can be applied lazily to build up complex deferred data-processing pipelines, which can aid your data exploration and drive interactive visualizations and dashboards.
+
+## Other types of operation
+
+As we have seen ``Operation`` is defined at the level of processing HoloViews elements or overlays of elements. In some situations, you may want to compute a new HoloViews datastructure from a number of elements contained in a structure other than an overlay, such as a HoloMap or a Layout. 
+
+One such pattern is an operation that accepts and returns a ``HoloMap`` where each of the output element depends on all the data in the input ``HoloMap``. For situations such as these, subclassing ``Operation`` is not appropriate and we recommend defining your own function. These custom operation types won't automatically gain support for lazy pipelines as described in the [Data processing pipelines](./14-Data_Pipelines.ipynb) guide and how these custom operations are pipelined is left as a design decision for the user. Note that as long as these functions return simple elements or containers, their output can be used by subclasses of ``Operation`` as normal. 
+
+What we *do* recommend is that you subclass from ``param.ParameterizedFunction`` so that you can declare well-documented and validated parameters, add a description of your operation with a class level docstring and gain automatic documentation support via ``hv.help``.

hvplot_docs/12-Responding_to_Events.md

@@ -0,0 +1,511 @@
+# Responding to Events
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh')
+```
+
+In the [Live Data](./07-Live_Data.ipynb) guide we saw how ``DynamicMap`` allows us to explore high dimensional data using the widgets in the same style as ``HoloMaps``. Although suitable for unbounded exploration of large parameter spaces, the ``DynamicMaps`` described in that notebook support exactly the same mode of interaction as ``HoloMaps``. In particular, the key dimensions are used to specify a set of widgets that when manipulated apply the appropriate indexing to invoke the user-supplied callable.
+
+In this user guide we will explore the HoloViews streams system that allows *any* sort of value to be supplied from *anywhere*. This system opens a huge set of new possible visualization types, including continuously updating plots that reflect live data as well as dynamic visualizations that can be interacted with directly, as described in the [Custom Interactivity](./13-Custom_Interactivity.ipynb) guide.
+
+<center><div class="alert alert-info" role="alert">To use visualize and use a <b>DynamicMap</b> you need to be running a live Jupyter server.<br>When viewing this user guide as part of the documentation DynamicMaps will be sampled with a limited number of states.<br></div></center>
+
+
+```python
+# Styles and plot options used in this user guide
+
+opts.defaults(
+    opts.Area(fill_color='cornsilk', line_width=2,
+              line_color='black'),
+    opts.Ellipse(bgcolor='white', color='black'),
+    opts.HLine(color='red', line_width=2),
+    opts.Image(cmap='viridis'),
+    opts.Path(bgcolor='white', color='black', line_dash='dashdot',
+              show_grid=False),
+    opts.VLine(color='red', line_width=2))
+```
+
+## A simple ``DynamicMap``
+
+Before introducing streams, let us declare a simple ``DynamicMap`` of the sort discussed in the [Live Data](07-Live_Data.ipynb) user guide. This example consists of a ``Curve`` element showing a [Lissajous curve](https://en.wikipedia.org/wiki/Lissajous_curve) with ``VLine`` and ``HLine`` annotations to form a crosshair:
+
+
+```python
+lin = np.linspace(-np.pi,np.pi,300)
+
+def lissajous(t, a=3, b=5, delta=np.pi/2.):
+    return (np.sin(a * t + delta), np.sin(b * t))
+
+def lissajous_crosshair(t, a=3, b=5, delta=np.pi/2):
+    (x,y) = lissajous(t,a,b,delta)
+    return hv.VLine(x) * hv.HLine(y)
+
+crosshair = hv.DynamicMap(lissajous_crosshair, kdims='t').redim.range(t=(-3.,3.))
+
+path = hv.Path(lissajous(lin))
+
+path * crosshair
+```
+
+As expected, the declared key dimension (``kdims``) has turned into a slider widget that lets us move the crosshair along the curve. Now let's see how to position the crosshair using streams.
+
+## Introducing streams
+
+
+
+The core concept behind a stream is simple: it defines one or more parameters that can change over time that automatically refreshes code depending on those parameter values. 
+
+Like all objects in HoloViews, these parameters are declared using [param](https://param.holoviz.org/) and streams are defined as a parameterized subclass of the ``holoviews.streams.Stream``. A more convenient way is to use the ``Stream.define`` classmethod:
+
+
+```python
+from holoviews.streams import Stream, param
+Time = Stream.define('Time', t=0.0)
+```
+
+This results in a ``Time`` class with a numeric ``t`` parameter that defaults to zero. As this object is parameterized, we can use ``hv.help`` to view its parameters:
+
+
+```python
+hv.help(Time)
+```
+
+This parameter is a ``param.Number`` as we supplied a float, if we had supplied an integer it would have been a ``param.Integer``. Notice that there is no docstring in the help output above but we can add one by explicitly defining the parameter as follows:
+
+
+```python
+Time = Stream.define('Time', t=param.Number(default=0.0, doc='A time parameter'))
+hv.help(Time)
+```
+
+Now we have defined this ``Time`` stream class, we can make of an instance of it and look at its parameters:
+
+
+```python
+time_dflt = Time()
+print('This Time instance has parameter t={t}'.format(t=time_dflt.t))
+```
+
+As with all parameterized classes, we can choose to instantiate our parameters with suitable values instead of relying on defaults.
+
+
+```python
+time = Time(t=np.pi/4)
+print('This Time instance has parameter t={t}'.format(t=time.t))
+```
+
+For more information on defining ``Stream`` classes this way, use ``hv.help(Stream.define)``.
+
+### Simple streams example
+
+We can now supply this streams object to a ``DynamicMap`` using the same ``lissajous_crosshair`` callback from above by adding it to the ``streams`` list:
+
+
+```python
+dmap = hv.DynamicMap(lissajous_crosshair, streams=[time])
+path * dmap + path * lissajous_crosshair(t=np.pi/4.)
+```
+
+Immediately we see that the crosshair position of the ``DynamicMap`` reflects the ``t`` parameter values we set on the ``Time`` stream. This means that the ``t`` parameter  was supplied as the argument  to the ``lissajous_curve`` callback. As we now have no key dimensions, there is no longer a widget for the ``t`` dimensions.
+
+Although we have what looks like a static plot, it is in fact dynamic and can be updated in place at any time. To see this, we can call the ``event`` method on our ``DynamicMap``:
+
+
+
+```python
+dmap.event(t=0.2)
+```
+
+Running this cell will have updated the crosshair from its original position where $t=\frac{\pi}{4}$ to a new position where ``t=0.2``. Try running the cell above with different values of ``t`` and watch the plot update!
+
+This ``event`` method is the recommended way of updating the stream parameters on a ``DynamicMap`` but if you have a handle on the relevant stream instance, you can also call the ``event`` method on that:
+
+
+```python
+time.event(t=-0.2)
+```
+
+Running the cell above also moves the crosshair to a new position. As there are no key dimensions, there is only a single valid (empty) key that can be accessed with ``dmap[()]`` or ``dmap.select()`` making ``event`` the only way to explore new parameters.
+
+We will examine the ``event`` method and the machinery that powers streams in more detail later in the user guide after we have looked at more examples of how streams are used in practice.
+
+### Working with multiple streams
+
+The previous example showed a curve parameterized by a single dimension ``t``. Often you will have multiple stream parameters you would like to declare as follows:
+
+
+```python
+ls = np.linspace(0, 10, 200)
+xx, yy = np.meshgrid(ls, ls)
+
+XY = Stream.define('XY',x=0.0,y=0.0)
+
+def marker(x,y):
+    return hv.VLine(x) * hv.HLine(y)
+
+image = hv.Image(np.sin(xx)*np.cos(yy))
+
+dmap = hv.DynamicMap(marker, streams=[XY()])
+
+image * dmap
+```
+
+You can update both ``x`` and ``y`` by passing multiple keywords to the ``event`` method:
+
+
+```python
+dmap.event(x=-0.2, y=0.1)
+```
+
+Note that the definition above behaves the same as the following definition where we define separate ``X`` and ``Y`` stream classes:
+
+```python
+X = Stream.define('X',x=0.0)
+Y = Stream.define('Y',y=0.0)
+hv.DynamicMap(marker, streams=[X(), Y()])
+```
+
+The reason why you might want to list multiple streams instead of always defining a single stream containing all the required stream parameters will be made clear in the [Custom Interactivity](./13-Custom_Interactivity.ipynb) guide.
+
+## Using Parameterized classes as a stream
+
+Creating a custom ``Stream`` class is one easy way to declare parameters. However, there's no need to make a Stream if you have already expressed your domain knowledge on a ``Parameterized`` class. For instance, let's assume you have made a simple parameterized `BankAccount` class:
+
+
+
+```python
+class BankAccount(param.Parameterized):
+    balance = param.Number(default=0, doc="Bank balance in USD")
+    overdraft = param.Number(default=200, doc="Overdraft limit")
+
+account = BankAccount(name='Jane', balance=300)
+```
+
+You can link parameter changes straight to DynamicMap callable parameters by passing a keyword:param dictionary to the `streams` argument (for HoloViews version >= 1.14.2):
+
+
+```python
+streams = dict(total=account.param.balance, overdraft=account.param.overdraft, owner=account.param.name)
+
+def table(owner, total, overdraft):
+    return hv.Table([(owner, overdraft, total)], ['Owner', 'Overdraft ($)', 'Total ($)'])
+
+bank_dmap = hv.DynamicMap(table, streams=streams)
+bank_dmap.opts(height=100)
+```
+
+Now as you set the `balance` parameter on the `janes_account` instance, the DynamicMap above updates. Note that the dictionary specifies that the `balance` parameter is mapped to the `total` argument of the callable.
+
+
+```python
+account.balance=65.4
+account.overdraft=350
+```
+
+### Use with `panel`
+
+This dictionary format is particularly useful when used with the [Panel](http://panel.pyviz.org/) library (a dependency of HoloViews that should always be available), because `panel` widgets always reflect their values on the `value` parameter. This means that if you declare two Panel widgets as follows:
+
+
+```python
+import panel as pn
+
+slider = pn.widgets.FloatSlider(start=0, end=500, name='Balance')
+checkbox = pn.widgets.Select(options=['student','regular', 'savings'], name='Account Type')
+pn.Row(slider, checkbox)
+```
+
+You can map both widget values into a `DynamicMap` callback without having a name clash as follows:
+
+
+```python
+overdraft_limits = {'student':300, 'regular':100, 'savings':0} # Overdraft limits for different account types
+streams = dict(owner=account.param.name, total=slider.param.value, acc=checkbox.param.value)
+
+def account_info(owner, total, acc):
+    return hv.Table([(owner, acc, overdraft_limits[acc], total)], 
+                    ['Owner', 'Account Type', 'Overdraft ($)', 'Total ($)'])
+
+widget_dmap = hv.DynamicMap(account_info, streams=streams)
+widget_dmap.opts(height=100)
+```
+
+
+You can now update the plot above using the slider and dropdown widgets. Note that for all these examples, a `Params` stream is created internally. This type of stream can wrap Parameterized objects or sets of Parameters but (since HoloViews 1.10.8) it is rare that an explicit stream object like that needs to be used directly at the user level.  To see more examples of how to use Panel with HoloViews, see the [Dashboards user guide](./16-Dashboards.ipynb).
+
+### Using `.apply.opts`
+
+You can supplying Parameters in a similar manner to the `.apply.opts` method. In the following example, a `Style` class has Parameters that indicate the desired colorma and color levels for the `image` instance defined earlier. We can link these together as follows:
+
+
+```python
+class Style(param.Parameterized):
+
+    colormap = param.ObjectSelector(default='viridis', objects=['viridis', 'plasma', 'magma'])
+
+    color_levels = param.Integer(default=255, bounds=(1, 255))
+
+style = Style()
+image.apply.opts(colorbar=True, width=400, cmap=style.param.colormap, color_levels=style.param.color_levels)
+```
+
+Using the `.apply` accessor in this automatically makes the resulting `DynamicMap` depend on the streams specified by the Parameters. Unlike a regular streams class, the plot will update whenever a Parameter on the instance or class changes. For instance, we can update the ``cmap`` and ``color_level`` parameters and watch the plot update in response:
+
+
+```python
+style.color_levels = 10
+style.colormap = 'plasma' # Note that this is mapped to the 'cmap' keyword in .apply.opts
+```
+
+## Combining streams and key dimensions
+
+
+All the ``DynamicMap`` examples above can't be indexed with anything other than ``dmap[()]`` or ``dmap.select()`` as none of them had any key dimensions. This was to focus exclusively on the streams system at the start of the user guide and not because you can't combine key dimensions and streams:
+
+
+```python
+xs = np.linspace(-3, 3, 400)
+
+def function(xs, time):
+    "Some time varying function"
+    return np.exp(np.sin(xs+np.pi/time))
+
+def integral(limit, time):
+    curve = hv.Curve((xs, function(xs, time)))[limit:]
+    area  = hv.Area ((xs, function(xs, time)))[:limit]
+    summed = area.dimension_values('y').sum() * 0.015  # Numeric approximation
+    return (area * curve * hv.VLine(limit) * hv.Text(limit + 0.5, 2.0, '%.2f' % summed))
+
+Time = Stream.define('Time', time=1.0)
+dmap = hv.DynamicMap(integral, kdims='limit', streams=[Time()]).redim.range(limit=(-3,2))
+dmap
+```
+
+In this example, you can drag the slider to see a numeric approximation to the integral on the left side on the ``VLine``.
+
+As ``'limit'`` is declared as a key dimension, it is given a normal HoloViews slider. As we have also defined a ``time`` stream, we can update the displayed curve for any time value:
+
+
+```python
+dmap.event(time=8)
+```
+
+We now see how to control the ``time`` argument of the integral function by triggering an event with a new time value, and how to control the ``limit`` argument by moving a slider. Controlling ``limit`` with a slider this way is valid but also a little unintuitive: what if you could control ``limit`` just by hovering over the plot?
+
+In the [Custom Interactivity](13-Custom_Interactivity.ipynb) user guide, we will see how we can do exactly this by switching to the bokeh backend and using the linked streams system.
+
+### Matching names to arguments
+
+Note that in the example above, the key dimension names and the stream parameter names match the arguments to the callable. This *must* be true for stream parameters but this isn't a requirement for key dimensions: if you replace the word 'radius' with 'size' in the example above after ``XY`` is defined, the example still works. 
+
+Here are the rules regarding the callback argument names:
+
+* If your key dimensions and stream parameters match the callable argument names, the definition is valid.
+* If your callable accepts mandatory positional arguments and their number matches the number of key dimensions, the names don't need to match and these arguments will be passed key dimensions values.
+
+As stream parameters always need to match the argument names, there is a method to allow them to be easily renamed. Let's say you imported a stream class as shown in  [Custom_Interactivity](13-Custom_Interactivity.ipynb) or for this example, reuse the existing ``XY`` stream class. You can then use the ``rename`` method allowing the following definition:
+
+
+```python
+def integral2(lim, t): 
+    'Same as integral with different argument names'
+    return integral(lim, t)
+
+dmap = hv.DynamicMap(integral2, kdims='limit', streams=[Time().rename(time='t')]).redim.range(limit=(-3.,3.))
+dmap
+```
+
+Occasionally, it is useful to suppress some of the stream parameters of a stream class, especially when using the *linked streams* described in [Custom_Interactivity](13-Custom_Interactivity.ipynb). To do this you can rename the stream parameter to ``None`` so that you no longer need to worry about it being passed as an argument to the callable. To re-enable a stream parameter, it is sufficient to either give the stream parameter its original string name or a new string name.
+
+## Overlapping stream and key dimensions
+
+In the above example above, the stream parameters do not overlap with the declared key dimension. What happens if we add 'time' to the declared key dimensions?
+
+
+
+```python
+dmap=hv.DynamicMap(integral, kdims=['time','limit'], streams=[Time()]).redim.range(limit=(-3.,3.))
+dmap
+```
+
+First you might notice that the 'time' value is now shown in the title but that there is no corresponding time slider as its value is supplied by the stream.
+
+The 'time' parameter is now an instance of what are called 'dimensioned streams' which re-enable indexing of these dimensions:
+
+
+```python
+dmap[1,0] + dmap.select(time=3,limit=1.5) + dmap[None,1.5]
+```
+
+In **A**, we supply our own values for the 'time and 'limit' parameters. This doesn't change the values of the 'time' parameters on the stream itself but it does allow us to see what would happen when the time value is one. Note the use of ``None`` in **C** as a way of leaving an explicit value unspecified, allowing the current stream value to be used.
+
+This is one good reason to use dimensioned streams - it restores access to convenient indexing and selecting operation as a way of exploring your visualizations. The other reason it is useful is that if you keep all your parameters dimensioned, it re-enables the ``DynamicMap`` cache described in the [Live Data](07-Live_Data.ipynb), allowing you to record your interaction with streams and allowing you to cast to ``HoloMap`` for export:
+
+
+```python
+dmap.reset()  # Reset the cache, we don't want the values from the cell above
+# TODO: redim the limit dimension to a default of 0
+dmap.event(time=1)
+dmap.event(time=1.5)
+dmap.event(time=2)
+hv.HoloMap(dmap)
+```
+
+One use of this would be to have a simulator drive a visualization forward using ``event`` in a loop. You could then stop your simulation and retain the recent history of the output as long as the allowed ``DynamicMap`` cache.
+
+## Generators and argument-free callables
+
+In addition to callables, Python supports [generators](https://docs.python.org/3/glossary.html#term-generator) that can be defined with the ``yield`` keyword. Calling a function that uses yield returns a [generator iterator](https://docs.python.org/3/glossary.html#term-generator-iterator) object that accepts no arguments but returns new values when iterated or when ``next()`` is applied to it.
+
+HoloViews supports Python generators for completeness and [generator expressions](https://docs.python.org/3/glossary.html#term-generator-expression) can be a convenient way to define code inline instead of using lambda functions. As generators expressions don't accept arguments and can get 'exhausted' ***we recommend using callables with ``DynamicMap``*** - exposing the relevant arguments also exposes control over your visualization.
+
+Unlike generators, callables that have arguments allow you to re-visit portions of your parameter space instead of always being forced in one direction via calls to ``next()``. With this caveat in mind, here is an example of a generator and the corresponding generator iterator that returns a ``BoxWhisker`` element:
+
+
+```python
+def sample_distributions(samples=10, tol=0.04):
+    np.random.seed(42)
+    while True:
+        gauss1 = np.random.normal(size=samples)
+        gauss2 = np.random.normal(size=samples)
+        data = (['A']*samples + ['B']*samples, np.hstack([gauss1, gauss2]))
+        yield hv.BoxWhisker(data, 'Group', 'Value')
+        samples+=1
+        
+sample_generator = sample_distributions()
+```
+
+This returns two box whiskers representing samples from two Gaussian distributions of 10 samples. Iterating over this generator simply resamples from these distributions using an additional sample each time.
+
+As with a callable, we can pass our generator iterator to ``DynamicMap``:
+
+
+```python
+hv.DynamicMap(sample_generator)
+```
+
+Without using streams, we now have a problem as there is no way to trigger the generator to view the next distribution in the sequence. We can solve this by defining a stream with no parameters:
+
+
+```python
+dmap = hv.DynamicMap(sample_generator, streams=[Stream.define('Next')()])
+dmap
+```
+
+### Stream event update loops
+
+Now we can simply use ``event()`` to drive the generator forward and update the plot, showing how the two Gaussian distributions converge as the number of samples increase.
+
+
+```python
+for i in range(40):
+    dmap.event()
+```
+
+Note that there is a better way to run loops that drive ``dmap.event()`` which supports a ``period`` (in seconds) between updates and a ``timeout`` argument (also in seconds):
+
+
+```python
+dmap.periodic(0.1, 1000, timeout=3)
+```
+
+In this generator example, ``event`` does not require any arguments but you can set the ``param_fn`` argument to a callable that takes an iteration counter and returns a dictionary for setting the stream parameters. In addition you can use ``block=False`` to avoid blocking the notebook using a threaded loop. This can be very useful although it has two downsides 1. all running visualizations using non-blocking updates will be competing for computing resources 2. if you override a variable that the thread is actively using, there can be issues with maintaining consistent state in the notebook.
+
+Generally, the ``periodic`` utility is recommended for all such event update loops and it will be used instead of explicit loops in the rest of the user guides involving streams.
+
+
+### Using ``next()``
+
+The approach shown above of using an empty stream works in an exactly analogous fashion for callables that take no arguments. In both cases, the ``DynamicMap`` ``next()`` method is enabled:
+
+
+```python
+hv.HoloMap({i:next(dmap) for i in range(10)}, kdims='Iteration')
+```
+
+## Next steps
+
+The streams system allows you to update plots in place making it possible to build live visualizations that update in response to incoming live data or any other type of event. As we have seen in this user guide, you can use streams together with key dimensions to add additional interactivity to your plots while retaining the familiar widgets.
+
+This user guide used examples that work with either the matplotlib or bokeh backends. In the [Custom Interactivity](13-Custom_Interactivity.ipynb) user guide, you will see how you can directly interact with dynamic visualizations when using the bokeh backend.
+
+## [Advanced] How streams work
+
+
+
+This optional section is not necessary for users who simply want to use the streams system, but it does describe how streams actually work in more detail.
+
+A stream class is one that inherits from ``Stream`` that typically defines some new parameters. We have already seen one convenient way of defining a stream class:
+
+
+```python
+defineXY = Stream.define('defineXY', x=0.0, y=0.0)
+```
+
+This is equivalent to the following definition which would be more appropriate in library code or for complex stream class requiring lots of parameters that need to be documented:
+
+
+```python
+class XY(Stream):
+    x = param.Number(default=0.0, constant=True, doc='An X position.')
+    y = param.Number(default=0.0, constant=True, doc='A Y position.')
+```
+
+As we have already seen, we can make an instance of ``XY`` with some initial values for ``x`` and ``y``.
+
+
+```python
+xy = XY(x=2,y=3)
+```
+
+However, trying to modify these parameters directly will result in an exception as they have been declared constant (e.g ``xy.x=4`` will throw an error). This is because there are two allowed ways of modifying these parameters, the simplest one being ``update``:
+
+
+```python
+xy.update(x=4,y=50)
+xy.rename(x='xpos', y='ypos').contents
+```
+
+This shows how you can update the parameters and also shows the correct way to view the stream parameter values via the ``contents`` property as this will apply any necessary renaming.
+
+So far, using ``update`` has done nothing but force us to access parameter a certain way. What makes streams work are the side-effects you can trigger when changing a value via the ``event`` method. The relevant side-effect is to invoke callables called 'subscribers'
+
+### Subscribers
+
+Without defining any subscribes, the ``event`` method is identical to ``update``:
+
+
+```python
+xy = XY()
+xy.event(x=4,y=50)
+xy.contents
+```
+
+Now let's add a subscriber:
+
+
+```python
+def subscriber(xpos,ypos):
+    print('The subscriber received xpos={xpos} and ypos={ypos}'.format(xpos=xpos,ypos=ypos))
+
+xy = XY().rename(x='xpos', y='ypos')
+xy.add_subscriber(subscriber)
+xy.event(x=4,y=50)
+```
+
+As we can see, now when you call ``event``, our subscriber is called with the updated parameter values, renamed as appropriate. The ``event`` method accepts the original parameter names and the subscriber receives the new values after any renaming is applied. You can add as many subscribers as you want and you can clear them using the ``clear`` method:
+
+
+```python
+xy.clear()
+xy.event(x=0,y=0)
+```
+
+When you define a ``DynamicMap`` using streams, the HoloViews plotting system installs the necessary callbacks as subscribers to update the plot when the stream parameters change. The above example clears all subscribers (it is equivalent to ``clear('all')``. To clear only the subscribers you define yourself use ``clear('user')`` and to clear any subscribers installed by the HoloViews plotting system use ``clear('internal')``.
+
+When using linked streams as described in the [Custom Interactivity](13-Custom_Interactivity.ipynb) user guide, the plotting system recognizes the stream class and registers the necessary machinery with Bokeh to update the stream values based on direct interaction with the plot.

hvplot_docs/13-Custom_Interactivity.md

@@ -0,0 +1,222 @@
+# Custom Interactivity
+
+
+```python
+import param
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh', 'matplotlib')
+```
+
+In previous notebooks we discovered how the ``DynamicMap`` class allows us to declare objects in a lazy way to enable exploratory analysis of large parameter spaces. In the [Responding to Events](./12-Responding_to_Events.ipynb) guide we learned how to interactively push updates to existing plots by declaring Streams on a DynamicMap. In this user guide we will extend the idea to so called *linked* Streams, which allows complex interactions to be declared by specifying which events should be exposed when a plot is interacted with. By passing information about live interactions to a simple Python based callback, you will be able to build richer, even more interactive visualizations that enable seamless data exploration.
+
+Some of the possibilities this opens up include:
+
+* Dynamically aggregating datasets of billions of datapoints depending on the plot axis ranges using the [datashader](./15-Large_Data.ipynb) library.
+* Responding to ``Tap`` and ``DoubleTap`` events to reveal more information in subplots.
+* Computing statistics in response to selections applied with box- and lasso-select tools.
+
+Currently only the bokeh backend for HoloViews supports the linked streams system but the principles used should extend to any backend that can define callbacks that fire when a user zooms or pans or interacts with a plot.
+
+<center><div class="alert alert-info" role="alert">To use and visualize <b>DynamicMap</b> with linked <b>Stream</b> objects you need to be running a live Jupyter server.<br>This user guide assumes that it will be run in a live notebook environment.<br>
+When viewed statically, DynamicMaps on this page will only show the first available Element.<br></div></center>
+
+## Available Linked Streams
+
+There are a huge number of ways one might want to interact with a plot. The HoloViews streams module aims to expose many of the most common interactions you might want want to employ, while also supporting extensibility via custom linked Streams. 
+
+Here is the full list of linked Stream that are all descendants of the ``LinkedStream`` baseclass:
+
+
+```python
+from holoviews import streams
+listing = ', '.join(sorted([str(s.name) for s in param.descendents(streams.LinkedStream)]))
+print('The linked stream classes supported by HoloViews are:\n\n{listing}'.format(listing=listing))
+```
+
+As you can see, most of these events are about specific interactions with a plot such as the current axis ranges (the ``RangeX``, ``RangeY`` and ``RangeXY`` streams), the mouse pointer position (the ``PointerX``, ``PointerY`` and ``PointerXY`` streams), click or tap positions (``Tap``, ``DoubleTap``). Additionally there a streams to access plotting selections made using box- and lasso-select tools (``Selection1D``), the plot size (``PlotSize``) and the ``Bounds`` of a selection. Finally there are a number of drawing/editing streams such as ``BoxEdit``, ``PointDraw``, ``FreehandDraw``, ``PolyDraw`` and ``PolyEdit``.
+
+Each of these linked Stream types has a corresponding backend specific ``Callback``, which defines which plot attributes or events to link the stream to and triggers events on the ``Stream`` in response to changes on the plot. Defining custom ``Stream`` and ``Callback`` types will be covered in future guides.
+
+## Linking streams to plots
+
+At the end of the [Responding to Events](./12-Responding_to_Events.ipynb) guide we discovered that streams have ``subscribers``, which allow defining user defined callbacks on events, but also allow HoloViews to install subscribers that let plots respond to Stream updates. Linked streams add another concept on top of ``subscribers``, namely the Stream ``source``.
+
+The source of a linked stream defines which plot element to receive events from. Any plot containing the ``source`` object will be attached to the corresponding linked stream and will send event values in response to the appropriate interactions.
+
+Let's start with a simple example. We will declare one of the linked Streams from above, the ``PointerXY`` stream. This stream sends the current mouse position in plot axes coordinates, which may be continuous or categorical. The first thing to note is that we haven't specified a ``source`` which means it uses the default value of ``None``.
+
+
+```python
+pointer = streams.PointerXY()
+print(pointer.source)
+```
+
+Before continuing, we can check the stream parameters that are made available to user callbacks from a given stream instance by looking at its contents:
+
+
+```python
+print('The %s stream has contents %r' % (pointer, pointer.contents))
+```
+
+#### Automatic linking
+
+A stream instance is automatically linked to the first ``DynamicMap`` we pass it to, which we can confirm by inspecting the stream's ``source`` attribute after supplying it to a ``DynamicMap``:
+
+
+```python
+pointer_dmap = hv.DynamicMap(lambda x, y: hv.Points([(x, y)]), streams=[pointer])
+print(pointer.source is pointer_dmap)
+```
+
+The ``DynamicMap`` we defined above simply defines returns a ``Points`` object composed of a single point that marks the current ``x`` and ``y`` position supplied by our ``PointerXY`` stream. The stream is linked whenever this ``DynamicMap`` object is displayed as it is the stream source:
+
+
+```python
+pointer_dmap.opts(size=10)
+```
+
+If you hover over the plot canvas above you can see that the point tracks the current mouse position. We can also inspect the last cursor position by examining the stream contents:
+
+
+```python
+pointer.contents
+```
+
+In the [Responding to Events](12-Responding_to_Events.ipynb) user guide, we introduced an integration example that would work more intuitively with linked streams. Here it is again with the ``limit`` value controlled by the ``PointerX`` linked stream:
+
+
+```python
+xs = np.linspace(-3, 3, 400)
+
+def function(xs, time):
+    "Some time varying function"
+    return np.exp(np.sin(xs+np.pi/time))
+
+def integral(limit, time):
+    limit = -3 if limit is None else np.clip(limit,-3,3)
+    curve = hv.Curve((xs, function(xs, time)))[limit:]
+    area  = hv.Area ((xs, function(xs, time)))[:limit]
+    summed = area.dimension_values('y').sum() * 0.015  # Numeric approximation
+    return (area * curve * hv.VLine(limit) * hv.Text(limit + 0.8, 2.0, '%.2f' % summed))
+
+integral_streams = [
+    streams.Stream.define('Time', time=1.0)(),
+    streams.PointerX().rename(x='limit')]
+
+integral_dmap = hv.DynamicMap(integral, streams=integral_streams)
+
+integral_dmap.opts(
+    opts.Area(color='#fff8dc', line_width=2),
+    opts.Curve(color='black'),
+    opts.VLine(color='red'))
+```
+
+We only needed to import and use the ``PointerX`` stream and rename the ``x`` parameter that tracks the cursor position to 'limit' so that it maps to the corresponding argument. Otherwise, the example only required bokeh specific style options to match the matplotlib example as closely as possible.
+
+#### Explicit linking
+
+In the example above, we took advantage of the fact that a ``DynamicMap`` automatically becomes the stream source if a source isn't explicitly specified. If we want to link the stream instance to a different object we can specify our source explicitly. Here we will create a 2D ``Image`` of sine gratings, and then declare that this image is the ``source`` of the ``PointerXY`` stream. This pointer stream is then used to generate a single point that tracks the cursor when hovering over the image:
+
+
+```python
+xvals = np.linspace(0,4,202)
+ys,xs = np.meshgrid(xvals, -xvals[::-1])
+img = hv.Image(np.sin(((ys)**3)*xs))
+
+pointer = streams.PointerXY(x=0,y=0, source=img)
+pointer_dmap = hv.DynamicMap(lambda x, y: hv.Points([(x, y)]), streams=[pointer])
+```
+
+Now if we display a ``Layout`` consisting of the ``Image`` acting as the source together with the ``DynamicMap``, the point shown on the right tracks the cursor position when hovering over the image on the left:
+
+
+```python
+img + pointer_dmap.opts(size=10, xlim=(-.5, .5), ylim=(-.5, .5))
+```
+
+This will even work across different cells. If we use this particular stream instance in another ``DynamicMap`` and display it, this new visualization will also be supplied with the cursor position when hovering over the image. 
+
+To illustrate this, we will now use the pointer ``x`` and ``y`` position to generate cross-sections of the image at the cursor position on the ``Image``, making use of the ``Image.sample`` method. Note the use of ``np.clip`` to make sure the cross-section is well defined when the cusor goes out of bounds:
+
+
+```python
+x_sample = hv.DynamicMap(lambda x, y: img.sample(x=np.clip(x,-.49,.49)), streams=[pointer])
+y_sample = hv.DynamicMap(lambda x, y: img.sample(y=np.clip(y,-.49,.49)), streams=[pointer])
+
+(x_sample + y_sample).opts(opts.Curve(framewise=True))
+```
+
+Now when you hover over the ``Image`` above, you will see the cross-sections update while the point position to the right of the ``Image`` simultaneously updates.
+
+#### Unlinking objects
+
+Sometimes we just want to display an object designated as a source without linking it to the stream. If the object is not a ``DynamicMap``, like the ``Image`` we designated as a ``source`` above, we can make a copy of the object using the ``clone`` method. We can do the same with ``DynamicMap`` though we just need to supply ``link_inputs=False`` as an extra argument.
+
+Here we will create a ``DynamicMap`` that draws a cross-hair at the cursor position:
+
+
+```python
+pointer = streams.PointerXY(x=0, y=0)
+cross_dmap = hv.DynamicMap(lambda x, y: (hv.VLine(x) * hv.HLine(y)), streams=[pointer])
+```
+
+Now we will add two copies of the ``cross_dmap`` into a Layout but the subplot on the right will not be linking the inputs. Try hovering over the two subplots and observe what happens:
+
+
+```python
+cross_dmap + cross_dmap.clone(link=False)
+```
+
+Notice how hovering over the left plot updates the crosshair position on both subplots, while hovering over the right subplot has no effect.
+
+## Transient linked streams
+
+In the basic  [Responding to Events](12-Responding_to_Events.ipynb) user guide we saw that stream parameters can be updated and those values are then passed to the callback. This model works well for many different types of streams that have well-defined values at all times.
+
+This approach is not suitable for certain events which only have a well defined value at a particular point in time. For instance, when you hover your mouse over a plot, the hover position always has a well-defined value but the click position is only defined when a click occurs (if it occurs).
+
+This latter case is an example of what are called 'transient' streams. These streams are supplied new values only when they occur and fall back to a default value at all other times. This default value is typically ``None`` to indicate that the event is not occurring and therefore has no data.
+
+
+Transient streams are particularly useful when you are subscribed to multiple streams, some of which are only occasionally triggered. A good example are the ``Tap`` and ``DoubleTap`` streams; while you sometimes just want to know the last tapped position, we can only tell the two events apart if their values are ``None`` when not active. 
+
+We'll start by declaring a ``SingleTap`` and a ``DoubleTap`` stream as ``transient``. Since both streams supply 'x' and 'y' parameters, we will rename the ``DoubleTap`` parameters to 'x2' and 'y2'.
+
+
+```python
+tap = streams.SingleTap(transient=True)
+double_tap = streams.DoubleTap(rename={'x': 'x2', 'y': 'y2'}, transient=True)
+```
+
+Next we define a list of taps we can append to, and a function that accumulates the tap and double tap coordinates along with the number of taps, returning a ``Points`` Element of the tap positions.
+
+
+```python
+taps = []
+
+def record_taps(x, y, x2, y2):
+    if None not in [x,y]:
+        taps.append((x, y, 1))
+    elif None not in [x2, y2]:
+        taps.append((x2, y2, 2))
+    return hv.Points(taps, vdims='Taps')
+```
+
+Finally we can create a ``DynamicMap`` from our callback and attach the streams. We also apply some styling so the points are colored depending on the number of taps.
+
+
+```python
+taps_dmap = hv.DynamicMap(record_taps, streams=[tap, double_tap])
+
+taps_dmap.opts(color='Taps', cmap={1: 'red', 2: 'gray'}, size=10, tools=['hover'])
+```
+
+Now try single- and double-tapping within the plot area, each time you tap a new point is appended to the list and displayed. Single taps show up in red and double taps show up in grey.  We can also inspect the list of taps directly:
+
+
+```python
+taps
+```

hvplot_docs/14-Data_Pipelines.md

@@ -0,0 +1,123 @@
+# Data Processing Pipelines
+
+
+```python
+import pandas as pd
+import holoviews as hv
+
+from holoviews import opts
+from bokeh.sampledata import stocks
+from holoviews.operation.timeseries import rolling, rolling_outlier_std
+
+hv.extension('bokeh')
+
+opts.defaults(opts.Curve(width=600, framewise=True))
+```
+
+In the previous guides we discovered how to load and declare [dynamic, live data](./07-Live_Data.ipynb) and how to [transform elements](./11-Transforming_Elements.ipynb) using `dim` expressions and operations. In this guide we will discover how to combine dynamic data with operations to declare lazy and declarative data processing pipelines, which can be used for interactive exploration but can also drive complex dashboards or even bokeh apps.
+
+## Declaring dynamic data
+
+We will begin by declaring a function which loads some data. In this case we will just load some stock data from the bokeh  but you could imagine querying this data using REST interface or some other API or even loading some large collection of data from disk or generating the data from some simulation or data processing job.
+
+
+```python
+def load_symbol(symbol, **kwargs):
+    df = pd.DataFrame(getattr(stocks, symbol))
+    df['date'] = df.date.astype('datetime64[ns]')
+    return hv.Curve(df, ('date', 'Date'), ('adj_close', 'Adjusted Close'))
+
+stock_symbols = ['AAPL', 'FB', 'GOOG', 'IBM', 'MSFT']
+dmap = hv.DynamicMap(load_symbol, kdims='Symbol').redim.values(Symbol=stock_symbols)
+```
+
+We begin by displaying our DynamicMap to see what we are dealing with. Recall that a ``DynamicMap`` is only evaluated when you request the key so the ``load_symbol`` function is only executed when first displaying the ``DynamicMap`` and whenever we change the widget dropdown:
+
+
+```python
+dmap
+```
+
+## Processing data
+
+It is very common to want to process some data, for this purpose HoloViews provides so-called ``Operations``, which are described in detail in the [Transforming Elements](./11-Transforming_Elements.ipynb). ``Operations`` are simply parameterized functions, which take HoloViews objects as input, transform them in some way and then return the output.
+
+In combination with [Dimensioned Containers](./05-Dimensioned_Containers.ipynb) such as ``HoloMap`` and ``GridSpace`` they are a powerful way to explore how the parameters of your transform affect the data. We will start with a simple example. HoloViews provides a ``rolling`` function which smoothes timeseries data with a rolling window. We will apply this operation with a ``rolling_window`` of 30, i.e. roughly a month of our daily timeseries data:
+
+
+```python
+smoothed = rolling(dmap, rolling_window=30)
+smoothed
+```
+
+As you can see the ``rolling`` operation applies directly to our ``DynamicMap``, smoothing each ``Curve`` before it is displayed. Applying an operation to a ``DynamicMap`` keeps the data as a ``DynamicMap``, this means the operation is also applied lazily whenever we display or select a different symbol in the dropdown widget.
+
+### Dynamically evaluating parameters on operations and transforms with ``.apply``
+
+The ``.apply`` method allows us to automatically build a dynamic pipeline given an object and some operation or function along with parameter, stream or widget instances passed in as keyword arguments. Internally it will then build a `Stream` to ensure that whenever one of these changes the plot is updated. To learn more about streams see the [Responding to Events](./12-Responding_to_Events.ipynb).
+
+This mechanism allows us to build powerful pipelines by linking parameters on a user defined class or even an external widget, e.g. here we import an ``IntSlider`` widget from [``panel``](https://pyviz.panel.org):
+
+
+```python
+import panel as pn
+
+slider = pn.widgets.IntSlider(name='rolling_window', start=1, end=100, value=50)
+```
+
+Using the ``.apply`` method we could now apply the ``rolling`` operation to the DynamicMap and link the slider to the operation's ``rolling_window`` parameter (which also works for simple functions as will be shown below). However, to further demonstrate the features of `dim` expressions and the `.transform` method, which we first introduced in the [Transforming elements user guide](11-Transforming_Elements.ipynb), we will instead apply the rolling mean using the `.df` namespace accessor on a `dim` expression:
+
+
+```python
+rolled_dmap = dmap.apply.transform(adj_close=hv.dim('adj_close').df.rolling(slider).mean())
+
+rolled_dmap
+```
+
+The ``rolled_dmap`` is another DynamicMap that defines a simple two-step pipeline, which calls the original callback when the ``symbol`` changes and reapplies the expression whenever the slider value changes. Since the widget's value is now linked to the plot via a ``Stream`` we can display the widget and watch the plot update:
+
+
+```python
+slider
+```
+
+The power of building pipelines is that different visual components can share the same inputs but compute very different things from that data. The part of the pipeline that is shared is only evaluated once making it easy to build efficient data processing code. To illustrate this we will also apply the ``rolling_outlier_std`` operation which computes outliers within the ``rolling_window`` and again we will supply the widget ``value``:
+
+
+```python
+outliers = dmap.apply(rolling_outlier_std, rolling_window=slider.param.value)
+
+rolled_dmap * outliers.opts(color='red', marker='triangle')
+```
+
+We can chain operations like this indefinitely and attach parameters or explicit streams to each stage. By chaining we can watch our visualization update whenever we change a stream value anywhere in the pipeline and HoloViews will be smart about which parts of the pipeline are recomputed, which allows us to build complex visualizations very quickly.
+
+The ``.apply`` method is also not limited to operations. We can just as easily apply a simple Python function to each object in the ``DynamicMap``. Here we define a function to compute the residual between the original ``dmap`` and the ``rolled_dmap``.
+
+
+```python
+def residual_fn(overlay):
+    # Get first and second Element in overlay
+    el1, el2 = overlay.get(0), overlay.get(1)
+
+    # Get x-values and y-values of curves
+    xvals  = el1.dimension_values(0)
+    yvals  = el1.dimension_values(1)
+    yvals2 = el2.dimension_values(1)
+
+    # Return new Element with subtracted y-values
+    # and new label
+    return el1.clone((xvals, yvals-yvals2),
+                     vdims='Residual')
+```
+
+If we overlay the two DynamicMaps we can then dynamically broadcast this function to each of the overlays, producing a new DynamicMap which responds to both the symbol selector widget and the slider:
+
+
+```python
+residual = (dmap * rolled_dmap).apply(residual_fn)
+
+residual
+```
+
+In later guides we will see how we can combine HoloViews plots and Panel widgets into custom layouts allowing us to define complex dashboards. For more information on how to deploy bokeh apps from HoloViews and build dashboards see the [Deploying Bokeh Apps](./Deploying_Bokeh_Apps.ipynb) and [Dashboards](./17-Dashboards.ipynb) guides. To get a quick idea of what this might look like let's compose all the components we have no built:

hvplot_docs/15-Large_Data.md

@@ -0,0 +1,576 @@
+# Working with large data using Datashader
+
+The various plotting-library backends supported by HoloViews, such as Matplotlib, Bokeh, and Plotly, each have limitations on the amount of data that is practical to work with.  Bokeh and Plotly in particular mirror your data directly into an HTML page viewable in your browser, which can cause problems when data sizes approach the limited memory available for each web page in current browsers.
+
+Luckily, a visualization of even the largest dataset will be constrained by the resolution of your display device, and so one approach to handling such data is to pre-render or rasterize the data into a fixed-size array or image *before* sending it to the backend plotting library and thus to your local web browser. The [Datashader](https://github.com/bokeh/datashader) library provides a high-performance big-data server-side rasterization pipeline that works seamlessly with HoloViews to support datasets that are orders of magnitude larger than those supported natively by the plotting-library backends, including millions or billions of points even on ordinary laptops.
+
+Here, we will see how and when to use Datashader with HoloViews Elements and Containers. For simplicity in this discussion we'll focus on simple synthetic datasets, but [Datashader's examples](http://datashader.org/topics) include a wide variety of real datasets that give a much better idea of the power of using Datashader with HoloViews, and [HoloViz.org](http://holoviz.org) shows how to install and work with HoloViews and Datashader together.
+
+<style>.container { width:100% !important; }</style>
+
+
+```python
+import datashader as ds
+import numpy as np
+import holoviews as hv
+import pandas as pd
+import numpy as np
+
+from holoviews import opts
+from holoviews.operation.datashader import datashade, rasterize, shade, dynspread, spread
+from holoviews.operation.resample import ResampleOperation2D
+from holoviews.operation import decimate
+
+hv.extension('bokeh','matplotlib', width=100)
+
+# Default values suitable for this notebook
+decimate.max_samples=1000
+dynspread.max_px=20
+dynspread.threshold=0.5
+ResampleOperation2D.width=500
+ResampleOperation2D.height=500
+
+def random_walk(n, f=5000):
+    """Random walk in a 2D space, smoothed with a filter of length f"""
+    xs = np.convolve(np.random.normal(0, 0.1, size=n), np.ones(f)/f).cumsum()
+    ys = np.convolve(np.random.normal(0, 0.1, size=n), np.ones(f)/f).cumsum()
+    xs += 0.1*np.sin(0.1*np.array(range(n-1+f))) # add wobble on x axis
+    xs += np.random.normal(0, 0.005, size=n-1+f) # add measurement noise
+    ys += np.random.normal(0, 0.005, size=n-1+f)
+    return np.column_stack([xs, ys])
+
+def random_cov():
+    """Random covariance for use in generating 2D Gaussian distributions"""
+    A = np.random.randn(2,2)
+    return np.dot(A, A.T)
+
+def time_series(T = 1, N = 100, mu = 0.1, sigma = 0.1, S0 = 20):  
+    """Parameterized noisy time series"""
+    dt = float(T)/N
+    t = np.linspace(0, T, N)
+    W = np.random.standard_normal(size = N) 
+    W = np.cumsum(W)*np.sqrt(dt) # standard brownian motion
+    X = (mu-0.5*sigma**2)*t + sigma*W 
+    S = S0*np.exp(X) # geometric brownian motion
+    return S
+```
+
+<center><div class="alert alert-info" role="alert">This notebook makes use of dynamic updates, which require a running a live Jupyter or Bokeh server.<br>
+When viewed statically, the plots will not update fully when you zoom and pan.<br></div></center>
+
+# Principles of datashading
+
+Because HoloViews elements are fundamentally data containers, not visualizations, you can very quickly declare elements such as ``Points`` or ``Path`` containing datasets that may be as large as the full memory available on your machine (or even larger if using Dask dataframes). So even for very large datasets, you can easily  specify a data structure that you can work with for making selections, sampling, aggregations, and so on. However, as soon as you try to visualize it directly with either the Matplotlib, Plotly, or Bokeh plotting extensions, the rendering process may be prohibitively expensive.
+
+Let's start with a simple example that's easy to visualize in any plotting library:
+
+
+```python
+np.random.seed(1)
+points = hv.Points(np.random.multivariate_normal((0,0), [[0.1, 0.1], [0.1, 1.0]], (1000,)),label="Points")
+paths = hv.Path([random_walk(2000,30)], kdims=["u","v"], label="Paths")
+
+points + paths
+```
+
+These browser-based plots are fully interactive, as you can see if you select the Wheel Zoom or Box Zoom tools and use your scroll wheel or click and drag.  
+
+Because all of the data in these plots gets transferred directly into the web browser, the interactive functionality will be available even on a static export of this figure as a web page. Note that even though the visualization above is not computationally expensive, even with just 1000 points as in the scatterplot above, the plot already suffers from [overplotting](https://anaconda.org/jbednar/plotting_pitfalls), with later points obscuring previously plotted points.  
+
+With much larger datasets, these issues will quickly make it impossible to see the true structure of the data.  We can easily declare 50X or 1000X larger versions of the same plots above, but if we tried to visualize them directly they would be unusably slow even if the browser did not crash:
+
+
+```python
+np.random.seed(1)
+points = hv.Points(np.random.multivariate_normal((0,0), [[0.1, 0.1], [0.1, 1.0]], (1000000,)),label="Points")
+paths = hv.Path([0.15*random_walk(100000) for i in range(10)], kdims=["u","v"], label="Paths")
+
+#points + paths  ## Danger! Browsers can't handle 1 million points!
+```
+
+Luckily, HoloViews Elements are just containers for data and associated metadata, not plots, so HoloViews can generate entirely different types of visualizations from the same data structure when appropriate.  For instance, in the plot on the left below you can see the result of applying a `decimate()` operation acting on the `points` object, which will automatically downsample this million-point dataset to at most 1000 points at any time as you zoom in or out:
+
+
+```python
+decimate( points).relabel("Decimated Points") + \
+rasterize(points).relabel("Rasterized Points").opts(colorbar=True, width=350) + \
+rasterize(paths ).relabel("Rasterized Paths")
+```
+
+Decimating a plot in this way can be useful, but it discards most of the data even while still suffering from overplotting. 
+
+If you have Datashader installed, you can instead use Datashader operations like `rasterize()` to create a dynamic Datashader-based Bokeh plot. The middle plot above shows the result of using `rasterize()` to create a dynamic Datashader-based plot out of an Element with arbitrarily large data. In the rasterized version, the data is binned into a fixed-size 2D array automatically on every zoom or pan event, revealing all the data available at that zoom level and avoiding issues with overplotting by dynamically rescaling the colors used. Each pixel is colored by how many datapoints fall in that pixel, faithfully revealing the data's distribution in a easy-to-display plot. The colorbar indicates the number of points indicated by that color, up to 300 or so for the pixels with the most points here. The same process is used for the line-based data in the Paths plot, where darker colors represent path intersections.
+
+These two Datashader-based plots are similar to the native Bokeh plots above, but instead of making a static Bokeh plot that embeds points or line segments directly into the browser, HoloViews sets up a Bokeh plot with dynamic callbacks instructing Datashader to rasterize the data into a fixed-size array (effectively a 2D histogram) instead. The dynamic re-rendering provides an interactive user experience, even though the data itself is never provided directly to the browser. Of course, because the full data is not in the browser, a static export of this page (e.g. on holoviews.org or on anaconda.org) will only show the initially rendered version, and will not update with new rasterized arrays when zooming as it will when there is a live Python process available.
+
+Though you can no longer have a completely interactive exported file, with the Datashader version on a live server you can now change the number of data points from 1000000 to 10000000 or more to see how well your machine will handle larger datasets. It will get a bit slower, but if you have enough memory, it should still be very usable, and should never crash your browser like transferring the whole dataset into your browser would.  If you don't have enough memory, you can instead set up a [Dask](http://dask.pydata.org) dataframe as shown in other Datashader examples, which will provide out-of-core and/or distributed processing to handle even the largest datasets if you have enough computational power and memory or are willing to wait for out-of-core computation.
+
+# HoloViews operations for datashading
+
+HoloViews provides several operations for calling Datashader on HoloViews elements, including `rasterize()`, `shade()`, and `datashade()`.
+
+`rasterize()` uses Datashader to render the data into what is by default a 2D histogram, where every array cell counts the data points falling into that pixel. Bokeh then colormaps that array, turning each cell into a pixel in an image. 
+
+Instead of having Bokeh do the colormapping, you can instruct Datashader to do so, by wrapping the output of `rasterize()` in a call to `shade()`, where `shade()` is Datashader's colormapping function. The `datashade()` operation is also provided as a simple macro, where `datashade(x)` is equivalent to `shade(rasterize(x))`:
+
+
+```python
+ropts = dict(colorbar=True, tools=["hover"], width=350)
+
+rasterize(      points).opts(cmap="kbc_r", cnorm="linear").relabel('rasterize()').opts(**ropts).hist() + \
+shade(rasterize(points),     cmap="kbc_r", cnorm="linear").relabel("shade(rasterize())") + \
+datashade(      points,      cmap="kbc_r", cnorm="linear").relabel("datashade()")
+```
+
+In all three of the above plots, `rasterize()` is being called to aggregate the data (a large set of x,y locations) into a rectangular grid, with each grid cell counting up the number of points that fall into it.  In the first plot, only `rasterize()` is done, and the resulting numeric array of counts is passed to Bokeh for colormapping. That way hover and colorbars can be supported (as shown), and Bokeh can then provide dynamic (client-side, browser-based) colormapping tools in JavaScript, allowing users to have dynamic control over even static HTML plots.  For instance, in this case, users can use the Box Select tool and select a range of the histogram shown, dynamically remapping the colors used in the plot to cover the selected range.
+
+The other two plots should be identical in appearance, but with the numerical array output of `rasterize()` mapped into RGB colors by Datashader itself, in Python ("server-side"), which allows some special Datashader computations described below but prevents other Bokeh-based features like hover and colorbars from being used. Here we've instructed Datashader to use the same colormap used by bokeh, so that the plots look similar, but as you can see the `rasterize()` colormap is determined by a HoloViews plot option, while the `shade` and `datashade` colormap is determined by an argument to those operations. See ``hv.help(rasterize)``,  ``hv.help(shade)``, and ``hv.help(datashade)`` for options that can be selected, and the [Datashader web site](http://datashader.org) for all the details. HoloViews also provides lower-level `aggregate()` and `regrid()` operations that implement `rasterize()` and give more control over how the data is aggregated, but these are not needed for typical usage.
+
+# Setting options
+
+By their nature, the datashading operations accept one HoloViews Element type and return a different Element type. Regardless of what type they are given, `rasterize()` returns an `hv.Image`, while `shade()` and `datashade()` return an `hv.RGB`. It is important to keep this transformation in mind, because HoloViews options that you set on your original Element type are not normally transferred to your new Element:
+
+
+```python
+points2 = decimate(points, dynamic=False, max_samples=3000)
+points2.opts(color="green", size=6, marker="s")
+
+points2 + rasterize(points2).relabel("Rasterized") + datashade(points2).relabel("Datashaded")
+```
+
+The datashaded plot represents each point as a single pixel, many of which are very difficult to see, and you can see that the color, size, and marker shape that you set on the Points element will not be applied to the rasterized or datashaded plot, because `size` and `marker` are not directly applicable to the numerical arrays of `hv.Image` and the pixel arrays of `hv.RGB`. 
+
+If you want to use Datashader to recreate the options from the original plot, you can usually do so, but you will have to use the various Datashader-specific features explained in the sections below along with HoloViews options specifically for `hv.Image` or `hv.RGB`. For example:
+
+
+```python
+w=225
+
+points2 + \
+spread(rasterize(points2, width=w, height=w), px=4, shape='square').opts(cmap=["green"]).relabel("Rasterized") + \
+spread(datashade(points2, width=w, height=w, cmap=["green"]), px=4, shape='square').relabel("Datashaded")
+```
+
+Note that by forcing the single-color colormap `["green"]`, Datashader's support for avoiding overplotting has been lost. In most cases you will want to reveal the underlying distribution while avoiding overplotting, either by using a proper colormap (**Rasterized** below) or by using the alpha channel to convey the number of overlapping points (**Datashaded** below).
+
+
+```python
+import bokeh.palettes as bp
+greens = bp.Greens[256][::-1][64:]
+```
+
+
+```python
+points2 + \
+spread(rasterize(points2, width=w, height=w), px=4, shape='square').opts(cmap=greens, cnorm='eq_hist').relabel("Rasterized") +\
+spread(datashade(points2, width=w, height=w, cmap="green", cnorm='eq_hist'), px=4, shape='square').relabel("Datashaded")
+```
+
+# Colormapping
+
+As you can see above, the choice of colormap and the various colormapping options can be very important for datashaded plots. One issue often seen in large, real-world datasets is that there is structure at many spatial and value scales, which requires special attention to colormapping options. This example dataset from the [Datashader documentation](https://datashader.org/getting_started/Pipeline.html) illustrates the issues, with data clustering at five different spatial scales:
+
+
+```python
+num=10000
+np.random.seed(1)
+
+dists = {cat: pd.DataFrame(dict([('x',np.random.normal(x,s,num)), 
+                                 ('y',np.random.normal(y,s,num)), 
+                                 ('val',val), 
+                                 ('cat',cat)]))      
+         for x,  y,  s,  val, cat in 
+         [(  2,  2, 0.03, 10, "d1"), 
+          (  2, -2, 0.10, 20, "d2"), 
+          ( -2, -2, 0.50, 30, "d3"), 
+          ( -2,  2, 1.00, 40, "d4"), 
+          (  0,  0, 3.00, 50, "d5")] }
+
+df = pd.concat(dists,ignore_index=True)
+df["cat"]=df["cat"].astype("category")
+df
+```
+
+Each of the five categories has 10000 points, but distributed over different spatial areas. Bokeh supports three colormap normalization options, which each behave differently:
+
+
+```python
+ropts = dict(tools=["hover"], height=380, width=330, colorbar=True, colorbar_position="bottom")
+
+hv.Layout([rasterize(hv.Points(df)).opts(**ropts).opts(cnorm=n).relabel(n)
+           for n in ["linear", "log", "eq_hist"]])
+```
+
+Here, the `linear` map is easy to interpret, but nearly all of the pixels are drawn in the lightest blue, because the highest-count pixel (around a count of 6000) is much larger in value than the typical pixels. The other two plots show the full structure (five concentrations of data points, including one in the background), with `log` using a standard logarithmic transformation of the count data before colormapping, and `eq_hist` using a histogram-equalization technique (see the [Datashader docs](https://datashader.org/getting_started/Pipeline.html)) to reveal structure without any assumptions about the incoming distribution (but with an irregularly spaced colormap that makes the numeric values difficult to reason about). In practice, it is generally a good idea to use `eq_hist` when exploring a large dataset initially, so that you will see any structure present, then switch to `log` or `linear` as appropriate to share the plots with a simpler-to-explain colormap. All three of these options are supported by the various backends (including Bokeh version 2.2.3 or later)  and by `shade()` and `datashade()` except that `eq_hist` is not yet available for the Plotly backend.
+
+Since datashader only sends the data currently in view to the plotting backend, the default behavior is to rescale the colormap to the range of the visible data as the zoom level changes. This behavior may not be desirable when working with images; to instead use a fixed colormap range, the `clim` parameter can be passed to the `bokeh` backend via the `opts()` method. Note that this approach works with `rasterize()` where the colormapping is done by the `bokeh` backend. With `datashade()`, the colormapping is done with the `shade()` function which takes a `clims` parameter directly instead of passing additional parameters to the backend via `opts()`. For example (removing the semicolon in a live notebook to see the output):
+
+
+```python
+pts1 = rasterize(hv.Points(df)).opts(**ropts).opts(tools=[], cnorm='log', axiswise=True)
+pts2 = rasterize(hv.Points(df)).opts(**ropts).opts(tools=[], cnorm='log', axiswise=True)
+
+pts1 + pts2.opts(clim=(0, 10000));
+```
+
+<img src="http://assets.holoviews.org/gifs/guides/user_guide/Large_Data/rasterize_clim_example.gif"></img>
+
+By default, pixels with an integer count of zero or a floating-point value of NaN are transparent, letting the plot background show through so that the data can be used in overlays. If you want zero to map to the lowest colormap color instead to make a dense, fully filled-in image, you can use `redim.nodata` to set the `Dimension.nodata` parameter to None:
+
+
+```python
+hv.Layout([rasterize(hv.Points(df), vdim_prefix='').redim.nodata(Count=n)\
+           .opts(**ropts, cnorm="eq_hist").relabel("nodata="+str(n))
+           for n in [0, None]])
+```
+
+## Spreading and antialiasing
+
+By default, Datashader treats points and lines as infinitesimal in width, such that a given point or small bit of line segment appears in at most one pixel. This approach ensures that the overall distribution of the points will be mathematically well founded -- each pixel will scale in value directly by the number of points that fall into it, or by the lines that cross it. As a consequence, Datashader's "marker size" and "line width" are effectively one pixel by default.
+
+However, many monitors are sufficiently high resolution that a single-pixel point or line can be difficult to see---one pixel may not be visible at all on its own, and even if it is visible it is often difficult to see its color. To compensate for this, HoloViews provides access to Datashader's raster-based "spreading" (a generalization of image dilation and convolution), which makes isolated nonzero cells "spread" into adjacent ones for visibility.  There are two varieties of spreading supported:
+
+1. ``spread``: fixed spreading of a certain number of cells (pixels), which is useful if you want to be sure how much spreading is done regardless of the properties of the data.
+2. ``dynspread``: spreads up to a maximum size as long as it does not exceed a specified fraction of adjacency between cells (pixels) (controlled by a `threshold` parameter).
+
+Dynamic spreading is typically more useful for interactive plotting, because it adjusts depending on how close the datapoints are to each other on screen. As of Datashader 0.12, both types of spreading are supported for both `rasterize()` and `shade()`, but previous Datashader versions only support spreading on the RGB output of `shade()`.
+
+As long as you have Datashader 0.12 or later, you can compare the results when you zoom the two plots below; when you zoom in far enough you should be able to see that the in the two zoomed-in plots below, then zoom out to see that the plots are the same when points are clustered together to form a distribution. (If running a live notebook; remove the semicolon so that you see the live output rather than the saved GIF.)
+
+
+```python
+pts = rasterize(points).opts(cnorm='eq_hist')
+
+pts + dynspread(pts);
+```
+
+<img src="http://assets.holoviews.org/gifs/guides/user_guide/Large_Data/dynspread.gif"></img>
+
+Both plots show the same data, and look identical when zoomed out, but when zoomed in enough you should be able to see the individual data points on the right while the ones on the left are barely visible.  The dynspread parameters typically need some hand tuning, as the only purpose of such spreading is to make things visible on a particular monitor for a particular observer; the underlying mathematical operations in Datashader do not normally need parameters to be adjusted.
+
+Dynspread is not usable with connected plots like trajectories or curves, because the spreading amount is measured by the fraction of cells that have neighbors closer than the given spread distance, which is always 100% when datapoints are connected together. For connected plots you can instead use `spread` with a fixed value to expand patterns by `px` in every direction after they are drawn, or (for Datashader 0.14 or later) pass an explicit width like `line_width=1` to the rasterizer (at some cost in performance) to draw fully antialiased lines with the specified width:
+
+
+```python
+rasterize(paths).relabel("Rasterized") + \
+spread(rasterize(paths), px=1).relabel("Spread 1") + \
+rasterize(paths, line_width=2).relabel("Antialiased line_width 2")
+```
+
+# Multidimensional plots
+
+The above plots show two dimensions of data plotted along *x* and *y*, but Datashader operations can be used with additional dimensions as well.  For instance, an extra dimension (here called `k`), can be treated as a category label and used to colorize the points or lines, aggregating the data points separately depending on which category value they have. Compared to a standard overlaid scatterplot that would suffer from overplotting, here the result will be merged mathematically by Datashader, completely avoiding any overplotting issues except any local issues that may arise from spreading when zoomed in:
+
+
+```python
+np.random.seed(3)
+kdims=['d1','d2']
+num_ks=8
+
+def rand_gauss2d(value=0, n=100000):
+    """Return a randomly shaped 2D Gaussian distribution with an associated numeric value"""
+    g = 100*np.random.multivariate_normal(np.random.randn(2), random_cov(), (n,))
+    return np.hstack((g,value*np.ones((g.shape[0],1))))
+```
+
+
+```python
+gaussians = {str(i): hv.Points(rand_gauss2d(i), kdims, "i") for i in range(num_ks)}
+
+c = dynspread(datashade(hv.NdOverlay(gaussians, kdims='k'), aggregator=ds.by('k', ds.count())))
+m = dynspread(datashade(hv.NdOverlay(gaussians, kdims='k'), aggregator=ds.by('k', ds.mean("i"))))
+
+c.opts(width=400) + m.opts(width=400)
+```
+
+Above you can see that (as of Datashader 0.11) categorical aggregates can take any reduction function, either `count`ing the datapoints (left) or reporting some other statistic (e.g. the mean value of a column, right). This type of categorical mixing is currently only supported by `shade()` and `datashade()`, not `rasterize()` alone, because it depends on Datashader's custom color mixing code.
+
+Categorical aggregates are one way to allow separate lines or other shapes to be visually distinctive from one another while avoiding obscuring data due to overplotting:
+
+
+```python
+lines = {str(i): hv.Curve(time_series(N=10000, S0=200+np.random.rand())) for i in range(num_ks)}
+lineoverlay = hv.NdOverlay(lines, kdims='k')
+datashade(lineoverlay, pixel_ratio=2, line_width=4, aggregator=ds.by('k', ds.count())).opts(width=800)
+```
+
+As you can see, overlapping colors yield color mixtures that indicate that the given pixels contain data from multiple curves, which helps users realize where they need to zoom in to see further detail.
+
+Note that Bokeh only ever sees an image come out of `datashade`, not any of the actual data. As a result, providing legends and keys has to be done separately, though we are hoping to make this process more seamless.  For now, you can show a legend by adding a suitable collection of "fake" labeled points (size zero and thus invisible):
+
+
+```python
+# definition copied here to ensure independent pan/zoom state for each dynamic plot
+gaussspread2 = dynspread(datashade(hv.NdOverlay(gaussians, kdims=['k']), aggregator=ds.by('k', ds.count())))
+
+from datashader.colors import Sets1to3 # default datashade() and shade() color cycle
+color_key = list(enumerate(Sets1to3[0:num_ks]))
+color_points = hv.NdOverlay({k: hv.Points([(0,0)], label=str(k)).opts(color=v, size=0) for k, v in color_key})
+
+(color_points * gaussspread2).opts(width=600)
+```
+
+Here the dummy points are at (0,0) for this dataset, but would need to be at another suitable value for data that is in a different range.
+
+## Working with time series
+
+HoloViews also makes it possible to datashade large timeseries using the ``datashade`` and ``rasterize`` operations. For smoother lines, datashader implements anti-aliasing if a `line_width` > 0 is set:
+
+
+```python
+dates = pd.date_range(start="2014-01-01", end="2016-01-01", freq='1D') # or '1min'
+curve = hv.Curve((dates, time_series(N=len(dates), sigma = 1)))
+rasterize(curve, width=800, line_width=3, pixel_ratio=2).opts(width=800, cmap=['lightblue','blue'])
+```
+
+Here we're also doubling the resolution in x and y using `pixel_ratio=2`, allowing for more precise rendering of the line shape; higher pixel ratios work well for lines and other shapes, though they can make individual points more difficult to see in points plots.
+
+HoloViews also supplies some operations that are useful in combination with Datashader timeseries.  For instance, you can compute a rolling mean of the results and then show a subset of outlier points, which will then support hover, selection, and other interactive Bokeh features:
+
+
+```python
+from holoviews.operation.timeseries import rolling, rolling_outlier_std
+smoothed = rolling(curve, rolling_window=50)
+outliers = rolling_outlier_std(curve, rolling_window=50, sigma=2)
+
+ds_curve    = rasterize(curve, line_width=2.5, pixel_ratio=2).opts(cmap=["lightblue","blue"])
+curvespread = rasterize(smoothed, line_width=6, pixel_ratio=2).opts(cmap=["pink","red"], width=800) 
+
+(ds_curve * curvespread * outliers).opts(
+    opts.Scatter(line_color="black", fill_color="red", size=10, tools=['hover', 'box_select'], width=800))
+```
+
+Another option when working with time series is to downsample the data before plotting it. This can be done with `downsample1D`. Algorithms supported are `lttb` (Largest Triangle Three Buckets) and `nth` element. The two algorithm is overlaid on top of the original curve in the example below. 
+
+
+```python
+from holoviews.operation.downsample import downsample1d
+
+lttb = downsample1d(curve)
+nth = downsample1d(curve, algorithm="nth")
+
+lttb_com = (curve * lttb).opts(width=800, title="lttb comparison")
+nth_com = (curve * nth).opts(width=800, title="nth comparison")
+
+(lttb_com + nth_com).cols(1)
+```
+
+The result of all these operations can be laid out, overlaid, selected, and sampled just like any other HoloViews element, letting you work naturally with even very large datasets.
+
+Note that the above plot will look blocky in a static export (such as on anaconda.org), because the exported version is generated without taking the size of the actual plot (using default height and width for Datashader) into account, whereas the live notebook automatically regenerates the plot to match the visible area on the page. 
+
+# Element types supported for Datashading
+
+Fundamentally, what Datashader does is to rasterize data, i.e., render a representation of it into a regularly gridded rectangular portion of a two-dimensional plane.  Datashader natively supports six basic types of rasterization:
+
+- **points**: zero-dimensional objects aggregated by position alone, each point covering zero area in the plane and thus falling into exactly one grid cell of the resulting array (if the point is within the bounds being aggregated).
+- **line**: polyline/multiline objects (connected series of line segments), with each segment having a fixed length but either zero width (not antialiased) or a specified width, and crossing each grid cell at most once.
+- **area**: a region to fill either between the supplied y-values and the origin or between two supplied lines.
+- **trimesh**: irregularly spaced triangular grid, with each triangle covering a portion of the 2D plane and thus potentially crossing multiple grid cells (thus requiring interpolation/upsampling). Depending on the zoom level, a single pixel can also include multiple triangles, which then becomes similar to the `points` case (requiring aggregation/downsampling of all triangles covered by the pixel).
+- **raster**: an axis-aligned regularly gridded two-dimensional subregion of the plane, with each grid cell in the source data covering more than one grid cell in the output grid (requiring interpolation/upsampling), or with each grid cell in the output grid including contributions from more than one grid cell in the input grid (requiring aggregation/downsampling).
+- **quadmesh**: a recti-linear or curvi-linear mesh (like a raster, but allowing nonuniform spacing and coordinate mapping) where each quad can cover one or more cells in the output (requiring upsampling, currently only as nearest neighbor), or with each output grid cell including contributions from more than one input grid cell (requiring aggregation/downsampling).
+- **polygons**:  arbitrary filled shapes in 2D space (bounded by a piecewise linear set of segments), optionally punctuated by similarly bounded internal holes.
+
+Datashader focuses on implementing those four cases very efficiently, and HoloViews in turn can use them to render a very large range of specific types of data: 
+
+### Supported Elements
+
+- **points**: [`hv.Nodes`](../reference/elements/bokeh/Graph.ipynb), [`hv.Points`](../reference/elements/bokeh/Points.ipynb), [`hv.Scatter`](../reference/elements/bokeh/Scatter.ipynb)
+- **line**: [`hv.Contours`](../reference/elements/bokeh/Contours.ipynb), [`hv.Curve`](../reference/elements/bokeh/Curve.ipynb), [`hv.Path`](../reference/elements/bokeh/Path.ipynb), [`hv.Graph`](../reference/elements/bokeh/Graph.ipynb), [`hv.EdgePaths`](../reference/elements/bokeh/Graph.ipynb), [`hv.Spikes`](../reference/elements/bokeh/Spikes.ipynb), [`hv.Segments`](../reference/elements/bokeh/Segments.ipynb)
+- **area**: [`hv.Area`](../reference/elements/bokeh/Area.ipynb), [`hv.Rectangles`](../reference/elements/bokeh/Rectangles.ipynb), [`hv.Spread`](../reference/elements/bokeh/Spread.ipynb)
+- **raster**: [`hv.Image`](../reference/elements/bokeh/Image.ipynb), [`hv.HSV`](../reference/elements/bokeh/HSV.ipynb), [`hv.RGB`](../reference/elements/bokeh/RGB.ipynb)
+- **trimesh**: [`hv.TriMesh`](../reference/elements/bokeh/TriMesh.ipynb)
+- **quadmesh**: [`hv.QuadMesh`](../reference/elements/bokeh/QuadMesh.ipynb)
+- **polygons**: [`hv.Polygons`](../reference/elements/bokeh/Polygons.ipynb)
+
+Other HoloViews elements *could* be supported, but do not currently have a useful datashaded representation:
+
+### Elements not yet supported
+
+- **line**: [`hv.Spline`](../reference/elements/bokeh/Spline.ipynb), [`hv.VectorField`](../reference/elements/bokeh/VectorField.ipynb)
+- **raster**: [`hv.HeatMap`](../reference/elements/bokeh/HeatMap.ipynb), [`hv.Raster`](../reference/elements/bokeh/Raster.ipynb)
+
+There are also other Elements that are not expected to be useful with datashader because they are isolated annotations, are already summaries or aggregations of other data, have graphical representations that are only meaningful at a certain size, or are text based:
+
+### Not useful to support
+
+- datashadable annotations: [`hv.Arrow`](../reference/elements/bokeh/Arrow.ipynb), [`hv.Bounds`](../reference/elements/bokeh/Bounds.ipynb), [`hv.Box`](../reference/elements/bokeh/Box.ipynb), [`hv.Ellipse`](../reference/elements/bokeh/Ellipse.ipynb) (actually do work with datashade currently, but not officially supported because they are not vectorized and thus unlikely to have enough items to be worth datashading)
+- other annotations: [`hv.Labels`](../reference/elements/bokeh/Labels.ipynb), [`hv.HLine`](../reference/elements/bokeh/HLine.ipynb), [`hv.VLine`](../reference/elements/bokeh/VLine.ipynb), [`hv.Text`](../reference/elements/bokeh/Text.ipynb)
+- kdes: [`hv.Distribution`](../reference/elements/bokeh/Distribution.ipynb), [`hv.Bivariate`](../reference/elements/bokeh/Bivariate.ipynb) (already aggregated)
+- categorical/symbolic: [`hv.BoxWhisker`](../reference/elements/bokeh/BoxWhisker.ipynb), [`hv.Bars`](../reference/elements/bokeh/Bars.ipynb), [`hv.ErrorBars`](../reference/elements/bokeh/ErrorBars.ipynb)
+- tables: [`hv.Table`](../reference/elements/bokeh/Table.ipynb), [`hv.ItemTable`](../reference/elements/bokeh/ItemTable.ipynb)
+
+Let's make some examples of each supported Element type. First, some dummy data:
+
+
+```python
+from bokeh.sampledata.unemployment import data as unemployment
+from bokeh.sampledata.us_counties import data as counties
+
+np.random.seed(12)
+N=50
+pts = [(10*i/N, np.sin(10*i/N)) for i in range(N)]
+
+x = y = np.linspace(0, 5, int(np.sqrt(N)))
+xs,ys = np.meshgrid(x,y)
+z = np.sin(xs)*np.cos(ys)
+
+r = 0.5*np.sin(0.1*xs**2+0.05*ys**2)+0.5
+g = 0.5*np.sin(0.02*xs**2+0.2*ys**2)+0.5
+b = 0.5*np.sin(0.02*xs**2+0.02*ys**2)+0.5
+
+n=20
+coords = np.linspace(-1.5,1.5,n)
+X,Y = np.meshgrid(coords, coords);
+Qx = np.cos(Y) - np.cos(X)
+Qy = np.sin(Y) + np.sin(X)
+Z = np.sqrt(X**2 + Y**2)
+
+rect_colors = {True: 'red', False: 'green'}
+s = np.random.randn(100).cumsum()
+e = s + np.random.randn(100)
+```
+
+Next, some options:
+
+
+```python
+hv.output(backend='matplotlib')
+
+opts.defaults(opts.Layout(vspace=0.1, hspace=0.1, sublabel_format='', fig_size=48))
+eopts = dict(aspect=1, axiswise=True, xaxis='bare', yaxis='bare', xticks=False, yticks=False)
+opts2 = dict(filled=True, edge_color='z')
+rect_opts = opts.Rectangles(lw=0, color=hv.dim('sign').categorize(rect_colors))
+ds_point_opts = dict(aggregator='any')
+ds_line_opts  = dict(aggregator='any', line_width=1)
+ResampleOperation2D.width=115
+ResampleOperation2D.height=115
+
+ds_opts = {
+    hv.Path:       ds_line_opts,
+    hv.Graph:      ds_line_opts,
+    hv.Contours:   ds_line_opts,
+    hv.EdgePaths:  ds_line_opts,
+    hv.Curve:      ds_line_opts,
+    hv.Scatter:    ds_point_opts,
+    hv.Points:     ds_point_opts,
+    hv.Segments:   ds_point_opts,
+    hv.Rectangles: dict(aggregator=ds.count_cat('sign'), color_key=rect_colors)
+}
+```
+
+Now, some Elements that support datashading, in categories depending on whether they work best with `spread(rasterize())`, with plain `rasterize()`, or require `datashade()`:
+
+
+```python
+tri = hv.TriMesh.from_vertices(hv.Points(np.random.randn(N,3), vdims='z')).opts(**opts2)
+
+rasterizable  = [hv.Curve(pts)]
+rasterizable += [hv.operation.contours(hv.Image((x,y,z)), levels=10)]
+rasterizable += [hv.Area(np.random.randn(10000).cumsum())]
+rasterizable += [hv.Spread((np.arange(10000), np.random.randn(10000).cumsum(), np.random.randn(10000)*10))]
+rasterizable += [hv.Spikes(np.random.randn(1000))]
+rasterizable += [hv.Graph(((np.zeros(N//2), np.arange(N//2)),))]
+rasterizable += [hv.QuadMesh((Qx,Qy,Z))]
+rasterizable += [hv.Image((x,y,z))]
+rasterizable += [hv.RGB(np.dstack([r,g,b])), hv.HSV(np.dstack([g,b,r]))]
+rasterizable += [tri, tri.edgepaths]
+rasterizable += [hv.Path(counties[(1, 1)], ['lons', 'lats'])]
+
+polys = hv.Polygons([dict(county, unemployment=unemployment[k]) 
+                     for k, county in counties.items()
+                     if county['state'] == 'tx'], 
+                    ['lons', 'lats'], ['unemployment']).opts(color='unemployment')
+try:
+    import spatialpandas # Needed for datashader polygon support
+    rasterizable += [polys]
+except: pass
+
+spreadable  = [e(pts) for e in [hv.Scatter]]
+spreadable += [hv.Points(counties[(1, 1)], ['lons', 'lats'])]
+spreadable += [hv.Segments((np.arange(100), s, np.arange(100), e))]
+
+shadeable  = [hv.Rectangles((np.arange(100)-0.4, s, np.arange(100)+0.4, e, s>e), vdims='sign').opts(rect_opts)]
+```
+
+We can now view these with Datashader via `spread(rasterize())`, `rasterize()`, or `datashade()`:
+
+
+```python
+def nop(x,**k):      return x
+def spread2(e, **k): return spread(rasterize(e, **k), px=2).opts(cnorm='eq_hist', padding=0.1) 
+def plot(e, operation=nop):
+    return operation(e.relabel(e.__class__.name), **ds_opts.get(e.__class__, {})).opts(**eopts)
+
+hv.Layout(
+    [plot(e, rasterize) for e in rasterizable] + \
+    [plot(e, spread2)   for e in spreadable] + \
+    [plot(e, datashade) for e in shadeable]).cols(6)
+```
+
+For comparison, you can see the corresponding non-datashaded plots (as long as you leave N lower than 10000 unless you have a long time to wait!):
+
+
+```python
+hv.Layout([plot(e) for e in rasterizable + spreadable + shadeable]).cols(6)
+```
+
+The previous two sets of examples use Matplotlib, but if they were switched to Bokeh and you had a live server, they would support dynamic re-rendering on zoom and pan so that you could explore the full range of data available (e.g. even very large raster images, networks, paths, point clouds, or meshes).
+
+
+```python
+hv.output(backend='bokeh') # restore bokeh backend in case cells will run out of order
+```
+
+# Container types supported for datashading
+
+In the above examples `datashade()` or `rasterize` was called directly on each Element, but these operations can also be called on Containers, in which case each Element in the Container will be datashaded separately (for all Container types other than a Layout):
+
+
+```python
+curves = {'+':hv.Curve(pts), '-':hv.Curve([(x, -1.0*y) for x, y in pts])}
+rasterize(hv.HoloMap(curves,'sign'), line_width=3)
+```
+
+
+```python
+rasterize(hv.NdLayout(curves,'sign'), line_width=3)
+```
+
+
+```python
+containers = [hv.Overlay(list(curves.values())), hv.NdOverlay(curves), hv.GridSpace(hv.NdOverlay(curves))]
+hv.Layout([rasterize(e.relabel(e.__class__.name), line_width=3) for e in containers]).cols(3)
+```
+
+# Optimizing performance
+
+Datashader and HoloViews have different design principles that are worth keeping in mind when using them in combination, if you want to ensure good overall performance. By design, Datashader supports only a small number of operations and datatypes, focusing only on what can be implemented very efficiently.  HoloViews instead focuses on supporting the typical workflows of Python users, recognizing that the most computationally efficient choice is only going to be faster overall if it also minimizes the time users have to spend getting things working. 
+
+HoloViews thus helps you get something working quickly, but once it is working and you realize that you need to do this often or that it comes up against the limits of your computing hardware, you can consider whether you can get much better performance by considering the following issues and suggestions.
+
+### Use a Datashader-supported data structure
+
+HoloViews helpfully tries to convert whatever data you have provided into what Datashader supports, which is good for optimizing your time to an initial solution, but will not always be the fastest approach computationally.  If you ensure that you store your data in a format that Datashader understands already, HoloViews can simply pass it down to Datashader without copying or transforming it:
+
+1. For point, line, and trimesh data, Datashader supports Dask and Pandas dataframes, and so those two data sources will be fastest. Of those two, Dask Dataframes will usually be somewhat faster and also able to make use of distributed computational resources and out-of-core processing.
+2. For rasters and quadmeshes, Datashader supports xarray objects natively, and so if your data is provided as an xarray already, plotting will be faster.
+3. For polygons Datashader supports [spatialpandas](https://github.com/holoviz/spatialpandas) DataFrames.
+
+See the [Datashader docs](http://datashader.org) for examples of dealing with even quite large datasets (in the billions of points) on commodity hardware, including many HoloViews-based examples.
+
+### Cache initial processing with `precompute=True`
+
+In the typical case of having datasets much larger than the plot resolution, HoloViews Datashader-based operations that work on the full dataset (`rasterize`, `aggregate`,`regrid`) are computationally expensive; the others are not (`shade`, `spread`, `dynspread`, etc.) 
+
+The expensive operations are all of type `ResamplingOperation`, which has a parameter `precompute` (see `hv.help(hv.operation.datashader.rasterize)`, etc.)  Precompute can be used to get faster performance in interactive usage by caching the last set of data used in plotting (*after* any transformations needed) and reusing it when it is requested again. This is particularly useful when your data is not in one of the supported data formats already and needs to be converted. `precompute` is False by default, because it requires using memory to store the cached data, but if you have enough memory, you can enable it so that repeated interactions (such as zooming and panning) will be much faster than the first one.  In practice, most Datashader-plots don't need to do extensive precomputing, but enabling it for TriMesh and Polygon plots can greatly speed up interactive usage.
+
+### Use GPU support
+
+Many elements now also support aggregation directly on a GPU-based datastructure such as a [cuDF DataFrame](https://github.com/rapidsai/cudf) or an Xarray DataArray backed by a [cupy](https://github.com/cupy/cupy) array. These data structures can be passed directly to the appropriate HoloViews elements just as you would use a Pandas or other Xarray object. For instance, a cuDF can be used on elements like `hv.Points` and `hv.Curve`, while a cupy-backed DataArray raster or quadmesh can be passed to `hv.QuadMesh` elements. When used with Datashader, the GPU implementation can result in 10-100x speedups, as well as avoiding having to transfer the data out of the GPU for plotting (sending only the final rendered plot out of the GPU's memory). To see which HoloViews elements are supported, see the [datashader performance guide](https://datashader.org/user_guide/Performance.html). As of the Datashader 0.11 release, all point, line, area, and quadmesh aggregations are supported when using a GPU backed datastructure, including raster objects like `hv.Image` if first converted to `hv.Quadmesh`.
+
+### Project data only once
+
+If you are working with geographic data using [GeoViews](http://geoviews.org) that needs to be projected before display and/or before datashading, GeoViews will have to do this every time you update a plot, which can drown out the performance improvement you get by using Datashader.  GeoViews allows you to project the entire dataset at once using `gv.operation.project`, and once you do this you should be able to use Datashader at full speed.
+
+If you follow these suggestions, the combination of HoloViews and Datashader will allow you to work uniformly with data covering a huge range of sizes. Per session or per plot, you can trade off the ability to export user-manipulable plots against file size and browser compatibility, and allowing you to render even the largest dataset faithfully. HoloViews makes the full power of Datashader available in just a few lines of code, giving you a natural way to work with your data regardless of its size.

hvplot_docs/16-Streaming_Data.md

@@ -0,0 +1,338 @@
+# Working with Streaming Data
+
+"Streaming data" is data that is continuously generated, often by some external source like a remote website, a measuring device, or a simulator. This kind of data is common for financial time series, web server logs, scientific applications, and many other situations. We have seen how to visualize any data output by a callable in the [Live Data](07-Live_Data.ipynb) user guide and we have also seen how to use the HoloViews stream system to push events in the user guide sections [Responding to Events](12-Responding_to_Events.ipynb) and [Custom Interactivity](13-Custom_Interactivity.ipynb).
+
+This user guide shows a third way of building an interactive plot, using ``DynamicMap`` and streams.  Here, instead of pushing plot metadata (such as zoom ranges, user triggered events such as ``Tap`` and so on) to a ``DynamicMap`` callback, the underlying data in the visualized elements are updated directly using a HoloViews ``Stream``.
+
+In particular, we will show how the HoloViews ``Pipe`` and ``Buffer`` streams can be used to work with streaming data sources without having to fetch or generate the data from inside the ``DynamicMap`` callable. Apart from simply setting element data from outside a ``DynamicMap``, we will also explore ways of working with streaming data coordinated by the separate [``streamz``](http://matthewrocklin.com/blog/work/2017/10/16/streaming-dataframes-1) library from Matt Rocklin, which can make building complex streaming pipelines much simpler.
+
+As this notebook makes use of the ``streamz`` library, you will need to install it with ``conda install streamz`` or ``pip install streamz``.
+
+
+```python
+import time
+import numpy as np
+import pandas as pd
+import holoviews as hv
+import streamz
+import streamz.dataframe
+
+from holoviews import opts
+from holoviews.streams import Pipe, Buffer
+
+hv.extension('bokeh')
+```
+
+## ``Pipe``
+
+A ``Pipe`` allows data to be pushed into a DynamicMap callback to change a visualization, just like the streams in the [Responding to Events](./12-Responding_to_Events.ipynb) user guide were used to push changes to metadata that controlled the visualization. A ``Pipe`` can be used to push data of any type and make it available to a ``DynamicMap`` callback. Since all ``Element`` types accept ``data`` of various forms we can use ``Pipe`` to push data directly to the constructor of an ``Element`` through a DynamicMap.
+
+
+We can take advantage of the fact that most Elements can be instantiated without providing any data, so we declare the the ``Pipe`` with an empty list, declare the ``DynamicMap``, providing the pipe as a stream, which will dynamically update a ``VectorField`` :
+
+
+```python
+pipe = Pipe(data=[])
+vector_dmap = hv.DynamicMap(hv.VectorField, streams=[pipe])
+vector_dmap.opts(color='Magnitude', xlim=(-1, 1), ylim=(-1, 1))
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/pipe_vectorfield.gif"></img>
+
+Having set up this ``VectorField`` tied to a ``Pipe`` we can start pushing data to it varying the orientation of the VectorField:
+
+
+```python
+x,y  = np.mgrid[-10:11,-10:11] * 0.1
+sine_rings  = np.sin(x**2+y**2)*np.pi+np.pi
+exp_falloff = 1/np.exp((x**2+y**2)/8)
+
+for i in np.linspace(0, 1, 25):
+    time.sleep(0.1)
+    pipe.send((x,y,sine_rings*i, exp_falloff))
+```
+
+This approach of using an element constructor directly does not allow you to use anything other than the default key and value dimensions. One simple workaround for this limitation is to use ``functools.partial`` as demonstrated in the **Controlling the length section** below.
+
+Since ``Pipe`` is completely general and the data can be any custom type, it provides a completely general mechanism to stream structured or unstructured data. Due to this generality, ``Pipe`` does not offer some of the more complex features and optimizations available when using the ``Buffer`` stream described in the next section.
+
+## ``Buffer``
+
+While ``Pipe`` provides a general solution for piping arbitrary data to ``DynamicMap`` callback,  ``Buffer`` on the other hand provides a very powerful means of working with streaming tabular data, defined as pandas dataframes, arrays or dictionaries of columns (as well as StreamingDataFrame, which we will cover later). ``Buffer`` automatically accumulates the last ``N`` rows of the tabular data, where ``N`` is defined by the ``length``.
+
+The ability to accumulate data allows performing operations on a recent history of data, while plotting backends (such as bokeh) can optimize plot updates by sending just the latest patch. This optimization works only if the ``data`` object held by the ``Buffer`` is identical to the plotted ``Element`` data, otherwise all the data will be updated as normal.
+
+#### A simple example: Brownian motion
+
+To initialize a ``Buffer`` we have to provide an example dataset which defines the columns and dtypes of the data we will be streaming. Next we define the ``length`` to keep the last 100 rows of data. If the data is a DataFrame we can specify whether we will also want to use the ``DataFrame`` ``index``. In this case we will simply define that we want to plot a ``DataFrame`` of 'x' and 'y' positions and a 'count' as ``Points`` and ``Curve`` elements:
+
+
+```python
+example = pd.DataFrame({'x': [], 'y': [], 'count': []}, columns=['x', 'y', 'count'])
+dfstream = Buffer(example, length=100, index=False)
+curve_dmap = hv.DynamicMap(hv.Curve, streams=[dfstream])
+point_dmap = hv.DynamicMap(hv.Points, streams=[dfstream])
+```
+
+After applying some styling we will display an ``Overlay`` of the dynamic ``Curve`` and ``Points``
+
+
+```python
+(curve_dmap * point_dmap).opts(
+    opts.Points(color='count', line_color='black', size=5, padding=0.1, xaxis=None, yaxis=None),
+    opts.Curve(line_width=1, color='black'))
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/brownian.gif"></img>
+
+Now that we have set up the ``Buffer`` and defined a ``DynamicMap`` to plot the data we can start pushing data to it. We will define a simple function which simulates brownian motion by accumulating x, y positions. We can ``send`` data through the ``hv.streams.Buffer`` directly.
+
+
+```python
+def gen_brownian():
+    x, y, count = 0, 0, 0
+    while True:
+        x += np.random.randn()
+        y += np.random.randn()
+        count += 1
+        yield pd.DataFrame([(x, y, count)], columns=['x', 'y', 'count'])
+
+brownian = gen_brownian()
+for i in range(200):
+    dfstream.send(next(brownian))
+```
+
+Finally we can clear the data on the stream and plot using the ``clear`` method:
+
+
+```python
+dfstream.clear()
+```
+
+Note that when using the ``Buffer`` stream the view will always follow the current range of the data by default, by setting ``buffer.following=False`` or passing following as an argument to the constructor this behavior may be disabled.
+
+## Using the Streamz library
+
+Now that we have discovered what ``Pipe`` and ``Buffer`` can do it's time to show how you can use them together with the ``streamz`` library. Although HoloViews does not depend on ``streamz`` and you can use the streaming functionality without needing to learn about it, the two libraries work well together, allowing you to build pipelines to manage continuous streams of data. Streamz is easy to use for simple tasks, but also supports complex pipelines that involve branching, joining, flow control, feedback and more. Here we will mostly focus on connecting streamz output to ``Pipe`` and then ``Buffer`` so for more details about the streamz API, consult the [streamz documentation](https://streamz.readthedocs.io/en/latest/).
+
+#### Using ``streamz.Stream`` together with ``Pipe``
+
+Let's start with a fairly simple example:
+
+1. Declare a ``streamz.Stream`` and a ``Pipe`` object and connect them into a pipeline into which we can push data. 
+2. Use a ``sliding_window`` of 10, which will first wait for 10 sets of stream updates to accumulate. At that point and for every subsequent update, it will apply ``pd.concat`` to combine the most recent 10 updates into a new dataframe.
+3. Use the ``sink`` method on the ``streamz.Stream`` to ``send`` the resulting collection of 10 updates to ``Pipe``.
+4. Declare a ``DynamicMap`` that takes the sliding window of concatenated DataFrames and displays it using a ``Scatter`` Element.
+5. Color the ``Scatter`` points by their 'count' and set a range, then display:
+
+
+```python
+point_source = streamz.Stream()
+pipe = Pipe(data=pd.DataFrame({'x': [], 'y': [], 'count': []}))
+point_source.sliding_window(20).map(pd.concat).sink(pipe.send) # Connect streamz to the Pipe
+scatter_dmap = hv.DynamicMap(hv.Scatter, streams=[pipe])
+```
+
+After set up our streaming pipeline we can again display it:
+
+
+```python
+scatter_dmap.opts(bgcolor='black', color='count', ylim=(-4, 4), show_legend=False)
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz1.gif"></img>
+
+There is now a pipeline, but initially this plot will be empty, because no data has been sent to it. To see the plot update, let's use the ``emit`` method of ``streamz.Stream`` to send small chunks of random pandas ``DataFrame``s to our plot:
+
+
+```python
+for i in range(100):
+    df = pd.DataFrame({'x': np.random.rand(100), 'y': np.random.randn(100), 'count': i},
+                      columns=['x', 'y', 'count'])
+    point_source.emit(df)
+```
+
+#### Using StreamingDataFrame and StreamingSeries
+
+The streamz library provides ``StreamingDataFrame`` and ``StreamingSeries`` as a powerful way to easily work with live sources of tabular data. This makes it perfectly suited to work with ``Buffer``. With the ``StreamingDataFrame`` we can easily stream data, apply computations such as cumulative and rolling statistics and then visualize the data with HoloViews.
+
+The ``streamz.dataframe`` module provides a ``Random`` utility that generates a ``StreamingDataFrame`` that emits random data with a certain frequency at a specified interval. The ``example`` attribute lets us see the structure and dtypes of the data we can expect:
+
+
+```python
+simple_sdf = streamz.dataframe.Random(freq='10ms', interval='100ms')
+print(simple_sdf.index)
+simple_sdf.example.dtypes
+```
+
+Since the ``StreamingDataFrame`` provides a pandas-like API, we can specify operations on the data directly. In this example we subtract a fixed offset and then compute the cumulative sum, giving us a randomly drifting timeseries. We can then pass the x-values of this dataframe to the HoloViews ``Buffer`` and supply ``hv.Curve`` as the ``DynamicMap`` callback to stream the data into a HoloViews ``Curve`` (with the default key and value dimensions):
+
+
+```python
+sdf = (simple_sdf-0.5).cumsum()
+hv.DynamicMap(hv.Curve, streams=[Buffer(sdf.x)]).opts(width=500, show_grid=True)
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz3.gif"></img>
+
+The ``Random`` StreamingDataFrame will asynchronously emit events, driving the visualization forward, until it is explicitly stopped, which we can do by calling the ``stop`` method.
+
+
+```python
+simple_sdf.stop()
+```
+
+#### Making use of the ``StreamingDataFrame`` API
+
+So far we have only computed the cumulative sum, but the ``StreamingDataFrame`` actually has an extensive API that lets us run a broad range of streaming computations on our data. For example, let's apply a rolling mean to our x-values with a window of 500ms and overlay it on top of the 'raw' data:
+
+
+```python
+source_df = streamz.dataframe.Random(freq='5ms', interval='100ms')
+sdf = (source_df-0.5).cumsum()
+raw_dmap = hv.DynamicMap(hv.Curve, streams=[Buffer(sdf.x)])
+smooth_dmap = hv.DynamicMap(hv.Curve, streams=[Buffer(sdf.x.rolling('500ms').mean())])
+
+(raw_dmap.relabel('raw') * smooth_dmap.relabel('smooth')).opts(
+    opts.Curve(width=500, show_grid=True))
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz4.gif"></img>
+
+
+```python
+source_df.stop()
+```
+
+#### Customizing elements with ``functools.partial``
+
+In this notebook we have avoided defining custom functions for ``DynamicMap`` by simply supplying the element class and using the element constructor instead. Although this works well for examples, it often won't generalize to real-life situations, because you don't have an opportunity to use anything other than the default dimensions. One simple way to get around this limitation is to use ``functools.partial``:
+
+
+
+
+```python
+from functools import partial
+```
+
+Now you can now easily create an inline callable that creates an element with custom key and value dimensions by supplying them to ``partial`` in the form ``partial(hv.Element, kdims=[...], vdims=[...])``. In the next section, we will see an example of this pattern using ``hv.BoxWhisker``.
+
+#### Controlling the length
+
+By default the ``Buffer`` accumulates a ``length`` of 1000 samples. In many cases this may be excessive, but we can specify a shorter (or longer) length value to control how much history we accumulate, often depending on the element type.
+
+In the following example, a custom ``length`` is used together with a ``partial`` wrapping ``hv.BoxWhisker`` in order to display a cumulative sum generated from a stream of random dataframes:
+
+
+```python
+multi_source = streamz.dataframe.Random(freq='50ms', interval='500ms')
+sdf = (multi_source-0.5).cumsum()
+hv.DynamicMap(hv.Table, streams=[Buffer(sdf.x, length=10)]) +\
+hv.DynamicMap(partial(hv.BoxWhisker, kdims=[], vdims='x'), streams=[Buffer(sdf.x, length=100)])
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz5.gif"></img>
+
+Here the given stream ``sdf`` is being consumed by a table showing a short length (where only the items visible in the table need to be kept), along with a plot computing averages and variances over a longer length (100 items).
+
+#### Updating multiple cells
+
+Since a ``StreamingDataFrame`` will emit data until it is stopped, we can subscribe multiple plots across different cells to the same stream.  Here, let's add a ``Scatter`` plot of the same data stream as in the preceding cell:
+
+
+```python
+hv.DynamicMap(hv.Scatter, streams=[Buffer(sdf.x)]).redim.label(x='value', index='time')
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz6.gif"></img>
+
+Here we let the ``Scatter`` elements use the column names from the supplied ``DataFrames`` which are relabelled using the ``redim`` method. Stopping the stream will now stop updates to all three of these DynamicMaps:
+
+
+```python
+multi_source.stop()
+```
+
+## Operations over streaming data
+
+As we discovered above, the ``Buffer`` lets us set a ``length``, which defines how many rows we want to accumulate. We can use this to our advantage and apply an operation over this length window. In this example we declare a ``Dataset`` and then apply the ``histogram`` operation to compute a ``Histogram`` over the specified ``length`` window:
+
+
+```python
+hist_source = streamz.dataframe.Random(freq='5ms', interval='100ms')
+sdf = (hist_source-0.5).cumsum()
+dmap = hv.DynamicMap(hv.Dataset, streams=[Buffer(sdf.x, length=500)])
+hv.operation.histogram(dmap, dimension='x')
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz7.gif"></img>
+
+
+```python
+hist_source.stop()
+```
+
+#### Datashading
+
+The same approach will also work for the datashader operation letting us datashade the entire ``length`` window even if we make it very large such as 1 million samples:
+
+
+```python
+from holoviews.operation.datashader import datashade
+from bokeh.palettes import Blues8
+
+large_source = streamz.dataframe.Random(freq='100us', interval='200ms')
+sdf = (large_source-0.5).cumsum()
+dmap = hv.DynamicMap(hv.Curve, streams=[Buffer(sdf.x, length=1000000)])
+datashade(dmap, streams=[hv.streams.PlotSize], cnorm='linear', cmap=list(Blues8)).opts(width=600)
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz8.gif"></img>
+
+
+```python
+large_source.stop()
+```
+
+## Asynchronous updates using the tornado ``IOLoop``
+
+In most cases, instead of pushing updates manually from the same Python process, you'll want the object to update asynchronously as new data arrives. Since both Jupyter and Bokeh server run on [tornado](http://www.tornadoweb.org/en/stable/), we can use the tornado ``IOLoop`` in both cases to define a non-blocking co-routine that can push data to our stream whenever it is ready. The ``PeriodicCallback`` makes this approach very simple, we simply define a function which will be called periodically with a timeout defined in milliseconds. Once we have declared the callback we can call ``start`` to begin emitting events:
+
+
+```python
+from tornado.ioloop import PeriodicCallback
+from tornado import gen
+
+count = 0
+buffer = Buffer(np.zeros((0, 2)), length=50)
+
+@gen.coroutine
+def f():
+    global count
+    count += 1
+    buffer.send(np.array([[count, np.random.rand()]]))
+
+cb = PeriodicCallback(f, 100)
+cb.start()
+
+hv.DynamicMap(hv.Curve, streams=[buffer]).opts(padding=0.1, width=600)
+```
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz2.gif"></img>
+
+Since the callback is non-blocking we can continue working in the notebook and execute other cells. Once we're done we can stop the callback by calling ``cb.stop()``.
+
+
+```python
+cb.stop()
+```
+
+## Real examples
+
+Using the ``Pipe`` and ``Buffer`` streams we can create complex streaming plots very easily. In addition to the toy examples we presented in this guide it is worth looking at looking at some of the examples using real, live, streaming data.
+
+* The [streaming_psutil](http://holoviews.org/gallery/apps/bokeh/streaming_psutil.html) bokeh app is one such example which display CPU and memory information using the ``psutil`` library  (install with ``pip install psutil`` or ``conda install psutil``)
+
+<img class="gif" src="https://assets.holoviews.org/gifs/guides/user_guide/Streaming_Data/streamz9.gif"></img>
+
+As you can see, streaming data works like streams in HoloViews in general, flexibly handling changes over time under either explicit control or governed by some external data source.

hvplot_docs/17-Dashboards.md

@@ -0,0 +1,159 @@
+# Creating interactive dashboards
+
+
+```python
+import pandas as pd
+import holoviews as hv
+
+from bokeh.sampledata import stocks
+from holoviews.operation.timeseries import rolling, rolling_outlier_std
+
+hv.extension('bokeh')
+```
+
+In the [Data Processing Pipelines section](./14-Data_Pipelines.ipynb) we discovered how to declare a ``DynamicMap`` and control multiple processing steps with the use of custom streams as described in the [Responding to Events](./12-Responding_to_Events.ipynb) guide. A DynamicMap works like a tiny web application, with widgets that select values along a dimension, and a plot that updates.  Let's start with a function that loads stock data and see what a DynamicMap can do:
+
+
+```python
+def load_symbol(symbol, variable, **kwargs):
+    df = pd.DataFrame(getattr(stocks, symbol))
+    df['date'] = df.date.astype('datetime64[ns]')
+    return hv.Curve(df, ('date', 'Date'), variable).opts(framewise=True)
+
+stock_symbols = ['AAPL', 'IBM', 'FB', 'GOOG', 'MSFT']
+variables = ['open', 'high', 'low', 'close', 'volume', 'adj_close']
+dmap = hv.DynamicMap(load_symbol, kdims=['Symbol','Variable'])
+dmap = dmap.redim.values(Symbol=stock_symbols, Variable=variables)
+
+dmap.opts(framewise=True)
+rolling(dmap, rolling_window=2)
+```
+
+Here we already have widgets for Symbol and Variable, as those are dimensions in the DynamicMap, but what if we wanted a widget to control the `rolling_window`width value in the HoloViews operation?  We could redefine the DynamicMap to include the operation and accept that parameter as another dimension, but in complex cases we would quickly find we need more flexibility in defining widgets and layouts than DynamicMap can give us directly.
+
+## Building dashboards
+
+For more flexibility, we can build a full-featured dashboard using the [Panel](https://panel.pyviz.org) library, which is what a DynamicMap is already using internally to generate widgets and layouts. We can easily declare our own custom Panel widgets and link them to HoloViews streams to get dynamic, user controllable analysis workflows.
+
+Here, let's start with defining various Panel widgets explicitly, choosing a `RadioButtonGroup` for the `symbol` instead of DynamicMaps's default `Select` widget:
+
+
+```python
+import panel as pn
+
+symbol = pn.widgets.RadioButtonGroup(options=stock_symbols)
+variable = pn.widgets.Select(options=variables)
+rolling_window = pn.widgets.IntSlider(name='Rolling Window', value=10, start=1, end=365)
+
+pn.Column(symbol, variable, rolling_window)
+```
+
+As you can see, these widgets can be displayed but they aren't yet attached to anything, so they don't do much. We can now use ``pn.bind`` to bind the `symbol` and `variable` widgets to the arguments of the DynamicMap callback function, and provide `rolling_window` to the `rolling` operation argument. (HoloViews operations accept Panel widgets or param Parameter values, and they will then update reactively to changes in those widgets.)
+
+We can then lay it all out into a simple application that works similarly to the regular DynamicMap display but where we can add our additional widget and control every aspect of the widget configuration and the layout:
+
+
+```python
+dmap = hv.DynamicMap(pn.bind(load_symbol, symbol=symbol, variable=variable))
+smoothed = rolling(dmap, rolling_window=rolling_window)
+
+app = pn.Row(pn.WidgetBox('## Stock Explorer', symbol, variable, rolling_window), 
+             smoothed.opts(width=500, framewise=True)).servable()
+app
+```
+
+Here we chose to lay the widgets out into a box to the left of the plot, but we could put the widgets each in different locations, add different plots, etc., to create a full-featured dashboard. See [panel.holoviz.org](https://panel.holoviz.org) for the full set of widgets and layouts supported.
+
+Now that we have an app, we can launch it in a separate server if we wish (using `app.show()`), run it as an entirely separate process (`panel serve <thisfilename>.ipynb`, to serve the object marked `servable` above), or export it to a static HTML file (sampling the space of parameter values using "embed"):
+
+
+```python
+app.save("dashboard.html", embed=True)
+```
+
+## Declarative dashboards
+
+What if we want our analysis code usable both as a dashboard and also in "headless" contexts such as batch jobs or remote execution? Both Panel and HoloViews are built on the [param](https://param.holoviz.org) library, which lets you capture the definitions and allowable values for your widgets in a way that's not attached to any GUI. That way you can declare all of your attributes and allowed values once, presenting a GUI if you want to explore them interactively or else simply provide specific values if you want batch operation.
+
+With this approach, we declare a ``StockExplorer`` class subclassing ``Parameterized`` and defining three parameters, namely the rolling window, the symbol, and the variable to show for that symbol:
+
+
+```python
+import param
+
+class StockExplorer(param.Parameterized):
+
+    rolling_window = param.Integer(default=10, bounds=(1, 365))
+    symbol = param.ObjectSelector(default='AAPL', objects=stock_symbols)
+    variable = param.ObjectSelector(default='adj_close', objects=variables)
+
+    @param.depends('symbol', 'variable')
+    def load_symbol(self):
+        df = pd.DataFrame(getattr(stocks, self.symbol))
+        df['date'] = df.date.astype('datetime64[ns]')
+        return hv.Curve(df, ('date', 'Date'), self.variable).opts(framewise=True)
+```
+
+Here the StockExplorer class will look similar to the Panel code above, defining most of the same information that's in the Panel widgets, but without any dependency on Panel or other GUI libraries; it's simply declaring that this code accepts certain parameter values of the specified types and ranges. These declarations are useful even outside a GUI context, because they allow type and range checking for detecting user errors, but they are also sufficient for creating a GUI later. 
+
+Instead of using `pn.bind` to bind widget values to functions, here we are declaring that each method depends on the specified parameters, which can be expressed independently of whether there is a widget controlling those parameters; it simply declares (in a way that Panel can utilize) that the given method needs re-running when any of the parameters in that list changes. 
+
+Now let's use the `load_symbol` method, which already declares which parameters it depends on, as the callback of a DynamicMap and create widgets out of those parameters to build a little GUI:
+
+
+```python
+explorer = StockExplorer()
+stock_dmap = hv.DynamicMap(explorer.load_symbol)
+pn.Row(explorer.param, stock_dmap)
+```
+
+Here you'll notice that the `rolling_window` widget doesn't do anything, because it's not connected to anything (e.g., nothing `@param.depends` on it). As we saw in the [Data Processing Pipelines section](./14-Data_Pipelines.ipynb), the ``rolling`` and ``rolling_outlier_std`` operations both accept a ``rolling_window`` parameter, so lets provide that to the operations and display the output of those operations. Finally we compose everything into a panel ``Row``:
+
+
+```python
+# Apply rolling mean
+smoothed = rolling(stock_dmap, rolling_window=explorer.param.rolling_window)
+
+# Find outliers
+outliers = rolling_outlier_std(stock_dmap, rolling_window=explorer.param.rolling_window).opts(
+    color='red', marker='triangle')
+
+pn.Row(explorer.param, (smoothed * outliers).opts(width=600))
+```
+
+## Replacing the output
+
+Updating plots using a ``DynamicMap`` is a very efficient means of updating a plot since it will only update the data that has changed. In some cases it is either necessary or more convenient to redraw a plot entirely. ``Panel`` makes this easy by annotating a method with any dependencies that should trigger the plot to be redrawn. In the example below we extend the ``StockExplorer`` by adding a ``datashade`` boolean and a view method which will flip between a datashaded and regular view of the plot:
+
+
+```python
+from holoviews.operation.datashader import datashade, dynspread
+
+class AdvancedStockExplorer(StockExplorer):    
+
+    datashade = param.Boolean(default=False)
+
+    @param.depends('datashade')
+    def view(self):
+        stocks = hv.DynamicMap(self.load_symbol)
+
+        # Apply rolling mean
+        smoothed = rolling(stocks, rolling_window=self.param.rolling_window)
+        if self.datashade:
+            smoothed = dynspread(datashade(smoothed, aggregator='any')).opts(framewise=True)
+
+        # Find outliers
+        outliers = rolling_outlier_std(stocks, rolling_window=self.param.rolling_window).opts(
+            width=600, color='red', marker='triangle', framewise=True)
+        return (smoothed * outliers)
+```
+
+In the previous example we explicitly called the ``view`` method, but to allow ``panel`` to update the plot when the datashade parameter is toggled we instead pass it the actual view method. Whenever the datashade parameter is toggled ``panel`` will call the method and update the plot with whatever is returned:
+
+
+```python
+explorer = AdvancedStockExplorer()
+pn.Row(explorer.param, explorer.view)
+```
+
+As you can see using streams we have bound the widgets to the streams letting us easily control the stream values and making it trivial to define complex dashboards. For more information on how to deploy bokeh apps from HoloViews and build dashboards see the [Deploying Bokeh Apps](./Deploying_Bokeh_Apps.ipynb) user guide section.

hvplot_docs/Annotators.md

@@ -0,0 +1,229 @@
+```python
+import holoviews as hv
+import numpy as np
+import panel as pn
+
+hv.extension('bokeh')
+```
+
+HoloViews-generated plots generally convey information from Python _to_ a viewer of the plot, but there are also circumstances where information needs to be collected _from_ the viewer and made available for processing in Python:
+
+* annotating data with contextual information to aid later interpretation
+* labeling or tagging data for automated machine-learning or other processing pipelines
+* indicating regions of interest, outliers, or other semantic information
+* specifying inputs to a query, command, or simulation
+* testing sensitivity of analyses to adding, changing, or deleting user-selected data points
+
+In such cases, it is important to be able to augment, edit, and annotate datasets and to access those values from Python. To perform these actions, HoloViews provides an ``annotate`` helper using [Bokeh's drawing tools](https://docs.bokeh.org/en/latest/docs/reference/models/tools.html#bokeh.models.tools.PointDrawTool) to make it easy to edit HoloViews Elements and add additional information using an associated table. The `annotate` helper:
+
+* Adds plot tools that allow editing and adding new elements to a plot  
+* Adds table(s) to allow editing the element in a tabular format
+* Returns a layout of these two components
+* Makes the edits, annotations, and selections available on a property of the annotate object so that they can be utilized in Python
+
+## Basics
+
+Let us start by annotating a small set of Points. To do this, we need two things:
+
+1. A Points Element to annotate or edit
+2. An annotator object to collect and store annotations
+
+The annotator is a callable object with its own state that can be called to return a Layout consisting of the object to be annotated and an Overlay of editable table(s):
+
+
+```python
+points = hv.Points([(0.0, 0.0), (1.0, 1.0), (200000.0, 2000000.0)]).opts(size=10, min_height=500)
+
+annotator = hv.annotate.instance()
+layout = annotator(hv.element.tiles.OSM() * points, annotations=['Label'], name="Point Annotations")
+
+print(layout)
+```
+
+This layout of a DynamicMap (the user-editable Element data) and an Overlay (the user-editable table) lets a user input the required information:
+
+
+```python
+layout
+```
+
+Here we have pre-populated the Element with three points. Each of the points has three bits of information that can be edited using the table: the x location, y location, and a "Label",  which was initialized to dummy values when we called `annotate` and asked that there be a `Label` column.  Try clicking on one of the rows and editing the location or the label to anything you like. As long as Python is running and the new location is in the viewport, you should see the dot move when you edit the location, and any labels you entered should be visible in the table.
+
+You can also edit the locations graphically using the [PointDraw tool](../reference/streams/bokeh/PointDraw.ipynb) in the toolbar:<img src="https://bokeh.pydata.org/en/latest/_images/PointDraw.png">
+
+Once you select that tool, you should be able to click and drag any of the existing points and see the location update in the table. Whether you click on the table or the points, the same object should be selected in each, so that you can see how the graphical and tabular representations relate.
+
+The PointDraw tool also allows us to add completely new points; once the tool is selected, just click on the plot above in locations not already containing a point and you can see a new point and a new table row appear ready for editing. You can also delete points by selecting them in the plot then pressing Backspace or Delete (depending on operating system).
+
+All the above editing and interaction could have been done if we had simply called `hv.annotate(points, annotations=['Label'])` directly, but instead we first saved an "instance" of the annotator object so that we'd also be able to access the resulting data. So, once we are done collecting data from the user, let's use the saved `annotator` object handle to read out the values (by re-evaluating the following line):
+
+
+```python
+annotator.annotated.dframe()
+```
+
+You should see that you can access the current set of user-provided or user-modified points and their user-provided labels from within Python, ready for any subsequent processing you need to do. 
+
+We can also access the currently `selected` points, in case we care only about a subset of the points (which will be empty if no points/rows are selected):
+
+
+```python
+annotator.selected.dframe()
+```
+
+## Configuring the Annotator
+
+In addition to managing the list of `annotations`, the `annotate` helper exposes a few additional parameters. Remember like most Param-based objects you can get help about `annotate` parameters using the `hv.help` function:
+
+
+```python
+hv.help(hv.annotate)
+```
+
+### Annotation types
+
+The default annotation type is a string, to allow you to put in arbitrary information that you later process in Python. If you want to enforce a more specific type, you can specify the annotation-value types explicitly using a dictionary mapping from column name to the type:
+
+
+```python
+hv.annotate(points, annotations={'int': int, 'float': float, 'str': str})
+```
+
+This example also shows how to collect multiple columns of information for the same data point.
+
+## Types of Annotators
+
+Currently only a limited set of Elements may be annotated, which include:
+
+* ``Points``/``Scatter``
+* ``Curve``
+* ``Path``
+* ``Polygons``
+* ``Rectangles``
+
+Adding support for new elements, in most cases, requires adding corresponding drawing/edit tools to Bokeh itself. But if you have data of other types, you may still be able to annotate it by casting it to one of the indicated types, collecting the data, then casting it back.
+
+## Annotating Curves
+
+To allow dragging the vertices of the Curve, the ``Curve`` annotator uses the PointDraw tool in the toolbar: <img src="https://bokeh.pydata.org/en/latest/_images/PointDraw.png">
+The vertices will appear when the tool is selected or a vertex is selected in the table. Unlike most other annotators the Curve annotator only allows editing the vertices and does not allow adding new ones.
+
+
+```python
+curve = hv.Curve(np.random.randn(50).cumsum())
+
+curve_annotator = hv.annotate.instance()
+
+curve_annotator(curve.opts(width=800, height=400, responsive=False), annotations={'Label': str})
+```
+
+To access the data you can make use of the ``annotated`` property on the annotator:
+
+
+```python
+curve_annotator.annotated.dframe().head(5)
+```
+
+## Annotating Rectangles
+
+The `Rectangles` annotator behaves very similarly to the Points annotator. It allows adding any number of annotation columns, using Bokeh's `BoxEdit` tool that allows both drawing and moving boxes. To see how to use the BoxEdit tool, refer to the HoloViews [BoxEdit stream reference](../reference/streams/bokeh/BoxEdit.ipynb), but briefly:
+
+* Select the `BoxEdit` tool in the toolbar: <img src="https://bokeh.pydata.org/en/latest/_images/BoxEdit.png">
+* Click and drag on an existing Rectangle to move it
+* Double click to start drawing a new Rectangle at one corner, and double click to complete the rectangle at the opposite corner
+* Select a rectangle and press the Backspace or Delete key (depending on OS) to delete it
+* Edit the box coordinates in the table to resize it
+
+
+```python
+boxes = hv.Rectangles([(0, 0, 1, 1), (1.5, 1.5, 2.5, 2.5)])
+
+box_annotator = hv.annotate.instance()
+
+box_annotator(boxes.opts(width=800, height=400, responsive=False), annotations=['Label'])
+```
+
+To access the data we can make use of the ``annotated`` property on the annotator instance:
+
+
+```python
+box_annotator.annotated.dframe()
+```
+
+### Annotating paths/polygons
+
+Unlike the Points and Boxes annotators, the Path and Polygon annotators allow annotating not just each individual entity but also the vertices that make up the paths and polygons. For more information about using the editing tools associated with this annotator refer to the HoloViews [PolyDraw](../reference/streams/PolyDraw.ipynb) and [PolyEdit](../reference/streams/PolyEdit.ipynb) stream reference guides, but briefly:
+
+##### Drawing/Selecting Deleting Paths/Polygons
+
+- Select the PolyDraw tool in the toolbar: <img src="https://bokeh.pydata.org/en/latest/_images/PolyDraw.png">
+- Double click to start a new object, single click to add each vertex, and double-click to complete it.
+- Delete paths/polygons by selecting and pressing Delete key (OSX) or Backspace key (PC)
+
+##### Editing Paths/Polygons
+
+- Select the PolyEdit tool in the toolbar: <img src="https://bokeh.pydata.org/en/latest/_images/PolyEdit.png">
+- Double click a Path/Polygon to start editing
+- Drag vertices to edit them, delete vertices by selecting them
+
+To edit and annotate the vertices, use the draw tool or the first table to select a particular path/polygon and then navigate to the Vertices tab.
+
+
+```python
+path = hv.Path([hv.Box(0, 0, 1), hv.Ellipse(1, 1, 1)])
+
+path_annotator = hv.annotate.instance()
+
+path_annotator(path.opts(width=800, height=400, responsive=False), annotations=['Label'], vertex_annotations=['Value'])
+```
+
+To access the data we can make use of the iloc method on `Path` objects to access a particular path, and then access the `.data` or convert it to a dataframe:
+
+
+```python
+path_annotator.annotated.iloc[0].dframe()
+```
+
+## Composing Annotators
+
+Often we will want to add some annotations on top of one or more other elements which provide context, e.g. when annotating an image with a set of `Points`. As long as only one annotation layer is required you can pass an overlay of multiple elements to the `annotate` operation and it will automatically associate the annotator with the layer that supports annotation. Note however that this will error if multiple elements that support annotation are provided. Below we will annotate a two-photon microscopy image with a set of Points, e.g. to mark the location of each cell:
+
+
+```python
+img = hv.Image(np.load('../assets/twophoton.npz')['Calcium'][..., 0])
+cells = hv.Points([]).opts(width=500, height=500, responsive=False, padding=0)
+
+hv.annotate(img * cells, annotations=['Label'], name="Cell Annotator")
+```
+
+### Multiple Annotators
+
+If you want to work with multiple annotators in the same plot, you can recompose and rearrange the components returned by each `annotate` helper manually, but doing so can get confusing. To simplify working with multiple annotators at the same time, the `annotate` helper provides a special classmethod that allows composing multiple annotators and other elements, e.g. making a set of tiles into a combined layout consisting of all the components:
+
+
+```python
+point_annotate = hv.annotate.instance()
+points = hv.Points([(500000, 500000), (1000000, 1000000)]).opts(size=10, color='red', line_color='black')
+point_layout = point_annotate(points, annotations=['Label'])
+
+poly_annotate = hv.annotate.instance()
+poly_layout = poly_annotate(hv.Polygons([]), annotations=['Label'])
+
+hv.annotate.compose(hv.element.tiles.OSM(), point_layout, poly_layout)
+```
+
+## Internals
+
+The `annotate` function builds on [Param](https://param.holoviz.org) and [Panel](https://panel.holoviz.org), creating and wrapping Panel `Annotator` panes internally. These objects make it easy to include the annotator in Param-based workflows and trigger actions when parameters change and/or update the annotator in response to external events. The Annotator of a `annotate` instance can be accessed using the `annotator` attribute:
+
+
+```python
+print(point_annotate.annotator)
+```
+
+This object can be included directly in a Panel layout, be used to watch for parameter changes, or updated directly. To see the effect of updating directly, uncomment the line below, execute that cell, and then look at the previous plot of Africa, which should get updated with 10 randomly located blue dots.
+
+
+```python
+#point_annotate.annotator.object = hv.Points(np.random.randn(10, 2)*1000000).opts(color='blue')
+```

hvplot_docs/Colormaps.md

@@ -0,0 +1,234 @@
+## Using colormaps
+
+HoloViews supports a wide range of colormaps, each of which allow you to translate numerical data values into visible colors in a plot. Here we will review all the colormaps provided for HoloViews and discuss when and how to use them.
+
+The [Styling_Plots](Styling_Plots.ipynb) user guide discusses how to specify any of the colormaps discussed here, using the `cmap` style option:
+
+
+```python
+import numpy as np
+import holoviews as hv
+hv.extension('matplotlib')
+
+ls  = np.linspace(0, 10, 400)
+x,y = np.meshgrid(ls, ls)
+img = hv.Image(np.sin(x)*np.cos(y)+0.1*np.random.rand(400,400), 
+               bounds=(-20,-20,20,20)).opts(colorbar=True, xaxis=None, yaxis=None)
+
+hv.Layout([img.relabel(c).opts(cmap=c) for c in ['gray','PiYG','flag','Set1']])
+```
+
+As you can see, the colormap you choose can dramatically change how your data appears. A well-chosen colormap can help guide the user to notice the features of the data you want to highlight, while a poorly chosen colormap can completely obscure the data and lead to erroneous conclusions. E.g. the low levels of noise present in this data are very difficult to see in A and B, but they completely dominate the plot in C and are visible only at specific (presumably arbitrary) value levels that correspond to color transitions in D. Thus it is important to choose colormaps very carefully!
+
+Note that the `cmap` style option used above is applied by the underlying plotting library, not by HoloViews itself. In the above example, Matplotlib uses it as the colormap constructs the image, whereas a Bokeh version of the same plot would provide the colormap to the Bokeh JavaScript code running in the local web browser, which allows the user to control the colormap dynamically in some cases.
+
+Colormaps can also be used with the [Datashader `shade()` operation](15-Large_Data.ipynb), in which the provided `cmap` is applied by Datashader to create an image *before* passing the image to the plotting library, which enables additional Datashader features but disables client-side features like colorbars and dynamic colormapping on display.
+
+## Available colormaps
+
+As outlined in [Styling_Plots](Styling_Plots.ipynb), you can easily make your own custom colormaps, but it's quite difficult to ensure that a custom map is designed well, so it's generally best to choose an existing, well-tested colormap. Here we will show the many different types of colormaps available, discussing each category and how to use that type of map. The ones shown here are those that are available by name, if the corresponding provider has been installed. E.g. those labelled "(bokeh)" will only be available if Bokeh is installed.
+
+Most of these colormaps will work best on *either* a light or a dark background, but not both. To faithfully and intuitively represent monotonically increasing values, you will generally want a colormap where the lowest values are similar in tone to the page background, and higher values become more perceptually salient compared to the page background. To let you match the colormap to the page, the maps listed below have a variant suffixed with `_r` (not shown), which is the same map but with the reverse order.
+
+
+```python
+from math import ceil
+from holoviews.plotting.util import process_cmap
+
+colormaps = hv.plotting.list_cmaps()
+spacing = np.linspace(0, 1, 64)[np.newaxis]
+opt_kwargs = dict(aspect=6, xaxis=None, yaxis=None, sublabel_format='')
+
+def filter_cmaps(category):
+    return hv.plotting.util.list_cmaps(records=True,category=category,reverse=False)
+
+def cmap_examples(category,cols=4):
+    cms = filter_cmaps(category)
+    n = len(cms)*1.0
+    c=ceil(n/cols) if n>cols else cols
+    bars = [hv.Image(spacing, ydensity=1, label="{0} ({1})".format(r.name,r.provider))\
+            .opts(cmap=process_cmap(r.name,provider=r.provider), **opt_kwargs)
+           for r in cms]
+    return hv.Layout(bars).opts(vspace=0.1, hspace=0.1, transpose=(n>cols)).cols(c)
+```
+
+### Perceptually uniform sequential colormaps
+
+Useful for the typical case of having increasing numeric values that you want to distinguish without bias for any specific value. The colormaps in this category are designed to represent similar distances in value space (e.g. a numerical difference from 0.2 to 0.4, or one from 0.4 to 0.6, with similar differences in what we perceive visually).  
+
+For detailed discussions of this important issue, see
+[Kovesi,](https://arxiv.org/abs/1509.03700)
+[van der Walt & Smith,](https://bids.github.io/colormap) and 
+[Karpov,](http://inversed.ru/Blog_2.htm) who each argue for different color spaces and criteria for evaluating colormaps and thus develop different types of colormaps.  Despite the disagreements over important details, *all* of the maps here will be significantly more uniform than an arbitrary map designed without perceptual criteria, such as those in "Other Sequential" below, and thus these colormaps represent good default choices in most cases.
+
+When choosing one of these, be sure to consider whether you wish your page background to be distinguishable from a color in the colormap. If your data covers the entire plot, then using the background color is fine, but if you need the background color to show through (e.g. to show missing values), then you should avoid maps that include black (`fire`, `magma`, `inferno`, `gray`, `k*`) on a black page or white (`fire`,`gray`) on a white page.
+
+
+```python
+cmap_examples('Uniform Sequential')
+```
+
+### Diverging colormaps
+
+Useful to highlight differences from a neutral central value, which is typically chosen to match the page background (e.g. white or yellow when using a white page, or black when using a black page).  
+
+Most of the diverging maps listed here were *not* developed to match a definition of perceptual uniformity, but those coming from `colorcet` were and should thus be preferred over the rest (which can be obtained by specifying `Uniform Diverging` here).
+
+Some of these colormaps include both red and green, making them ambiguous for people with the most common types of colorblindness, and should thus be avoided where possible.
+
+
+```python
+cmap_examples('Diverging')
+```
+
+### Rainbow colormaps
+
+Rainbow-like colormaps convey value primarily through color rather than luminance.  They result in eye-catching plots, but because rainbow colors form a continuous, cyclic spectrum, they can be ambiguous about which values are higher than the others.  Most of them are also highly perceptually non-uniform, with pronounced banding that makes some values easily distinguished from their neighbors, and other wide ranges of values nearly indistinguishable (e.g. the greenish colors in the `gist_rainbow` and `jet` colormaps). 
+
+If you do want a rainbow colormap, please consider using one of the three perceptually uniform versions (category `Uniform Rainbow`) included here:
+
+- `colorwheel` (colorcet): for cyclic values like angles and longitudes that wrap around to the same value at the end of the range (notice that the lowest and highest colors are both blue)
+- `rainbow` (colorcet): for monotonically and uniformly increasing values (skips purple region to avoid ordering ambiguity)
+- `isolum` (colorcet): for monotonically and uniformly increasing values, but only uses hue changes, with a constant lightness.  Nearly all the other maps are dominated by changes in lightness, which is much more perceptually salient than strict changes in hue as in this map.  Useful as a counterpart and illustration of the role of lightness.
+
+Of course, rainbow colormaps have the disadvantage that they are inherently unsuitable for most colorblind viewers, because they require viewers to distinguish between red and green to determine value.
+
+
+```python
+cmap_examples('Rainbow')
+```
+
+### Categorical colormaps
+
+Primarily useful as color cycles rather than colormaps, i.e. as a list of discrete color values, not a continuous range of colors. Will produce discrete banding when used on continuous values, like in a geographic contour plot, but if that effect is desired it's probably better to use `color_levels` with a sequential colormap to be able to control how many levels there are and give them a natural ordering.
+
+Most of these color sets are constructed by hand, with a relatively small number of distinct colors.  If you want a larger number of colors, the `glasbey_` categorical maps from Colorcet are generated using a systematic procedure based on sampling a perceptual space for widely separated colors, which allows large numbers of categories to be distinguished from each other. 
+
+The `glasbey_hv` colors have the useful property that they share the same first 12 colors as the default HoloViews color cycle, which means that if you want the same colors as usual but with more available when needed, you can switch the HoloViews default using `hv.Cycle.default_cycles['default_colors']=colorcet.glasbey_hv`.
+
+
+```python
+cmap_examples('Categorical')
+```
+
+### Mono Sequential colormaps
+
+Monotonically increasing values that serve the same purpose as [Uniform Sequential](#Perceptually-uniform-sequential-colormaps) (above), but are not specifically constructed to be perceptually uniform. Useful when you want to fit into a particular visual theme or color scheme, or when you want to color entire plots differently from other entire plots (e.g. to provide a visual "traffic light" indicator for the entire plot, making some plots stand out relative to others).  If you just need a single colormap, try to select a Uniform Sequential map instead of these.
+
+
+```python
+cmap_examples('Mono Sequential')
+```
+
+### Other Sequential colormaps
+
+Other sequential colormaps are included, but are not meant for general use.  Some of these have a very high degree of perceptual non-uniformity, making them highly misleading. E.g. the `hot` (matplotlib) colormap includes pronounced banding (with sharp perceptual discontinuities and long stretches of indistinguishable colors); consider using the perceptually uniform `fire` (colorcet) map instead. Others like `gray` largely duplicate maps in the other categories above, and so can cause confusion. The Uniform Sequential maps, or if necessary Mono Sequential, are generally good alternatives to these.
+
+
+```python
+cmap_examples('Other Sequential')
+```
+
+### Miscellaneous colormaps
+
+There are a variety of other colormaps not fitting into the categories above, mostly of limited usefuless. Exceptions include the `flag` and `prism` (matplotlib) colormaps that could be useful for highlighting local changes in value (details), with no information about global changes in value (due to the repeating colors).
+
+
+```python
+cmap_examples('Miscellaneous')
+```
+
+See the [Styling_Plots](Styling_Plots.ipynb) user guide for how these colormaps can be used to control how your data is plotted.
+
+## Querying and filtering the list of colormaps
+
+For most purposes, you can just pick one of the colormaps above for a given plot. However, HoloViews is very often used to build applications and dashboards, many of which include a "colormap" selection widget. Because there are so many colormaps available, most of which are inappropriate for any specific plot, it's useful to be able to pull up a list of all the colormaps that are suitable for the specific type of plot used in the app.
+
+To allow such filtering, HoloViews stores the following information about each named colormap, matched by substring:
+
+- **name**: string name for the colormap
+- **category**: Type of map by intended use or purpose ('[Uniform|Mono|Other ]Sequential', '[Uniform ]Diverging', '[Uniform ]Rainbow', '[Uniform ]Categorical', or 'Miscellaneous')
+- **provider**: package offering the colormap ('matplotlib', 'bokeh', or 'colorcet')
+- **source**: original source or creator of the colormaps ('cet', 'colorbrewer', 'd3', 'bids','misc')
+- **bg**: base/background color expected for the map ('light','dark','medium','any')
+- **reverse**: whether the colormap name includes `_r` indicating that it is a reverse of a base map (True, False)
+
+The `hv.plotting.list_cmaps()` function used above can select a subset of the available colormaps by filtering based on the above values:
+
+```
+list_cmaps(provider, records, name, category, source, bg, reverse)
+```
+
+The examples below should make it clear how to use this function.
+
+
+```python
+from holoviews.plotting import list_cmaps
+def format_list(l):
+    print(' '.join(sorted([k for k in l])))
+```
+
+All named colormaps provided by `colorcet`, reversed:
+
+
+```python
+format_list(list_cmaps(provider='colorcet',reverse=True))
+```
+
+All non-reversed colormaps provided by `matplotlib` and originating from `d3` that have `20` in their names:
+
+
+```python
+format_list(list_cmaps(name='20', source='d3', provider='matplotlib', reverse=False))
+```
+
+Colormaps provided by Bokeh that are suitable for dark-colored (e.g. black) backgrounds:
+
+
+```python
+format_list(list_cmaps(category='Other Sequential', bg='dark'))
+```
+
+Notice how some of these have `_r`, because those two natively start with light values and must be reversed to be suitable on a dark background.  In this case the results for `bg='light'` are the complementary set of colormaps:
+
+
+```python
+format_list(list_cmaps(category='Other Sequential', bg='light'))
+```
+
+However, `Diverging` colormaps do not change their background color when reversed, and so requesting a light or dark background gives different maps altogether (depending on their central color):
+
+
+```python
+format_list(list_cmaps(category='Diverging', bg='dark'))
+```
+
+
+```python
+format_list(list_cmaps(category='Diverging', bg='light'))
+```
+
+Matches are done by substring, so all sequential colormaps suitable for `dark` or `any` backgrounds can be obtained with:
+
+
+```python
+format_list(list_cmaps(category='Sequential', bg='a'))
+```
+
+In the examples above, `list_cmaps` is returning just the colormap name, but if you want to work with the filter information yourself to do more complex queries, you can ask that it return the full records as namedtuples instead:
+
+
+```python
+list_cmaps(category="Uniform Sequential", provider='bokeh', bg='light', records=True)
+```
+
+In addition to populating GUI widgets, another way to use this filtering is to systematically evaluate how your plot will look with a variety of different colormaps of the same type:
+
+
+```python
+hv.Layout([img.relabel(c).opts(cmap=c, colorbar=False, sublabel_format='') 
+           for c in list_cmaps(category='Diverging', bg='light', reverse=False)][:14])\
+    .opts(vspace=0.1, hspace=0.1).cols(7)
+```
+
+You could also consider filtering on the actual values in the colormap, perhaps to ensure that the specific background color you are using is not present in the colormap.  For this you can use the `hv.plotting.util.process_cmap` function to look up the actual colormap values by name and provider.

hvplot_docs/Continuous_Coordinates.md

@@ -0,0 +1,201 @@
+# Continuous Coordinates
+
+HoloViews is designed to work with scientific and engineering data, which is often in the form of discrete samples from an underlying continuous system.  Imaging data is one clear example: measurements taken at a regular interval over a grid covering a two-dimensional area.  Although the measurements are discrete, they approximate a continuous distribution, and HoloViews provides extensive support for working naturally with data of this type.
+
+## 2D Continuous spaces
+
+In this user guide we will show the support provided by HoloViews for working with two-dimensional regularly sampled grid data like images, and then in subsequent sections discuss how HoloViews supports one-dimensional, higher-dimensional, and irregularly sampled data with continuous coordinates.
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh')
+
+np.set_printoptions(precision=2, linewidth=80)
+opts.defaults(opts.Layout(shared_axes=False))
+```
+
+First, let's consider: 
+
+|||
+|:--------------:|:----------------|
+| **``f(x,y)``** | a simple function that accepts a location in a 2D plane specified in millimeters (mm) |
+| **``region``** | a 1mm×1mm square region of this 2D plane, centered at the origin, and |
+| **``coords``** | a function returning a square (s×s) grid of (x,y) coordinates regularly sampling the region in the given bounds, at the centers of each grid cell |
+||||
+
+
+
+
+```python
+def f(x,y): 
+    return x+y/3.1
+    
+region=(-0.5,-0.5,0.5,0.5)
+
+def coords(bounds,samples):
+    l,b,r,t=bounds
+    hc=0.5/samples
+    return np.meshgrid(np.linspace(l+hc,r-hc,samples),
+                       np.linspace(b+hc,t-hc,samples))
+```
+
+Now let's build a Numpy array regularly sampling this function at a density of 5 samples per mm: 
+
+
+```python
+f5=f(*coords(region,5))
+f5
+```
+
+We can visualize this array (and thus the function ``f``) either using a ``Raster``, which uses the array's own integer-based coordinate system (which we will call "array" coordinates), or an ``Image``, which uses a continuous coordinate system, or as a ``HeatMap`` labelling each value explicitly:
+
+
+```python
+r5 = hv.Raster(f5, label="R5")
+i5 = hv.Image( f5, label="I5", bounds=region)
+h5 = hv.HeatMap([(x, y, round(f5[4-y,x],2)) for x in range(0,5) for y in range(0,5)], label="H5")
+
+h5_labels = hv.Labels(h5).opts(padding=0)
+
+r5 + i5 + h5*h5_labels
+```
+
+Both the ``Raster`` and ``Image`` ``Element`` types accept the same input data and show the same arrangement of colors, but a visualization of the ``Raster`` type reveals the underlying raw array indexing, while the ``Image`` type has been labelled with the coordinate system from which we know the data has been sampled.  All ``Image`` operations work with this continuous coordinate system instead, while the corresponding operations on a ``Raster`` use raw array indexing.
+
+For instance, all five of these indexing operations refer to the same element of the underlying Numpy array, i.e. the second item in the first row:
+
+
+```python
+"r5[0,1]=%0.2f  r5.data[0,1]=%0.2f  i5[-0.2,0.4]=%0.2f  i5[-0.24,0.37]=%0.2f  i5.data[0,1]=%0.2f" % \
+(r5[1,0],       r5.data[0,1],       i5[-0.2,0.4],       i5[-0.24,0.37],       i5.data[0,1])
+```
+
+You can see that the ``Raster`` and the underlying ``.data`` elements both use Numpy's raw integer indexing, while the ``Image`` uses floating-point values that are then mapped onto the appropriate array element.
+
+This diagram should help show the relationships between the ``Raster`` coordinate system in the plot (which ranges from 0 at the top edge to 5 at the bottom), the underlying raw Numpy integer array indexes (labelling each dot in the **Array coordinates** figure), and the underlying **Continuous coordinates**:
+
+<TABLE style='border:5'>
+<TR>
+<TH><CENTER>Array coordinates</CENTER></TH>
+<TH><CENTER>Continuous coordinates</CENTER></TH>
+</TR>
+<TR>
+<TD><IMG src="http://ioam.github.io/topographica/_images/matrix_coords.png"></TD>
+<TD><IMG src="http://ioam.github.io/topographica/_images/sheet_coords_-0.2_0.4.png"></TD>
+</TR>
+</TABLE>
+
+Importantly, although we used a 5&times;5 array in this example, we could substitute a much larger array with the same continuous coordinate system if we wished, without having to change any of our continuous indexes -- they will still point to the correct location in the continuous space:
+
+
+```python
+f10=f(*coords(region,10))
+f10
+```
+
+
+```python
+r10 = hv.Raster(f10, label="R10")
+i10 = hv.Image(f10, label="I10", bounds=region)
+r10+i10
+```
+
+The image now has higher resolution, but still visualizes the same underlying continuous function, now evaluated at 100 grid positions instead of 25:
+
+<TABLE style='border:5'>
+<TR>
+<TH><CENTER>Array coordinates</CENTER></TH>
+<TH><CENTER>Continuous coordinates</CENTER></TH>
+</TR>
+<TR>
+<TD><IMG src="http://ioam.github.io/topographica/_images/matrix_coords_hidensity.png"></TD>
+<TD><IMG src="http://ioam.github.io/topographica/_images/sheet_coords_-0.2_0.4.png"></TD>
+</TR>
+</TABLE>
+
+Indexing the exact same coordinates as above now gets very different results:
+
+
+```python
+"r10[0,1]=%0.2f  r10.data[0,1]=%0.2f  i10[-0.2,0.4]=%0.2f  i10[-0.24,0.37]=%0.2f  i10.data[0,1]=%0.2f" % \
+(r10[1,0],       r10.data[0,1],       i10[-0.2,0.4],       i10[-0.24,0.37],       i10.data[0,1])
+```
+
+The array-based indexes used by ``Raster`` and the Numpy array in ``.data`` still return the second item in the first row of the array, but this array element now corresponds to location (-0.35,0.4) in the continuous function, and so the value is different.  These indexes thus do *not* refer to the same location in continuous space as they did for the other array density, because raw Numpy-based indexing is *not* independent of density or resolution.
+
+Luckily, the two continuous coordinates still return very similar values to what they did before, since they always return the value of the array element corresponding to the closest location in continuous space.  They now return elements just above and to the right, or just below and to the left, of the earlier location, because the array now has a higher resolution with elements centered at different locations.  
+
+Indexing in continuous coordinates always returns the value closest to the requested value, given the available resolution.  Note that in the case of coordinates truly on the boundary between array elements (as for -0.2,0.4), the bounds of each array cell are taken as right exclusive and upper exclusive, and so (-0.2,0.4) returns array index (3,0). 
+
+## Slicing in 2D
+
+In addition to indexing (looking up a value), slicing (selecting a region) works as expected in continuous space (see the [Indexing and Selecting](10-Indexing_and_Selecting.ipynb) user guide for more explanation).  For instance, we can ask for a slice from (-0.275,-0.0125) to (0.025,0.2885) in continuous coordinates:
+
+
+```python
+sl10=i10[-0.275:0.025,-0.0125:0.2885]
+sl10.data
+```
+
+
+```python
+sl10
+```
+
+This slice has selected those array elements whose centers are contained within the specified continuous space.  To do this, the continuous coordinates are first converted by HoloViews into the floating-point range (5.125,2.250) (2.125,5.250) of array coordinates, and all those elements whose centers are in that range are selected:
+
+<TABLE style='border:5'>
+<TR>
+<TH><CENTER>Array coordinates</CENTER></TH>
+<TH><CENTER>Continuous coordinates</CENTER></TH>
+</TR>
+<TR>
+<TD><IMG src="http://ioam.github.io/topographica/_images/connection_field.png"></TD>
+<TD><IMG src="http://ioam.github.io/topographica/_images/sheet_coords_-0.275_-0.0125_0.025_0.2885.png"></TD>
+</TR>
+</TABLE>
+
+Slicing also works for ``Raster`` elements, but it results in an object that always reflects the contents of the underlying Numpy array (i.e., always with the upper left corner labelled 0,0):
+
+
+```python
+r5[0:3,1:3] + r5[0:3,1:2]
+```
+
+Hopefully these examples make it clear that if you are using data that is sampled from some underlying continuous system, you should use the continuous coordinates offered by HoloViews objects like ``Image`` so that your programs can be independent of the resolution or sampling density of that data, and so that your axes and indexes can be expressed naturally, using the actual units of the underlying continuous space.  The data will still be stored in the same Numpy array, but now you can treat it consistently like the approximation to continuous values that it is.
+
+## 1D and nD Continuous coordinates
+
+All of the above examples use the common case for visualizations of a two-dimensional regularly gridded continuous space, which is implemented in ``holoviews.core.sheetcoords.SheetCoordinateSystem``.  
+
+Similar continuous coordinates and slicing are also supported for ``Chart`` elements, such as ``Curve``s, but using a single index and allowing arbitrary irregular spacing, implemented in ``holoviews.elements.chart.Chart``. 
+
+They also work the same for the n-dimensional coordinates and slicing supported by the [container](Containers) types ``HoloMap``, ``NdLayout``, and ``NdOverlay``, implemented in ``holoviews.core.dimension.Dimensioned`` and again allowing arbitrary irregular spacing.  
+
+``QuadMesh`` elements are similar but allow more general types of mapping between the underlying array and the continuous space, with arbitrary spacing along each of the axes or even over the entire array. See the ``QuadMesh`` element for more details.
+
+Together, these powerful continuous-coordinate indexing and slicing operations allow you to work naturally and simply in the full *n*-dimensional space that characterizes your data and parameter values.
+
+## Sampling
+
+The above examples focus on indexing and slicing, but as described in the [Indexing and Selecting](10-Indexing_and_Selecting.ipynb) user guide there is another related operation supported for continuous spaces, called sampling.  Sampling is similar to indexing and slicing, in that all of them can reduce the dimensionality of your data, but sampling is implemented in a general way that applies for any of the 1D, 2D, or nD datatypes.  For instance, if we take our 10&times;10 array from above, we can ask for the value at a given location, which will come back as a ``Table``, i.e. a dictionary with one (key,value) pair:
+
+
+```python
+e10=i10.sample(x=-0.275, y=0.2885)
+e10.opts(height=75)
+```
+
+Similarly, if we ask for the value of a given *y* location in continuous space, we will get a ``Curve`` with the array row closest to that *y* value in the ``Image`` 2D array returned as arrays of `x` values and the corresponding *z* value from the image:
+
+
+```python
+r10=i10.sample(y=0.2885)
+r10
+```
+
+The same sampling syntax can be used on HoloViews objects with any number of continuous-coordinate dimensions, in each case returning a HoloViews object of the correct dimensionality.  This support for working in continuous spaces makes it much more natural to work with HoloViews objects than directly with the underlying raw Numpy arrays, but the raw data always remains available when needed.

hvplot_docs/Customization.md

@@ -0,0 +1,185 @@
+```python
+import hvplot
+import hvplot.pandas  # noqa
+```
+
+The hvPlot API is closely modeled on the pandas plot API but also diverges in certain cases, either to improve consistency or to provide additional functionality. This section will outline the valid options to control the axes of a plot, to control datashading and to modify the style of a plot. To look these options up interactively you may either use the tab-completion machinery in IPython or the Jupyter notebook, e.g.:
+
+```python
+df.hvplot.line(<TAB>
+```
+
+OR use the help method:
+
+```
+hvplot.help('line')
+```
+
+## Generic options
+
+The generic set of options which may apply to all plot types include:
+
+    clim: tuple
+        Lower and upper bound of the color scale
+    cnorm (default='linear'): str
+        Color scaling which must be one of 'linear', 'log' or 'eq_hist'
+    colorbar (default=False): boolean
+        Enables a colorbar
+    fontscale: number
+        Scales the size of all fonts by the same amount, e.g. fontscale=1.5
+        enlarges all fonts (title, xticks, labels etc.) by 50%
+    fontsize: number or dict
+        Set title, label and legend text to the same fontsize. Finer control
+        by using a dict: {'title': '15pt', 'ylabel': '5px', 'ticks': 20}
+    flip_xaxis/flip_yaxis: boolean
+        Whether to flip the axis left to right or up and down respectively
+    grid (default=False): boolean
+        Whether to show a grid
+    hover : boolean
+        Whether to show hover tooltips, default is True unless datashade is
+        True in which case hover is False by default
+    hover_cols (default=[]): list or str
+        Additional columns to add to the hover tool or 'all' which will
+        includes all columns (including indexes if use_index is True).
+    invert (default=False): boolean
+        Swaps x- and y-axis
+    frame_width/frame_height: int
+        The width and height of the data area of the plot
+    legend (default=True): boolean or str
+        Whether to show a legend, or a legend position
+        ('top', 'bottom', 'left', 'right')
+    logx/logy (default=False): boolean
+        Enables logarithmic x- and y-axis respectively
+    logz (default=False): boolean
+        Enables logarithmic colormapping
+    loglog (default=False): boolean
+        Enables logarithmic x- and y-axis
+    max_width/max_height: int
+        The maximum width and height of the plot for responsive modes
+    min_width/min_height: int
+        The minimum width and height of the plot for responsive modes
+    padding: number or tuple
+        Fraction by which to increase auto-ranged extents to make
+        datapoints more visible around borders. Supports tuples to
+        specify different amount of padding for x- and y-axis and
+        tuples of tuples to specify different amounts of padding for
+        upper and lower bounds.
+    responsive: boolean
+        Whether the plot should responsively resize depending on the
+        size of the browser. Responsive mode will only work if at
+        least one dimension of the plot is left undefined, e.g. when
+        width and height or width and aspect are set the plot is set
+        to a fixed size, ignoring any responsive option.
+    rot: number
+        Rotates the axis ticks along the x-axis by the specified
+        number of degrees.
+    shared_axes (default=True): boolean
+        Whether to link axes between plots
+    transforms (default={}): dict
+        A dictionary of HoloViews dim transforms to apply before plotting
+    title (default=''): str
+        Title for the plot
+    tools (default=[]): list
+        List of tool instances or strings (e.g. ['tap', box_select'])
+    xaxis/yaxis: str or None
+        Whether to show the x/y-axis and whether to place it at the
+        'top'/'bottom' and 'left'/'right' respectively.
+    xformatter/yformatter (default=None): str or TickFormatter
+        Formatter for the x-axis and y-axis (accepts printf formatter,
+        e.g. '%.3f', and bokeh TickFormatter)
+    xlabel/ylabel/clabel (default=None): str
+        Axis labels for the x-axis, y-axis, and colorbar
+    xlim/ylim (default=None): tuple or list
+        Plot limits of the x- and y-axis
+    xticks/yticks (default=None): int or list
+        Ticks along x- and y-axis specified as an integer, list of
+        ticks positions, or list of tuples of the tick positions and labels
+    width (default=700)/height (default=300): int
+        The width and height of the plot in pixels
+    attr_labels (default=None): bool
+        Whether to use an xarray object's attributes as labels, defaults to
+        None to allow best effort without throwing a warning. Set to True
+        to see warning if the attrs can't be found, set to False to disable
+        the behavior.
+    sort_date (default=True): bool
+        Whether to sort the x-axis by date before plotting
+    symmetric (default=None): bool
+        Whether the data are symmetric around zero. If left unset, the data
+        will be checked for symmetry as long as the size is less than
+        ``check_symmetric_max``.
+    check_symmetric_max (default=1000000):
+        Size above which to stop checking for symmetry by default on the data.
+
+## Datashading options
+
+In addition to regular plot options hvplot also exposes options for dealing with large data:
+
+    aggregator (default=None):
+        Aggregator to use when applying rasterize or datashade operation
+        (valid options include 'mean', 'count', 'min', 'max' and more, and
+        datashader reduction objects)
+    dynamic (default=True):
+        Whether to return a dynamic plot which sends updates on widget and
+        zoom/pan events or whether all the data should be embedded
+        (warning: for large groupby operations embedded data can become
+        very large if dynamic=False)
+    datashade (default=False):
+        Whether to apply rasterization and shading using datashader
+        library returning an RGB object
+    dynspread (default=False):
+        Allows plots generated with datashade=True to increase the point
+        size to make sparse regions more visible
+    rasterize (default=False):
+        Whether to apply rasterization using the datashader library
+        returning an aggregated Image
+    x_sampling/y_sampling (default=None):
+        Specifies the smallest allowed sampling interval along the x/y axis.
+
+## Geographic options
+
+When dealing with geographic data, there are a number of options that become available. See the [geographic section](Geographic_Data.ipynb) for more information on working with geographic data:
+
+    coastline (default=False):
+        Whether to display a coastline on top of the plot, setting
+        coastline='10m'/'50m'/'110m' specifies a specific scale.
+    crs (default=None):
+        Coordinate reference system of the data specified as Cartopy
+        CRS object, proj.4 string or EPSG code.
+    features (default=None): dict or list
+        A list of features or a dictionary of features and the scale
+        at which to render it. Available features include 'borders',
+        'coastline', 'lakes', 'land', 'ocean', 'rivers' and 'states'.
+        Available scales include '10m'/'50m'/'110m'.
+    geo (default=False):
+        Whether the plot should be treated as geographic (and assume
+        PlateCarree, i.e. lat/lon coordinates).
+    global_extent (default=False):
+        Whether to expand the plot extent to span the whole globe.
+    project (default=False):
+        Whether to project the data before plotting (adds initial
+        overhead but avoids projecting data when plot is dynamically
+        updated).
+    tiles (default=False):
+        Whether to overlay the plot on a tile source. Tiles sources
+        can be selected by name or a tiles object or class can be passed,
+        the default is 'Wikipedia'.
+
+## Kind options
+
+Each type of plot may have a number of options to visual attributes specific to that plot type. In general these are provided in the docstring of the plot type, which can be viewed using ``help`` method:
+
+
+```python
+hvplot.help('scatter', generic=False, style=False)
+```
+
+## Styling options
+
+Beyond the options specific to each plot type (or ``kind``) it is also possible to customize each component in detail, exposing all the options bokeh exposes. These usually include options to color the line and fill color, alpha and style. To see the full listing we can once again use the ``help`` method:
+
+
+```python
+hvplot.help('line', docstring=False, generic=False)
+```
+
+In general, the objects returned by hvPlot are regular HoloViews objects, which can be overlaid, laid out, composed and customized like all other HoloViews objects.  The [HoloViews](https://holoviews.org) website explains all the functionality available, but what's on this hvPlot website should be enough to get you up and running for typical usage.  

hvplot_docs/Customizing_Plots.md

@@ -0,0 +1,439 @@
+# Customizing Plots
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import dim, opts
+
+hv.extension('bokeh', 'matplotlib')
+```
+
+The HoloViews options system allows controlling the various attributes of a plot. While different plotting extensions like bokeh, matplotlib and plotly offer different features and the style options may differ, there are a wide array of options and concepts that are shared across the different extensions. Specifically this guide provides an overview on controlling the various aspects of a plot including titles, axes, legends and colorbars. 
+
+Plots have an overall hierarchy and here we will break down the different components:
+
+* [**Plot**](#customizing-the-plot): Refers to the overall plot which can consist of one or more axes
+    - [Titles](#title): Using title formatting and providing custom titles
+    - [Background](#background): Setting the plot background color
+    - [Font sizes](#font-sizes): Controlling the font sizes on a plot
+    - [Legends](#legend-customization): Controlling the position and styling of the legend
+    - [Plot hooks](#plot-hooks): Using custom hooks to modify plots
+* [**Axes**](#customizing-axes): A set of axes provides scales describing the mapping between data and the space on screen
+    - [Types of axes](#types-of-axes):
+        - [Linear axes](#linear-axes)
+        - [Logarithmic axes](#log-axes)
+        - [Datetime axes](#datetime-axes)
+        - [Categorical axes](#categorical-axes)
+    - [Axis position](#axis-position): Positioning and hiding axes
+    - [Inverting axes](#inverting-axes): Flipping the x-/y-axes and inverting an axis
+    - [Axis labels](#axis-labels): Setting axis labels using dimensions and options
+    - [Axis ranges](#axis-ranges): Controlling axes ranges using dimensions, padding and options
+    - [Axis ticks](#axis-ticks): Controlling axis tick locations, labels and formatting
+    - [Twin axes](#twin-axes): Enabling twin axes
+
+## Customizing the plot
+
+### Title
+
+A plot's title is usually constructed using a formatter which takes the group and label along with the plots dimensions into consideration. The default formatter is:
+
+    '{label} {group}  {dimensions}'
+    
+where the ``{label}`` and ``{group}`` are inherited from the objects group and label parameters and ``dimensions`` represent the key dimensions in a HoloMap/DynamicMap:
+
+
+```python
+hv.HoloMap({i: hv.Curve([1, 2, 3-i], group='Group', label='Label') for i in range(3)}, 'Value')
+```
+
+The title formatter may however be overridden with an explicit title, which may include any combination of the three formatter variables:
+
+
+```python
+hv.Curve([1, 2, 3]).opts(title="Custom Title")
+```
+
+### Background
+
+Another option which can be controlled at the level of a plot is the background color which may be set using the `bgcolor` option:
+
+
+```python
+hv.Curve([1, 2, 3]).opts(bgcolor='lightgray')
+```
+
+### Font sizes
+
+Controlling the font sizes of a plot is very common so HoloViews provides a convenient option to set the ``fontsize``. The ``fontsize`` accepts a dictionary which allows supplying fontsizes for different components of the plot from the title, to the axis labels, ticks and legends. The full list of plot components that can be customized separately include:
+
+    ['xlabel', 'ylabel', 'zlabel', 'labels', 'xticks', 'yticks', 'zticks', 'ticks', 'minor_xticks', 'minor_yticks', 'minor_ticks', 'title', 'legend', 'legend_title']
+
+Let's take a simple example customizing the title, the axis labels and the x/y-ticks separately:
+
+
+```python
+hv.Curve([1, 2, 3], label='Title').opts(fontsize={'title': 16, 'labels': 14, 'xticks': 6, 'yticks': 12})
+```
+
+### Font scaling
+
+Instead of control each property individually it is often useful to scale all fonts by a constant factor, e.g. to produce a more legible plot for presentations and posters. The `fontscale` option will affect the title, axis labels, tick labels, and legend:
+
+
+```python
+(hv.Curve([1, 2, 3], label='A') * hv.Curve([3, 2, 1], label='B')).opts(fontscale=2, width=500, height=400, title='Title')
+```
+
+### Legend customization
+
+When overlaying plots with different labels, a legend automatically appears to differentiate elements in the overlay. This legend can be customized in several ways:
+
+- by **position**
+    - by adjusting the legend location within the figure using the `legend_position` option (e.g. `legend_position='bottom_right'`)
+    - by adjusting the legend location *outside* of the figure using the `legend_position` and `legend_offset` parameters (which then positions the legend in *screen* space) (e.g. `legend_position='right', legend_offset=(0, 200)`). **Note**: the `legend_position` option applies to `bokeh` and `matplotlib` backends but the `legend_offset` only applies to `bokeh`.
+- by **style**
+    - by muting elements with `legend_muted=True` (applies only to the `bokeh` backend)
+    - by putting the legend elements in a column layout with `legend_cols=True` or (`legend_cols=int` in matplotlib)
+    
+These customizations are demonstrated by the examples that follow.
+
+Moving the legend to the bottom right:
+
+
+```python
+overlay = (hv.Curve([1, 2, 3], label='A') * hv.Curve([3, 2, 1], label='B')).opts(width=500, height=400)
+overlay.opts(legend_position='bottom_right')
+```
+
+Moving the legend outside, to the right of the plot:
+
+
+```python
+overlay.opts(legend_position='right')
+```
+
+Moving the legend outside, to the right of the plot but offset it 200 pixels higher:
+
+
+```python
+overlay.opts(width=500, height=400, legend_position='right', legend_offset=(0, 200))
+```
+
+Muting the legend and laying the labels out as columns.
+
+
+```python
+overlay.opts(legend_muted=True, legend_cols=2)
+```
+
+### Plot hooks
+
+HoloViews does not expose every single option a plotting extension like matplotlib or bokeh provides, therefore it is sometimes necessary to dig deeper to achieve precisely the customizations one might need. One convenient way of doing so is to use plot hooks to modify the plot object directly. The hooks are applied after HoloViews is done with the plot, allowing for detailed manipulations of the backend specific plot object.
+
+The signature of a hook has two arguments, the HoloViews `plot` object that is rendering the plot and the `element` being rendered. From there the hook can modify the objects in the plot's handles, which provides convenient access to various components of a plot or simply access the ``plot.state`` which corresponds to the plot as a whole, e.g. in this case we define colors for the x- and y-labels of the plot.
+
+
+```python
+def hook(plot, element):
+    print('plot.state:   ', plot.state)
+    print('plot.handles: ', sorted(plot.handles.keys()))
+    plot.handles['xaxis'].axis_label_text_color = 'red'
+    plot.handles['yaxis'].axis_label_text_color = 'blue'
+    
+hv.Curve([1, 2, 3]).opts(hooks=[hook])
+```
+
+## Customizing axes
+
+Controlling the axis scales is one of the most common changes to make to a plot, so we will provide a quick overview of the four main types of axes and then go into some more detail on how to control the axis labels, ranges, ticks and orientation.
+
+### Types of axes
+
+There are four main types of axes supported across plotting backends, standard linear axes, log axes, datetime axes and categorical axes. In most cases HoloViews automatically detects the appropriate axis type to use based on the type of the data, e.g. numeric values use linear/log axes, date(time) values use datetime axes and string or other object types use categorical axes.
+
+#### Linear axes
+
+A linear axes is simply the default, as long as the data is numeric HoloViews will automatically use a linear axis on the plot.
+
+#### Log axes
+
+When the data is exponential it is often useful to use log axes, which can be enabled using independent ``logx`` and ``logy`` options. This way both semi-log and log-log plots can be achieved:
+
+
+```python
+semilogy = hv.Curve(np.logspace(0, 5), label='Semi-log y axes')
+loglog = hv.Curve((np.logspace(0, 5), np.logspace(0, 5)), label='Log-log axes')
+
+semilogy.opts(logy=True) + loglog.opts(logx=True, logy=True, shared_axes=False)
+```
+
+#### Datetime axes
+
+All current plotting extensions allow plotting datetime data, if you ensure the dates array is of a valid datetime dtype.
+
+
+```python
+from bokeh.sampledata.stocks import GOOG, AAPL
+
+goog_dates = np.array(GOOG['date'], dtype=np.datetime64)
+aapl_dates = np.array(AAPL['date'], dtype=np.datetime64)
+
+goog = hv.Curve((goog_dates, GOOG['adj_close']), 'Date', 'Stock Index', label='Google')
+aapl = hv.Curve((aapl_dates, AAPL['adj_close']), 'Date', 'Stock Index', label='Apple')
+
+(goog * aapl).opts(width=600, legend_position='top_left')
+```
+
+#### Categorical axes
+
+While the handling of categorical data handles significantly between plotting extensions the same basic concepts apply. If the data is a string type or other object type it is formatted as a string and each unique category is assigned a tick along the axis. When overlaying elements the categories are combined and overlaid appropriately.
+
+Whether an axis is categorical also depends on the Element type, e.g. a ``HeatMap`` always has two categorical axes while a ``Bars`` element always has a categorical x-axis. As a simple example let us create a set of points with categories along the x- and y-axes and render them on top of a `HeatMap` of th same data:
+
+
+```python
+points = hv.Points([(chr(i+65), chr(j+65), i*j) for i in range(10) for j in range(10)], vdims='z')
+
+heatmap = hv.HeatMap(points)
+
+(heatmap * points).opts(
+    opts.HeatMap(toolbar='above', tools=['hover']),
+    opts.Points(tools=['hover'], size=dim('z')*0.3))
+```
+
+As a more complex example which does not implicitly assume categorical axes due to the element type we will create a set of random samples indexed by categories from 'A' to 'E' using the ``Scatter`` Element and overlay them. Secondly we compute the mean and standard deviation for each category displayed using a set of ``ErrorBars`` and finally we overlay these two elements with a ``Curve`` representing the mean value . All these Elements respect the categorical index, providing us a view of the distribution of values in each category:
+
+
+```python
+overlay = hv.NdOverlay({group: hv.Scatter(([group]*100, np.random.randn(100)*(5-i)-i))
+                        for i, group in enumerate(['A', 'B', 'C', 'D', 'E'])})
+
+errorbars = hv.ErrorBars([(k, el.reduce(function=np.mean), el.reduce(function=np.std))
+                          for k, el in overlay.items()])
+
+curve = hv.Curve(errorbars)
+
+(errorbars * overlay * curve).opts(
+    opts.ErrorBars(line_width=5), opts.Scatter(jitter=0.2, alpha=0.5, size=6, height=400, width=600))
+```
+
+Categorical axes are special in that they support multi-level nesting in some cases. Currently this is only supported for certain element types (BoxWhisker, Violin and Bars) but eventually all chart-like elements will interpret multiple key dimensions as a multi-level categorical hierarchy. To demonstrate this behavior consider the `BoxWhisker` plot below which support two-level nested categories:
+
+
+```python
+groups = [chr(65+g) for g in np.random.randint(0, 3, 200)]
+boxes = hv.BoxWhisker((groups, np.random.randint(0, 5, 200), np.random.randn(200)),
+                      ['Group', 'Category'], 'Value').sort()
+
+boxes.opts(width=600)
+```
+
+### Axis positions
+
+Axes may be hidden or moved to a different location using the ``xaxis`` and ``yaxis`` options, which accept `None`, `'right'`/`'bottom'`, `'left'`/`'top'` and `'bare'` as values.
+
+
+```python
+np.random.seed(42)
+ys = np.random.randn(101).cumsum(axis=0)
+
+curve = hv.Curve(ys, ('x', 'x-label'), ('y', 'y-label'))
+
+(curve.relabel('No axis').opts(xaxis=None, yaxis=None) +
+ curve.relabel('Bare axis').opts(xaxis='bare') +
+ curve.relabel('Moved axis').opts(xaxis='top', yaxis='right'))
+```
+
+### Inverting axes
+
+Another option to control axes is to invert the x-/y-axes using the ``invert_axes`` options, i.e. turn a vertical plot into a horizontal plot. Secondly each individual axis can be flipped left to right or upside down respectively using the ``invert_xaxis`` and ``invert_yaxis`` options.
+
+
+```python
+bars = hv.Bars([('Australia', 10), ('United States', 14), ('United Kingdom', 7)], 'Country')
+
+(bars.relabel('Invert axes').opts(invert_axes=True, width=400) +
+ bars.relabel('Invert x-axis').opts(invert_xaxis=True) +
+ bars.relabel('Invert y-axis').opts(invert_yaxis=True)).opts(shared_axes=False)
+```
+
+### Axis labels
+
+Ordinarily axis labels are controlled using the dimension label, however explicitly ``xlabel`` and ``ylabel`` options make it possible to override the label at the plot level. Additionally the ``labelled`` option allows specifying which axes should be labelled at all, making it possible to hide axis labels:
+
+
+```python
+(curve.relabel('Dimension labels') +
+ curve.relabel("xlabel='Custom x-label'").opts(xlabel='Custom x-label') +
+ curve.relabel('Unlabelled').opts(labelled=[]))
+```
+
+### Axis ranges
+
+The ranges of a plot are ordinarily controlled by computing the data range and combining it with the dimension ``range`` and ``soft_range`` but they may also be padded or explicitly overridden using ``xlim`` and ``ylim`` options.
+
+#### Dimension ranges
+
+* **data range**: The data range is computed by min and max of the dimension values
+* **range**: Hard override of the data range
+* **soft_range**: Soft override of the data range
+
+##### **Dimension.range**
+
+Setting the ``range`` of a Dimension overrides the data ranges, i.e. here we can see that despite the fact the data extends to x=100 the axis is cut off at 90:
+
+
+```python
+curve.redim(x=hv.Dimension('x', range=(-10, 90)))
+```
+
+##### Dimension.soft_range
+
+Declaringa ``soft_range`` on the other hand combines the data range and the supplied range, i.e. it will pick whichever extent is wider. Using the same example as above we can see it uses the -10 value supplied in the soft_range but also extends to 100, which is the upper bound of the actual data:
+
+
+```python
+curve.redim(x=hv.Dimension('x', soft_range=(-10, 90)))
+```
+
+#### Padding
+
+Applying padding to the ranges is an easy way to ensure that the data is not obscured by the margins. The padding is specified by the fraction by which to increase auto-ranged extents to make datapoints more visible around borders. The default for most elements is `padding=0.1`. The padding considers the width and height of the plot to keep the visual extent of the padding equal. The padding values can be specified with three levels of detail:
+
+* 1. A single numeric value (e.g. ``padding=0.1``)
+* 2. A tuple specifying the padding for the x/y(/z) axes respectively (e.g. ``padding=(0, 0.1)``)
+* 3. A tuple of tuples specifying padding for the lower and upper bound respectively (e.g. ``padding=(0, (0, 0.1))``)
+
+
+```python
+(curve.relabel('Pad both axes').opts(padding=0.1) +
+ curve.relabel('Pad y-axis').opts(padding=(0, 0.1)) +
+ curve.relabel('Pad y-axis upper bound').opts(padding=(0, (0, 0.1)))).opts(shared_axes=False)
+```
+
+#### xlim/ylim
+
+The data ranges, dimension ranges and padding combine across plots in an overlay to ensure that all the data is contained in the viewport. In some cases it is more convenient to override the ranges with explicit ``xlim`` and ``ylim`` options which have the highest precedence and will be respected no matter what.
+
+
+```python
+curve.relabel('Explicit xlim/ylim').opts(xlim=(-10, 110), ylim=(-14, 6))
+```
+
+#### Autoranging
+
+With the `autorange` keyword, you can ensure the data in the viewport is automatically ranged to maximise the use of the x- or y-axis. To illustrate, here is the same `curve` autoranging on the `y-axis`: note the difference in behavior when zooming into the data:
+
+
+```python
+curve.relabel('Autoranging on y').opts(autorange='y')
+```
+
+To pin the ends of the ranges you can use the `xlim` and `ylim` options, using a value of `None` to allow autoranging to operate. Here the bottom range of the y-axis is pinned to the value of `-14`:
+
+
+```python
+curve.relabel('Autoranging on y with set lower limit').opts(autorange='y', ylim=(-14,None))
+```
+
+Autoranging works analogously for the x-axis and also respects the padding setting. In addition, autoranging is triggered when the plotted data is updated dynamically, as is common when building interactive visualizations with operations or `DynamicMap`s.
+
+### Axis ticks
+
+Setting tick locations differs a little bit depending on the plotting extension, interactive backends such as bokeh or plotly dynamically update the ticks, which means fixed tick locations may not be appropriate and the formatters have to be applied in Javascript code. Nevertheless most options to control the ticking are consistent across extensions.
+
+#### Tick locations
+
+The number and locations of ticks can be set in three main ways:
+
+* Number of ticks: Declare the number of desired ticks as an integer
+* List of tick positions: An explicit list defining the list of positions at which to draw a tick
+* List of tick positions and labels: A list of tuples of the form (position, label)
+
+
+```python
+(curve.relabel('N ticks (xticks=10)').opts(xticks=10) +
+ curve.relabel('Listed ticks (xticks=[0, 1, 2])').opts(xticks=[0, 50, 100]) +
+ curve.relabel("Tick labels (xticks=[(0, 'zero'), ...").opts(xticks=[(0, 'zero'), (50, 'fifty'), (100, 'one hundred')]))
+```
+
+Lastly each extension will accept the custom Ticker objects the library provides, which can be used to achieve layouts not usually available.
+
+#### Tick formatters
+
+Tick formatting works very differently in different backends, however the ``xformatter`` and ``yformatter`` options try to minimize these differences. Tick formatters may be defined in one of three formats:
+
+* A classic format string such as ``'%d'``, ``'%.3f'`` or ``'%d'`` which may also contain other characters (``'$%.2f'``)
+* A ``bokeh.models.TickFormatter`` in bokeh and a ``matplotlib.ticker.Formatter`` instance in matplotlib
+
+Here is a small example demonstrating how to use the string approaches:
+
+
+```python
+curve.relabel('Tick formatters').opts(xformatter='%.0f days', yformatter='$%.2f', width=500)
+```
+
+#### Tick orientation
+
+Particularly when dealing with categorical axes it is often useful to control the tick rotation. This can be achieved using the ``xrotation`` and ``yrotation`` options which accept angles in degrees.
+
+
+```python
+bars.opts(xrotation=45)
+```
+
+### Twin axes
+*(Available in HoloViews >= 1.17, requires Bokeh >=3.2)*
+
+HoloViews now supports displaying overlays containing two different value dimensions as twin axes for chart elements. To maintain backwards compatibility, this feature is only enabled by setting the `multi_y=True` option on the overlay.
+
+To illustrate, here is an overlay containing three curves with two value dimensions ('A' and 'B'). Setting `multi_y=True` then maps these two value dimensions to twin-axes:
+
+
+```python
+overlay = hv.Curve([1, 2, 3], vdims=['A']) * hv.Curve([2, 3, 4], vdims=['A']) * hv.Curve([3, 2, 1], vdims=['B'])
+overlay.opts(multi_y=True)
+```
+
+Additional value dimensions do map to additional axes but be aware that support of multi axes beyond twin axes is currently considered experimental.
+
+The first value dimension is mapped to the left-hand axis and the second value dimension maps to the right axis. Note that the two axes are individually zoomable by hovering over them and using the Bokeh wheelzoom tool.
+
+
+#### Supported `multi_y` options
+
+When `multi_y` is enabled, you can set individual axis options on the elements of the overlay.
+
+In this example, the left axis uses the default options while the right axis is an inverted, autoranged, log axis with a set `ylim`:
+
+
+```python
+(hv.Curve([1, 2, 3], vdims=['A']) 
+ * hv.Curve([2, 3, 4], vdims=['B']).opts(autorange='y', invert_yaxis=True, logy=True, ylim=(1,10), 
+                                         ylabel='B custom', fontsize={'ylabel':10})
+).opts(multi_y=True)
+```
+
+Supported options for customizing individual axes are `apply_ranges`, `autorange='y'`, `invert_yaxis`, `logy` and `ylim`, `yaxis` as well as the following options for labelling: `labelled`, `ylabel` and the `'ylabel'` setting in `fontsize`.
+
+Note that as of HoloViews 1.17.0, `multi_y` does not have streaming plot support, extra axis labels are not dynamic and only the `RangeXY` linked stream is aware of additional y-axes.
+
+### Subcoordinate y-axis
+*(Available in HoloViews >= 1.18)*
+
+HoloViews enables you to create overlays where each element has its own distinct y-axis subcoordinate system. To activate this feature, set the `subcoordinate_y` keyword to True for **each** overlay element; the default is False. When using `subcoordinate_y=True`, setting a `label` for each element is required for proper rendering and identification.This will automatically distribute overlay elements along the y-axis.
+
+For more fine-grained control over y-axis positioning, you can specify a numerical 2-tuple for subcoordinate_y with values ranging from 0 to 1. Additionally, the `subcoordinate_scale` keyword, which defaults to 1, allows you to adjust the vertical scale of each element. This option is only applicable when `subcoordinate_y=True`. For example, setting a single Curve's `subcoordinate_scale` to 2 will result in it overlapping 50% with its adjacent elements.
+
+
+```python
+x = np.linspace(0, 10*np.pi)
+
+curves = [
+    hv.Curve((x + i*np.pi/2, np.sin(x)), label=f'Line {i}').opts(subcoordinate_y=True, subcoordinate_scale=1.2)
+    for i in range(3)
+]
+
+hv.Overlay(curves).opts(show_legend=False)
+```

hvplot_docs/Deploying_Bokeh_Apps.md

@@ -0,0 +1,553 @@
+# Deploying Bokeh Apps
+
+
+```python
+import numpy as np
+import holoviews as hv
+hv.extension('bokeh')
+```
+
+## Purpose
+
+HoloViews is an incredibly convenient way of working interactively and exploratively within a notebook or commandline context. However, once you have implemented a polished interactive dashboard or some other complex interactive visualization, you will often want to deploy it outside the notebook to share with others who may not be comfortable with the notebook interface. 
+
+In the simplest case, to visualize some HoloViews container or element `obj`, you can export it to a standalone HTML file for sharing using the `save` function of the Bokeh renderer:
+
+```
+hv.save(obj, 'out.html')
+```
+
+This command will generate a file `out.html` that you can put on any web server, email directly to colleagues, etc.; it is fully self-contained and does not require any Python server to be installed or running.  
+
+Unfortunately, a static approach like this cannot support any HoloViews object that uses DynamicMap (either directly or via operations that return DynamicMaps like `decimate`, `datashade`, and `rasterize`).  Anything with DynamicMap requires a live, running Python server to dynamically select and provide the data for the various parameters that can be selected by the user. Luckily, when you need a live Python process during the visualization, the [Bokeh server](http://bokeh.pydata.org/en/latest/docs/user_guide/server.html) provides a very convenient way of deploying HoloViews plots and interactive dashboards in a scalable and flexible manner. The Bokeh server allows all the usual interactions that HoloViews lets you define and more including:
+
+* responding to plot events and tool interactions via [Linked Streams](./13-Custom_Interactivity.ipynb)
+* generating and interacting with plots via the usual widgets that HoloViews supports for HoloMap and DynamicMap objects.
+* using periodic and timeout events to drive plot updates
+* combining HoloViews plots with custom Bokeh plots to quickly write highly customized apps.
+
+## Overview
+
+In this guide we will cover how we can deploy a Bokeh app from a HoloViews plot in a number of different ways:
+
+1. Inline from within the Jupyter notebook
+
+2. Starting a server interactively and open it in a new browser window.
+
+3. From a standalone script file
+
+4. Combining HoloViews and Bokeh models to create a more customized app
+
+If you have read a bit about HoloViews you will know that HoloViews objects are not themselves plots, instead they contain sufficient data and metadata allowing them to be rendered automatically in a notebook context. In other words, when a HoloViews object is evaluated a backend specific ``Renderer`` converts the HoloViews object into Bokeh models, a Matplotlib figure or a Plotly graph. This intermediate representation is then rendered as an image or as HTML with associated Javascript, which is what ends up being displayed.
+
+## The workflow
+
+The most convenient way to work with HoloViews is to iteratively improve a visualization in the notebook. Once you have developed a visualization or dashboard that you would like to deploy you can use the ``BokehRenderer`` to export the visualization as illustrated above, or you can deploy it as a Bokeh server app. 
+
+Here we will create a small interactive plot, using [Linked Streams](./13-Custom_Interactivity.ipynb), which mirrors the points selected using box- and lasso-select tools in a second plot and computes some statistics:
+
+
+```python
+# Declare some points
+points = hv.Points(np.random.randn(1000,2 ))
+
+# Declare points as source of selection stream
+selection = hv.streams.Selection1D(source=points)
+
+# Write function that uses the selection indices to slice points and compute stats
+def selected_info(index):
+    arr = points.array()[index]
+    if index:
+        label = 'Mean x, y: %.3f, %.3f' % tuple(arr.mean(axis=0))
+    else:
+        label = 'No selection'
+    return points.clone(arr, label=label).opts(color='red')
+
+# Combine points and DynamicMap
+selected_points = hv.DynamicMap(selected_info, streams=[selection])
+layout = points.opts(tools=['box_select', 'lasso_select']) + selected_points
+
+layout
+```
+
+<img src='https://assets.holoviews.org/gifs/examples/streams/bokeh/point_selection1d.gif'></img>
+
+#### Working with the BokehRenderer
+
+When working with Bokeh server or wanting to manipulate a backend specific plot object you will have to use a HoloViews ``Renderer`` directly to convert the HoloViews object into the backend specific representation. Therefore we will start by getting a hold of a ``BokehRenderer``:
+
+
+```python
+renderer = hv.renderer('bokeh')
+print(renderer)
+```
+
+```python
+BokehRenderer()
+```
+
+All ``Renderer`` classes in HoloViews are so called ParameterizedFunctions; they provide both classmethods and instance methods to render an object. You can easily create a new ``Renderer`` instance using the ``.instance`` method:
+
+
+```python
+renderer = renderer.instance(mode='server')
+```
+
+Renderers can also have different modes. In this case we will instantiate the renderer in ``'server'`` mode, which tells the Renderer to render the HoloViews object to a format that can easily be deployed as a server app. Before going into more detail about deploying server apps we will quickly remind ourselves how the renderer turns HoloViews objects into Bokeh models.
+
+### Figures
+
+The BokehRenderer converts the HoloViews object to a HoloViews ``Plot``, which holds the Bokeh models that will be rendered to screen. As a very simple example we can convert a HoloViews ``Image`` to a HoloViews plot:
+
+
+```python
+plot = renderer.get_plot(layout)
+print(plot)
+```
+
+```
+<LayoutPlot LayoutPlot01811>
+```
+
+Using the ``state`` attribute on the HoloViews plot we can access the Bokeh ``Column`` model, which we can then work with directly.
+
+
+```python
+plot.state
+```
+
+**Column**(id='1570', ...)
+
+In the background this is how HoloViews converts any HoloViews object into Bokeh models, which can then be converted to embeddable or standalone HTML and be rendered in the browser. This conversion is usually done in the background using the ``figure_data`` method:
+
+
+```python
+html = renderer._figure_data(plot, 'html')
+```
+
+### Bokeh Documents
+
+In Bokeh the [``Document``](http://bokeh.pydata.org/en/latest/docs/reference/document.html) is the basic unit at which Bokeh models (such as plots, layouts and widgets) are held and serialized. The serialized JSON representation is then sent to BokehJS on the client-side browser. When in ``'server'`` mode the BokehRenderer will automatically return a server Document:
+
+
+```python
+renderer(layout)
+```
+
+```
+(<bokeh.document.Document at 0x11afc7590>,
+ {'file-ext': 'html', 'mime_type': u'text/html'})
+```
+
+We can also easily use the ``server_doc`` method to get a Bokeh ``Document``, which does not require you to make an instance in 'server' mode.
+
+
+```python
+doc = renderer.server_doc(layout)
+doc.title = 'HoloViews App'
+```
+
+In the background however, HoloViews uses the Panel library to render components to a Bokeh model which can be rendered in the notebook, to a file or on a server:
+
+
+```python
+import panel as pn
+
+model = pn.panel(layout).get_root()
+model
+```
+
+For more information on the interaction between Panel and HoloViews see the the [Panel documentation](https://panel.holoviz.org/reference/panes/HoloViews.html).
+
+## Deploying with ``panel serve``
+
+Deployment from a script with `panel serve` is one of the most common ways to deploy a Bokeh app. Any ``.py`` or ``.ipynb`` file that attaches a plot to Bokeh's ``curdoc`` can be deployed using ``panel serve``. The easiest way to do this is using wrapping the HoloViews component in Panel using ``pn.panel(hvobj)`` and then calling the ``panel_obj.servable()`` method, which accepts any HoloViews object ensures that the plot is discoverable by Panel and the underlying Bokeh server. See below to see a full standalone script:
+
+```python
+import numpy as np
+import panel as pn
+import holoviews as hv
+import holoviews.plotting.bokeh
+
+points = hv.Points(np.random.randn(1000,2 )).opts(tools=['box_select', 'lasso_select'])
+selection = hv.streams.Selection1D(source=points)
+
+def selected_info(index):
+    arr = points.array()[index]
+    if index:
+        label = 'Mean x, y: %.3f, %.3f' % tuple(arr.mean(axis=0))
+    else:
+        label = 'No selection'
+    return points.clone(arr, label=label).opts(color='red')
+
+layout = points + hv.DynamicMap(selected_info, streams=[selection])
+
+pn.panel(layout).servable(title='HoloViews App')
+```
+
+In just a few steps we can iteratively refine in the notebook to a deployable Panel app. Note also that we can also deploy an app directly from a notebook. By using `.servable()` in a notebook any regular ``.ipynb`` file can be made into a valid Panel/Bokeh app, which can be served with ``panel serve example.ipynb``.
+
+It is also possible to create a Bokeh `Document` more directly working with the underlying Bokeh representation instead. This in itself is sufficient to make the plot servable using `bokeh serve`:
+
+
+```python
+hv.renderer('bokeh').server_doc(layout)
+```
+
+In addition to starting a server from a script we can also start up a server interactively, so let's do a quick deep dive into Bokeh ``Application`` and ``Server`` objects and how we can work with them from within HoloViews.
+
+## Bokeh Server
+
+To start a Bokeh server directly from a notebook we can also use Panel, specifically we'll use the `panel.serve` function. We'll define a ``DynamicMap`` of a sine ``Curve`` varying by frequency, phase and an offset and then create a server instance using Panel:
+
+
+```python
+def sine(frequency, phase, amplitude):
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(frequency*xs+phase)*amplitude)).opts(width=800)
+
+ranges = dict(frequency=(1, 5), phase=(-np.pi, np.pi), amplitude=(-2, 2), y=(-2, 2))
+dmap = hv.DynamicMap(sine, kdims=['frequency', 'phase', 'amplitude']).redim.range(**ranges)
+
+server = pn.serve(dmap, start=False, show=False)
+```
+
+```
+<bokeh.server.server.Server object at 0x10b3a0510>
+```
+
+Next we can define a callback on the IOLoop that will open the server app in a new browser window and actually start the app (and if outside the notebook the IOLoop):
+
+
+```python
+server.start()
+server.show('/')
+
+# Outside the notebook ioloop needs to be started
+# from tornado.ioloop import IOLoop
+# loop = IOLoop.current()
+# loop.start() 
+```
+
+After running the cell above you should have noticed a new browser window popping up displaying our plot. Once you are done playing with it you can stop it with:
+
+
+```python
+server.stop()
+```
+
+We can achieve the equivalent using the `.show` method on a Panel object:
+
+
+```python
+server = pn.panel(dmap).show()
+```
+
+<img width='80%' src="https://assets.holoviews.org/gifs/guides/user_guide/Deploying_Bokeh_Apps/bokeh_server_new_window.png"></img>
+
+We will once again stop this Server before continuing:
+
+
+```python
+server.stop()
+```
+
+## Inlining apps in the notebook
+
+Instead of displaying our app in a new browser window we can also display an app inline in the notebook simply by using the `.app` method on Panel object. The server app will be killed whenever you rerun or delete the cell that contains the output. Additionally, if your Jupyter Notebook server is not running on the default address or port (``localhost:8888``) supply the websocket origin, which should match the first part of the URL of your notebook:
+
+
+```python
+dmap
+```
+
+<img width='80%' src='https://assets.holoviews.org/gifs/guides/user_guide/Deploying_Bokeh_Apps/bokeh_server_inline_simple.gif'></img>
+
+## Periodic callbacks
+
+One of the most important features of deploying apps is the ability to attach asynchronous, periodic callbacks, which update the plot. The simplest way of achieving this is to attach a ``Counter`` stream on the plot which is incremented on each callback. As a simple demo we'll simply compute a phase offset from the counter value, animating the sine wave:
+
+
+```python
+def sine(counter):
+    phase = counter*0.1%np.pi*2
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(xs+phase))).opts(width=800)
+
+counter = hv.streams.Counter()
+hv.DynamicMap(sine, streams=[counter])
+
+dmap
+```
+
+<img width='80%' src='https://assets.holoviews.org/gifs/guides/user_guide/Deploying_Bokeh_Apps/bokeh_server_periodic.gif'></img>
+
+Once we have created a Panel object we can call the `add_periodic_callback` method to set up a periodic callback. The first argument to the method is the callback and the second argument period specified in milliseconds. As soon as we start this callback you should see the Curve above become animated.
+
+
+```python
+def update():
+    counter.event(counter=counter.counter+1)
+
+cb = pn.state.add_periodic_callback(update, period=200)
+```
+
+Once started we can stop and start it at will using the `.stop` and `.start` methods:
+
+
+```python
+cb.stop()
+```
+
+## Combining Bokeh Application and Flask Application
+
+While Panel and Bokeh are great ways to create an application often we want to leverage the simplicity of a Flask server. With Flask we can easily embed a HoloViews, Bokeh and Panel application in a regular website. The main idea for getting Bokeh and Flask to work together is to run both apps on ports and then use Flask to pull the Bokeh Serve session with `pull_session` from [bokeh.client.session](https://bokeh.pydata.org/en/latest/docs/reference/client/session.html). 
+
+
+```python
+def sine(frequency, phase, amplitude):
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(frequency*xs+phase)*amplitude)).options(width=800)
+
+ranges = dict(frequency=(1, 5), phase=(-np.pi, np.pi), amplitude=(-2, 2), y=(-2, 2))
+dmap = hv.DynamicMap(sine, kdims=['frequency', 'phase', 'amplitude']).redim.range(**ranges)
+
+pn.serve(dmap, websocket_origin='localhost:5000', port=5006, show=False)
+```
+
+We run load up our dynamic map into a Bokeh Application with the parameter `allow_websocket_origin=["localhost:5000"]`
+
+```python
+from bokeh.client import pull_session
+from bokeh.embed import server_session
+from flask import Flask, render_template
+from flask import send_from_directory
+
+app = Flask(__name__)
+
+
+# locally creates a page
+@app.route('/')
+def index():
+    with pull_session(url="http://localhost:5006/") as session:
+        # generate a script to load the customized session
+        script = server_session(session_id=session.id, url='http://localhost:5006')
+        # use the script in the rendered page
+    return render_template("embed.html", script=script, template="Flask")
+
+if __name__ == '__main__':
+    # runs app in debug mode
+    app.run(port=5000, debug=True)
+```
+
+Note that in a notebook context we cannot use `pull_session` but this example demonstrates how we can embed the Bokeh server inside a simple flask app.
+
+This is an example of a basic flask app. To find out more about Flask a tutorial can be found on the [Flask Quickstart Guide](http://flask.pocoo.org/docs/1.0/quickstart/#). 
+
+
+
+Below is an example of a basic Flask App that pulls from the Bokeh Application. The Bokeh Application is using `Server` from Bokeh and `IOLoop` from tornado to run the app. 
+
+```python
+# holoviews.py
+
+import holoviews as hv
+import panel as pn
+import numpy as np
+
+hv.extension('bokeh')
+
+def sine(frequency, phase, amplitude):
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(frequency*xs+phase)*amplitude)).options(width=800)
+
+if __name__ == '__main__':
+    ranges = dict(frequency=(1, 5), phase=(-np.pi, np.pi), amplitude=(-2, 2), y=(-2, 2))
+    dmap = hv.DynamicMap(sine, kdims=['frequency', 'phase', 'amplitude']).redim.range(**ranges)
+    pn.serve(dmap, port=5006, allow_websocket_origin=["localhost:5000"], show=False)
+```
+
+```python
+#flaskApp.py
+
+from bokeh.client import pull_session
+from bokeh.embed import server_session
+from flask import Flask, render_template
+from flask import send_from_directory
+
+app = Flask(__name__)
+
+# locally creates a page
+@app.route('/')
+def index():
+    with pull_session(url="http://localhost:5006/") as session:
+            # generate a script to load the customized session
+            script = server_session(session_id=session.id, url='http://localhost:5006')
+            # use the script in the rendered page
+    return render_template("embed.html", script=script, template="Flask")
+
+
+if __name__ == '__main__':
+    # runs app in debug mode
+    app.run(port=5000, debug=True)
+```
+
+```html
+<!-- embed.html -->
+
+<!doctype html>
+
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Embedding a Bokeh Server With Flask</title>
+</head>
+
+<body>
+  <div>
+    This Bokeh app below served by a Bokeh server that has been embedded
+    in another web app framework. For more information see the section
+    <a  target="_blank" href="https://bokeh.pydata.org/en/latest/docs/user_guide/server.html#embedding-bokeh-server-as-a-library">Embedding Bokeh Server as a Library</a>
+    in the User's Guide.
+  </div>
+  {{ script|safe }}
+</body>
+</html>
+```
+
+If you wish to replicate navigate to the `examples/gallery/apps/flask` directory and follow the these steps:
+
+* Step One: call `python holoviews_app.py` in the terminal (this will start the Panel/Bokeh server)
+* Step Two: open a new terminal and call `python flask_app.py` (this will start the Flask application)
+* Step Three: go to web browser and type `localhost:5000` and the app will appear
+
+## Combining HoloViews and Panel or Bokeh Plots/Widgets
+
+While HoloViews provides very convenient ways of creating an app it is not as fully featured as Bokeh itself is. Therefore we often want to extend a HoloViews based app with Panel or Bokeh plots and widgets. Here we will discover to achieve this with both Panel and then the equivalent using pure Bokeh.
+
+
+```python
+import holoviews as hv
+import numpy as np
+import panel as pn
+
+# Create the holoviews app again
+def sine(phase):
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(xs+phase))).opts(width=800)
+
+stream = hv.streams.Stream.define('Phase', phase=0.)()
+dmap = hv.DynamicMap(sine, streams=[stream])
+
+start, end = 0, np.pi*2
+slider = pn.widgets.FloatSlider(start=start, end=end, value=start, step=0.2, name="Phase")
+
+# Create a slider and play buttons
+def animate_update():
+    year = slider.value + 0.2
+    if year > end:
+        year = start
+    slider.value = year
+
+def slider_update(event):
+    # Notify the HoloViews stream of the slider update 
+    stream.event(phase=event.new)
+
+slider.param.watch(slider_update, 'value')
+
+def animate(event):
+    if button.name == '► Play':
+        button.name = '❚❚ Pause'
+        callback.start()
+    else:
+        button.name = '► Play'
+        callback.stop()
+
+button = pn.widgets.Button(name='► Play', width=60, align='end')
+button.on_click(animate)
+callback = pn.state.add_periodic_callback(animate_update, 50, start=False)
+
+app = pn.Column(
+    dmap,
+    pn.Row(slider, button)
+)
+
+app
+```
+
+If instead we want to deploy this we could add `.servable` as discussed before or use `pn.serve`. Note however that when using `pn.serve` all sessions will share the same state therefore it is best to 
+wrap the creation of the app in a function which we can then provide to `pn.serve`. For more detail on deploying Panel applications also see the [Panel server deployment guide](https://panel.holoviz.org/user_guide/Server_Deployment.html).
+
+Now we can reimplement the same example using Bokeh allowing us to compare and contrast the approaches:
+
+
+```python
+import numpy as np
+import holoviews as hv
+
+from bokeh.io import show, curdoc
+from bokeh.layouts import layout
+from bokeh.models import Slider, Button
+
+renderer = hv.renderer('bokeh').instance(mode='server')
+
+# Create the holoviews app again
+def sine(phase):
+    xs = np.linspace(0, np.pi*4)
+    return hv.Curve((xs, np.sin(xs+phase))).opts(width=800)
+
+stream = hv.streams.Stream.define('Phase', phase=0.)()
+dmap = hv.DynamicMap(sine, streams=[stream])
+
+# Define valid function for FunctionHandler
+# when deploying as script, simply attach to curdoc
+def modify_doc(doc):
+    # Create HoloViews plot and attach the document
+    hvplot = renderer.get_plot(dmap, doc)
+
+    # Create a slider and play buttons
+    def animate_update():
+        year = slider.value + 0.2
+        if year > end:
+            year = start
+        slider.value = year
+
+    def slider_update(attrname, old, new):
+        # Notify the HoloViews stream of the slider update 
+        stream.event(phase=new)
+        
+    start, end = 0, np.pi*2
+    slider = Slider(start=start, end=end, value=start, step=0.2, title="Phase")
+    slider.on_change('value', slider_update)
+    
+    callback_id = None
+
+    def animate():
+        global callback_id
+        if button.label == '► Play':
+            button.label = '❚❚ Pause'
+            callback_id = doc.add_periodic_callback(animate_update, 50)
+        else:
+            button.label = '► Play'
+            doc.remove_periodic_callback(callback_id)
+    button = Button(label='► Play', width=60)
+    button.on_click(animate)
+    
+    # Combine the holoviews plot and widgets in a layout
+    plot = layout([
+    [hvplot.state],
+    [slider, button]], sizing_mode='fixed')
+    
+    doc.add_root(plot)
+    return doc
+
+# To display in the notebook
+show(modify_doc, notebook_url='localhost:8888')
+
+# To display in a script
+#    doc = modify_doc(curdoc()) 
+```
+
+<img width='80%' src='https://assets.holoviews.org/gifs/guides/user_guide/Deploying_Bokeh_Apps/bokeh_server_play.gif'></img>
+
+As you can see depending on your needs you have complete freedom whether to use just HoloViews and deploy your application, combine it Panel or even with pure Bokeh.

hvplot_docs/Explorer.md

@@ -0,0 +1,123 @@
+```python
+import hvplot.pandas  # noqa
+import xarray as xr
+```
+
+hvPlot API provides a simple and intuitive way to create plots. However when you are exploring data you don't always know in advance the best way to display it, or even what kind of plot would be best to visualize the data. You will very likely embark in an iterative process that implies choosing a kind of plot, setting various options, running some code, and repeat until you're satisfied with the output and the insights you get. The *Explorer* is a *Graphical User Interface* that allows you to easily generate customized plots, which in practice gives you the possibility to **explore** both your data and hvPlot's extensive API.
+
+:::{note}
+The *Explorer* has been added to hvPlot in version <code>0.8.0</code> and improve over the next versions, in particular version <code>0.9.0</code> added support to Xarray input types. We plan to keep on improving the explorer, making it a powerful exploration app, in the meantime please report any issue or feature request <a href='https://github.com/holoviz/hvplot/'>on GitHub</a>.
+:::
+
+## Set up
+
+For an explorer to be displayed in a notebook you need to load the hvPlot extension, which happens automatically when you execute an import like `import hvplot.pandas`. You could also just run `hvplot.extension('bokeh')`. If instead of building Bokeh plots you would rather build Matplotlib or Plotly plots, simply execute once `hvplot.extension('matplotlib')` or `hvplot.extension('matplotlib')` before displaying the explorer.
+
+## Instantiate
+
+An explorer can be instantiated in two different ways:
+
+- via the top-level `explorer()` function: `from hvplot import explorer; explorer(data)`
+- via the `.explorer()` method available on the `.hvplot` namespace: `data.hvplot.explorer()` (added in version 0.9.0)
+
+The `explorer` callable accept options to pre-customize the plot, for example `data.hvplot.explorer(title='Penguins', width=200)`.
+
+## Interface
+
+The object returned by `explorer()` is a [Panel](https://panel.holoviz.org/) layout that can be displayed in a notebook or served in a web application. This small application includes:
+
+- right-hand side: a preview of the hvPlot plot and code you are building
+- left-hand side: the various options that you can set to customize the plot
+- top part: an Alert section that displays error messages
+- bottom part: a status bar which includes a *live update* checkbox to disable live updating the preview
+
+Let's create our first explorer instance.
+
+
+```python
+from bokeh.sampledata.penguins import data as df
+
+df.head(2)
+```
+
+
+```python
+hvexplorer = df.hvplot.explorer()
+hvexplorer
+```
+
+Spend some time browsing the options made available to you. Note however that to be fully interactive the explorer needs to be executed with a live Python kernel, updating the options on the website won't update the plot.
+
+Before diving more into the explorer's capabilities, we will update the explorer we just created as the default configuration doesn't lead to a very interesting preview for this dataset. We will do so programmatically for the purpose of building this website but you would usually not have to do that, so just assume you've changed a few options directly in the explorer using your mouse and keyboard.
+
+
+```python
+hvexplorer.param.update(x='bill_length_mm', y_multi=['bill_depth_mm'], by=['species'])
+hvexplorer.labels.title = 'Penguins Scatter'
+```
+
+### Record the plot state
+
+Quite often you will want to record the state of a plot you have obtained from the explorer. We even encourage the pattern of creating short-lived explorer instances that allow for quickly building the plots you want, record their state and then remove the instances from your notebook, possibly replacing them by simpler `.hvplot()` plot expressions.
+
+You can record the state of an explorer instance in multiple ways:
+
+- *Code* tab: displays a code snippet you can copy/paste in your notebook and that will generate exactly the same plot as previewed in the explorer
+- `code` parameter: holds the code snippet string
+- `.plot_code(var_name)` method: similar to the `code` parameter except you can configure the variable name
+- `.settings()` method: to obtain a dictionary of your customized settings
+- `.save(filename, **kwargs)` method: to save the plot to file
+- `.hvplot()` method: to get a handle on the displayed HoloViews plot
+
+We will explore a few of these approaches. Let's start with printng `code` and validating that is produces a snippet that can be copy/pasted into another cell and executed (using `eval` to simulate that).
+
+
+```python
+print(hvexplorer.code)
+```
+
+
+```python
+eval(hvexplorer.code)
+```
+
+The dictionary obtained from calling `.settings()` can be directly passed as kwargs to the `.hvplot()` data accessor to re-create the customized plot using the plotting API.
+
+
+```python
+settings = hvexplorer.settings()
+settings
+```
+
+Note that for the next line to display a plot `hvplot.pandas` has to be imported, which we did at the beginning of this notebook.
+
+
+```python
+df.hvplot(**settings)
+```
+
+## Supported data inputs
+
+The explorer was added in version `0.8.0` with support for Pandas DataFrames. Support for Xarray objects was added in version `0.9.0`.
+
+
+```python
+ds = xr.tutorial.open_dataset('air_temperature')
+
+hvplot.explorer(ds, x='lon', y='lat')
+```
+
+## Geographic options
+
+When `geoviews` is installed, it's also possible to geographically reference the data.
+
+
+```python
+hvexplorer = hvplot.explorer(ds, x='lon', y='lat', geo=True)
+hvexplorer.geographic.param.update(crs='PlateCarree', tiles='CartoDark', global_extent=False)
+hvexplorer
+```
+
+## Conclusion
+
+The *Explorer* makes it very easy to quickly spin up a small application in a notebook with which you can explore your data, generate the visualization that you want, record it in a simple way, and keep going with your analysis!

hvplot_docs/Exporting_and_Archiving.md

@@ -0,0 +1,246 @@
+# Exporting and Archiving
+
+Most of the other user guides show you how to use HoloViews for interactive, exploratory visualization of your data, while the [Applying Customizations](03-Applying_Customizations.ipynb) user guide shows how to use HoloViews completely non-interactively, generating and rendering images directly to disk using `hv.save`.  In this notebook, we show how HoloViews works together with the Jupyter Notebook to establish a fully interactive yet *also* fully reproducible scientific or engineering workflow for generating reports or publications.  That is, as you interactively explore your data and build visualizations in the notebook, you can automatically generate and export them as figures that will feed directly into your papers or web pages, along with records of how those figures were generated and even storing the actual data involved so that it can be re-analyzed later. 
+
+
+
+
+```python
+import holoviews as hv
+from holoviews import opts
+from holoviews.operation import contours
+hv.extension('matplotlib')
+```
+
+## Exporting specific files
+
+During interactive exploration in the Jupyter Notebook, your results are always visible within the notebook itself, but you can explicitly request that any visualization is also exported to an external file on disk:
+
+
+```python
+penguins = hv.RGB.load_image('../assets/penguins.png')
+hv.save(penguins, 'penguin_plot.png', fmt='png')
+penguins
+```
+
+This mechanism can be used to provide a clear link between the steps for generating the figure, and the file on disk.  You can now load the exported PNG image back into HoloViews, if you like, using ``hv.RGB.load_image`` although the result would be a bit confusing due to the nested axes.
+
+The ``fig="png"`` part of the ``hv.save`` function call above specified that the file should be saved in PNG format, which is useful for posting on web pages or editing in raster-based graphics programs. Note that `hv.save` also accepts `HoloMap`s which can be saved to formats such as ``'scrubber'``, ``'widgets'`` or even ``'gif'`` or ``'mp4'`` (if the necessary matplotlib dependencies are available). 
+
+If the file extension is part of the filename, that will automatically be used to set the format. Conversely, if the format is explicitly specified, then the extension does not have to be part of the filename (and any filename extension that is provided will be ignored). Sometimes the two pieces of information are independent: for instance, a filename ending in `.html` can support either the `'widgets'` or `'scrubber'` formats.
+
+For a publication, you will usually want to select SVG format because this vector format preserves the full resolution of all text and drawing elements.  SVG files can be be used in some document preparation programs directly (e.g. [LibreOffice](http://www.libreoffice.org/)), and can easily be converted and manipulated in vector graphics editors such as [Inkscape](https://inkscape.org).
+
+## Exporting notebooks
+
+The ``hv.save`` function is useful when you want specific plots saved into specific files.  Often, however, a notebook will contain an entire suite of results contained in multiple different cells, and manually specifying these cells and their filenames is error-prone, with a high likelihood of accidentally creating multiple files with the same name or using different names in different notebooks for the same objects.
+
+To make the exporting process easier for large numbers of outputs, as well as more predictable, HoloViews also offers a powerful automatic notebook exporting facility, creating an archive of all your results.  Automatic export is very useful in the common case of having a notebook that contains a series of figures to be used in a report or publication, particularly if you are repeatedly re-running the notebook as you finalize your results, and want the full set of current outputs to be available to an external document preparation system.
+
+The advantage of using this archival system over simply converting the notebook to a static HTML file with nbconvert is that you can generate a collection of individual file assets in one or more desired file formats.
+
+To turn on automatic adding of your files to the export archive, run ``hv.archive.auto()``:
+
+
+```python
+hv.archive.auto()
+```
+
+This object's behavior can be customized extensively; try pressing tab within the parentheses for a list of options, which are described more fully below.
+
+By default, the output will go into a directory with the same name as your notebook, and the names for each object will be generated from the groups and labels used by HoloViews.  Objects that contain HoloMaps are not exported by default, since those are usually rendered as animations that are not suitable for inclusion in publications, but you can change it to ``.auto(holomap='gif')`` if you want those as well.  
+
+### Adding files to an archive
+
+To see how the auto-exporting works, let's define a few HoloViews objects:
+
+
+```python
+penguins[:,:,'R'].relabel("Red") + penguins[:,:,'G'].relabel("Green") + penguins[:,:,'B'].relabel("Blue")
+```
+
+
+```python
+penguins * hv.Arrow(0.15, 0.3, 'Penguin', '>')
+```
+
+
+```python
+cs = contours(penguins[:,:,'R'], levels=[0.10,0.80])
+overlay = penguins[:, :, 'R'] * cs
+overlay.opts(
+    opts.Contours(linewidth=1.3, cmap='Autumn'),
+    opts.Image(cmap="gray"))
+```
+
+We can now list what has been captured, along with the names that have been generated:
+
+
+```python
+hv.archive.contents()
+```
+
+Here each object has resulted in two files, one in SVG format and one in Python "pickle" format (which appears as a ``zip`` file with extension ``.hvz`` in the listing).  We'll ignore the pickle files for now, focusing on the SVG images.
+
+The name generation code for these files is heavily customizable, but by default it consists of a list of dimension values and objects:
+
+  ``{dimension},{dimension},...{group}-{label},{group}-{label},...``.  
+
+The ``{dimension}`` shows what dimension values are included anywhere in this object, if it contains any high-level ``Dimensioned`` objects like ``HoloMap``, ``NdOverlay``, and ``GridSpace``.  Of course, nearly all HoloViews objects have dimensions, such as ``x`` and ``y`` in this case, but those dimensions are not used in the filenames because they are explicitly shown in the plots; only the top-level dimensions are used (those that determine which plot this is, not those that are shown in the plot itself.)
+
+The ``{group}-{label}`` information lists the names HoloViews uses for default titles and for attribute access for the various objects that make up a given displayed object.  E.g. the first SVG image in the list is a ``Layout`` of the three given ``Image`` objects, and the second one is an ``Overlay`` of an ``RGB`` object and an ``Arrow`` object.  This information usually helps distinguish one plot from another, because they will typically be plots of objects that have different labels.  
+
+If the generated names are not unique, a numerical suffix will be added to make them unique.  A maximum filename length is enforced, which can be set with ``hv.archive.max_filename=``_num_.
+
+If you prefer a fixed-width filename, you can use a hash for each name instead (or in addition), where ``:.8`` specifies how many characters to keep from the hash:
+
+
+```python
+hv.archive.filename_formatter="{SHA:.8}"
+cs
+```
+
+
+```python
+hv.archive.contents()
+```
+
+You can see that the newest files added have the shorter, fixed-width format, though the names are no longer meaningful.  If the ``filename_formatter`` had been set from the start, all filenames would have been of this type, which has both practical advantages (short names, all the same length) and disadvantages (no semantic clue about the contents).
+
+### Generated indexes
+
+In addition to the files that were added to the archive for each of the cell outputs above, the archive exporter will also add an ``index.html`` file with a static copy of the notebook, with each cell labelled with the filename used to save it once `hv.archive.export()` is called (you can verify this for yourself after this call is executed below).  This HTML file acts as a definitive index to your results, showing how they were generated and where they were exported on disk.  
+
+The exporter will also add a cleared, runnable copy of the notebook ``index.ipynb`` (with output deleted), so that you can later regenerate all of the output, with changes if necessary.  
+
+The exported archive will thus be a complete set of your results, along with a record of how they were generated, plus a recipe for regenerating them  -- i.e., fully reproducible research!  This HTML file and .ipynb file can the be submitted as supplemental materials for a paper, allowing any reader to build on your results, or it can just be kept privately so that future collaborators can start where this research left off.
+
+### Adding your own data to the archive
+
+Of course, your results may depend on a lot of external packages, libraries, code files, and so on, which will not automatically be included or listed in the exported archive.
+
+Luckily, the archive support is very general, and you can add any object to it that you want to be exported along with your output.  For instance, you can store arbitrary metadata of your choosing, such as version control information, here as a JSON-format text file: 
+
+
+```python
+import json
+hv.archive.add(filename='metadata.json', 
+               data=json.dumps({'repository':'git@github.com:holoviz/holoviews.git',
+                                'commit':'437e8d69'}), info={'mime_type':'text/json'})
+```
+
+The new file can now be seen in the contents listing:
+
+
+```python
+hv.archive.contents()
+```
+
+You can get a more direct list of filenames using the ``listing`` method:
+
+
+```python
+listing = hv.archive.listing()
+listing
+```
+
+In this way, you should be able to automatically generate output files, with customizable filenames, storing any data or metadata you like along with them so that you can keep track of all the important information for reproducing these results later.
+
+### Controlling the behavior of ``hv.archive``
+
+The ``hv.archive`` object provides numerous parameters that can be changed.  You can e.g.:
+
+- output the whole directory to a single compressed ZIP or tar archive file (e.g. ``hv.archive.param.update(pack=False, archive_format='zip')`` or ``archive_format='tar'``)
+
+- generate a new directory or archive every time the notebook is run (``hv.archive.uniq_name=True``); otherwise the old output directory is erased each time 
+
+- choose your own name for the output directory or archive (e.g. ``hv.archive.export_name="{timestamp}"``)
+
+- change the format of the optional timestamp (e.g. to retain snapshots hourly, ``archive.param.update(export_name="{timestamp}", timestamp_format="%Y_%m_%d-%H")``)
+
+- select PNG output, at a specified rendering resolution: ``hv.archive.exporters=[hv.renderer('bokeh').instance(size=50)])
+``
+
+These options and any others listed above can all be set in the ``hv.archive.auto()`` call at the start, for convenience and to ensure that they apply to all of the files that are added.
+
+### Writing the archive to disk
+
+To actually write the files you have stored in the archive to disk, you need to call ``export()`` after any cell that might contain computation-intensive code.  Usually it's best to do so as the last or nearly last cell in your notebook, though here we do it earlier because we wanted to show how to use the exported files.
+
+
+```python
+hv.archive.export()
+```
+
+Shortly after the ``export()`` command has been executed, the output should be available as a directory on disk, by default in the same directory as the notebook file, named with the name of the notebook:  
+
+
+```python
+import os
+os.getcwd()
+if os.path.exists(hv.archive.notebook_name):
+    print('\n'.join(sorted(os.listdir(hv.archive.notebook_name))))
+```
+
+For technical reasons to do with how the IPython Notebook interacts with JavaScript, if you use the Jupyter Notebook command ``Run all``, the ``hv.archive.export()`` command is not actually executed when the cell with that call is encountered during the run.  Instead, the ``export()`` is queued until after the final cell in the notebook has been executed.  This asynchronous execution has several awkward but not serious consequences:
+
+- It is not possible for the ``export()`` cell to show whether any errors were encountered during exporting, because these will not occur until after the notebook has completed processing.  To see any errors, you can run  ``hv.archive.last_export_status()`` separately, *after* the ``Run all`` has completed.  E.g. just press shift-[Enter] in the following cell, which will tell you whether the previous export was successful.
+
+- If you use ``Run all``, the directory listing ``os.listdir()`` above will show the results from the *previous* time this notebook was run, since it executes before the export.  Again, you can use shift-[Enter] to update the data once complete.
+
+- The ``Export name:`` in the output of ``hv.archive.export()`` will not always show the actual name of the directory or archive that will be created.  In particular, it may say ``{notebook}``, which when saving will actually expand to the name of your Jupyter Notebook.
+
+
+```python
+hv.archive.last_export_status()
+```
+
+### Accessing your saved data
+
+By default, HoloViews saves not only your rendered plots (PNG, SVG, etc.), but also the actual HoloViews objects that the plots visualize, which contain all your actual data.  The objects are stored in compressed Python pickle files (``.hvz``), which are visible in the directory listings above but have been ignored until now.  The plots are what you need for writing a document, but the raw data is is a crucial record to keep as well.  For instance, you now can load in the HoloViews object, and manipulate it just as you could when it was originally defined.  E.g. we can re-load our ``Levels`` ``Overlay`` file, which has the contours overlaid on top of the image, and easily pull out the underlying ``Image`` object:
+
+
+```python
+import os
+from holoviews.core.io import Unpickler
+c, a = None,None
+hvz_file = [f for f in listing if f.endswith('hvz')][0]
+path = os.path.join(hv.archive.notebook_name, hvz_file)
+
+if os.path.isfile(path):
+    print('Unpickling {filename}'.format(filename=hvz_file))
+    obj = Unpickler.load(open(path,"rb"))
+    print(obj)
+else:
+    print('Could not find file {path}'.format(path=path))
+    print('Current directory is {cwd}'.format(cwd=os.getcwd()))
+    print('Containing files and directories: {listing}'.format(listing=os.listdir(os.getcwd())))
+```
+
+Given the ``Image``, you can also access the underlying array data, because HoloViews objects are simply containers for your data and associated metadata. This means that years from now, as long as you can still run HoloViews, you can now easily re-load and explore your data, plotting it entirely different ways or running different analyses, even if you no longer have any of the original code you used to generate the data.  All you need is HoloViews, which is permanently archived on GitHub and is fully open source and thus should always remain available.  Because the data is stored conveniently in the archive alongside the figure that was published, you can see immediately which file corresponds to the data underlying any given plot in your paper, and immediately start working with the data, rather than laboriously trying to reconstruct the data from a saved figure.
+
+If you do not want the pickle files, you can of course turn them off if you prefer, by changing ``hv.archive.auto()`` to:
+
+```python
+hv.archive.auto(exporters=[hv.renderer('matplotlib').instance(holomap=None)])
+```
+
+Here, the exporters list has been updated to include the usual default exporters *without* the `Pickler` exporter that would usually be included.
+
+## Using HoloViews to do reproducible research
+
+The export options from HoloViews help you establish a feasible workflow for doing reproducible research: starting from interactive exploration, either export specific files with ``hv.save``, or enable ``hv.archive.auto()``, which will store a copy of your notebook and its output ready for inclusion in a document but retaining the complete recipe for reproducing the results later.  
+
+### Why reproducible research matters
+
+To understand why these capabilities are important, let's consider the process by which scientific results are typically generated and published without HoloViews.  Scientists and engineers use a wide variety of data-analysis tools, ranging from GUI-based programs like Excel spreadsheets, mixed GUI/command-line programs like Matlab, or purely scriptable tools like matplotlib or bokeh.  The process by which figures are created in any of these tools typically involves copying data from its original source, selecting it, transforming it, choosing portions of it to put into a figure, choosing the various plot options for a subfigure, combining different subfigures into a complete figure, generating a publishable figure file with the full figure, and then inserting that into a report or publication.  
+
+If using GUI tools, often the final figure is the only record of that process, and even just a few weeks or months later a researcher will often be completely unable to say precisely how a given figure was generated.  Moreover, this process needs to be repeated whenever new data is collected, which is an error-prone and time-consuming process. The lack of records is a serious problem for building on past work and revisiting the assumptions involved, which greatly slows progress both for individual researchers and for the field as a whole.  Graphical environments for capturing and replaying a user's GUI-based workflow have been developed, but these have greatly restricted the process of exploration, because they only support a few of the many analyses required, and thus they have rarely been successful in practice.  With GUI tools it is also very difficult to "curate" the sequence of steps involved, i.e., eliminating dead ends, speculative work, and unnecessary steps, with a goal of showing the clear path from incoming data to a final figure.
+
+In principle, using scriptable or command-line tools offers the promise of capturing the steps involved, in a form that can be curated.  In practice, however, the situation is often no better than with GUI tools, because the data is typically taken through many manual steps that culminate in a published figure, and without a laboriously manually created record of what steps are involved, the provenance of a given figure remains unknown.  Where reproducible workflows are created in this way, they tend to be "after the fact", as an explicit exercise to accompany a publication, and thus (a) they are rarely done, (b) they are very difficult to do if any of the steps were not recorded originally.  
+
+A Jupyter notebook helps significantly to make the scriptable-tools approach viable, by recording both code and the resulting output, and can thus in principle act as a record for establishing the full provenance of a figure.  But because typical plotting libraries require so much plotting-specific code before any plot is visible, the notebook quickly becomes unreadable.  To make notebooks readable, researchers then typically move the plotting code for a specific figure to some external file, which then drifts out of sync with the notebook so that the notebook no longer acts as a record of the link between the original data and the resulting figure.  
+
+HoloViews provides the final missing piece in this approach, by allowing researchers to work directly with their data interactively in a notebook, using small amounts of code that focus on the data and analyses rather than plotting code, yet showing the results directly alongside the specification for generating them.  This user guide will describe how use a Jupyter notebook with HoloViews to export your results in a way that preserves the information about how those results were generated, providing a clear chain of provenance and making reproducible research practical at last.
+
+For more information on how HoloViews can help build a reproducible workflow, see our [2015 paper on using HoloViews for reproducible research](http://conference.scipy.org/proceedings/scipy2015/pdfs/jean-luc_stevens.pdf).

hvplot_docs/Geographic_Data.md

@@ -0,0 +1,152 @@
+```python
+import xarray as xr
+import hvplot.pandas  # noqa
+import hvplot.xarray  # noqa
+import cartopy.crs as ccrs
+
+from bokeh.sampledata.airport_routes import airports
+```
+
+## Installation
+
+The plot API also has support for geographic data built on top of Cartopy and GeoViews. Both can be installed using conda with:
+
+    conda install geoviews
+    
+or with pip:
+
+    pip install geoviews
+
+## Usage
+
+Only certain hvPlot types support geographic coordinates, currently including: 'points', 'polygons', 'paths', 'image', 'quadmesh', 'contour', and 'contourf'. As an initial example, consider a dataframe of all US airports (including military bases overseas):
+
+
+```python
+airports.head(3)
+```
+
+### Plotting points
+
+If we want to overlay our data on geographic maps or reproject it into a geographic plot, we can set ``geo=True``, which declares that the data will be plotted in a geographic coordinate system.  The default coordinate system is the ``PlateCarree`` projection, i.e., raw longitudes and latitudes. If the data is in another coordinate system, you will need to [declare an explicit ``crs``](#Declaring-a-CRS) as an argument, in which case `geo=True` is assumed.  Once hvPlot knows that your data is in geo coordinates, you can use the ``tiles`` option to overlay a the plot on top of map tiles.
+
+
+```python
+airports.hvplot.points('Longitude', 'Latitude', geo=True, color='red', alpha=0.2,
+                       xlim=(-180, -30), ylim=(0, 72), tiles='ESRI')
+```
+
+### Declaring a CRS
+
+To declare a geographic plot we have to supply a ``cartopy.crs.CRS`` (or coordinate reference system).  Coordinate reference systems are described in the [GeoViews documentation](https://geoviews.org/user_guide/Projections.html) and the full list of available CRSs is in the [cartopy documentation](https://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html). 
+
+### Geopandas
+
+Since a GeoPandas ``DataFrame`` is just a Pandas DataFrames with additional geographic information, it inherits the ``.hvplot`` method. We can thus easily load shapefiles and plot them on a map:
+
+
+```python
+import geopandas as gpd
+
+cities = gpd.read_file(gpd.datasets.get_path('naturalearth_cities'))
+
+cities.hvplot(global_extent=True, frame_height=450, tiles=True)
+```
+
+The GeoPandas support allows plotting ``GeoDataFrames`` containing ``'Point'``, ``'Polygon'``, ``'LineString'`` and ``'LineRing'`` geometries, but not ones containing a mixture of different geometry types. Calling ``.hvplot`` will automatically figure out the geometry type to plot, but it also possible to call ``.hvplot.points``, ``.hvplot.polygons``, and ``.hvplot.paths`` explicitly.
+
+To draw multiple GeoDataFrames onto the same plot, use the ``*`` operator:
+
+
+```python
+world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))
+
+world.hvplot(geo=True) * cities.hvplot(geo=True, color='orange')
+```
+
+It is possible to declare a specific column to use as color with the ``c`` keyword:
+
+
+```python
+world.hvplot(geo=True) + world.hvplot(c='continent', geo=True)
+```
+
+## Spatialpandas
+
+Spatialpandas is another powerful library for working with geometries and is optimized for rendering with datashader, making it possible to plot millions of individual geometries very quickly:
+
+
+```python
+import spatialpandas as spd
+
+spd_world = spd.GeoDataFrame(world)
+
+spd_world.hvplot(datashade=True, project=True, aggregator='count_cat', c='continent', color_key='Category10')
+```
+
+### Declaring an output projection
+
+The ``crs=`` argument specifies the *input* projection, i.e. it declares how to interpret the incoming data values. You can independently choose any *output* projection, i.e. how you want to map the data points onto the screen for display, using the ``projection=`` argument. After loading the same temperature dataset explored in the [Gridded Data](Gridded_Data.ipynb) section, the data can be displayed on an Orthographic projection:
+
+
+```python
+air_ds = xr.tutorial.open_dataset('air_temperature').load()
+
+air_ds.hvplot.quadmesh(
+    'lon', 'lat', 'air', projection=ccrs.Orthographic(-90, 30),
+    global_extent=True, frame_height=540, cmap='viridis',
+    coastline=True
+)
+```
+
+If you don't need to pass any keyword arguments to a given projection and you don't have cartopy.crs (ccrs) imported, you can use the string representation: e.g. ``'LambertConformal'`` instead of ``ccrs.LambertConformal()``. Note that it is case sensitive!
+
+
+```python
+air_ds.hvplot.quadmesh(
+    'lon', 'lat', 'air', projection='LambertConformal',
+)
+```
+
+Note that when displaying raster data in a projection other than the one in which the data is stored, it is more accurate to render it as a ``quadmesh`` rather than an ``image``. As you can see above, a QuadMesh will project each original bin or pixel into the correct non-rectangular shape determined by the projection, accurately showing the geographic extent covered by each sample. An Image, on the other hand, will always be rectangularly aligned in the 2D plane, which requires warping and resampling the data in a way that allows efficient display but loses accuracy at the pixel level. Unfortunately, rendering a large QuadMesh using Bokeh can be very slow, but there are two useful alternatives for datasets too large to be practical as native QuadMeshes.
+
+The first is using the ``rasterize`` or ``datashade`` options to regrid the data before rendering it, i.e., rendering the data on the backend and then sending a more efficient image-based representation to the browser. One thing to note when using these operations is that it may be necessary to project the data **before** rasterizing it, e.g. to address wrapping issues. To do this provide ``project=True``, which will project the data before it is rasterized (this also works for other types and even when not using these operations). Another reason why this is important when rasterizing the data is that if the CRS of the data does not match the displayed projection, all the data will be projected every time you zoom or pan, which can be very slow. Deciding whether to ``project`` is therefore a tradeoff between projecting the raw data ahead of time or accepting the overhead on dynamic zoom and pan actions.
+
+
+```python
+rasm = xr.tutorial.open_dataset('rasm').load()
+
+
+
+rasm.hvplot.quadmesh(
+    'xc', 'yc', crs=ccrs.PlateCarree(), projection=ccrs.PlateCarree(),
+    ylim=(0, 90), cmap='viridis', project=True, geo=True,
+    rasterize=True, coastline=True, frame_width=800, dynamic=False,
+)
+```
+
+Another option that's still relatively slow for larger data but avoids sending large data into your browser is to plot the data using ``contour`` and ``contourf`` visualizations, generating a line or filled contour with a discrete number of levels:
+
+
+```python
+rasm.hvplot.contourf(
+    'xc', 'yc', crs=ccrs.PlateCarree(), projection=ccrs.PlateCarree(),
+    ylim=(0, 90), frame_width=800, cmap='viridis', levels=10,
+    coastline=True
+)
+```
+
+As you can see, hvPlot makes it simple to work with geographic data visually.  For more complex plot types and additional details, see the [GeoViews](https://geoviews.org) documentation.
+
+## Geographic options
+
+The API provides various geo-specific options:
+
+- ``coastline`` (default=False): Whether to display a coastline on top of the plot, setting ``coastline='10m'/'50m'/'110m'`` specifies a specific scale
+- ``crs`` (default=None): Coordinate reference system of the data specified as Cartopy CRS object, proj.4 string or EPSG code
+- ``features`` features (default=None): A list of features or a dictionary of features and the scale at which to render it. Available features include 'borders', 'coastline', 'lakes', 'land', 'ocean', 'rivers' and 'states'. Available scales include '10m'/'50m'/'110m'.
+- ``geo`` (default=False): Whether the plot should be treated as geographic (and assume PlateCarree, i.e. lat/lon coordinates)
+- ``global_extent`` (default=False): Whether to expand the plot extent to span the whole globe
+- ``project`` (default=False): Whether to project the data before plotting (adds initial overhead but avoids projecting data when plot is dynamically updated)
+- ``tiles`` (default=False): Whether to overlay the plot on a tile source. Tiles sources can be selected by name, the default is 'Wikipedia'.
+Other options are: 'CartoDark', 'CartoEco', 'CartoLight', 'CartoMidnight', 'EsriImagery', 'EsriNatGeo', 'EsriReference''EsriTerrain', 'EsriUSATopo', 'OSM', 'StamenLabels', 'StamenTerrain', 'StamenTerrainRetina', 'StamenToner', 'StamenTonerBackground', 'StamenWatercolor'. Stamen tile sources require a Stadia account when not running locally; see [stadiamaps.com](https://stadiamaps.com/).

hvplot_docs/Geometry_Data.md

@@ -0,0 +1,134 @@
+In addition to the two main types of data, namely tabular/columnar and gridded data HoloViews also provide extensible interfaces to represent path geometry data. Specifically it has three main element types used to representing different types of geometries. In this section we will cover the HoloViews data model for representing different kinds of geometries.
+
+There are many different ways of representing path geometries but HoloViews' data model is oriented on GEOS geometry definitions and allows faithfully round-tripping data between its element types and GEOS geometry definitions such as ``LinearString``, ``Polygon``, ``MultiLineString`` and ``MultiPolygon`` geometries (even if this is not implemented in HoloViews itself). HoloViews defines a dictionary based format for the geometries but also supports [spatialpandas](https://github.com/holoviz/spatialpandas), which is a highly optimized implementation similar to [geopandas](https://github.com/geopandas/geopandas/) but without the heavy geo-dependencies such as shapely and fiona. [GeoViews](https://geoviews.org/user_guide/Geometries.html) supports both geopandas and raw shapely geometries directly.
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh')
+```
+
+## Representing paths
+
+The ``Path`` element represents a collection of path geometries with optional associated values. Each path geometry may be split into sub-geometries on NaN-values and may be associated with scalar values or array values varying along its length. In analogy to GEOS geometry types a Path is a collection of LineString and MultiLineString geometries with associated values.
+
+While other formats can be supported through extensible interfaces (e.g. geopandas and shapely objects in GeoViews), natively HoloViews provides support for representing paths as one or more columnar data-structures including arrays, dataframes and dictionaries of column arrays and scalars. A simple path geometry may therefore be drawn using:
+
+
+```python
+hv.Path({'x': [1, 2, 3, 4, 5], 'y': [0, 0, 1, 1, 2]}, ['x', 'y'])
+```
+
+Here the dictionary of x- and y-coordinates could also be an NumPy array with two columns or a dataframe with 'x' and 'y' columns.
+
+To draw multiple paths the data-structures can be wrapped in a list. Additionally, it is also possible to associate a value with each path by declaring it as a value dimension:
+
+
+```python
+p = hv.Path([{'x': [1, 2, 3, 4, 5], 'y': [0, 0, 1, 1, 2], 'value': 0},
+             {'x': [5, 4, 3, 2, 1], 'y': [2, 2, 1, 1, 0], 'value': 1}], vdims='value').opts(color='value')
+p
+```
+
+#### Multi-geometry
+
+Splitting the geometries in this way allows assigning separate values to each geometry, however often multiple geometries share the same value in which case it may be desirable to represent them as a multi-geometry by combining the coordinates and separating them by a NaN value:
+
+
+```python
+hv.Path([{'x': [1, 2, 3, 4, 5, np.nan, 5, 4, 3, 2, 1],
+          'y': [0, 0, 1, 1, 2, np.nan, 2, 2, 1, 1, 0], 'value': 0}],
+        vdims='value').opts(color='value')
+```
+
+This represents a more efficient format particularly when there are very many small geometries with the same value.
+
+#### Scalar vs. continuously varying value dimensions
+
+Unlike ``Contours`` which are limited to representing iso-contours or isoclines, i.e. a function of two variables which describes a curve along which the function has a constant value, a ``Path`` element may also have continuously varying values along its path. Below we will declare a path with a value that varies along its path:
+
+
+```python
+a, b, delta = 3, 5, np.pi/2.
+
+vs = np.linspace(0, np.pi*2, 200)
+xs = np.sin(a * vs + delta)
+ys = np.sin(b * vs)
+
+hv.Path([{'x': xs, 'y': ys, 'value': vs}], vdims='value').opts(
+    color='value', cmap='hsv')
+```
+
+Note that since not all data formats allow storing scalar values as actual scalars, 1D-arrays matching the length of the coordinates but with only one unique value are also considered scalar. For example the following is a valid ``Contours`` element despite the fact that the value dimension is not a scalar variable:
+
+
+```python
+hv.Contours([{'x': xs, 'y': ys, 'value': np.ones(200)}], vdims='value').opts(color='value')
+```
+
+## Representing Polygons
+
+The ``Polygons`` element represents a collection of polygon geometries with associated scalar values. Each polygon geometry may be split into sub-geometries on NaN-values and may be associated with scalar values. In analogy to GEOS geometry types a ``Polygons`` element is a collection of Polygon and MultiPolygon geometries. Polygon geometries are defined as a set of coordinates describing the exterior bounding ring and any number of interior holes.
+
+In summary ``Polygons`` can be represented in much the same way as ``Paths`` above but have a special reserved key to store the polygon interiors or 'holes'. The holes are stored as a list-of-lists of arrays. This nested format is necessary to unambiguously associate holes with the sub-geometries in a multi-geometry. In the simplest case of a single Polygon geometry the format looks like this:
+
+
+```python
+xs = [1, 2, 3]
+ys = [2, 0, 7]
+holes = [[[(1.5, 2), (2, 3), (1.6, 1.6)], [(2.1, 4.5), (2.5, 5), (2.3, 3.5)]]]
+
+hv.Polygons([{'x': xs, 'y': ys, 'holes': holes}])
+```
+
+The 'x' and 'y' coordinates represent the exterior of the Polygon and the list-of-list of holes defines two interior regions inside the polygon.
+
+In a multi-Polygon arrangement where two Polygon geometries are separated by NaNs, the purpose of the nested format becomes a bit clearer. Here the polygon from above still has the two holes but the second polygon does not have any holes, which we declare with an empty list:
+
+
+```python
+xs = [1, 2, 3, np.nan, 6, 7, 3]
+ys = [2, 0, 7, np.nan, 7, 5, 2]
+
+holes = [
+    [[(1.5, 2), (2, 3), (1.6, 1.6)], [(2.1, 4.5), (2.5, 5), (2.3, 3.5)]],
+    []
+]
+
+hv.Polygons([{'x': xs, 'y': ys, 'holes': holes}])
+```
+
+If a polygon has no holes at all the 'holes' key may be omitted entirely:
+
+
+```python
+hv.Polygons([{'x': xs, 'y': ys, 'holes': holes, 'value': 0},
+             {'x': [4, 6, 6], 'y': [0, 2, 1], 'value': 1},
+             {'x': [-3, -1, -6], 'y': [3, 2, 1], 'value': 3}], vdims='value')
+```
+
+## Accessing the data
+
+To access the underlying data the geometry elements (``Path``/``Contours``/``Polygons``) implement a ``split`` method. By default it simply returns a list of elements, where each contains only one geometry:
+
+
+```python
+poly = hv.Polygons([
+    {'x': xs, 'y': ys, 'holes': holes, 'value': 0},
+    {'x': [4, 6, 6], 'y': [0, 2, 1], 'value': 1}
+], vdims='value')
+
+hv.Layout(poly.split())
+```
+
+Using the ``datatype`` argument the data may instead be returned in the desired format, e.g. 'dictionary', 'array' or 'dataframe'. Here we return the 'dictionary' format:
+
+
+```python
+poly.split(datatype='dictionary')
+```
+
+Note that this conversion may be lossy if the converted format has no way of representing 'holes' or other data.

hvplot_docs/Gridded_Data.md

@@ -0,0 +1,129 @@
+hvPlot provides one API to explore data of many different types. Previous sections have exclusively worked with tabular data stored in pandas (or pandas-like) DataFrames. The other most common type of data are n-dimensional arrays. hvPlot aims to eventually support different array libraries but for now focuses on [xarray](https://xarray.pydata.org/en/stable/). XArray provides a convenient and very powerful wrapper to label the axis and coordinates of multi-dimensional (n-D) arrays. This user guide will cover how to leverage ``xarray`` and ``hvplot`` to visualize and explore data of different dimensionality ranging from simple 1D data, to 2D image-like data, to multi-dimensional cubes of data.
+
+For these examples we’ll use the North American air temperature dataset:
+
+
+```python
+import xarray as xr
+import hvplot.xarray  # noqa
+
+air_ds = xr.tutorial.open_dataset('air_temperature').load()
+air = air_ds.air
+air_ds
+```
+
+## 1D Plots
+
+Selecting the data at a particular lat/lon coordinate we get a 1D dataset of air temperatures over time:
+
+
+```python
+air1d = air.sel(lat=40, lon=285)
+air1d.hvplot()
+```
+
+Notice how the axes are already appropriately labeled, because xarray stores the metadata required. We can also further subselect the data and use `*` to overlay plots:
+
+
+```python
+air1d_sel = air1d.sel(time='2013-01')
+air1d_sel.hvplot(color='purple') * air1d_sel.hvplot.scatter(marker='o', color='blue', size=15)
+```
+
+
+```python
+air.lat
+```
+
+### Selecting multiple
+
+If we select multiple coordinates along one axis and plot a chart type, the data will automatically be split by the coordinate:
+
+
+```python
+air.sel(lat=[20, 40, 60], lon=285).hvplot.line()
+```
+
+To plot a different relationship we can explicitly request to display the latitude along the y-axis and use the ``by`` keyword to color each longitude (or 'lon') differently (note that this differs from the ``hue`` keyword xarray uses):
+
+
+```python
+air.sel(time='2013-02-01 00:00', lon=[280, 285]).hvplot.line(y='lat', by='lon', legend='top_right')
+```
+
+## 2D Plots
+
+By default the ``DataArray.hvplot()`` method generates an image if the data is two-dimensional.
+
+
+```python
+air2d = air.sel(time='2013-06-01 12:00')
+air2d.hvplot(width=400)
+```
+
+Alternatively we can also plot the same data using the ``contour`` and ``contourf`` methods, which provide a ``levels`` argument to control the number of iso-contours to draw:
+
+
+```python
+air2d.hvplot.contour(width=400, levels=20) + air2d.hvplot.contourf(width=400, levels=8)
+```
+
+## n-D Plots
+
+If the data has more than two dimensions it will default to a histogram without providing it further hints:
+
+
+```python
+air.hvplot()
+```
+
+However we can tell it to apply a ``groupby`` along a particular dimension, allowing us to explore the data as images along that dimension with a slider:
+
+
+```python
+air.hvplot(groupby='time', width=500)
+```
+
+By default, for numeric types you'll get a slider and for non-numeric types you'll get a selector. Use ``widget_type`` and ``widget_location`` to control the look of the widget. To learn more about customizing widget behavior see [Widgets](Widgets.ipynb).
+
+
+```python
+air.hvplot(groupby='time', width=600, widget_type='scrubber', widget_location='bottom')
+```
+
+If we pick a different, lower dimensional plot type (such as a 'line') it will automatically apply a groupby over the remaining dimensions:
+
+
+```python
+air.hvplot.line(width=600)
+```
+
+## Statistical plots
+
+Statistical plots such as histograms, kernel-density estimates, or violin and box-whisker plots aggregate the data across one or more of the coordinate dimensions. For instance, plotting a KDE provides a summary of all the air temperature values but we can, once again, use the ``by`` keyword to view each selected latitude (or 'lat') separately:
+
+
+```python
+air.sel(lat=[25, 50, 75]).hvplot.kde('air', by='lat', alpha=0.5)
+```
+
+Using the ``by`` keyword we can break down the distribution of the air temperature across one or more variables:
+
+
+```python
+air.hvplot.violin('air', by='lat', color='lat', cmap='Category20')
+```
+
+## Rasterizing
+
+If you are plotting a large amount of data at once, you can consider using the hvPlot interface to [Datashader](https://datashader.org), which can be enabled simply by setting `rasterize=True`.
+
+Note that by declaring that the data should not be grouped by another coordinate variable, i.e. by setting `groupby=[]`, we can plot all the datapoints, showing us the spread of air temperatures in the dataset:
+
+
+```python
+air.hvplot.scatter('time', groupby=[], rasterize=True) *\
+air.mean(['lat', 'lon']).hvplot.line('time', color='indianred')
+```
+
+Here we also overlaid a non-datashaded line plot of the average temperature at each time.  If you enable the appropriate hover tool, the overlaid data supports hovering and zooming even in a static export such as on a web server or in an email, while the raw-data plot has been aggregated spatially before it is sent to the browser, and thus it has only the fixed spatial binning available at that time.  If you have a live Python process, the raw data will be aggregated each time you pan or zoom, letting you see the entire dataset regardless of size.

hvplot_docs/Installing_and_Configuring.md

@@ -0,0 +1,107 @@
+# Installing and Configuring Holoviews
+
+HoloViews can be installed on any platform where [NumPy](http://numpy.org) and Python 3 are available.
+
+That said, HoloViews is designed to work closely with many other libraries, which can make installation and configuration more complicated.  This user guide page describes some of these less-common or not-required options that may be helpful for some users.
+
+## Other installation options
+
+The main [installation instructions](http://holoviews.org/#installation) should be sufficient for most users, but you may also want the [Matplotlib](http://matplotlib.org) and [Plotly](https://plot.ly/python/) backends, which are required for some of the examples:
+
+    conda install matplotlib plotly
+
+HoloViews can also be installed using one of these `pip` commands:
+
+    pip install holoviews
+    pip install 'holoviews[recommended]'
+    pip install 'holoviews[extras]'
+    pip install 'holoviews[all]'
+
+The first option installs just the bare library and the [NumPy](http://numpy.org) and [Param](https://github.com/holoviz/param) libraries, which is all you need on your system to generate and work with HoloViews objects without visualizing them. The other options install additional libraries that are often useful, with the `recommended` option being similar to the `conda` install command above.
+
+Between releases, development snapshots are made available as conda packages:
+
+    conda install -c pyviz/label/dev holoviews
+
+To get the very latest development version you can clone our git
+repository and put it on the Python path:
+
+    git clone https://github.com/holoviz/holoviews.git
+    cd holoviews
+    pip install -e .
+
+## JupyterLab configuration
+
+To work with JupyterLab you will also need the HoloViews JupyterLab
+extension:
+
+```
+conda install -c conda-forge jupyterlab
+jupyter labextension install @pyviz/jupyterlab_pyviz
+```
+
+Once you have installed JupyterLab and the extension launch it with:
+
+```
+jupyter-lab
+```
+
+## ``hv.config`` settings
+
+The default HoloViews installation will use the latest defaults and options available, which is appropriate for new users.  If you want to work with code written for older HoloViews versions, you can use the top-level ``hv.config`` object to control various backwards-compatibility options:
+
+* ``future_deprecations``: Enables warnings about future deprecations (introduced in 1.11).
+* ``warn_options_call``: Warn when using the to-be-deprecated ``__call__`` syntax for specifying options, instead of the recommended ``.opts`` method.
+
+It is recommended you set ``warn_options_call`` to ``True`` in your holoviews.rc file (see section below).
+
+It is possible to set the configuration using `hv.config` directly:
+
+
+```python
+import holoviews as hv
+hv.config(future_deprecations=True)
+```
+
+However, because in some cases this configuration needs to be declared before the plotting extensions are imported, the recommended way of setting configuration options is:
+
+
+```python
+hv.extension('bokeh', config=dict(future_deprecations=True))
+```
+
+In addition to backwards-compatibility options, ``hv.config`` holds some global options:
+
+* ``image_rtol``: The tolerance used to enforce regular sampling for regular, gridded data. Used to validate ``Image`` data.
+
+This option allows you to set the ``rtol`` parameter of [``Image``](../reference/elements/bokeh/Image.ipynb) elements globally.
+
+
+## Improved tab-completion
+
+Both ``Layout`` and ``Overlay`` are designed around convenient tab-completion, with the expectation of upper-case names being listed first. In recent versions of Jupyter/IPython there has been a regression whereby the tab-completion is no longer case-sensitive. This can be fixed with:
+
+
+```python
+import holoviews as hv
+hv.extension(case_sensitive_completion=True)
+```
+
+## The holoviews.rc file
+
+HoloViews searches for the first rc file it finds in the following places (in order): 
+
+1. ``holoviews.rc`` in the parent directory of the top-level ``__init__.py`` file (useful for developers working out of the HoloViews git repo)
+2. ``~/.holoviews.rc``
+3. ``~/.config/holoviews/holoviews.rc``
+
+The rc file location can be overridden via the ``HOLOVIEWSRC`` environment variable.
+
+The rc file is a Python script, executed as HoloViews is imported. An example rc file to include various options discussed above might look like this:
+
+```
+import holoviews as hv
+hv.config(warn_options_call=True)
+hv.extension.case_sensitive_completion=True
+```
+

hvplot_docs/Integrations.md

@@ -0,0 +1,251 @@
+```python
+import numpy as np
+
+np.random.seed(1)
+```
+
+## Data sources
+
+The `.hvplot()` plotting API supports a wide range of data sources. Most frequently, a special import can be executed to register the `.hvplot` accessor on a data type. For instance, importing `hvplot.pandas` registers the `.hvplot` accessor on Pandas `DataFrame` and `Series` objects, allowing to call `df.hvplot.line()`.
+
+Among the data sources introduced below, Pandas](https://pandas.pydata.org) is the only library that doesn't need to be installed separately as it is a direct dependency of hvPlot.
+
+:::{note}
+Supporting so many data sources is hard work! We are aware that the support for some of them isn't as good as we would like. If you encounter any issue please report it <a href='https://github.com/holoviz/hvplot/'>on GitHub</a>, we always welcome Pull Requests too!
+:::
+
+### Columnar/tabular
+
+#### Pandas
+
+`.hvplot()` supports [Pandas](https://pandas.pydata.org) `DataFrame` and `Series` objects.
+
+
+```python
+import hvplot.pandas  # noqa
+import pandas as pd
+
+df_pandas = pd.DataFrame(np.random.randn(1000, 4), columns=list('ABCD')).cumsum()
+df_pandas.head(2)
+```
+
+
+```python
+# Pandas DataFrame
+df_pandas.hvplot.line(height=150)
+```
+
+
+```python
+# Pandas Series
+s_pandas = df_pandas['A']
+s_pandas.hvplot.line(height=150)
+```
+
+#### [Dask](https://www.dask.org)
+
+`.hvplot()` supports [Dask](https://www.dask.org) `DataFrame` and `Series` objects.
+
+
+```python
+import hvplot.dask  # noqa
+import dask
+
+df_dask = dask.dataframe.from_pandas(df_pandas, npartitions=2)
+df_dask
+```
+
+
+```python
+# Dask DataFrame
+df_dask.hvplot.line(height=150)
+```
+
+
+```python
+# Dask Series
+s_dask = df_dask['A']
+s_dask.hvplot.line(height=150)
+```
+
+#### GeoPandas
+
+`.hvplot()` supports [GeoPandas](https://geopandas.org) `GeoDataFrame` objects.
+
+
+```python
+import hvplot.pandas  # noqa
+import geopandas as gpd
+
+p_geometry = gpd.points_from_xy(
+    x=[12.45339, 12.44177, 9.51667, 6.13000],
+    y=[41.90328, 43.93610, 47.13372, 49.61166],
+    crs='EPSG:4326'
+)
+p_names = ['Vatican City', 'San Marino', 'Vaduz', 'Luxembourg']
+gdf = gpd.GeoDataFrame(dict(name=p_names), geometry=p_geometry)
+gdf.head(2)
+```
+
+
+```python
+# GeoPandas GeoDataFrame
+gdf.hvplot.points(geo=True, tiles='CartoLight', frame_height=150, data_aspect=0.5)
+```
+
+#### Ibis
+
+[Ibis](https://ibis-project.org/) is the "portable Python dataframe library", it provides a unified interface to many data backends (e.g. DuckDB, SQLite, SnowFlake, Google BigQuery). `.hvplot()` supports [Ibis](https://ibis-project.org/) `Expr` objects.
+
+
+```python
+import hvplot.ibis  # noqa
+import ibis
+
+table = ibis.memtable(df_pandas.reset_index())
+table
+```
+
+
+```python
+# Ibis Expr
+table.hvplot.line(x='index', height=150)
+```
+
+#### Polars
+
+:::{note}
+Added in version `0.9.0`.
+:::
+
+:::{important}
+While other data sources like `Pandas` or `Dask` have built-in support in HoloViews, as of version 1.17.1 this is not yet the case for `Polars`. You can track this [issue](https://github.com/holoviz/holoviews/issues/5939) to follow the evolution of this feature in HoloViews. Internally hvPlot simply selects the columns that contribute to the plot and casts them to a Pandas object using Polars' `.to_pandas()` method.
+:::
+
+
+```python
+import hvplot.polars  # noqa 
+import polars
+
+df_polars = polars.from_pandas(df_pandas)
+df_polars.head(2)
+```
+
+`.hvplot()` supports [Polars](https://www.pola.rs/) `DataFrame`, `LazyFrame` and `Series` objects.
+
+
+```python
+# Polars DataFrame
+df_polars.hvplot.line(y=['A', 'B', 'C', 'D'], height=150)
+```
+
+
+```python
+# Polars LazyFrame
+df_polars.lazy().hvplot.line(y=['A', 'B', 'C', 'D'], height=150)
+```
+
+
+```python
+# Polars Series
+df_polars['A'].hvplot.line(height=150)
+```
+
+#### Rapids cuDF
+
+:::{important}
+[Rapids cuDF](https://docs.rapids.ai/api/cudf) is a Python **GPU** DataFrame library. Neither hvPlot's nor HoloViews' test suites currently run on a GPU part of their CI, as of versions 0.9.0 and 1.17.1, respectively. This is due to the non availability of machines equipped with a GPU on the free CI system we rely on (Github Actions). Therefore it's possible that support for cuDF gets degraded in hvPlot without us noticing it immediately. Please report any issue you might encounter.
+:::
+
+`.hvplot()` supports [cuDF](https://docs.rapids.ai/api/cudf) `DataFrame` and `Series` objects.
+
+#### Fugue
+
+:::{admonition} Experimental
+:class: caution
+[Fugue](https://fugue-tutorials.readthedocs.io/) support, added in version `0.9.0`, is experimental and may change in future versions.
+:::
+
+hvPlot adds the `hvplot` plotting extension to FugueSQL.
+
+
+```python
+import hvplot.fugue  # noqa
+import fugue
+
+fugue.api.fugue_sql(
+    """
+    OUTPUT df_pandas USING hvplot:line(
+        height=150,
+    )
+    """
+)
+```
+
+### Multidimensional
+
+#### Xarray
+
+`.hvplot()` supports [XArray](https://xarray.pydata.org) `Dataset` and `DataArray` labelled multidimensional objects.
+
+
+```python
+import hvplot.xarray  # noqa
+import xarray as xr
+
+ds = xr.Dataset({
+    'A': (['x', 'y'], np.random.randn(100, 100)),
+    'B': (['x', 'y'], np.random.randn(100, 100))},
+    coords={'x': np.arange(100), 'y': np.arange(100)}
+)
+ds
+```
+
+
+```python
+# Xarray Dataset
+ds.hvplot.hist(height=150)
+```
+
+
+```python
+# Xarray DataArray
+ds['A'].hvplot.image(height=150)
+```
+
+### Catalog
+
+#### Intake
+
+`.hvplot()` supports [Intake](https://github.com/ContinuumIO/intake) `DataSource` objects.
+
+### Streaming
+
+#### Streamz
+
+`.hvplot()` supports [Streamz](https://streamz.readthedocs.io) `DataFrame`, `DataFrames`, `Series` and `Seriess` objects.
+
+### Graph
+
+#### NetworkX
+
+The hvPlot [NetworkX](https://networkx.github.io) plotting API is meant as a drop-in replacement for the `networkx.draw` methods. The `draw` and other `draw_<>` methods are available in the `hvplot.networkx` module.
+
+
+```python
+import hvplot.networkx as hvnx
+import networkx as nx
+
+G = nx.petersen_graph()
+hvnx.draw(G, with_labels=True, height=150)
+```
+
+## Plotting extensions
+
+hvPlot is capable of producing plots with [Bokeh](https://www.bokeh.org) (default, interactive), [Matplotlib](https://matplotlib.org) (static) and [Plotly](https://plotly.com/python/) (interactive). Under the hood, hvPlot delegates plotting to HoloViews which itself calls these plotting libraries. This is why we call hvPlot a high-level plotting library!
+
+Follow the [Plotting Extensions Guide](Plotting_Extensions.ipynb) for more information.
+
+:::{note}
+Similarly to having to support many data sources, supporting three plotting extensions is hard work! We are aware they are not supported equivalently, you will get best support for Bokeh, followed by Matplotlib and finally Plotly. If you encounter any issue with a specific plotting extension please report it <a href='https://github.com/holoviz/hvplot/'>on GitHub</a>, we always welcome Pull Requests too!
+:::