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!
+:::

hvplot_docs/Interactive.md

@@ -0,0 +1,238 @@
+```python
+import ipywidgets as ipw
+import hvplot.xarray # noqa
+import hvplot.pandas # noqa
+import panel as pn
+import pandas as pd
+import panel.widgets as pnw
+import xarray as xr
+```
+
+Interactive command-line or notebook interfaces are incredibly powerful tools for quickly doing exploratory analysis, letting you supply arguments to Python methods and functions and see the results immediately. However, this process of exploration can be slow and awkward for large parameter spaces because it requires manually typing each argument value. To further ease exploratory workflows, hvPlot ships with a convenient `.interactive` API, which mirrors the regular API of your favorite data analysis libraries like Pandas, Dask, and xarray but makes it possible to pass in _widgets_ for each argument value, not just a constant. When the widgets are used, the output will dynamically update the full pipeline of method calls so that it works just as if that particular value had been specified in the call being wrapped.
+
+In this user guide we will explore how to use the .interactive API on xarray and pandas objects:
+
+
+```python
+ds = xr.tutorial.load_dataset('air_temperature')
+ds
+```
+
+
+```python
+from bokeh.sampledata.stocks import IBM
+
+df = pd.DataFrame(IBM)
+df['date'] = pd.to_datetime(df.date)
+```
+
+## Interactive widgets
+
+We can supply both regular values, widgets and parameters as arguments to methods on the `.interactive` accessor. Here, we'll use widgets from the [Panel](https://panel.holoviz.org) library.  The repr of the resulting object will contain a layout of the widget and a view of the resulting output:
+
+
+```python
+slider = pnw.IntSlider(name='time', start=0, end=10)
+
+ds.air.interactive(width=800).isel(time=slider)
+```
+
+You can also use widgets from the [ipywidgets](https://ipywidgets.readthedocs.io) library:
+
+
+```python
+slider = ipw.IntSlider(description='time', min=0, max=10)
+
+ds.air.interactive(width=800).isel(time=slider)
+```
+
+Note that this works just as well for DataFrame objects whether they are Pandas, Dask or cuDF dataframes:
+
+
+```python
+nrows = pn.widgets.IntSlider(start=1, end=100, value=10)
+
+df.interactive(width=500).head(nrows)
+```
+
+For Panel widgets, we can let .interactive automatically configure the widget, which is particularly convenient when working with `DiscreteSlider` widgets:
+
+
+```python
+ds.air.interactive(width=800).sel(time=pnw.DiscreteSlider)
+```
+
+## Functions as inputs
+
+In some cases your starting point for your interactive pipeline may not simply be a DataFrame or xarray Dataset but a function that fetches some data or applies some initial processing on your data. In such a case you can use the `hvplot.bind` function to bind static AND dynamic arguments to your function. Binding dynamic arguments such as a widget or parameter means that whenever the widget/parameter value changes the output of the function will change as well. This makes it possible to construct functions as the input to your interactive pipeline that themselves represent some data pipeline.
+
+In the example below we will explicitly declare a `Select` widget to select between multiple stock tickers and a function that loads dataframes containing data for each of those stocks. Using the `hvplot.bind` function we then bind the `ticker` select widget to the `ticker` argument of the `stock_df` function and call `.interactive` on the resulting bound function:
+
+
+```python
+from bokeh import sampledata
+
+ticker = pn.widgets.Select(options=['AAPL', 'IBM', 'GOOG', 'MSFT'], name='Ticker')
+
+def stock_df(ticker):
+    df = pd.DataFrame(getattr(sampledata.stocks, ticker))
+    df['date'] = pd.to_datetime(df.date)
+    return df
+
+stock_dfi = hvplot.bind(stock_df, ticker).interactive(width=600)
+
+stock_dfi.head(10)
+```
+
+As you can see this `interactive` component behaves just like any other, allowing us to chain `.head` on it and updating when the `ticker` widget changes.
+
+Just like any other `interactive` component you may also chain it further:
+
+
+```python
+ticker = pn.widgets.Select(options=['AAPL', 'IBM', 'GOOG', 'MSFT'], name='Ticker')
+
+def stock_df(ticker):
+    df = pd.DataFrame(getattr(sampledata.stocks, ticker))
+    df['date'] = pd.to_datetime(df.date)
+    return df
+
+stock_dfi = hvplot.bind(stock_df, ticker).interactive()
+
+dt_range = pn.widgets.DateRangeSlider(start=df.date.iloc[-1000], end=df.date.max(), value=(df.date.iloc[-100], df.date.max()))
+
+stock_dfi[(stock_dfi.date>=dt_range.param.value_start) & (stock_dfi.date<=dt_range.param.value_end)].hvplot(kind='ohlc', grid=True, title=ticker)
+```
+
+## Docstrings
+
+When accessing a method on the `.interactive` accessor it will transparently mirror the docstring of the equivalent method in the underlying library being wrapped:
+
+
+```python
+print(ds.air.interactive.isel.__doc__)
+```
+
+## Plotting
+
+One of the most useful aspects of the .interactive API is to feed the output of chained method calls into a plot.
+
+### Matplotlib
+
+The output can be almost anything, such as the HTML repr (above) or a matplotlib plot:
+
+
+```python
+ds.air.interactive.sel(time=pnw.DiscreteSlider).plot()
+```
+
+If we like, we can animate the output with a `Player` widget, and customize the location of the widget using the `loc` keyword argument to `.interactive`:
+
+
+```python
+time = pnw.Player(name='time', start=0, end=10, loop_policy='loop', interval=100)
+
+ds.air.interactive(loc='bottom').isel(time=time).plot()
+```
+
+### hvPlot
+
+We can also make use of the `.hvplot` method to get fully interactive Bokeh-based plots:
+
+
+```python
+slider = pnw.FloatSlider(name='quantile', start=0, end=1)
+
+ds.air.interactive.quantile(slider, dim='time').hvplot(data_aspect=1)
+```
+
+You can chain any number of methods, with as many widgets controlling steps in this pipeline as you wish:
+
+
+```python
+q = pnw.FloatSlider(name='quantile', start=0, end=1)
+
+(ds.air.interactive(loc='left')
+ .sel(time=pnw.DiscreteSlider)
+ .quantile(q=q, dim='lon')
+ .hvplot(aspect=1))
+```
+
+We can also use a `RangeSlider` to select a slice and compute the mean over that range instead of selecting a specific time:
+
+
+```python
+range_slider = pnw.IntRangeSlider
+
+(ds.air.interactive
+ .isel(time=range_slider)
+ .mean('time')
+ .hvplot())
+```
+
+`.interactive` supports arbitrary chains of method calls, including anything that is supported by your data object. For instance, you can even convert your xarray object into a dataframe using `.to_dataframe`, then call pandas methods:
+
+
+```python
+ds.air.interactive.sel(lat=pnw.DiscreteSlider).to_dataframe().groupby('time').mean().hvplot('time', 'air')
+```
+
+## Operators
+
+You can further transform your output, if desired, by applying math operators on the interactive object:
+
+
+```python
+slider = pnw.IntSlider(name='time', start=0, end=10)
+baseline = ds.air.mean().item()
+baseline
+```
+
+
+```python
+ds.air.interactive(width=800).isel(time=slider).mean().item() - baseline
+```
+
+You can even do math with a widget:
+
+
+```python
+slider = pnw.IntSlider(name='time',   start=0, end=10)
+offset = pnw.IntSlider(name='offset', start=0, end=500)
+
+ds.air.interactive.isel(time=slider).mean().item() + offset
+```
+
+Math operators work with array data as well, such as the time-averaged value of each array value:
+
+
+```python
+diff = ds.air.interactive.sel(time=pnw.DiscreteSlider) - ds.air.mean('time')
+kind = pnw.Select(options=['contour', 'contourf', 'image'])
+
+diff.hvplot(cmap='RdBu_r', clim=(-20, 20), kind=kind)
+```
+
+If you want more control over the layout, you can use any of the features from [Panel](https://panel.holoviz.org). In this case, `interactive.panel()` (or `interactive.output()`) make sure you display the interactive plot only, with the widgets explicitly declared by `interactive.widgets()`:
+
+
+```python
+diff = ds.air.interactive.sel(time=pnw.DiscreteSlider) - ds.air.mean('time')
+kind = pnw.Select(options=['contourf', 'contour', 'image'], value='image')
+interactive = diff.hvplot(cmap='RdBu_r', clim=(-20, 20), kind=kind)
+
+pn.Column(
+    pn.Row(
+        pn.panel("https://hvplot.holoviz.org/assets/hvplot-wm.png", width=100), 
+        pn.Spacer(width=20),
+        pn.Column(
+            pn.panel("## Select a time and type of plot", width=400),
+            interactive.widgets()
+        ),
+        pn.panel("https://panel.holoviz.org/_static/logo_stacked.png", width=100)
+    ),
+    interactive.panel()
+).servable()
+```
+
+As you can see, the `.interactive` functionality makes it simple to work interactively with your data, letting you use widgets about as easily as any other method argument! See the Panel or ipwidgets docs for the various widgets and other functionality available.

hvplot_docs/Introduction.md

@@ -0,0 +1,115 @@
+The PyData ecosystem has a number of core Python data containers that allow users to work with a wide array of datatypes, including:
+
+* [Pandas](https://pandas.pydata.org): DataFrame, Series (columnar/tabular data)
+* [Rapids cuDF](https://docs.rapids.ai/api/cudf/stable/): GPU DataFrame, Series (columnar/tabular data)
+* [Polars](https://www.pola.rs/): Polars is a fast DataFrame library/in-memory query engine (columnar/tabular data)
+* [Dask](https://www.dask.org): DataFrame, Series (distributed/out of core arrays and columnar data)
+* [XArray](https://xarray.pydata.org): Dataset, DataArray (labelled multidimensional arrays)
+* [Streamz](https://streamz.readthedocs.io): DataFrame(s), Series(s) (streaming columnar data)
+* [Intake](https://github.com/ContinuumIO/intake): DataSource (data catalogues)
+* [GeoPandas](https://geopandas.org): GeoDataFrame (geometry data)
+* [NetworkX](https://networkx.github.io/documentation/stable/): Graph (network graphs)
+
+Many of these libraries have the concept of a high-level plotting API that lets a user generate common plot types very easily. The native plotting APIs are generally built on [Matplotlib](https://matplotlib.org), which provides a solid foundation, but means that users miss out the benefits of modern, interactive plotting libraries for the web like [Bokeh](https://bokeh.pydata.org) and [HoloViews](https://holoviews.org).
+
+**hvPlot** provides a high-level plotting API built on HoloViews that provides a general and consistent API for plotting data in all the formats mentioned above.
+
+As a first simple illustration of using hvPlot, let's create a small set of random data in Pandas to explore:
+
+
+```python
+import numpy as np
+import pandas as pd
+
+index = pd.date_range('1/1/2000', periods=1000)
+df = pd.DataFrame(np.random.randn(1000, 4), index=index, columns=list('ABCD')).cumsum()
+
+df.head()
+```
+
+## Pandas default .plot()
+
+Pandas provides Matplotlib-based plotting by default, using the  `.plot()` method:
+
+
+```python
+%matplotlib inline
+
+df.plot();
+```
+
+The result is a PNG image that displays easily, but is otherwise static. 
+
+## Switching Pandas backend
+
+To allow using hvPlot directly with Pandas we have to import `hvplot.pandas` and swap the Pandas backend with:
+
+
+```python
+import hvplot.pandas  # noqa
+
+pd.options.plotting.backend = 'holoviews'
+```
+
+**NOTE:** This requires a recent version of pandas (later than 0.25.0), see the [Pandas API](Pandas_API.ipynb) for more details.
+
+
+```python
+df.plot()
+```
+
+## .hvplot()
+
+If we instead change `%matplotlib inline` to `import hvplot.pandas` and use the ``df.hvplot`` method, it will now display an interactively explorable [Bokeh](https://bokeh.pydata.org) plot with panning, zooming, hovering, and clickable/selectable legends:
+
+
+```python
+df.hvplot()
+```
+
+This interactive plot makes it much easier to explore the properties of the data, without having to write code to select ranges, columns, or data values manually. Note that while pandas, dask and xarray all use the `.hvplot` method, `intake` uses hvPlot as its main plotting API, which means that is available using `.plot()`.
+
+## hvPlot native API
+
+For the plot above, hvPlot dynamically added the Pandas `.hvplot()` method, so that you can use the same syntax as with the Pandas default plotting.  If you prefer to be more explicit, you can instead work directly with hvPlot objects:
+
+
+```python
+from hvplot import hvPlot
+hvplot.extension('bokeh')
+
+plot = hvPlot(df)
+plot(y=['A', 'B', 'C', 'D'])
+```
+
+## Switching the plotting extension to Matplotlib or Plotly
+
+While the default plotting extension of hvPlot is [Bokeh](https://bokeh.pydata.org), it is possible to load either Matplotlib or Plotly with `.extension()` and later switch from a plotting library to another with `.output()`. More information about working with multiple plotting backends can be found in the [plotting extensions guide](Plotting_Extensions.ipynb).
+
+
+```python
+hvplot.extension('matplotlib')
+
+df.hvplot(rot=30)
+```
+
+## Getting help
+
+When working inside IPython or the Jupyter notebook hvplot methods will automatically complete valid keywords, e.g. pressing tab after declaring the plot type will provide all valid keywords and the docstring:
+
+```python
+df.hvplot.line(<TAB>
+```
+
+Outside an interactive environment ``hvplot.help`` will bring up information providing the ``kind`` of plot, e.g.:
+
+```python
+hvplot.help('line')
+```
+
+For more detail on the available options see the [Customization](Customization.ipynb) user guide.
+
+
+## Next steps
+
+Now that you can see how hvPlot is used, let's jump straight in and discover some of the more powerful things we can do with it in the [Plotting](Plotting.ipynb) section.

hvplot_docs/Linking_Plots.md

@@ -0,0 +1,159 @@
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+
+hv.extension('bokeh')
+```
+
+When working with the bokeh backend in HoloViews complex interactivity can be achieved using very little code, whether that is shared axes, which zoom and pan together or shared datasources, which allow for linked cross-filtering. Separately it is possible to create custom interactions by attaching LinkedStreams to a plot and thereby triggering events on interactions with the plot. The Streams based interactivity affords a lot of flexibility to declare custom interactivity on a plot, however it always requires a live Python kernel to be connected either via the notebook or bokeh server. The ``Link`` classes described in this user guide however allow declaring interactions which do not require a live server, opening up the possibility of declaring complex interactions in a plot that can be exported to a static HTML file.
+
+## What is a ``Link``?
+
+A ``Link`` defines some connection between a source and target object in their visualization. It is quite similar to a ``Stream`` as it allows defining callbacks in response to some change or event on the source object, however, unlike a Stream, it does not transfer data between the browser and a Python process. Instead a ``Link`` directly causes some action to occur on the ``target``, for JS based backends this usually means that a corresponding JS callback will effect some change on the target in response to a change on the source.
+
+One of the simplest examples of a ``Link`` is the ``DataLink`` which links the data from two sources as long as they match in length, e.g. below we create two elements with data of the same length. By declaring a ``DataLink`` between the two we can ensure they are linked and can be selected together:
+
+
+```python
+from holoviews.plotting.links import DataLink
+
+scatter1 = hv.Scatter(np.arange(100))
+scatter2 = hv.Scatter(np.arange(100)[::-1], 'x2', 'y2')
+
+dlink = DataLink(scatter1, scatter2)
+
+(scatter1 + scatter2).opts(
+    opts.Scatter(tools=['box_select', 'lasso_select']))
+```
+
+If we want to display the elements subsequently without linking them we can call the ``unlink`` method:
+
+
+```python
+dlink.unlink()
+
+(scatter1 + scatter2)
+```
+
+Another example of a link is the ``RangeToolLink`` which adds a RangeTool to the ``source`` plot which is linked to the axis range on the ``target`` plot. In this way the source plot can be used as an overview of the full data while the target plot provides a more detailed view of a subset of the data:
+
+
+```python
+from holoviews.plotting.links import RangeToolLink
+
+data = np.random.randn(1000).cumsum()
+
+source = hv.Curve(data).opts(width=800, height=125, axiswise=True, default_tools=[])
+target = hv.Curve(data).opts(width=800, labelled=['y'], toolbar=None)
+
+rtlink = RangeToolLink(source, target)
+
+(target + source).opts(merge_tools=False).cols(1)
+```
+
+## Advanced: Writing a ``Link``
+
+A ``Link`` consists of two components the ``Link`` itself and a ``LinkCallback`` which provides the actual implementation behind the ``Link``. In order to demonstrate writing a ``Link`` we'll start with a fairly straightforward example, linking an ``HLine`` or ``VLine`` to the mean value of a selection on a ``Scatter`` element. To express this we declare a ``MeanLineLink`` class subclassing from the ``Link`` baseclass and declare ``ClassSelector`` parameters for the ``source`` and ``target`` with the appropriate types to perform some basic validation. Additionally we declare a ``column`` parameter to specify which column to compute the mean on.
+
+
+```python
+import param
+from holoviews.plotting.links import Link
+
+class MeanLineLink(Link):
+    
+    column = param.String(default='x', doc="""
+        The column to compute the mean on.""")
+    
+    _requires_target = True
+```
+
+Now we have the ``Link`` class we need to write the implementation in the form of a ``LinkCallback``, which in the case of bokeh will be translated into a [``CustomJS`` callback](https://bokeh.pydata.org/en/latest/docs/user_guide/interaction/callbacks.html#userguide-interaction-jscallbacks). A ``LinkCallback`` should declare the ``source_model`` we want to listen to events on and a ``target_model``, declaring which model should be altered in response. To find out which models we can attach the ``Link`` to we can create a ``Plot`` instance and look at the ``plot.handles``, e.g. here we create a ``ScatterPlot`` and can see it has a 'cds', which represents the ``ColumnDataSource``.
+
+
+```python
+renderer = hv.renderer('bokeh')
+
+plot = renderer.get_plot(hv.Scatter([]))
+
+plot.handles.keys()
+```
+
+In this case we are interested in the 'cds' handle, but we still have to tell it which events should trigger the callback. Bokeh callbacks can be grouped into two types, model property changes and events. For more detail on these two types of callbacks see the [Bokeh user guide](https://bokeh.pydata.org/en/latest/docs/user_guide/interaction/callbacks.html#userguide-interaction-jscallbacks).
+
+For this example we want to respond to changes to the ``ColumnDataSource.selected`` property. We can declare this in the ``on_source_changes`` class attribute on our callback. So now that we have declared which model we want to listen to events on and which events we want to listen to, we have to declare the model on the target we want to change in response. 
+
+We can once again look at the handles on the plot corresponding to the ``HLine`` element:
+
+
+```python
+plot = renderer.get_plot(hv.HLine(0))
+plot.handles.keys()
+```
+
+We now want to change the ``glyph``, which defines the position of the ``HLine``, so we declare the ``target_model`` as ``'glyph'``. Having defined both the source and target model and the events we can finally start writing the JS callback that should be triggered. To declare it we simply define the ``source_code`` class attribute. To understand how to write this code we need to understand how the source and target models, we have declared, can be referenced from within the callback.
+
+The ``source_model`` will be made available by prefixing it with ``source_``, while the target model is made available with the prefix ``target_``. This means that the ``ColumnDataSource`` on the ``source`` can be referenced as ``source_source``, while the glyph on the target can be referenced as ``target_glyph``.
+
+Finally, any parameters other than the ``source`` and ``target`` on the ``Link`` will also be made available inside the callback, which means we can reference the appropriate ``column`` in the ``ColumnDataSource`` to compute the mean value along a particular axis.
+
+Once we know how to reference the bokeh models and ``Link`` parameters we can access their properties to compute the mean value of the current selection on the source ``ColumnDataSource`` and set the ``target_glyph.position`` to that value.
+
+A ``LinkCallback`` may also define a validate method to validate that the Link parameters and plots are compatible, e.g. in this case we can validate that the ``column`` is actually present in the source_plot ``ColumnDataSource``.
+
+
+```python
+from holoviews.plotting.bokeh import LinkCallback
+
+class MeanLineCallback(LinkCallback):
+
+    source_model = 'selected'
+    source_handles = ['cds']
+    on_source_changes = ['indices']
+
+    target_model = 'glyph'
+    
+    source_code = """
+        var inds = source_selected.indices
+        var d = source_cds.data
+        var vm = 0
+        if (inds.length == 0)
+            return
+        for (var i = 0; i < inds.length; i++)
+            vm += d[column][inds[i]]
+        vm /= inds.length
+        target_glyph.location = vm
+    """
+    
+    def validate(self):
+        assert self.link.column in self.source_plot.handles['cds'].data
+```
+
+Finally we need to register the ``MeanLineLinkCallback`` with the ``MeanLineLink`` using the ``register_callback`` classmethod:
+
+
+```python
+MeanLineLink.register_callback('bokeh', MeanLineCallback)
+```
+
+Now the newly declared Link is ready to use, we'll create a ``Scatter`` element along with an ``HLine`` and ``VLine`` element and link each one:
+
+
+```python
+options = opts.Scatter(
+    selection_fill_color='firebrick', alpha=0.4, line_color='black', size=8,
+    tools=['lasso_select', 'box_select'], width=500, height=500,
+    active_tools=['lasso_select']
+)
+scatter = hv.Scatter(np.random.randn(500, 2)).opts(options)
+vline = hv.VLine(scatter['x'].mean()).opts(color='black')
+hline = hv.HLine(scatter['y'].mean()).opts(color='black')
+
+MeanLineLink(scatter, vline, column='x')
+MeanLineLink(scatter, hline, column='y')
+
+scatter * hline * vline
+```
+
+Using the 'box_select' and 'lasso_select' tools will now update the position of the HLine and VLine.

hvplot_docs/NetworkX.md

@@ -0,0 +1,552 @@
+The hvPlot NetworkX plotting API is meant as a drop-in replacement for the ``networkx.draw`` methods. In most cases the existing code will work as is or with minor modifications, returning a HoloViews object rendering an interactive bokeh plot, equivalent to the matplotlib plot the standard API constructs. First let us import the plotting interface and give it the canonical name ``hvnx``:
+
+
+```python
+import hvplot.networkx as hvnx
+
+import networkx as nx
+import holoviews as hv
+```
+
+In this user guide we will follow along with many of the examples in the [NetworkX tutorial](https://networkx.github.io/documentation/stable/tutorial.html#drawing-graphs) on drawing graphs.
+
+The ``hxnx`` namespace provides all the same plotting functions as ``nx``, this means in most cases one can simply be swapped for the other. This also includes most keywords used to customize the plots. The main difference is in the way multiple plots are composited, like all other hvPlot APIs the networkX functions returns HoloViews objects which can be composited using ``+`` and ``*`` operations:
+
+
+```python
+G = nx.petersen_graph()
+
+spring = hvnx.draw(G, with_labels=True)
+shell = hvnx.draw_shell(G, nlist=[range(5, 10), range(5)], with_labels=True, font_weight='bold')
+
+spring + shell
+```
+
+
+```python
+H = nx.triangular_lattice_graph(1, 20)
+hvnx.draw_planar(H, node_color='green', edge_color='brown')
+```
+
+The most common ``layout`` functions have dedicated drawing methods such as the ``draw_shell`` function above, which automatically computes the node positions.
+
+However layout algorithms are not necessarily deterministic, so if we want to plot and overlay subsets of either the nodes or edges using the ``nodelist`` and ``edgelist`` keywords the node positions should be computed ahead of time and passed in explicitly:
+
+
+```python
+pos = nx.layout.spring_layout(G)
+
+hvnx.draw(G, pos, nodelist=[0, 1, 2, 3, 4], node_color='blue') *\
+hvnx.draw_networkx_nodes(G, pos, nodelist=[5, 6, 7, 8, 9], node_color='green')
+```
+
+The ``hvnx`` namespace also makes ``save`` and ``show utilities available to save the plot to HTML or PNG files or display it in a separate browser window when working in a standard Python interpreter.
+
+
+```python
+G = nx.dodecahedral_graph()
+
+shells = [[2, 3, 4, 5, 6], [8, 1, 0, 19, 18, 17, 16, 15, 14, 7], [9, 10, 11, 12, 13]]
+shell = hvnx.draw_shell(G, nlist=shells)
+
+pos = nx.nx_agraph.graphviz_layout(G)
+graphviz = hvnx.draw(G, pos=pos)
+
+layout = shell + graphviz
+
+hvnx.save(layout, 'graph_layout.png')
+```
+
+#### Styling Graphs
+
+The full set of options which are inherited from networkx's API are listed in the ``hxnx.draw()`` docstring. Using these the more common styling of nodes and edges can easily be altered through the common set of options that are inherited from networkx. In addition common HoloViews options to control the size of the plots, axes and styling are also supported. Finally, some ``layout`` functions also accept special keyword arguments such as the ``nlist`` argument for the shell layout which specifies the shells.
+
+
+```python
+options = {
+    'node_color': 'black',
+    'node_size': 100,
+    'edge_width': 3,
+    'width': 300,
+    'height': 300
+}
+
+random = hvnx.draw_random(G, **options)
+circular = hvnx.draw_circular(G, **options)
+spectral = hvnx.draw_spectral(G, **options)
+shell = hvnx.draw_shell(G, nlist=[range(5,10), range(5)], **options)
+
+(random + circular + spectral + shell).cols(2)
+```
+
+In addition to being able to set scalar style values hvPlot also supports the HoloViews concept of [style mapping](https://holoviews.org/user_guide/Style_Mapping.html#styling-mapping), which uses so called ``dim`` transforms to map attributes of the graph nodes and edges to vary the visual attributes of the plot. For example we might construct a graph with edge weights and node sizes as attributes. The plotting function will extract these attributes which means they can be used to scale visual properties of the plot such as the ``edge_width``, ``edge_color`` or ``node_size``:
+
+
+```python
+G = nx.Graph()
+
+G.add_edge('a', 'b', weight=0.6)
+G.add_edge('a', 'c', weight=0.2)
+G.add_edge('c', 'd', weight=0.1)
+G.add_edge('c', 'e', weight=0.7)
+G.add_edge('c', 'f', weight=0.9)
+G.add_edge('a', 'd', weight=0.3)
+
+G.add_node('a', size=20)
+G.add_node('b', size=10)
+G.add_node('c', size=12)
+G.add_node('d', size=5)
+G.add_node('e', size=8)
+G.add_node('f', size=3)
+
+pos = nx.spring_layout(G)  # positions for all nodes
+
+hvnx.draw(G, pos, edge_color='weight', edge_cmap='viridis',
+          edge_width=hv.dim('weight')*10, node_size=hv.dim('size')*20)
+```
+
+The full set of options that are supported can be accessed on the ``hvnx.draw`` function (note this does not include some bokeh specific option to control the styling of selection, nonselection and hover nodes and edges which may also be supplied and follow a pattern like ``hover_node_fill_color`` or ``selection_edge_line_alpha``).
+
+For reference here is the docstring listing the main supported option:
+
+
+```python
+print(hvnx.draw.__doc__)
+```
+
+The main difference to the networkx.draw API are a few options which are not supported (such as `font_weight` and `arrowsize`) and the renaming of `width` (which controls the edge line width) to ``edge_width`` since `width` and `height` are reserved for defining the screen dimensions of the plot.
+
+## Examples
+
+To demonstrate that the API works almost identically this section reproduces various examples from the NetworkX documentation.
+
+### Plot properties
+
+Compute some network properties for the lollipop graph.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/basic/plot_properties.html
+
+
+```python
+#    Copyright (C) 2004-2018 by
+#    Aric Hagberg <hagberg@lanl.gov>
+#    Dan Schult <dschult@colgate.edu>
+#    Pieter Swart <swart@lanl.gov>
+#    All rights reserved.
+#    BSD license.
+
+#    Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+G = nx.lollipop_graph(4, 6)
+
+pathlengths = []
+
+print("source vertex {target:length, }")
+for v in G.nodes():
+    spl = dict(nx.single_source_shortest_path_length(G, v))
+    print('{} {} '.format(v, spl))
+    for p in spl:
+        pathlengths.append(spl[p])
+
+print('')
+print("average shortest path length %s" % (sum(pathlengths) / len(pathlengths)))
+
+# histogram of path lengths
+dist = {}
+for p in pathlengths:
+    if p in dist:
+        dist[p] += 1
+    else:
+        dist[p] = 1
+
+print('')
+print("length #paths")
+verts = dist.keys()
+for d in sorted(verts):
+    print('%s %d' % (d, dist[d]))
+
+print("radius: %d" % nx.radius(G))
+print("diameter: %d" % nx.diameter(G))
+print("eccentricity: %s" % nx.eccentricity(G))
+print("center: %s" % nx.center(G))
+print("periphery: %s" % nx.periphery(G))
+print("density: %s" % nx.density(G))
+
+hvnx.draw(G, with_labels=True)
+```
+
+### Simple Path
+
+Draw a graph with hvPlot.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_simple_path.html
+
+
+```python
+G = nx.path_graph(8)
+hvnx.draw(G)
+```
+
+### Node colormap
+
+Draw a graph with hvPlot, color by degree.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_node_colormap.html
+
+
+```python
+# Author: Aric Hagberg (hagberg@lanl.gov)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+G = nx.cycle_graph(24)
+pos = nx.spring_layout(G, iterations=200)
+
+# Preferred API
+# hvnx.draw(G, pos, node_color='index', node_size=500, cmap='Blues')
+
+# Original code
+hvnx.draw(G, pos, node_color=range(24), node_size=500, cmap='Blues')
+```
+
+### Edge Colormap
+
+Draw a graph with hvPlot, color edges.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_edge_colormap.html
+
+
+```python
+# Author: Aric Hagberg (hagberg@lanl.gov)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+G = nx.star_graph(20)
+pos = nx.spring_layout(G)
+colors = range(20)
+hvnx.draw(G, pos, node_color='#A0CBE2', edge_color=colors,
+          edge_width=4, edge_cmap='Blues', with_labels=False)
+```
+
+### House With Colors
+
+Draw a graph with hvPlot.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_house_with_colors.html
+
+
+```python
+# Author: Aric Hagberg (hagberg@lanl.gov)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+G = nx.house_graph()
+# explicitly set positions
+pos = {0: (0, 0),
+       1: (1, 0),
+       2: (0, 1),
+       3: (1, 1),
+       4: (0.5, 2.0)}
+
+hvnx.draw_networkx_nodes(G, pos, node_size=2000, nodelist=[4], padding=0.2) *\
+hvnx.draw_networkx_nodes(G, pos, node_size=3000, nodelist=[0, 1, 2, 3], node_color='black') *\
+hvnx.draw_networkx_edges(G, pos, alpha=0.5, width=6, xaxis=None, yaxis=None)
+```
+
+### Circular Tree
+
+URL: https://networkx.org/documentation/stable/auto_examples/graphviz_layout/plot_circular_tree.html
+
+
+```python
+try:
+    import pygraphviz  # noqa
+    from networkx.drawing.nx_agraph import graphviz_layout
+except ImportError:
+    try:
+        import pydot  # noqa
+        from networkx.drawing.nx_pydot import graphviz_layout
+    except ImportError:
+        raise ImportError("This example needs Graphviz and either "
+                          "PyGraphviz or pydot")
+
+G = nx.balanced_tree(3, 5)
+pos = graphviz_layout(G, prog='twopi', args='')
+hvnx.draw(G, pos, node_size=20, alpha=0.5, node_color="blue", with_labels=False, width=600, height=600)
+```
+
+### Spectral Embedding
+
+The spectral layout positions the nodes of the graph based on the eigenvectors of the graph Laplacian L=D−A, where A is the adjacency matrix and D is the degree matrix of the graph. By default, the spectral layout will embed the graph in two dimensions (you can embed your graph in other dimensions using the dim argument to either draw_spectral() or spectral_layout()).
+
+When the edges of the graph represent similarity between the incident nodes, the spectral embedding will place highly similar nodes closer to one another than nodes which are less similar.
+
+This is particularly striking when you spectrally embed a grid graph. In the full grid graph, the nodes in the center of the graph are pulled apart more than nodes on the periphery. As you remove internal nodes, this effect increases.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_spectral_grid.html
+
+
+```python
+options = {
+    'node_size': 100,
+    'width': 250, 'height': 250
+}
+
+G = nx.grid_2d_graph(6, 6)
+spectral1 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((2, 2), (2, 3))
+spectral2 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((3, 2), (3, 3))
+spectral3 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((2, 2), (3, 2))
+spectral4 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((2, 3), (3, 3))
+spectral5 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((1, 2), (1, 3))
+spectral6 = hvnx.draw_spectral(G, **options)
+
+G.remove_edge((4, 2), (4, 3))
+spectral7 = hvnx.draw_spectral(G, **options)
+
+(hv.Empty() + spectral1 + hv.Empty() +
+ spectral2 + spectral3 + spectral4 +
+ spectral5 + spectral6 + spectral7).cols(3)
+```
+
+### Plot four grids
+
+Draw a graph with hvPlot.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_four_grids.html
+
+
+```python
+# Author: Aric Hagberg (hagberg@lanl.gov)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+#    Copyright (C) 2004-2018
+#    Aric Hagberg <hagberg@lanl.gov>
+#    Dan Schult <dschult@colgate.edu>
+#    Pieter Swart <swart@lanl.gov>
+#    All rights reserved.
+#    BSD license.
+
+G = nx.grid_2d_graph(4, 4)  # 4x4 grid
+
+pos = nx.spring_layout(G, iterations=100)
+
+g1 = hvnx.draw(G, pos, font_size=8)
+
+g2 = hvnx.draw(G, pos, node_color='black', node_size=0, with_labels=False)
+
+g3 = hvnx.draw(G, pos, node_color='green', node_size=250, with_labels=False, edge_width=6)
+
+H = G.to_directed()
+g4 = hvnx.draw(H, pos, node_color='blue', node_size=20, with_labels=False)
+
+(g1 + g2 + g3 + g4).cols(2)
+```
+
+### Ego Graph
+
+Example using the NetworkX ego_graph() function to return the main egonet of the largest hub in a Barabási-Albert network.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_ego_graph.html
+
+
+```python
+# Author:  Drew Conway (drew.conway@nyu.edu)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+from operator import itemgetter
+
+# Create a BA model graph
+n = 1000
+m = 2
+G = nx.generators.barabasi_albert_graph(n, m)
+# find node with largest degree
+node_and_degree = G.degree()
+(largest_hub, degree) = sorted(node_and_degree, key=itemgetter(1))[-1]
+# Create ego graph of main hub
+hub_ego = nx.ego_graph(G, largest_hub)
+# Draw graph
+pos = nx.spring_layout(hub_ego)
+g = hvnx.draw(hub_ego, pos, node_color='blue', node_size=50, with_labels=False)
+# Draw ego as large and red
+gnodes = hvnx.draw_networkx_nodes(hub_ego, pos, nodelist=[largest_hub], node_size=300, node_color='red')
+
+g * gnodes
+```
+
+### Random Geometric Graph
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_random_geometric_graph.html
+
+
+```python
+G = nx.random_geometric_graph(200, 0.125)
+# position is stored as node attribute data for random_geometric_graph
+pos = nx.get_node_attributes(G, 'pos')
+
+# find node near center (0.5,0.5)
+dmin = 1
+ncenter = 0
+for n in pos:
+    x, y = pos[n]
+    d = (x - 0.5)**2 + (y - 0.5)**2
+    if d < dmin:
+        ncenter = n
+        dmin = d
+
+# color by path length from node near center
+p = nx.single_source_shortest_path_length(G, ncenter)
+
+hvnx.draw_networkx_edges(G, pos, nodelist=[ncenter], alpha=0.4, width=600, height=600) *\
+hvnx.draw_networkx_nodes(G, pos, nodelist=list(p.keys()),
+                         node_size=80,
+                         node_color=list(p.values()),
+                         cmap='Reds_r')
+```
+
+### Weighted Graph
+
+An example using Graph as a weighted network.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_weighted_graph.html
+
+
+```python
+# Author: Aric Hagberg (hagberg@lanl.gov)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+import networkx as nx
+
+G = nx.Graph()
+
+G.add_edge('a', 'b', weight=0.6)
+G.add_edge('a', 'c', weight=0.2)
+G.add_edge('c', 'd', weight=0.1)
+G.add_edge('c', 'e', weight=0.7)
+G.add_edge('c', 'f', weight=0.9)
+G.add_edge('a', 'd', weight=0.3)
+
+elarge = [(u, v) for (u, v, attr) in G.edges(data=True) if attr['weight'] > 0.5]
+esmall = [(u, v) for (u, v, attr) in G.edges(data=True) if attr['weight'] <= 0.5]
+
+pos = nx.spring_layout(G)  # positions for all nodes
+
+# nodes
+nodes = hvnx.draw_networkx_nodes(G, pos, node_size=700)
+
+# edges
+edges1 = hvnx.draw_networkx_edges(
+    G, pos, edgelist=elarge, edge_width=6)
+edges2 = hvnx.draw_networkx_edges(
+    G, pos, edgelist=esmall, edge_width=6, alpha=0.5, edge_color='blue', style='dashed')
+labels = hvnx.draw_networkx_labels(G, pos, font_size=20, font_family='sans-serif')
+
+edges1 * edges2 * nodes * labels
+```
+
+### Directed Graph
+
+Draw a graph with directed edges using a colormap and different node sizes.
+
+Edges have different colors and alphas (opacity). Drawn using matplotlib.
+
+URL: https://networkx.github.io/documentation/stable/auto_examples/drawing/plot_directed.html
+
+
+```python
+# Author: Rodrigo Dorantes-Gilardi (rodgdor@gmail.com)
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+G = nx.generators.directed.random_k_out_graph(10, 3, 0.5)
+pos = nx.layout.spring_layout(G)
+
+node_sizes = [3 + 10 * i for i in range(len(G))]
+M = G.number_of_edges()
+edge_colors = range(2, M + 2)
+edge_alphas = [(5 + i) / (M + 4) for i in range(M)]
+
+nodes = hvnx.draw_networkx_nodes(G, pos, node_size=node_sizes, node_color='blue')
+edges = hvnx.draw_networkx_edges(G, pos, node_size=node_sizes, arrowstyle='->',
+                               arrowsize=10, edge_color=edge_colors,
+                               edge_cmap='Blues', edge_width=2, colorbar=True)
+
+nodes * edges
+```
+
+### Giant Component
+
+This example illustrates the sudden appearance of a giant connected component in a binomial random graph.
+
+https://networkx.org/documentation/stable/auto_examples/graphviz_layout/plot_giant_component.html
+
+
+```python
+#    Copyright (C) 2006-2018
+#    Aric Hagberg <hagberg@lanl.gov>
+#    Dan Schult <dschult@colgate.edu>
+#    Pieter Swart <swart@lanl.gov>
+#    All rights reserved.
+#    BSD license.
+
+# Adapted by Philipp Rudiger <prudiger@anaconda.com>
+
+import math
+
+try:
+    import pygraphviz  # noqa
+    from networkx.drawing.nx_agraph import graphviz_layout
+    layout = graphviz_layout
+except ImportError:
+    try:
+        import pydot  # noqa
+        from networkx.drawing.nx_pydot import graphviz_layout
+        layout = graphviz_layout
+    except ImportError:
+        print("PyGraphviz and pydot not found;\n"
+              "drawing with spring layout;\n"
+              "will be slow.")
+        layout = nx.spring_layout
+
+n = 150  # 150 nodes
+# p value at which giant component (of size log(n) nodes) is expected
+p_giant = 1.0 / (n - 1)
+# p value at which graph is expected to become completely connected
+p_conn = math.log(n) / float(n)
+
+# the following range of p values should be close to the threshold
+pvals = [0.003, 0.006, 0.008, 0.015]
+
+region = 220  # for pylab 2x2 subplot layout
+plots = []
+for p in pvals:
+    G = nx.binomial_graph(n, p)
+    pos = layout(G)
+    region += 1
+    g = hvnx.draw(G, pos, with_labels=False, node_size=15)
+    # identify largest connected component
+    Gcc = sorted([G.subgraph(c) for c in nx.connected_components(G)], key=len, reverse=True)
+    G0 = Gcc[0]
+    edges = hvnx.draw_networkx_edges(
+        G0, pos, with_labels=False, edge_color='red', edge_width=6.0)
+    
+    # show other connected components
+    other_edges = []
+    for Gi in Gcc[1:]:
+        if len(Gi) > 1:
+            edge = hvnx.draw_networkx_edges(Gi, pos,
+                                   with_labels=False,
+                                   edge_color='red',
+                                   alpha=0.3,
+                                   edge_width=5.0
+                                  )
+            other_edges.append(edge)
+    plots.append((g*edges*hv.Overlay(other_edges)).relabel("p = %6.3f" % (p)))
+
+hv.Layout(plots).cols(2)
+```

hvplot_docs/Network_Graphs.md

@@ -0,0 +1,249 @@
+```python
+import numpy as np
+import pandas as pd
+import holoviews as hv
+import networkx as nx
+from holoviews import opts
+
+hv.extension('bokeh')
+
+defaults = dict(width=400, height=400)
+hv.opts.defaults(
+    opts.EdgePaths(**defaults), opts.Graph(**defaults), opts.Nodes(**defaults))
+```
+
+Visualizing and working with network graphs is a common problem in many different disciplines. HoloViews provides the ability to represent and visualize graphs very simply and easily with facilities for interactively exploring the nodes and edges of the graph, especially using the bokeh plotting interface.
+
+The ``Graph`` ``Element`` differs from other elements in HoloViews in that it consists of multiple sub-elements. The data of the ``Graph`` element itself are the abstract edges between the nodes. By default the element will automatically compute concrete ``x`` and ``y`` positions for the nodes and represent them using a ``Nodes`` element, which is stored on the Graph. The abstract edges and concrete node positions are sufficient to render the ``Graph`` by drawing straight-line edges between the nodes. In order to supply explicit edge paths we can also declare ``EdgePaths``, providing explicit coordinates for each edge to follow.
+
+To summarize a ``Graph`` consists of three different components:
+
+* The ``Graph`` itself holds the abstract edges stored as a table of node indices.
+* The ``Nodes`` hold the concrete ``x`` and ``y`` positions of each node along with a node ``index``. The ``Nodes`` may also define any number of value dimensions, which can be revealed when hovering over the nodes or to color the nodes by.
+* The ``EdgePaths`` can optionally be supplied to declare explicit node paths.
+
+#### A simple Graph
+
+Let's start by declaring a very simple graph connecting one node to all others. If we simply supply the abstract connectivity of the ``Graph``, it will automatically compute a layout for the nodes using the ``layout_nodes`` operation, which defaults to a circular layout:
+
+
+```python
+# Declare abstract edges
+N = 8
+node_indices = np.arange(N, dtype=np.int32)
+source = np.zeros(N, dtype=np.int32)
+target = node_indices
+
+
+simple_graph = hv.Graph(((source, target),))
+simple_graph
+```
+
+#### Accessing the nodes and edges
+
+We can easily access the ``Nodes`` and ``EdgePaths`` on the ``Graph`` element using the corresponding properties:
+
+
+```python
+simple_graph.nodes + simple_graph.edgepaths
+```
+
+#### Displaying directed graphs
+
+When specifying the graph edges the source and target node are listed in order, if the graph is actually a directed graph this may used to indicate the directionality of the graph. By setting ``directed=True`` as a plot option it is possible to indicate the directionality of each edge using an arrow:
+
+
+```python
+simple_graph.relabel('Directed Graph').opts(directed=True, node_size=5, arrowhead_length=0.05)
+```
+
+The length of the arrows can be set as an fraction of the overall graph extent using the ``arrowhead_length`` option.
+
+#### Supplying explicit paths
+
+Next we will extend this example by supplying explicit edges:
+
+
+```python
+def bezier(start, end, control, steps=np.linspace(0, 1, 100)):
+    return (1-steps)**2*start + 2*(1-steps)*steps*control+steps**2*end
+
+x, y = simple_graph.nodes.array([0, 1]).T
+
+paths = []
+for node_index in node_indices:
+    ex, ey = x[node_index], y[node_index]
+    paths.append(np.column_stack([bezier(x[0], ex, 0), bezier(y[0], ey, 0)]))
+    
+bezier_graph = hv.Graph(((source, target), (x, y, node_indices), paths))
+bezier_graph
+```
+
+## Interactive features
+
+#### Hover and selection policies
+
+Thanks to Bokeh we can reveal more about the graph by hovering over the nodes and edges. The ``Graph`` element provides an ``inspection_policy`` and a ``selection_policy``, which define whether hovering and selection highlight edges associated with the selected node or nodes associated with the selected edge, these policies can be toggled by setting the policy to ``'nodes'`` (the default) and ``'edges'``.
+
+
+```python
+bezier_graph.relabel('Edge Inspection').opts(inspection_policy='edges')
+```
+
+In addition to changing the policy we can also change the colors used when hovering and selecting nodes:
+
+
+```python
+bezier_graph.opts(
+    opts.Graph(inspection_policy='nodes', tools=['hover', 'box_select'],
+               edge_hover_line_color='green', node_hover_fill_color='red'))
+```
+
+#### Additional information
+
+We can also associate additional information with the nodes and edges of a graph. By constructing the ``Nodes`` explicitly we can declare additional value dimensions, which are revealed when hovering and/or can be mapped to the color by setting the ``color`` to the dimension name ('Weight'). We can also associate additional information with each edge by supplying a value dimension to the ``Graph`` itself, which we can map to various style options, e.g. by setting the ``edge_color`` and ``edge_line_width``.
+
+
+```python
+node_labels = ['Output']+['Input']*(N-1)
+np.random.seed(7)
+edge_labels = np.random.rand(8)
+
+nodes = hv.Nodes((x, y, node_indices, node_labels), vdims='Type')
+graph = hv.Graph(((source, target, edge_labels), nodes, paths), vdims='Weight')
+
+(graph + graph.opts(inspection_policy='edges', clone=True)).opts(
+    opts.Graph(node_color='Type', edge_color='Weight', cmap='Set1',
+               edge_cmap='viridis', edge_line_width=hv.dim('Weight')*10))
+```
+
+If you want to supply additional node information without specifying explicit node positions you may pass in a ``Dataset`` object consisting of various value dimensions.
+
+
+```python
+node_info = hv.Dataset(node_labels, vdims='Label')
+hv.Graph(((source, target), node_info)).opts(node_color='Label', cmap='Set1')
+```
+
+## Working with NetworkX
+
+NetworkX is a very useful library when working with network graphs and the Graph Element provides ways of importing a NetworkX Graph directly. Here we will load the Karate Club graph and use the ``circular_layout`` function provided by NetworkX to lay it out:
+
+
+```python
+G = nx.karate_club_graph()
+hv.Graph.from_networkx(G, nx.layout.circular_layout).opts(tools=['hover'])
+```
+
+It is also possible to pass arguments to the NetworkX layout function as keywords to ``hv.Graph.from_networkx``, e.g. we can override the k-value of the Fruchteran Reingold layout
+
+
+```python
+hv.Graph.from_networkx(G, nx.layout.fruchterman_reingold_layout, k=1)
+```
+
+Finally if we want to layout a Graph after it has already been constructed, the ``layout_nodes`` operation may be used, which also allows applying the ``weight`` argument to graphs which have not been constructed with networkx:
+
+
+```python
+from holoviews.element.graphs import layout_nodes
+
+graph = hv.Graph([
+    ('a', 'b', 3),
+    ('a', 'c', 0.2),
+    ('c', 'd', 0.1),
+    ('c', 'e', 0.7),
+    ('c', 'f', 5),
+    ('a', 'd', 0.3)
+], vdims='weight')
+
+layout_nodes(graph, layout=nx.layout.fruchterman_reingold_layout, kwargs={'weight': 'weight'})
+```
+
+## Adding labels
+
+If the ``Graph`` we have constructed has additional metadata we can easily use those as labels, we simply get a handle on the nodes, cast them to hv.Labels and then overlay them:
+
+
+```python
+graph = hv.Graph.from_networkx(G, nx.layout.fruchterman_reingold_layout)
+labels = hv.Labels(graph.nodes, ['x', 'y'], 'club')
+
+(graph * labels.opts(text_font_size='8pt', text_color='white', bgcolor='gray'))
+```
+
+## Animating graphs
+
+Like all other elements ``Graph`` can be updated in a ``HoloMap`` or ``DynamicMap``. Here we animate how the Fruchterman-Reingold force-directed algorithm lays out the nodes in real time.
+
+
+```python
+hv.HoloMap({i: hv.Graph.from_networkx(G, nx.spring_layout, iterations=i, seed=10) for i in range(5, 30, 5)},
+           kdims='Iterations')
+```
+
+## Real world graphs
+
+As a final example let's look at a slightly larger graph. We will load a dataset of a Facebook network consisting a number of friendship groups identified by their ``'circle'``. We will load the edge and node data using pandas and then color each node by their friendship group using many of the things we learned above.
+
+
+```python
+kwargs = dict(width=800, height=800, xaxis=None, yaxis=None)
+opts.defaults(opts.Nodes(**kwargs), opts.Graph(**kwargs))
+
+colors = ['#000000']+hv.Cycle('Category20').values
+edges_df = pd.read_csv('../assets/fb_edges.csv')
+fb_nodes = hv.Nodes(pd.read_csv('../assets/fb_nodes.csv')).sort()
+fb_graph = hv.Graph((edges_df, fb_nodes), label='Facebook Circles')
+
+fb_graph.opts(cmap=colors, node_size=10, edge_line_width=1,
+              node_line_color='gray', node_color='circle')
+```
+
+## Bundling graphs
+
+The datashader library provides algorithms for bundling the edges of a graph and HoloViews provides convenient wrappers around the libraries. Note that these operations need ``scikit-image`` which you can install using:
+
+```
+conda install scikit-image
+```
+
+or
+
+```
+pip install scikit-image
+```
+
+
+```python
+from holoviews.operation.datashader import datashade, bundle_graph
+bundled = bundle_graph(fb_graph)
+bundled
+```
+
+## Datashading graphs
+
+For graphs with a large number of edges we can datashade the paths and display the nodes separately. This loses some of the interactive features but will let you visualize quite large graphs:
+
+
+```python
+(datashade(bundled, normalization='linear', width=800, height=800) * bundled.nodes).opts(
+    opts.Nodes(color='circle', size=10, width=1000, cmap=colors, legend_position='right'))
+```
+
+### Applying selections
+
+Alternatively we can select the nodes and edges by an attribute that resides on either. In this case we will select the nodes and edges for a particular circle and then overlay just the selected part of the graph on the datashaded plot. Note that selections on the ``Graph`` itself will select all nodes that connect to one of the selected nodes. In this way a smaller subgraph can be highlighted and the larger graph can be datashaded.
+
+
+```python
+datashade(bundle_graph(fb_graph), normalization='linear', width=800, height=800) *\
+bundled.select(circle='circle15').opts(node_fill_color='white')
+```
+
+To select just nodes that are in 'circle15' set the ``selection_mode='nodes'`` overriding the default of 'edges':
+
+
+```python
+bundled.select(circle='circle15', selection_mode='nodes')
+```

hvplot_docs/Notebook_Magics.md

@@ -0,0 +1,156 @@
+# Notebook Magics
+
+
+```python
+import pandas as pd
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+hv.extension('bokeh', 'matplotlib')
+```
+
+The [Applying Customizations](03-Applying_Customizations.ipynb) user guide describes the currently *recommended* way to customize your visualizations in HoloViews. Those mechanisms use standard Python syntax but they are not the only way to apply options as there is a much older approach for working with HoloViews that is specific to notebooks.
+
+From the start, HoloViews aimed to enable rapid exploration of data in Jupyter Notebooks. For this reason, when you load the HoloViews extension in a notebook, you also get a set of IPython magics. IPython magics use a syntax that is not standard Python and the HoloViews magics only apply in the notebook environment (and not the IPython terminal for instance).
+
+The advantages of the notebook magics are:
+
+* They allow tab-completion in the notebook environment (but so do the more recent option builders and `hv.output` mechanisms).
+* They allow very concise expression of options and settings.
+
+
+Unfortunately, they also have some serious disadvantages:
+
+* They are not Python syntax which makes it difficult to use code written with magics in notebooks anywhere else. For instance, it makes it harder to use such code with [bokeh server](https://bokeh.pydata.org/en/latest/docs/reference/server.html) or [panel](http://panel.pyviz.org/).
+* They have their own special syntax which is very concise but also rather mysterious.
+
+
+These disadvantages means the magics can be bewildering to anyone unfamiliar with the IPython specific syntax and HoloViews itself, and are no longer recommended for these reasons. This user guide documents these magics to allow people to understand older notebooks using HoloViews and to help people update these old notebooks to use the recommended Python API.
+
+## Line and cell magics
+
+There are two types of magic supported in Jupyter notebooks called *line magics* and *cell magics* respectively. Both typically appear at the top of code cells prefixed by `%` (line magics) or `%%` (cell magics).
+
+* **line magics**: These can appear anywhere in a code cell and effect global changes to the current notebook session. HoloViews has the `%opts` and `%output` line magics.
+* **cell magics**: These have to appear at the top of the cell and are used to modify how that cell is executed. HoloViews has the `%%opts` and `%%output` cell magics.
+
+
+
+## The %opts and %%opts magics
+
+These two magics are now served by `opts.defaults` and the `.opts` method respectively, as described in the [Applying Customizations](03-Applying_Customizations.ipynb) user guide.
+
+* *The ``%opts`` line magic*: IPython specific syntax applied globally *[string format]*
+* *The ``%%opts`` cell magic*: IPython specific syntax applies to displayed object *[string format]*
+
+These magics have their own syntax that separates between *style*, *plot* and *norm* options described towards the end of the [Applying Customizations](03-Applying_Customizations.ipynb) user guide. The definition of the syntax is as follows:
+
+```
+[[spec] [normalization] [plotting options] [style options]]+
+
+spec:             A dotted type.group.label specification
+                  (e.g. Curve,Sinusoid.Squared)
+
+normalization:    List of normalization options delimited by braces.
+                  One of | -axiswise | -framewise | +axiswise | +framewise |
+                  E.g. { +axiswise +framewise }
+
+plotting options: List of plotting option keywords delimited by
+                  square brackets. E.g. [show_title=False]
+
+style options:    List of style option keywords delimited by
+                  parentheses. E.g. (lw=10 marker='+')
+```
+
+In other words, you have a list of spec strings (for instance `Curve` or `Curve.Sinusoid`) followed by keywords in either parentheses, square brackets or braces to represent the style, plot and normalization options respectively.
+
+## Example `%%opts` cell magic
+
+Here is the example from the [Customization](../getting_started/2-Customization.ipynb) section of the 'Getting Started' customized using the `%%opts` cell magic:
+
+
+```python
+%%opts Curve  [height=200 width=900 xaxis=None tools=['hover']]
+%%opts Curve (color='red' line_width=1.5)
+%%opts Spikes [height=150 width=900 yaxis=None] (color='grey' line_width=0.25)
+
+spike_train = pd.read_csv('../assets/spike_train.csv.gz')
+curve  = hv.Curve( spike_train, 'milliseconds', vdims='Hertz')
+spikes = hv.Spikes(spike_train, 'milliseconds', vdims=[])
+layout = (curve+spikes).cols(1)
+layout
+```
+
+This `layout` object is now customized in a way that will persist, just like it would using the recommended `.opts` method together with option builders. It is worth noting that instead of just using element names, you can specify the group and label (e.g `Curve.Sinusoid.Squared`) to condition on that metadata, just the way you can using the option builders.
+
+
+## Example `%opts` line magic
+
+Here is how you could use the `%opts` line magic instead of `opts.default` as detailed in the [Applying Customizations](03-Applying_Customizations.ipynb) user guide:
+
+
+
+
+```python
+%opts HeatMap (cmap='Summer') [colorbar=True, toolbar='above']
+```
+
+Now all `HeatMap` elements will use the 'Summer' colormap, showing a colorbar with the Bokeh toolbar at the top:
+
+
+```python
+data = [(chr(65+i), chr(97+j),  i*j) for i in range(5) for j in range(5) if i!=j]
+hv.HeatMap(data).sort()
+```
+
+## The `%output` line magic
+
+The `%output` line magic has been fairly directly replaced by the `hv.output` utility. Here is an example of the `%output` line magic:
+
+
+
+
+```python
+%output backend='matplotlib', fig='svg'
+```
+
+This ensures the following `Path` (and all subsequent `Path` objects) are rendered as SVG with matplotlib:
+
+
+```python
+lin = np.linspace(0, np.pi*2, 200)
+
+def lissajous(t, a, b, delta):
+    return (np.sin(a * t + delta), np.sin(b * t), t)
+
+path = hv.Path([lissajous(lin, 3, 5, np.pi/2)])
+path.opts(opts.Path(linewidth=2, color='red', linestyle='dotted'))
+```
+
+For the purposes of this notebook, let us switch the plotting extension back to bokeh:
+
+
+```python
+%output backend='bokeh'
+```
+
+Note that the `%output` magic accepts the same set of output settings as the `hv.output` utility.
+
+## The `%%output` cell magic
+
+If we want to *temporarily* switch to matplotlib with some custom output settings,  we can use the `%%output` cell magic in an example combines the `%%output` and `%%opts` cell magics in the same cell:
+
+
+
+```python
+%%output backend='matplotlib' fig='svg' size=50
+%%opts Path (linewidth=3 color='blue')
+lin = np.linspace(0, np.pi*2, 200)
+
+def lissajous(t, a, b, delta):
+    return (np.sin(a * t + delta), np.sin(b * t), t)
+
+hv.Path([lissajous(lin, 3, 5, np.pi/2)])
+```
+
+The recommended approach would now be to pass the `path` object to the `hv.output` utility as detailed in the [Applying Customizations](03-Applying_Customizations.ipynb) user guide. The magic processes the same set of output settings as the `hv.output` utility.

hvplot_docs/Pandas_API.md

@@ -0,0 +1,628 @@
+If hvplot and pandas are both installed, then we can use the pandas.options.plotting.backend to control the output of `pd.DataFrame.plot` and `pd.Series.plot`. This notebook is meant to recreate the [pandas visualization docs](https://pandas.pydata.org/pandas-docs/stable/user_guide/visualization.html).
+
+
+```python
+import numpy as np
+import pandas as pd
+
+pd.options.plotting.backend = 'holoviews'
+```
+
+## Basic Plotting: `plot`
+
+The plot method on Series and DataFrame is just a simple wrapper around `hvplot()`:
+
+
+```python
+ts = pd.Series(np.random.randn(1000), index=pd.date_range('1/1/2000', periods=1000))
+ts = ts.cumsum()
+ts.plot()
+```
+
+If the index consists of dates, they will be sorted (as long as `sort_date=True`) and formatted the x-axis nicely as per above.
+
+On DataFrame, `plot()` is a convenience to plot all of the columns with labels:
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 4), index=ts.index, columns=list('ABCD'))
+df = df.cumsum()
+df.plot()
+```
+
+You can plot one column versus another using the *x* and *y* keywords in `plot()`:
+
+
+```python
+df3 = pd.DataFrame(np.random.randn(1000, 2), columns=['B', 'C']).cumsum()
+df3['A'] = pd.Series(list(range(len(df))))
+df3.plot(x='A', y='B')
+```
+
+**Note** For more formatting and styling options, see [formatting](#plot-formatting) below.
+
+## Other Plots
+
+Plotting methods allow for a handful of plot styles other than the default `line` plot. These methods can be provided as the `kind` keyword argument to `plot()`. These include:
+
+* `bar` or `barh` for bar plots
+* `hist` for histogram
+* `box` for boxplot
+* `kde` or `density` for density plots
+* `area` for area plots
+* `scatter` for scatter plots
+* `hexbin` for hexagonal bin plots
+* ~~`pie` for pie plots~~
+
+For example, a bar plot can be created the following way:
+
+
+```python
+df.iloc[5].plot(kind='bar')
+```
+
+You can also create these other plots using the methods DataFrame.plot.<kind> instead of providing the kind keyword argument. This makes it easier to discover plot methods and the specific arguments they use:
+
+In addition to these `kind`s, there are the `DataFrame.hist()`, and `DataFrame.boxplot()` methods, which use a separate interface.
+
+Finally, there are several plotting functions in `hvplot.plotting` that take a `Series` or `DataFrame` as an argument. These include:
+
+* `Scatter Matrix`
+* `Andrews Curves`
+* `Parallel Coordinates`
+* `Lag Plot`
+* ~~`Autocorrelation Plot`~~
+* ~~`Bootstrap Plot`~~
+* ~~`RadViz`~~
+
+Plots may also be adorned with errorbars or tables.
+
+### Bar plots
+
+For labeled, non-time series data, you may wish to produce a bar plot:
+
+
+
+
+```python
+import holoviews as hv
+```
+
+
+```python
+df.iloc[5].plot.bar() * hv.HLine(0).opts(color='k')
+```
+
+Calling a DataFrame’s `plot.bar()` method produces a multiple bar plot:
+
+
+```python
+df2 = pd.DataFrame(np.random.rand(10, 4), columns=['a', 'b', 'c', 'd'])
+df2.plot.bar()
+```
+
+To produce a stacked bar plot, pass `stacked=True`:
+
+
+```python
+df2.plot.bar(stacked=True)
+```
+
+To get horizontal bar plots, use the `barh` method:
+
+
+```python
+df2.plot.barh(stacked=True)
+```
+
+### Histograms
+
+Histogram can be drawn by using the `DataFrame.plot.hist()` and `Series.plot.hist()` methods.
+
+
+```python
+df4 = pd.DataFrame({'a': np.random.randn(1000) + 1, 'b': np.random.randn(1000),
+                    'c': np.random.randn(1000) - 1}, columns=['a', 'b', 'c'])
+
+df4.plot.hist(alpha=0.5)
+```
+
+Using the matplotlib backend, histograms can be stacked using `stacked=True`; **stacking is not yet supported in the holoviews backend**. Bin size can be changed by `bins` keyword.
+
+
+```python
+# Stacked not supported
+df4.plot.hist(stacked=True, bins=20)
+```
+
+You can pass other keywords supported by matplotlib hist. For example, horizontal and cumulative histogram can be drawn by `invert=True` and `cumulative=True`.
+
+
+```python
+df4['a'].plot.hist(invert=True, cumulative=True)
+```
+
+The existing interface `DataFrame.hist` to plot histogram still can be used.
+
+
+```python
+df['A'].diff().hist()
+```
+
+`DataFrame.hist()` plots the histograms of the columns on multiple subplots:
+
+
+```python
+df.diff().hist(color='k', alpha=0.5, bins=50, subplots=True, width=300).cols(2)
+```
+
+The by keyword can be specified to plot grouped histograms:
+
+
+```python
+# by does not support arrays, instead the array should be added as a column
+data = pd.Series(np.random.randn(1000))
+data = pd.DataFrame({'data': data, 'by_column': np.random.randint(0, 4, 1000)})
+data.hist(by='by_column', width=300, subplots=True).cols(2)
+```
+
+### Box Plots
+
+Boxplot can be drawn calling `Series.plot.box()` and `DataFrame.plot.box()`, or `DataFrame.boxplot()` to visualize the distribution of values within each column.
+
+For instance, here is a boxplot representing five trials of 10 observations of a uniform random variable on [0,1).
+
+
+
+```python
+df = pd.DataFrame(np.random.rand(10, 5), columns=['A', 'B', 'C', 'D', 'E'])
+df.plot.box()
+```
+
+Using the matplotlib backend, boxplot can be colorized by passing `color` keyword. You can pass a `dict` whose keys are `boxes`, `whiskers`, `medians` and `caps`. 
+
+**This behavior is not supported in the holoviews backend.**
+
+You can pass other keywords supported by holoviews boxplot. For example, horizontal and custom-positioned boxplot can be drawn by `invert=True` and positions keywords.
+
+
+```python
+# positions not supported
+df.plot.box(invert=True, positions=[1, 4, 5, 6, 8])
+```
+
+See the boxplot method and the matplotlib boxplot documentation for more.
+
+The existing interface `DataFrame.boxplot` to plot boxplot still can be used.
+
+
+```python
+df = pd.DataFrame(np.random.rand(10, 5))
+df.boxplot()
+```
+
+You can create a stratified boxplot using the `groupby` keyword argument to create groupings. For instance,
+
+
+```python
+df = pd.DataFrame(np.random.rand(10,2), columns=['Col1', 'Col2'])
+
+df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
+
+df.boxplot(col='X')
+```
+
+You can also pass a subset of columns to plot, as well as group by multiple columns:
+
+
+```python
+df = pd.DataFrame(np.random.rand(10,3), columns=['Col1', 'Col2', 'Col3'])
+
+df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
+df['Y'] = pd.Series(['A','B','A','B','A','B','A','B','A','B'])
+
+df.boxplot(y=['Col1','Col2'], col='X', row='Y')
+```
+
+
+```python
+df_box = pd.DataFrame(np.random.randn(50, 2))
+df_box['g'] = np.random.choice(['A', 'B'], size=50)
+df_box.loc[df_box['g'] == 'B', 1] += 3
+df_box.boxplot(row='g')
+```
+
+For more control over the ordering of the levels, we can perform a groupby on the data before plotting.
+
+
+```python
+df_box.groupby('g').boxplot()
+```
+
+### Area Plot
+
+You can create area plots with `Series.plot.area()` and `DataFrame.plot.area()`. Area plots are *not* stacked by default. To produce stacked area plot, each column must be either all positive or all negative values.
+
+When input data contains *NaN*, it will be automatically filled by 0. If you want to drop or fill by different values, use `dataframe.dropna()` or `dataframe.fillna()` before calling plot.
+
+
+```python
+df = pd.DataFrame(np.random.rand(10, 4), columns=['a', 'b', 'c', 'd'])
+df.plot.area(alpha=0.5)
+```
+
+To produce an stacked plot, pass `stacked=True`. 
+
+
+```python
+df.plot.area(stacked=True)
+```
+
+### Scatter Plot
+
+Scatter plot can be drawn by using the `DataFrame.plot.scatter()` method. Scatter plot require that x and y be specified using the `x` and `y` keywords.
+
+
+```python
+df = pd.DataFrame(np.random.rand(50, 4), columns=['a', 'b', 'c', 'd'])
+df.plot.scatter(x='a', y='b')
+```
+
+To plot multiple column groups in a single axes, repeat `plot` method and then use the overlay operator (`*`) to combine the plots. It is recommended to specify color and label keywords to distinguish each groups.
+
+
+```python
+plot_1 = df.plot.scatter(x='a', y='b', color='DarkBlue', label='Group 1')
+plot_2 = df.plot.scatter(x='c', y='d', color='DarkGreen', label='Group 2')
+
+plot_1 * plot_2
+```
+
+The keyword `c` may be given as the name of a column to provide colors for each point:
+
+
+```python
+df.plot.scatter(x='a', y='b', c='c', s=50)
+```
+
+You can pass other keywords supported by matplotlib `scatter`. The example below shows a bubble chart using a column of the `DataFrame` as the bubble size.
+
+
+```python
+df.plot.scatter(x='a', y='b', s=df['c']*500)
+```
+
+The same effect can be accomplished using the `scale` option.
+
+
+```python
+df.plot.scatter(x='a', y='b', s='c', scale=25)
+```
+
+### Hexagonal Bin Plot
+
+
+You can create hexagonal bin plots with `DataFrame.plot.hexbin()`. Hexbin plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually.
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 2), columns=['a', 'b'])
+df['b'] = df['b'] + np.arange(1000)
+
+df.plot.hexbin(x='a', y='b', gridsize=25, width=500, height=400)
+```
+
+A useful keyword argument is `gridsize`; it controls the number of hexagons in the x-direction, and defaults to 100. A larger `gridsize` means more, smaller bins.
+
+By default, a histogram of the counts around each `(x, y)` point is computed. You can specify alternative aggregations by passing values to the `C` and `reduce_C_function` arguments. `C` specifies the value at each `(x, y)` point and `reduce_C_function` is a function of one argument that reduces all the values in a bin to a single number (e.g. `mean`, `max`, `sum`, `std`). In this example the positions are given by columns `a` and `b`, while the value is given by column z. The bins are aggregated with numpy’s `max` function.
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 2), columns=['a', 'b'])
+df['b'] = df['b'] = df['b'] + np.arange(1000)
+df['z'] = np.random.uniform(0, 3, 1000)
+
+df.plot.hexbin(x='a', y='b', C='z', reduce_function=np.max, gridsize=25, width=500, height=400)
+```
+
+### Density Plot
+
+You can create density plots using the `Series.plot.kde()` and `DataFrame.plot.kde()` methods.
+
+
+```python
+ser = pd.Series(np.random.randn(1000))
+
+ser.plot.kde()
+```
+
+### Pie plot
+
+**NOT SUPPORTED**
+
+
+## Plotting Tools
+
+These functions can be imported from `hvplot.plotting` and take a `Series` or `DataFrame` as an argument.
+
+### Scatter Matrix Plot
+
+You can create a scatter plot matrix using the `scatter_matrix` function:
+
+
+```python
+import pandas as pd, numpy as np
+```
+
+
+```python
+from hvplot import scatter_matrix
+
+df = pd.DataFrame(np.random.randn(1000, 4), columns=['a', 'b', 'c', 'd'])
+
+scatter_matrix(df, alpha=0.2, diagonal='kde')
+```
+
+Since scatter matrix plots may generate a large number of points (the one above renders 120,000 points!), you may want to take advantage of the power provided by [Datashader](https://datashader.org/) to rasterize the off-diagonal plots into a fixed-resolution representation:
+
+
+```python
+df = pd.DataFrame(np.random.randn(10000, 4), columns=['a', 'b', 'c', 'd'])
+
+scatter_matrix(df, rasterize=True, dynspread=True)
+```
+
+### Andrews Curves
+
+Andrews curves allow one to plot multivariate data as a large number of curves that are created using the attributes of samples as coefficients for Fourier series. By coloring these curves differently for each class it is possible to visualize data clustering. Curves belonging to samples of the same class will usually be closer together and form larger structures.
+
+
+
+
+```python
+from bokeh.sampledata import iris
+from hvplot import andrews_curves
+
+data = iris.flowers
+
+andrews_curves(data, 'species')
+```
+
+### Parallel Coordinates
+
+Parallel coordinates is a plotting technique for plotting multivariate data. It allows one to see clusters in data and to estimate other statistics visually. Using parallel coordinates points are represented as connected line segments. Each vertical line represents one attribute. One set of connected line segments represents one data point. Points that tend to cluster will appear closer together.
+
+
+```python
+from hvplot import parallel_coordinates
+
+parallel_coordinates(data, 'species')
+```
+
+### Lag Plot 
+
+Lag plots are used to check if a data set or time series is random. Random data should not exhibit any structure in the lag plot. Non-random structure implies that the underlying data are not random.
+
+
+```python
+from hvplot import lag_plot
+
+data = pd.Series(0.1 * np.random.rand(1000) +
+                 0.9 * np.sin(np.linspace(-99 * np.pi, 99 * np.pi, num=1000)))
+
+lag_plot(data, width=400, height=400)
+```
+
+
+### Autocorrelation Plot
+
+**NOT SUPPORTED**
+
+### Bootstrap Plot
+
+**NOT SUPPORTED**
+
+### RadViz
+
+**NOT SUPPORTED**
+
+
+
+
+## Plot Formatting
+
+### General plot style arguments
+
+Most plotting methods have a set of keyword arguments that control the layout and formatting of the returned plot:
+
+
+```python
+ts.plot(c='k', line_dash='dashed', label='Series')
+```
+
+For each kind of plot (e.g. *line*, *bar*, *scatter*) any additional arguments keywords are passed along to the corresponding holoviews object (`hv.Curve`, `hv.Bar`, `hv.Scatter`). These can be used to control additional styling, beyond what pandas provides.
+
+### Controlling the Legend
+
+You may set the `legend` argument to `False` to hide the legend, which is shown by default. You can also control the placement of the legend using the same `legend` argument set to one of: 'top_right', 'top_left', 'bottom_left', 'bottom_right', 'right', 'left', 'top', or 'bottom'.
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 4), 
+                  index=ts.index, columns=list('ABCD'))
+df = df.cumsum()
+
+df.plot(legend=False)
+```
+
+
+```python
+df.plot(legend='top_left')
+```
+
+### Scales
+
+You may pass `logy` to get a log-scale Y axis, similarly use `logx` to get a log-scale on the X axis or `logz` to get a log-scale on the color axis.
+
+
+```python
+ts = pd.Series(np.random.randn(1000), 
+               index=pd.date_range('1/1/2000', periods=1000))
+
+ts = np.exp(ts.cumsum())
+
+ts.plot(logy=True)
+```
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 2), columns=['a', 'b'])
+df['b'] = df['b'] + np.arange(1000)
+df.plot.hexbin(x='a', y='b', gridsize=25, width=500, height=400, logz=True)
+```
+
+### Plotting on a Secondary Y-axis
+
+**NOT SUPPORTED**
+
+### Suppressing tick resolution adjustment
+pandas includes automatic tick resolution adjustment for regular frequency time-series data. For limited cases where pandas cannot infer the frequency information (e.g., in an externally created twinx), you can choose to suppress this behavior for alignment purposes.
+
+Here is the default behavior, notice how the x-axis tick labeling is performed:
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 4), 
+                  index=ts.index, columns=list('ABCD'))
+df = df.cumsum()
+df.A.plot()
+```
+
+Formatters can be set using format strings, by declaring bokeh TickFormatters, or using custom functions. See [HoloViews Tick Docs](https://holoviews.org/user_guide/Customizing_Plots.html#Axis-ticks) for more information.
+
+
+```python
+from bokeh.models.formatters import DatetimeTickFormatter
+
+formatter = DatetimeTickFormatter(months='%b %Y')
+```
+
+
+```python
+df.A.plot(yformatter='$%.2f', xformatter=formatter)
+```
+
+### Subplots
+
+Each `Series` in a `DataFrame` can be plotted on a different axis with the `subplots` keyword:
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 4), 
+                  index=ts.index, columns=list('ABCD'))
+df = df.cumsum()
+df.plot(subplots=True, height=150).cols(1)
+```
+
+### Controlling layout and targeting multiple axes
+
+The layout of subplots can be specified using `.cols(n)`.
+
+
+```python
+df.plot(subplots=True, shared_axes=False, width=150).cols(3)
+```
+
+### Plotting with error bars
+
+Plotting with error bars is *not* supported in `DataFrame.plot()` and `Series.plot()`. To add errorbars, users should fall back to using hvplot directly.
+
+
+```python
+import hvplot.pandas  # noqa
+```
+
+
+```python
+df3 = pd.DataFrame({'data1': [3, 2, 4, 3, 2, 4, 3, 2],
+                    'data2': [6, 5, 7, 5, 4, 5, 6, 5]})
+mean_std = pd.DataFrame({'mean': df3.mean(), 'std': df3.std()})
+mean_std
+```
+
+
+```python
+(mean_std.plot.bar(y='mean', alpha=0.7) * \
+ mean_std.hvplot.errorbars(x='index', y='mean', yerr1='std')
+).opts(show_legend=False).redim.range(mean=(0, 6.5))
+```
+
+### Plotting tables
+
+The matplotlib backend includes support for the `table` keyword in `DataFrame.plot()` and `Series.plot()`. This same effect can be accomplished with holoviews by using `hvplot.table` and creating a layout of the resulting plots.
+
+
+```python
+df = pd.DataFrame(np.random.rand(5, 3), columns=['a', 'b', 'c'])
+
+(df.plot(xaxis=False, legend='top_right') + \
+ df.T.hvplot.table()).cols(1)
+```
+
+### Colormaps
+
+A potential issue when plotting a large number of columns is that it can be difficult to distinguish some series due to repetition in the default colors. To remedy this, DataFrame plotting supports the use of the `colormap` argument, which accepts either a colormap or a string that is a name of a colormap.
+
+To use the cubehelix colormap, we can pass `colormap='cubehelix'`.
+
+
+```python
+df = pd.DataFrame(np.random.randn(1000, 10), index=ts.index)
+df = df.cumsum()
+df.plot(colormap='cubehelix')
+```
+
+Colormaps can also be used with other plot types, like bar charts:
+
+
+```python
+dd = pd.DataFrame(np.random.randn(10, 10)).applymap(abs)
+dd = dd.cumsum()
+dd.plot.bar(colormap='Greens')
+```
+
+Parallel coordinates charts:
+
+
+```python
+from bokeh.sampledata import iris
+from hvplot import parallel_coordinates, andrews_curves
+
+data = iris.flowers
+parallel_coordinates(data, 'species', colormap='gist_rainbow')
+```
+
+Andrews curves charts:
+
+
+```python
+andrews_curves(data, 'species', colormap='winter')
+```
+
+## Plotting directly with holoviews
+
+In some situations it may still be preferable or necessary to prepare plots directly with hvplot or holoviews, for instance when a certain type of plot or customization is not (yet) supported by pandas. `Series` and `DataFrame` objects behave like arrays and can therefore be passed directly to holoviews functions without explicit casts.
+
+
+```python
+import holoviews as hv
+
+price = pd.Series(np.random.randn(150).cumsum(),
+                  index=pd.date_range('2000-1-1', periods=150, freq='B'), name='price')
+ma = price.rolling(20).mean()
+mstd = price.rolling(20).std()
+
+price.plot(c='k') * ma.plot(c='b', label='mean') * \
+hv.Area((mstd.index, ma - 2 * mstd, ma + 2 * mstd), 
+        vdims=['y', 'y2']).opts(color='b', alpha=0.2)
+```

hvplot_docs/Plots_and_Renderers.md

@@ -0,0 +1,343 @@
+```python
+import holoviews as hv
+import numpy as np
+```
+
+HoloViews ordinarily hides the plotting machinery from the user. This allows for very quick iteration over different visualizations to explore a dataset, however it is often important to customize the precise details of a plot. HoloViews makes it very easy to customize existing plots, or even create completely novel plots. This manual will provide a general overview of the plotting system.
+
+The separation of the data from the precise details of the visualization is one of the core principles of the HoloViews. [``Elements``](http://holoviews.org/reference/index.html#elements) provide thin wrappers around chunks of actual data, while [containers](http://holoviews.org/reference/index.html#containers) allow composing these Elements into overlays, layouts, grids and animations/widgets. Each Element or container type has a corresponding plotting class, which renders a visual representation of the data for a particular backend. While the precise details of the implementation differ between backends to accommodate the vastly different APIs  plotting backends provide, many of the high-level details are shared across backends.
+
+# The Store object
+
+The association between an Element or container and the backend specific plotting class is held on the global ``Store`` object. The ``Store`` object holds a ``registry`` of plot objects for each backend. We can view the registry for each backend by accessing ``Store.registry`` directly:
+
+
+```python
+import holoviews.plotting.mpl
+list(hv.Store.registry['matplotlib'].items())[0:5]
+```
+
+The Store object provides a global registry not only for the plots themselves but also creates an entry in the OptionsTree for that particular backend. This allows options for that backend to be validated and enables setting plot, style and normalization options via the [Options system](03-Applying_Customizations.ipynb) system. We can view the ``OptionsTree`` object by requesting it from the store. We'll make a copy with just the first few entries so we can view the structure of the tree:
+
+
+```python
+opts = hv.Store.options(backend='matplotlib')
+hv.core.options.OptionTree(opts.items()[0:10], groups=['plot', 'style', 'norm'])
+```
+
+# Saving and rendering
+
+The easiest entry points to rendering a HoloViews object either to the backend specific representation (e.g. a matplotlib figure) or directly to file are the ``hv.render`` and ``hv.save`` functions. Both are shortcuts for using an actual ``Renderer`` object, which will be introduced in the next section. To start with we will create a simple object, a ``Scatter`` element:
+
+
+```python
+curve = hv.Curve(range(10))
+curve
+```
+
+This abstract and declarative representation of a ``Curve`` can be turned into an actual plot object, defaulting to the currently selected (or default) backend:
+
+
+```python
+fig = hv.render(curve)
+print(type(fig))
+```
+
+By providing an explicit ``backend`` keyword the plot can be rendered using a different backend.
+
+
+```python
+p = hv.render(curve, backend='bokeh')
+print(type(p))
+```
+
+This can often be useful to customize a plot in more detail by tweaking styling in ways that are not directly supported by HoloViews. An alternative to ``hv.render`` in case you do not want to fully switch to the underlying plotting API are ``hooks``, which are a plot option on all elements. These allow defining hooks which modify a plot after it has been rendered in the backend but before it is displayed.
+
+A ``hook`` is given the HoloViews plot instance and the currently rendered element and thereby provides access to the rendered plot object to apply any customizations and changes which are not exposed by HoloViews:
+
+
+```python
+def hook(plot, element):
+    # Allows accessing the backends figure object
+    plot.state
+    
+    # The handles contain common plot objects
+    plot.handles
+
+curve = curve.opts(hooks=[hook])
+```
+
+Hooks allow for extensive tweaking of objects before they are finished rendering, without having to entirely abandon HoloViews' API and render the backend's plot object manually.
+
+In much the same way the ``hv.save`` function allows exporting plots straight to a file, by default inferring the format from the file extension:
+
+
+```python
+hv.save(curve, 'curve.png')
+```
+
+Just like ``hv.render`` the ``hv.save`` function also allows specifying an explicit backend.
+
+
+```python
+hv.save(curve, 'curve.html', backend='bokeh')
+```
+
+Additionally for ambiguous file extensions such as HTML it may be necessary to specify an explicit fmt to override the default, e.g. in the case of 'html' output the widgets will default to ``fmt='widgets'``, which may be changed to scrubber widgets using ``fmt='scrubber'``.
+
+# Renderers
+
+HoloViews provides a general ``Renderer`` baseclass, which defines a general interface to render the output from different backends to a number of standard output formats such as ``png``, ``html`` or ``svg``. The ``__call__`` method on the Renderer automatically looks up and instantiates the registered plotting classes for an object it is passed and then returns the output in the requested format. To make this a bit clearer we'll break this down step by step. First we'll get a handle on the ``MPLRenderer`` and create an object to render.
+
+Renderers aren't registered with the Store until the corresponding backends have been imported. Loading the notebook extension with ``hv.notebook_extension('matplotlib')`` is one way of loading a backend and registering a renderer. Another is to simply import the corresponding plotting module as we did above.
+
+
+```python
+hv.Store.renderers
+```
+
+This is one way to access a Renderer, another is to instantiate a Renderer instance directly, allowing you to override some of the default plot options.
+
+
+```python
+renderer = hv.plotting.mpl.MPLRenderer.instance(dpi=120)
+```
+
+The recommended way to get a handle on a renderer is to use the ``hv.renderer`` function which will also handle imports for you:
+
+
+```python
+hv.renderer('matplotlib')
+```
+
+# Working with a Renderer
+
+A ``Renderer`` in HoloViews is responsible for instantiating a HoloViews plotting class. It does this by looking up the plotting class in the ``Store.registry``:
+
+
+```python
+hv.Store.registry['matplotlib'][hv.Curve]
+```
+
+If we create a ``Curve`` we can instantiate a plotting class from it using the ``Renderer.get_plot`` method:
+
+
+```python
+curve = hv.Curve(range(10))
+curve_plot = renderer.get_plot(curve)
+curve_plot
+```
+
+We will revisit how to work with ``Plot`` instances later. For now all we need to know is that they are responsible for translating the HoloViews object (like the ``Curve``) into a backend specific plotting object, accessible on ``Plot.state``:
+
+
+```python
+print(type(curve_plot.state), curve_plot.state)
+curve_plot.state
+```
+
+In case of the matplotlib backend this is a ``Figure`` object. However the ``Renderer`` ignores the specific representation of the plot, instead providing a unified interface to translating it into a representation that can displayed, i.e. either an image format or an HTML representation.
+
+In this way we can convert the curve directly to its ``png`` representation by calling the ``Renderer`` with the object and the format:
+
+
+```python
+from IPython.display import display_png
+png, info = renderer(curve, fmt='png')
+print(info)
+display_png(png, raw=True)
+```
+
+<div class="alert alert-success">
+Tip: To find more information about any HoloViews object use <code>hv.help</code> to print a detailed docstring.
+</div>
+
+The valid figure display formats can be seen in the docstring of the Renderer or directly on the parameter:
+
+
+```python
+renderer.param['fig'].objects
+```
+
+Note that to export PNG files using the [bokeh renderer](./Plotting_with_Bokeh.ipynb) you may need to install some additional dependencies [detailed here](https://bokeh.pydata.org/en/latest/docs/user_guide/export.html). If you are using conda, it is currently sufficient to run ``conda install selenium phantomjs pillow``.
+
+In this way we can easily render the plot in different formats:
+
+
+```python
+from IPython.display import display_svg
+svg, info = renderer(curve, fmt='svg')
+print(info)
+display_svg(svg, raw=True)
+```
+
+We could save these byte string representations ourselves but the ``Renderer`` provides a convenient ``save`` method to do so. Simply supply the object the filename and the format, which doubles as the file extension:
+
+
+```python
+renderer.save(curve, '/tmp/test', fmt='png')
+```
+
+Another convenient way to render the object is to wrap it in HTML, which we can do with the ``html`` method:
+
+
+```python
+from IPython.display import display_html
+html = renderer.html(curve)
+display_html(html, raw=True)
+```
+
+Rendering plots containing ``HoloMap`` and ``DynamicMap`` objects will automatically generate a Panel HoloViews pane which can be rendered in the notebook, saved or rendered as a server app:
+
+
+```python
+holomap = hv.HoloMap({i: hv.Image(np.random.rand(10, 10)) for i in range(3)})
+widget = renderer.get_widget(holomap, 'widgets')
+widget
+```
+
+However most of the time it is more convenient to let the Renderer export the widget HTML, again via a convenient method, which will export a HTML document with all the required JS and CSS dependencies:
+
+
+```python
+html = renderer.static_html(holomap)
+```
+
+This covers the basics of working with HoloViews renderers. This API is consistent across plotting backends, whether matplotlib, bokeh or plotly.
+
+# Plots
+
+Above we saw how the Renderer looks up the appropriate plotting class but so far we haven't seen how the plotting actually works. Since HoloViews already nests the data into semantically meaningful components, which define the rough layout of the plots on the page, the plotting classes follow roughly the same hierarchy. To review this hierarchy have a look at the [nesting diagram](./06-Building_Composite_Objects.ipynb#Nesting-hierarchy-) in the Building Composite objects guide.
+
+The Layout and GridSpace plotting classes set up the figure and axes appropriately and then instantiate the subplots for all the objects that are contained within. For this purpose we will create a relatively complex object, a ``Layout`` of ``HoloMap``s containing ``Overlay``s containing ``Elements``. We'll instantiate the matching plotting hierarchy and then inspect it.
+
+
+```python
+hmap1 = hv.HoloMap({i: hv.Image(np.random.rand(10, 10)) * hv.Ellipse(0, 0, 0.2*i) for i in range(5)})
+element = hv.Curve((range(10), np.random.rand(10)))
+layout = hmap1 + element
+```
+
+We can see the hierarchy in the object's repr:
+
+
+```python
+print( repr(layout) )
+```
+
+Now that we've created the object we can again use the ``MPLRenderer`` to instantiate the plot:
+
+
+```python
+layout_plot = renderer.get_plot(layout)
+layout_plot
+```
+
+During instantiation the LayoutPlot expanded each object and created subplots. We can access them via a row, column based index and thereby view the first plot.
+
+
+```python
+adjoint_plot = layout_plot.subplots[0, 0]
+adjoint_plot
+```
+
+This plotting layer handles plots adjoined to the plot. They are indexed by their position in the AdjointLayout which may include 'top', 'right' and 'main':
+
+
+```python
+overlay_plot = adjoint_plot.subplots['main']
+overlay_plot
+```
+
+Now we've drilled all the way down to the OverlayPlot level, we see as expected that this contains two further subplots, one for the ``Image`` and one for ``Text`` Element. 
+
+
+```python
+overlay_plot.subplots.keys()
+```
+
+Now you might have noticed that the HoloMap seems to have disappeared from the hierarchy. This is because updating a particular plot is handled by the ``ElementPlots`` itself. With that knowledge we can now have a look at the actual plotting API.
+
+### Traversing plots
+
+When working with such deeply nested plots accessing leafs can be a lot of effort, therefore the plots also provide a ``traverse`` method letting you specify the types of plots you want to access:
+
+
+```python
+layout_plot.traverse(specs=[hv.plotting.mpl.CurvePlot])
+```
+
+# Plotting API
+
+There a few methods shared by all plotting classes, which allow the renderer to easily create, update and render a plot. The three most important methods and attributes are:
+
+* ``Plot.__init__`` - The constructor already handles a lot of the processing in a plot, it sets up all the subplots if there are any, computes ranges across the object to normalize the display, sets the options that were specified and instantiates the figure, axes, model graphs, or canvas objects depending on the backend.
+* ``Plot.initialize_plot`` - This method draws the initial frame to the appropriate figure, axis or canvas, setting up the various artists (matplotlib) or glyphs (bokeh).
+* ``Plot.update`` - This method updates an already instantiated plot with the data corresponding to the supplied key. This key should match the key in the HoloMap.
+
+### Initializing
+
+The Renderer and the widgets use these three methods to instantiate and update a plot to render both static frames and animations or widgets as defined by the ``HoloMap`` or ``DynamicMap``. Above we already instantiated a plot, now we initialize it, thereby drawing the first (or rather last frame).
+
+
+```python
+fig = layout_plot.initialize_plot()
+fig
+```
+
+### Updating
+
+We can see ``initialize_plot`` has rendered the last frame with the key ``4``. We can update the figure with another key simply by calling the ``Plot.update`` method with the corresponding key.
+
+
+```python
+layout_plot.update(0)
+```
+
+
+```python
+plot = hv.plotting.mpl.RasterPlot(holomap)
+plot
+```
+
+Internally each level of the plotting hierarchy updates all the objects below it, all the way down to the ElementPlots, which handle updating the plotting data.
+
+### Dynamic plot updates
+
+Since DynamicMaps may be updated based on stream events they don't work via quite the same API. Each stream automatically captures the plots it is attached to and whenever it receives an event it will update the plot.
+
+
+```python
+dmap = hv.DynamicMap(lambda x: hv.Points(np.arange(x)), kdims=[], streams=[hv.streams.PointerX(x=10)])
+plot = renderer.get_plot(dmap)
+plot.initialize_plot()
+```
+
+Internally the update to the stream value will automatically trigger the plot to update, here we will disable this by setting ``trigger=False`` and explicitly calling ``refresh`` on the plot:
+
+
+```python
+dmap.event(x=20,)
+plot.refresh()
+plot.state
+```
+
+### Plotting handles
+
+In addition to accessing the overall state of the plot each plotting class usually keeps direct handles for important plotting elements on the ``handles`` attribute:
+
+
+```python
+plot.handles
+```
+
+Here we can see how the ``PointPlot`` keeps track of the artist, which is a matplotlib ``PathCollection``, the axis, the figure and the plot title. In addition all matplotlib plots also keep track of a list of any additional plotting elements which should be considered in the bounding box calculation.
+
+This is only the top-level API, which is used by the Renderer to render the plot, animation or widget. Each backend has internal APIs to create and update the various plot components.
+
+### Using the matplotlib renderer outside of a Jupyter notebook
+
+The matplotlib renderer can be used outside of a notebook by using the `show` method. If running in a python script, this will cause the usual matplotlib window to appear. This is done as follows:
+
+    mr = hv.renderer('matplotlib')
+    mr.show(curve)

hvplot_docs/Plotting.md

@@ -0,0 +1,325 @@
+As we discovered in the [Introduction](Introduction.ipynb), HoloViews allows plotting a variety of data types. Here we will use the sample data module and load the pandas and dask hvPlot API:
+
+
+```python
+import numpy as np
+import hvplot.pandas  # noqa
+import hvplot.dask  # noqa
+```
+
+As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.holoviz.org) app.
+
+HoloViews provides an extensive, very rich set of objects along with a powerful set of operations to apply, as you can find out in the [HoloViews User Guide](https://holoviews.org/user_guide/index.html). But here we will focus on the most essential mechanisms needed to make your data visualizable, without having to worry about the mechanics going on behind the scenes.
+
+We will be focusing on two different datasets:
+
+- A small CSV file of US crime data, broken down by state
+- A larger Parquet-format file of airline flight data
+
+The ``hvplot.sample_data`` module makes these datasets Intake data catalogue, which we can load either using pandas:
+
+
+```python
+from hvplot.sample_data import us_crime, airline_flights
+
+crime = us_crime.read()
+print(type(crime))
+crime.head()
+```
+
+Or using dask as a ``dask.DataFrame``:
+
+
+```python
+flights = airline_flights.to_dask().persist()
+print(type(flights))
+flights.head()
+```
+
+## The plot interface
+
+The ``dask.dataframe.DataFrame.hvplot``, ``pandas.DataFrame.hvplot`` and ``intake.DataSource.plot`` interfaces (and Series equivalents) from HvPlot provide a powerful high-level API to generate complex plots. The ``.hvplot`` API can be called directly or used as a namespace to generate specific plot types.
+
+### The plot method
+
+The most explicit way to use the plotting API is to specify the names of columns to plot on the ``x``- and ``y``-axis respectively:
+
+
+```python
+crime.hvplot.line(x='Year', y='Violent Crime rate')
+```
+
+As you'll see in more detail below, you can choose which kind of plot you want to use for the data:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate', kind='scatter')
+```
+
+To group the data by one or more additional columns, specify an additional ``by`` variable. As an example here we will plot the departure delay ('depdelay') as a function of 'distance', grouping the data by the 'carrier'. There are many available carriers, so we will select only two of them so that the plot is readable:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['OH', 'F9'])]
+flight_subset.hvplot(x='distance', y='depdelay', by='carrier', kind='scatter', alpha=0.2, persist=True)
+```
+
+Here we have specified the `x` axis explicitly, which can be omitted if the Pandas index column is already the desired x axis. Similarly, here we specified the `y` axis; by default all of the non-index columns would be plotted (which would be a lot of data in this case). If you don't specify the 'y' axis, it will have a default label named 'value', but you can then provide a y axis label explicitly using the ``value_label`` option.
+
+Putting all of this together we will plot violent crime, robbery, and burglary rates on the y-axis, specifying 'Year' as the x, and relabel the y-axis to display the 'Rate'.
+
+
+```python
+crime.hvplot(x='Year', y=['Violent Crime rate', 'Robbery rate', 'Burglary rate'],
+             value_label='Rate (per 100k people)')
+```
+
+### The hvplot namespace
+
+Instead of using the ``kind`` argument to the plot call, we can use the ``hvplot`` namespace, which lets us easily discover the range of plot types that are supported. Use tab completion to explore the available plot types:
+
+```python
+crime.hvplot.<TAB>
+```
+
+Plot types available include:
+
+* <a href="#area">``.area()``</a>: Plots a  area chart similar to a line chart except for filling the area under the curve and optionally stacking 
+* <a href="#bars">``.bar()``</a>: Plots a bar chart that can be stacked or grouped
+* <a href="#bivariate">``.bivariate()``</a>: Plots 2D density of a set of points 
+* <a href="#box-whisker-plots">``.box()``</a>: Plots a box-whisker chart comparing the distribution of one or more variables
+* <a href="#heatmap">``.heatmap()``</a>: Plots a heatmap to visualizing a variable across two independent dimensions
+* <a href="#hexbins">``.hexbins()``</a>: Plots hex bins
+* <a href="#histogram">``.hist()``</a>: Plots the distribution of one or histograms as a set of bins
+* <a href="#kde-density">``.kde()``</a>: Plots the kernel density estimate of one or more variables.
+* <a href="#the-plot-method">``.line()``</a>: Plots a line chart (such as for a time series)
+* <a href="#scatter">``.scatter()``</a>: Plots a scatter chart comparing two variables
+* <a href="#step">``.step()``</a>: Plots a step chart akin to a line plot
+* <a href="#tables">``.table()``</a>: Generates a SlickGrid DataTable
+* <a href="#groupby">``.violin()``</a>: Plots a violin plot comparing the distribution of one or more variables using the kernel density estimate
+
+#### Area
+
+Like most other plot types the ``area`` chart supports the three ways of defining a plot outlined above. An area chart is most useful when plotting multiple variables in a stacked chart. This can be achieve by specifying ``x``, ``y``, and ``by`` columns or using the ``columns`` and ``index``/``use_index`` (equivalent to ``x``) options:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+We can also explicitly set ``stacked`` to False and define an ``alpha`` value to compare the values directly:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Aggravated assault', 'Robbery'], stacked=False, alpha=0.4)
+```
+
+Another use for an area plot is to visualize the spread of a value. For instance using the flights dataset we may want to see the spread in mean delay values across carriers. For that purpose we compute the mean delay by day and carrier and then the min/max mean delay for across all carriers. Since the output of ``hvplot`` is just a regular holoviews object, we can use the overlay operator (\*) to place the plots on top of each other.
+
+
+```python
+delay_min_max = flights.groupby(['day', 'carrier'])['carrier_delay'].mean().groupby('day').agg({'min': np.min, 'max': np.max})
+delay_mean = flights.groupby('day')['carrier_delay'].mean()
+
+delay_min_max.hvplot.area(x='day', y='min', y2='max', alpha=0.2) * delay_mean.hvplot()
+```
+
+#### Bars
+
+In the simplest case we can use ``.hvplot.bar`` to plot ``x`` against ``y``. We'll use ``rot=90`` to rotate the tick labels on the x-axis making the years easier to read:
+
+
+```python
+crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90)
+```
+
+If we want to compare multiple columns instead we can set ``y`` to a list of columns. Using the ``stacked`` option we can then compare the column values more easily:
+
+
+```python
+crime.hvplot.bar(x='Year', y=['Violent crime total', 'Property crime total'],
+                 stacked=True, rot=90, width=800, legend='top_left')
+```
+
+#### Scatter
+
+The scatter plot supports many of the same features as the other chart types we have seen so far but can also be colored by another variable using the ``c`` option. 
+
+
+```python
+crime.hvplot.scatter(x='Violent Crime rate', y='Burglary rate', c='Year')
+```
+
+Anytime that color is being used to represent a dimension, the ``cmap`` option can be used to control the colormap that is used to represent that dimension. Additionally, the colorbar can be disabled using ``colorbar=False``.
+
+#### Step
+
+A step chart is very similar to a line chart but instead of linearly interpolating between samples the step chart visualizes discrete steps. The point at which to step can be controlled via the ``where`` keyword allowing `'pre'`, `'mid'` (default) and `'post'` values:
+
+
+```python
+crime.hvplot.step(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+#### HexBins
+
+You can create hexagonal bin plots with the ``hexbin`` method. Hexbin plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually. Since these data are not regularly distributed, we'll use the ``logz`` option to map z-axis (color) to a log scale colorbar.
+
+
+```python
+flights.hvplot.hexbin(x='airtime', y='arrdelay', width=600, height=500, logz=True)
+```
+
+#### Bivariate
+
+You can create a 2D density plot with the ``bivariate`` method. Bivariate plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually.
+
+
+```python
+crime.hvplot.bivariate(x='Violent Crime rate', y='Burglary rate', width=600, height=500)
+```
+
+#### HeatMap
+
+A ``HeatMap`` lets us view the relationship between three variables, so we specify the 'x' and 'y' variables and an additional 'C' variable. Additionally we can define a ``reduce_function`` that computes the values for each bin from the samples that fall into it. Here we plot the 'depdelay' (i.e. departure delay) for each day of the month and carrier in the dataset:
+
+
+```python
+flights.compute().hvplot.heatmap(x='day', y='carrier', C='depdelay', reduce_function=np.mean, colorbar=True)
+```
+
+#### Tables
+
+Unlike all other plot types, a table only supports one signature: either all columns are plotted, or a subset of columns can be selected by defining the ``columns`` explicitly:
+
+
+```python
+crime.hvplot.table(columns=['Year', 'Population', 'Violent Crime rate'], width=400)
+```
+
+### Distributions
+
+Plotting distributions differs slightly from other plots since they plot only one variable in the simple case rather than plotting two or more variables against each other. Therefore when plotting these plot types no ``index`` or ``x`` value needs to be supplied. Instead:
+
+1. Declare a single ``y`` variable, e.g. ``source.plot.hist(variable)``, or
+2. Declare a ``y`` variable and ``by`` variable, e.g. ``source.plot.hist(variable, by='Group')``, or
+3. Declare columns or plot all columns, e.g. ``source.plot.hist()`` or ``source.plot.hist(columns=['A', 'B', 'C'])``
+
+#### Histogram
+
+The Histogram is the simplest example of a distribution; often we simply plot the distribution of a single variable, in this case the 'Violent Crime rate'. Additionally we can define a range over which to compute the histogram and the number of bins using the ``bin_range`` and ``bins`` arguments respectively:
+
+
+```python
+crime.hvplot.hist(y='Violent Crime rate')
+```
+
+Or we can plot the distribution of multiple columns:
+
+
+```python
+columns = ['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.hist(y=columns, bins=50, alpha=0.5, legend='top', height=400)
+```
+
+We can also group the data by another variable. Here we'll use ``subplots`` to split each carrier out into its own plot:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.hist('depdelay', by='carrier', bins=20, bin_range=(-20, 100), width=300, subplots=True)
+```
+
+#### KDE (density)
+
+You can also create density plots using ``hvplot.kde()`` or ``hvplot.density()``:
+
+
+```python
+crime.hvplot.kde(y='Violent Crime rate')
+```
+
+Comparing the distribution of multiple columns is also possible:
+
+
+```python
+columns=['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.kde(y=columns, alpha=0.5, value_label='Rate', legend='top_right')
+```
+
+The ``hvplot.kde`` also supports the ``by`` keyword:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.kde('depdelay', by='carrier', xlim=(-20, 70), width=300, subplots=True)
+```
+
+#### Box-Whisker Plots
+
+Just like the other distribution-based plot types, the box-whisker plot supports plotting a single column:
+
+
+```python
+crime.hvplot.box(y='Violent Crime rate')
+```
+
+It also supports multiple columns and the same options as seen previously (``legend``, ``invert``, ``value_label``):
+
+
+```python
+columns=['Burglary rate', 'Larceny-theft rate', 'Motor vehicle theft rate',
+         'Property crime rate', 'Violent Crime rate']
+crime.hvplot.box(y=columns, group_label='Crime', legend=False, value_label='Rate (per 100k)', invert=True)
+```
+
+Lastly, it also supports using the ``by`` keyword to split the data into multiple subsets:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.box('depdelay', by='carrier', ylim=(-10, 70))
+```
+
+## Composing Plots
+
+One of the core strengths of HoloViews is the ease of composing
+different plots. Individual plots can be composed using the ``*`` and
+``+`` operators, which overlay and compose plots into layouts
+respectively. For more information on composing objects, see the
+HoloViews [User Guide](https://holoviews.org/user_guide/Composing_Elements.html).
+
+By using these operators we can combine multiple plots into composite plots. A simple example is overlaying two plot types:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate') * crime.hvplot.scatter(x='Year', y='Violent Crime rate', c='k')
+```
+
+We can also lay out different plots and tables together:
+
+
+```python
+(crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90, width=550) +
+ crime.hvplot.table(['Year', 'Population', 'Violent Crime rate'], width=420))
+```
+
+## Large data
+
+The previous examples summarized the fairly large airline dataset using statistical plot types that aggregate the data into a feasible subset for plotting.  We can instead aggregate the data directly into the viewable image using [datashader](https://datashader.org), which provides a rendering of the entire set of raw data available (as far as the resolution of the screen allows). Here we plot the 'airtime' against the 'distance':
+
+
+```python
+flights.hvplot.scatter(x='distance', y='airtime', datashade=True)
+```
+
+## Groupby
+
+Thanks to the ability of HoloViews to explore a parameter space with a set of widgets we can apply a groupby along a particular column or dimension. For example we can view the distribution of departure delays by carrier grouped by day, allowing the user to choose which day to display:
+
+
+```python
+flights.hvplot.violin(y='depdelay', by='carrier', groupby='dayofweek', ylim=(-20, 60), height=500)
+```
+
+This user guide merely provided an overview over the available plot types; to see a detailed description on how to customize plots see the [Customization](Customization.ipynb) user guide.

hvplot_docs/Plotting_Extensions.md

@@ -0,0 +1,109 @@
+```python
+from hvplot.sample_data import us_crime
+```
+
+hvPlot allows to generate plots with three different plotting extensions: [Bokeh](https://docs.bokeh.org), [Matplotlib](https://matplotlib.org/) and [Plotly](https://plotly.com/). Support for Maplotlib and Plotly was added in version 0.8.0, before which Bokeh was the only option available and is as such kept as the default plotting extension.
+
+## Loading plotting extensions
+
+Importing hvPlot accessors as shown throughout the documentation (e.g. `import hvplot.pandas`, `import hvplot.xarray`, ...) loads by default the Bokeh plotting extension. The `extension` function can be used after this first import to additionally load the Matplotlib and Plotly plotting extensions, or just one of them. The currently active extension is the first one passed to `extension()`.
+
+
+```python
+import hvplot.pandas  # This import automatically loads the Bokeh extension.
+```
+
+
+```python
+hvplot.extension('matplotlib', 'plotly')  # This call loads the Matplotlib (the active one) and Plotly extensions.
+```
+
+
+```python
+us_crime.hvplot(x='Year', y='Violent Crime rate')
+```
+
+## Switching the plotting extension
+
+The `output` function allows to switch the plotting extension by setting the `backend` parameter. It must be called **after** importing an accessor (e.g. `import hvplot.pandas`) and calling to `extension`:
+
+
+```python
+hvplot.output(backend='plotly')
+
+us_crime.hvplot(x='Year', y='Violent Crime rate')
+```
+
+<div class="alert alert-warning" role="alert">
+    The <code>extension</code> function could also be used to switch the plotting extension. You should however prefer <code>output</code> as any call to <code>extension</code> actually internally loads code in the output of the cell where it is executed, which can significantly increase the notebook size if <code>extension</code> is called in multiple cells.
+</div>
+
+## Plot styling options
+
+On top of the parameters part of `.hvplot()`'s API, a plot can be further customized by providing detailed styling options. By default, i.e. without calling `hvplot.extension()`, the accepted styling options are those of Bokeh, such as `line_dash='dashed'`. When another extension is set with either `extension` or `output` the styling options of that extension are expected, e.g. `linestyle='dashed'` for Matplotlib.
+
+
+```python
+hvplot.output(backend='bokeh')
+us_crime.hvplot(x='Year', y='Violent Crime rate', line_dash='dashed')
+```
+
+
+```python
+hvplot.output(backend='matplotlib')
+us_crime.hvplot(x='Year', y='Violent Crime rate', linestyle='dashed')
+```
+
+It is also possible to generates plots with either Matplotlib or Plotly that are constructed with Bokeh options. This can be used for instance to create plots previously generated with Bokeh with another backend, without having to change any parameter. The only change required is to declare Bokeh as the compatible extension with `hvplot.extension('matplotlib', compatibility='bokeh')`, preferably at the beginning of the notebook.
+
+
+```python
+hvplot.extension('matplotlib', compatibility='bokeh')
+violent_crime = us_crime.hvplot(x='Year', y='Violent Crime rate', line_dash='dashed')
+violent_crime
+```
+
+
+```python
+violent_crime.opts.info()
+```
+
+You can see that `line_dash='dashed'` has been internally converted to `linestyle='dashed'` that is a valid option for the Matplotlib plotting extension. Note that support for all Bokeh options is currently incomplete and will continue to be improved while equivalent support for Plotly and Matplotlib is planned for a future release
+
+## Obtaining the underlying figure object 
+
+In some cases it can be convenient to construct a plot with hvPlot and then get a handle on the figure object of the underlying plotting library to further customize the plot or to embed it in some more complex application. The `render` function allows to get a handle on the figure object. The following examples show that it's possible to use the API of Bokeh, Matplotlib or Plotly to update the title of the `violent_crime` plot.
+
+
+```python
+violent_crime = us_crime.hvplot(x='Year', y='Violent Crime rate')
+```
+
+
+```python
+from bokeh.io import show
+
+bk_fig = hvplot.render(violent_crime, backend='bokeh')
+bk_fig.title = 'Violent crime'
+show(bk_fig)
+```
+
+
+```python
+%matplotlib inline
+mpl_fig = hvplot.render(violent_crime, backend='matplotlib')
+axes = mpl_fig.get_axes()
+axes[0].set_title('Violent crime')
+mpl_fig
+```
+
+
+```python
+from plotly.graph_objects import Figure
+
+plotly_fig = hvplot.render(violent_crime, backend='plotly')
+fig = Figure(plotly_fig).update_layout(title='Violent crime')
+fig
+```
+
+As demonstrated on this page hvPlot offers you the ability to choose your favorite plotting extension among those supported by [HoloViews](https://holoviews.org/), on which hvPlot is built.

hvplot_docs/Plotting_with_Bokeh.md

@@ -0,0 +1,549 @@
+# Plotting with Bokeh
+
+
+```python
+import numpy as np
+import pandas as pd
+import holoviews as hv
+from holoviews import dim, opts
+
+hv.extension('bokeh')
+```
+
+One of the major design principles of HoloViews is that the declaration of data is completely independent from the plotting implementation. Bokeh provides a powerful platform to generate interactive plots using HTML5 canvas and WebGL, and is ideally suited towards interactive exploration of data. By combining the ease of generating interactive, high-dimensional visualizations with the interactive widgets and fast rendering provided by Bokeh, HoloViews becomes even more powerful.
+
+This user guide will cover various interactive features that bokeh provides which is not covered by the more general user guides, including interactive tools, linked axes and brushing and more. The general principles behind customizing plots and styling the visual elements of a plot are covered in the [Style Mapping](04-Style_Mapping.ipynb) and [Customizing Plots](Customizing_Plots.ipynb) user guides.
+
+## Working with bokeh directly
+
+When HoloViews outputs bokeh plots it creates and manipulates bokeh models in the background. If at any time you need access to the underlying Bokeh representation of an object you can use the ``hv.render`` function to convert it. For example let us convert a HoloViews ``Image`` to a bokeh Figure, which will let us access and modify every aspect of the plot:
+
+
+```python
+img = hv.Image(np.random.rand(10, 10))
+
+fig = hv.render(img)
+
+print('Figure: ', fig)
+print('Renderers: ', fig.renderers[-1].glyph)
+```
+
+## Exporting static files
+
+Bokeh supports static export to png's using ``Selenium``, ``PhantomJS`` and ``pillow``, to install the required dependencies run:
+
+```
+conda install selenium phantomjs pillow
+```
+
+alternatively install PhantomJS from npm using:
+
+```
+npm install -g phantomjs-prebuilt
+```
+
+To switch to png output persistently you can run:
+
+```
+hv.output(fig='png')
+```
+
+
+```python
+violin = hv.Violin(np.random.randn(100))
+
+hv.output(violin, fig='png')
+```
+
+The exported png can also be saved to disk using the ``save`` function by changing the file extension from ``.html``, which exports an interactive plot, ``.png``:
+
+```python
+hv.save(violin, 'violin.png')
+```
+
+## Element Style options
+
+One of the major benefits of bokeh is that it was designed from the ground up with consistency in mind, therefore most style options are a combination of the fill, line, and text style options listed below:
+
+
+```python
+from holoviews.plotting.bokeh.styles import (line_properties, fill_properties, text_properties)
+print("""
+Line properties: %s\n
+Fill properties: %s\n
+Text properties: %s
+""" % (line_properties, fill_properties, text_properties))
+```
+
+Note also that most of these options support vectorized style mapping as described in the [Style Mapping user guide](04-Style_Mapping.ipynb). Here's an example of HoloViews Elements using a Bokeh backend, with bokeh's style options:
+
+
+```python
+curve_opts = opts.Curve(line_width=10, line_color='indianred', line_dash='dotted', line_alpha=0.5)
+point_opts = opts.Points(fill_color='#00AA00', fill_alpha=0.5, line_width=1, line_color='black', size=5)
+text_opts  = opts.Text(text_align='center', text_baseline='middle', text_color='gray', text_font='Arial')
+
+xs = np.linspace(0, np.pi*4, 100)
+data = (xs, np.sin(xs))
+
+(hv.Curve(data) + hv.Points(data) + hv.Text(6, 0, 'Here is some text')).opts(
+    curve_opts, point_opts, text_opts)
+```
+
+Notice that because the first two plots use the same underlying data, they become linked, such that zooming or panning one of the plots makes the corresponding change on the other.
+
+## Setting Backend Opts
+
+HoloViews does not expose every single option from Bokeh.
+
+Instead, HoloViews allow users to attach [hooks](Customizing_Plots.ipynb#plot-hooks) to modify the plot object directly--but writing these hooks could be cumbersome, especially if it's only used for a single line of update.
+
+Fortunately, HoloViews allows `backend_opts` for the Bokeh backend to configure options by declaring a dictionary with accessor specification for updating the plot components.
+
+For example, here's how to make the toolbar auto-hide.
+
+
+```python
+hv.Curve(data).opts(
+    backend_opts={"plot.toolbar.autohide": True}
+)
+```
+
+The following is the equivalent, as a hook.
+
+
+```python
+def hook(hv_plot, element):
+    toolbar = hv_plot.handles['plot'].toolbar
+    toolbar.autohide = True
+
+hv.Curve(data).opts(hooks=[hook])
+```
+
+Notice how much more concise it is with `backend_opts`!
+
+With knowledge of the attributes of Bokeh, it's possible to configure many other plot components besides `toolbar`. Some examples include `legend`, `colorbar`, `xaxis`, `yaxis`, and much, much more.
+
+If you're unsure, simply input your best guess and it'll try to provide a list of suggestions if there's an issue.
+
+## Sizing Elements
+
+In the bokeh backend the sizing of plots and specifically layouts of plots is determined in an inside-out or compositional manner. Each subplot can be sized independently and it will fill the allocated space. The sizing is determined by the combination of width, height, aspect and responsive options. In this section we will discover the different approaches to setting plot dimensions and aspects. 
+
+### Width and height
+
+The most straightforward approach to specifying the size of a plot is using a width and height specified in pixels. This is the default behavior and makes it easy to achieve precise alignment between plots but does not allow for keeping a constant aspect or responsive resizing. In particular, the specified size includes the axes and any legends or colorbars.
+
+
+```python
+points_a = hv.Points(data)
+points_b = hv.Points(data)
+
+points_a.opts(width=300, height=300) + points_b.opts(width=600, height=300)
+```
+
+### Frame width and height
+
+The frame width on the other hand provides precise control over the inner dimensions of a plot, it ensures the actual plot frame matches the specified dimensions exactly. This makes it possible to achieve a precise aspect ratio between the axis scales, without worrying about the size of axes, colorbars, titles and legends, e.g. below we can see two plots defined using explicit ``frame_width`` and ``frame_height`` share the same dimensions despite the fact that one has a colorbar.
+
+
+```python
+xs = ys  = np.arange(10)
+yy, xx = np.meshgrid(xs, ys)
+zz = xx*yy
+
+img = hv.Image(np.random.rand(100, 100))
+
+points_a.opts(frame_width=200, frame_height=200) +\
+img.opts(frame_width=200, frame_height=200, colorbar=True, axiswise=True)
+```
+
+### Aspect
+
+The ``aspect`` and ``data_aspect`` options provide control over the scaling of the plot dimensions and the axis limits.
+
+#### ``aspect``:
+
+The ``aspect`` specifies the ratio between the width and height dimensions of the plot. If specified this options takes absolute precedence over the dimensions of the plot but has no effect on the plot's axis limits. It supports the following options:
+
+* **``float``** : A numeric value will scale the ratio of plot width to plot height
+* **``"equal"``** : Sets aspect of the axis scaling to be equal, equivalent to **``data_aspect=1``**
+* **``"square"``** : Ensures the plot dimensions are square.
+
+#### ``data_aspect``:
+
+The ``data_aspect`` specifies the scaling between the x- and y-axis ranges. If specified this option will scale both the plot ranges and dimensions unless explicit ``aspect``, ``width`` or ``height`` value overrides the plot dimensions:
+
+* **``float``** : Sets ratio between the units on the x-scale and the y-scale
+
+
+```python
+xs = np.linspace(0, 10)
+ys = np.linspace(0, 5)
+
+img = hv.Image((xs, ys, xs[:, np.newaxis]*np.sin(ys*4)))
+
+(img.options(aspect='equal').relabel('aspect=\'equal\'') +
+ img.options(aspect='square', colorbar=True, frame_width=300).relabel('aspect=\'square\'') +
+ img.options(aspect=2).relabel('aspect=2') + 
+ img.options(data_aspect=2, frame_width=300).relabel('data_aspect=2')).cols(2)
+```
+
+## Responsive
+
+Since bokeh plots are rendered within a browser window which can be resized dynamically it supports responsive sizing modes allowing the plot to rescale when the window it is placed in is changed. If enabled, the behavior of ``responsive`` modes depends on whether an aspect or width/height option is set. Specifically 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. This leaves four different ``responsive`` modes:
+
+* **``scale_both``**: If neither a width or a height are defined but a fixed aspect is defined both axes will be scaled up to the maximum size of the container. Scaling ensures that the aspect ratio of the plot is maintained.
+* **``stretch_both``**: If neither a width, height or aspect are defined the plot will stretch to fill all available space.
+* **``stretch_width``**: If a height but neither a width or aspect are defined the plot will stretch to fill all available horizontal space.
+* **``stretch_height``**: If a width but neither a height or aspect are defined the plot will stretch to fill all available vertical space.
+
+**Note**: In the notebook stretching and scaling the height does not increase the size of a cell.
+
+As a simple example let us declare a plot that has a fixed height but stretches to fit all available horizontal space:
+
+
+```python
+hv.Points(data).opts(height=200, responsive=True, title='stretch width')
+```
+
+Similarly if we declare a fixed ``aspect`` or ``data_aspect`` responsive modes will try to fill all available space but avoid distorting the specified aspect:
+
+
+```python
+img.opts(data_aspect=0.5, responsive=True, title='scale both')
+```
+
+## Alignment
+
+The alignment of a plot in a row or column can be controlled using the ``align`` option. It controls both the vertical alignment in a row and the horizontal alignment in a column and can be set to one of `'start'`, `'center'` or `'end'` (where `'start'` is the default).
+
+#### Vertical
+
+
+```python
+points = hv.Points(data).opts(axiswise=True)
+img = hv.Image((xs, ys, xs[:, np.newaxis]*np.sin(ys*4)))
+
+img + points.opts(height=200, align='end')
+```
+
+#### Horizontal
+
+
+```python
+(img.opts(axiswise=True, width=200, align='center') + points).cols(1)
+```
+
+## Grid lines
+
+Grid lines can be controlled through the combination of ``show_grid`` and ``gridstyle`` parameters. The ``gridstyle`` allows specifying a number of options including:
+
+* ``grid_line_color``
+* ``grid_line_alpha``
+* ``grid_line_dash``
+* ``grid_line_width``
+* ``grid_bounds``
+* ``grid_band``
+
+These options may also be applied to minor grid lines by prepending the ``'minor_'`` prefix and may be applied to a specific axis by replacing ``'grid_`` with ``'xgrid_'`` or ``'ygrid_'``. Here we combine some of these options to generate a complex grid pattern:
+
+
+```python
+grid_style = {'grid_line_color': 'black', 'grid_line_width': 1.5, 'ygrid_bounds': (0.3, 0.7),
+              'minor_xgrid_line_color': 'lightgray', 'xgrid_line_dash': [4, 4]}
+
+hv.Points(np.random.rand(10, 2)).opts(gridstyle=grid_style, show_grid=True, size=5, width=600)
+```
+
+## Containers
+
+The bokeh plotting extension also supports a number of additional features relating to container components.
+
+### Tabs
+
+Using bokeh, both ``(Nd)Overlay`` and ``(Nd)Layout`` types may be displayed inside a ``tabs`` widget. This may be enabled via a plot option ``tabs``, and may even be nested inside a Layout.
+
+
+```python
+x,y = np.mgrid[-50:51, -50:51] * 0.1
+
+img = hv.Image(np.sin(x**2+y**2), bounds=(-1,-1,1,1))
+(img.relabel('Image') * img.sample(x=0).relabel('Cross-section')).opts(tabs=True)
+```
+
+Another reason to use ``tabs`` is that some Layout combinations may not be able to be displayed directly using HoloViews. For example, it is not currently possible to display a ``GridSpace`` as part of a ``Layout`` in any backend, and this combination will automatically switch to a ``tab`` representation for the bokeh backend.
+
+### Interactive Legends
+
+
+
+When using ``NdOverlay`` and ``Overlay`` containers each element will get a legend entry, which can be used to interactively toggle the visibility of the element. In this example we will create a number of ``Histogram`` elements each with a different mean. By setting a ``muted_fill_alpha`` we can define the style of the element when it is de-selected using the legend, simply try tapping on each legend entry to see the effect:
+
+
+```python
+hv.NdOverlay({i: hv.Histogram(np.histogram(np.random.randn(100)+i*2)) for i in range(5)}).opts(
+    'Histogram', width=600, alpha=0.8, muted_fill_alpha=0.1)
+```
+
+The other ``muted_`` options can be used to define other aspects of the Histogram style when it is unselected.
+
+If you have multiple plots in a ``Layout`` with the same legend label, muting one of them will automatically mute all of them. 
+
+
+```python
+overlay1 = hv.Curve([0, 0], label="A") * hv.Curve([1, 1], label="B")
+overlay2 = hv.Curve([2, 2], label="A") * hv.Curve([3, 3], label="B")
+layout = overlay1 + overlay2
+layout                                                           
+```
+
+If you want to turn off this behavior, use ``.opts(sync_legends=False)``
+
+
+```python
+layout.opts(sync_legends=False)
+```
+
+If you want to control the number of legend shown in the ``Layout`` or the position of them ``show_legends`` and ``legend_position`` can be used.
+
+
+```python
+layout.opts(sync_legends=True, show_legends=0, legend_position="top_left")
+```
+
+### Marginals
+
+
+The Bokeh backend also supports marginal plots to generate adjoined plots. The most convenient way to build an AdjointLayout is with the ``.hist()`` method.
+
+
+```python
+points = hv.Points(np.random.randn(500,2))
+points.hist(num_bins=51, dimension=['x','y'])
+```
+
+When the histogram represents a quantity that is mapped to a value dimension with a corresponding colormap, it will automatically share the colormap, making it useful as a colorbar for that dimension as well as a histogram.
+
+
+```python
+img.hist(num_bins=100, dimension=['x', 'y'], weight_dimension='z', mean_weighted=True) +\
+img.hist(dimension='z')
+```
+
+## Tools
+
+Bokeh provides a range of tools to interact with a plot and HoloViews adds a number of tools by default but also makes it easy to add additional tools. The ``default_tools`` define the list of tools that are added automatically and usually a user would override only the ``tools`` option to add additional tools. By default the ``default_tools`` include:
+
+    ['save', 'pan', 'wheel_zoom', 'box_zoom', 'reset']
+
+#### Toolbar
+
+The bokeh toolbar is added automatically and will be placed to the right for a single plot and on the top for a layout. Additionally for layouts of plots it will automatically merge the toolbars to avoid crowding the plot. However both behaviors can be customized, the toolbar can be hidden or moved to a different location on a plot by setting the ``toolbar`` option to one of:
+
+    ['above', 'below', 'left', 'right', 'disable', None]
+
+Secondly a layout or grid plot supports the ``merge_tools`` option which can be used to maintain one toolbar per plot:
+
+
+```python
+(hv.Curve([1, 2, 3]).opts(toolbar='above') + hv.Curve([1, 2, 3]).opts(toolbar=None)).opts(merge_tools=False)
+```
+
+#### Hover tools
+
+Some Elements allow revealing additional data by hovering over the data. To enable the hover tool, simply supply ``'hover'`` as a list to the ``tools`` plot option. By default the tool will display information for all the dimensions specified on the element:
+
+
+```python
+error = np.random.rand(100, 3)
+heatmap_data = {(chr(65+i), chr(97+j)):i*j for i in range(5) for j in range(5) if i!=j}
+data = [np.random.normal() for i in range(10000)]
+hist = np.histogram(data, 20)
+
+points = hv.Points(error)
+heatmap = hv.HeatMap(heatmap_data).sort()
+histogram = hv.Histogram(hist)
+image = hv.Image(np.random.rand(50,50))
+
+(points + heatmap + histogram + image).opts(
+    opts.Points(tools=['hover'], size=5), opts.HeatMap(tools=['hover']),
+    opts.Image(tools=['hover']), opts.Histogram(tools=['hover']),
+    opts.Layout(shared_axes=False)).cols(2)
+```
+
+Additionally, you can provide `'vline'`, the equivalent of passing `HoverTool(mode='vline')`, or `'hline'` to set the hit-testing behavior
+
+
+```python
+error = np.random.rand(100, 3)
+heatmap_data = {(chr(65+i), chr(97+j)):i*j for i in range(5) for j in range(5) if i!=j}
+data = [np.random.normal() for i in range(10000)]
+hist = np.histogram(data, 20)
+
+points = hv.Points(error)
+heatmap = hv.HeatMap(heatmap_data).sort()
+histogram = hv.Histogram(hist)
+image = hv.Image(np.random.rand(50,50))
+
+(points + heatmap + histogram + image).opts(
+    opts.Points(tools=['hline'], size=5), opts.HeatMap(tools=['hover']),
+    opts.Image(tools=['vline']), opts.Histogram(tools=['hover']),
+    opts.Layout(shared_axes=False)).cols(2)
+```
+
+It is also possible to explicitly declare the columns to display by manually constructing a `HoverTool` and declaring the tooltips as a list of tuples of the labels and a specification of the dimension name and how to display it (for a complete reference see the [bokeh user guide](https://bokeh.pydata.org/en/latest/docs/user_guide/tools.html#hovertool)).
+
+
+```python
+from bokeh.models import HoverTool
+from bokeh.sampledata.periodic_table import elements
+
+points = hv.Points(
+    elements, ['electronegativity', 'density'],
+    ['name', 'symbol', 'metal', 'CPK', 'atomic radius']
+).sort('metal')
+
+tooltips = [
+    ('Name', '@name'),
+    ('Symbol', '@symbol'),
+    ('CPK', '$color[hex, swatch]:CPK')
+]
+hover = HoverTool(tooltips=tooltips)
+
+points.opts(
+    tools=[hover], color='metal', cmap='Category20',
+    line_color='black', size=dim('atomic radius')/10,
+    width=600, height=400, show_grid=True,
+    title='Chemical Elements by Type (scaled by atomic radius)')
+```
+
+#### Selection tools
+
+Bokeh provides a number of tools for selecting data points including ``tap``, ``box_select``, ``lasso_select`` and ``poly_select``. To distinguish between selected and unselected data points we can also control the color and alpha of the ``selection`` and ``nonselection`` points.  You can try out any of these selection tools and see how the plot is affected:
+
+
+```python
+hv.Points(error).opts(
+    color='blue', nonselection_color='red', size=10, tools=['box_select', 'lasso_select', 'tap'])
+```
+
+#### Selection tool with shared axes and linked brushing
+
+When dealing with complex multi-variate data it is often useful to explore interactions between variables across plots. HoloViews will automatically link the data sources of plots in a Layout if they draw from the same data, allowing for both linked axes and brushing.
+
+We'll see what this looks like in practice using a small dataset of macro-economic data:
+
+
+```python
+macro_df = pd.read_csv('http://assets.holoviews.org/macro.csv', sep='\t')
+```
+
+By creating two ``Points`` Elements, which both draw their data from the same pandas DataFrame, the two plots become automatically linked. Note that the [Linking Plots user guide](Linking_Plots.ipynb) provides a more explicit way to declare two elements as being linked without having to share the same underlying datastructure. The automated linking behavior can be toggled with the ``shared_datasource`` plot option on a ``Layout`` or ``GridSpace``. You can try selecting data in one plot, and see how the corresponding data (those on the same rows of the DataFrame, even if the plots show different data, will be highlighted in each. 
+
+
+```python
+(hv.Scatter(macro_df, 'year', 'gdp') + hv.Scatter(macro_df, 'gdp',  'unem')).opts(
+    opts.Scatter(tools=['box_select', 'lasso_select']), opts.Layout(shared_axes=True, shared_datasource=True))
+```
+
+A gridmatrix is a clear use case for linked plotting.  This operation plots any combination of numeric variables against each other, in a grid, and selecting datapoints in any plot will highlight them in all of them.  Such linking can thus reveal how values in a particular range (e.g. very large outliers along one dimension) relate to each of the other dimensions.
+
+
+```python
+table = hv.Dataset(macro_df, kdims=['year', 'country'])
+matrix = hv.operation.gridmatrix(table.groupby('country'))
+
+matrix.select(country=['West Germany', 'United Kingdom', 'United States']).opts(
+    opts.Scatter(tools=['box_select', 'lasso_select', 'hover'], border=0))
+```
+
+#### Drawing Tools
+
+Another commonly useful set of tools are the drawing tools which are integrated with the linked streams introduced in the [Custom Interactivity guide](13-Custom_Interactivity.ipynb). These tools allow drawing and annotating a plot and accessing the annotation back in Python. The available drawing tools include:
+
+* [PointDraw](../reference/streams/bokeh/PointDraw.ipynb): The ``PointDraw`` stream adds a bokeh tool to the source plot, which allows drawing, dragging and deleting points.
+* [BoxEdit](../reference/streams/bokeh/BoxEdit.ipynb): The ``BoxEdit`` stream adds a bokeh tool to the source plot, which allows drawing, dragging and deleting boxes.
+* [FreehandDraw](../reference/streams/bokeh/FreehandDraw.ipynb): The ``FreehandDraw`` stream adds a bokeh tool to the source plot, which allows freehand drawing on the plot canvas
+* [PolyDraw](../reference/streams/bokeh/PolyDraw.ipynb): The ``PolyDraw`` stream adds a bokeh tool to the source plot, which allows drawing, dragging and deleting polygons and paths.
+* [PolyEdit](../reference/streams/bokeh/PolyEdit.ipynb): The ``PolyEdit`` stream adds a bokeh tool to the source plot, which allows drawing, dragging and deleting vertices on polygons and paths.
+
+Each of the reference notebooks explains the tools in more detail but to get an of how these tools work see the ``FreehandDraw`` example below, which allows drawing on the canvas and accessing the drawn data from Python:
+
+
+```python
+path = hv.Path([])
+freehand = hv.streams.FreehandDraw(source=path, num_objects=3)
+
+path.opts(
+    opts.Path(active_tools=['freehand_draw'], height=400, line_width=10, width=400))
+```
+
+To access the data from Python, you can access the ``element`` property on the stream, which lets us access each drawn line drawn as a separate ``Path`` element:
+
+
+```python
+freehand.element.split()
+```
+
+The [Reference Gallery](http://holoviews.org/reference/index.html) shows examples of all the Elements supported for Bokeh, in a format that can be compared with the corresponding matplotlib versions.
+
+## Theming
+
+Bokeh supports theming via the [Theme object](https://bokeh.pydata.org/en/latest/docs/reference/themes.html) object which can also be using in HoloViews. Applying a Bokeh theme is useful when you need to set detailed aesthetic options not directly exposed via the HoloViews style options.
+
+To apply a Bokeh theme, you will need to create a ``Theme`` object:
+
+
+```python
+from bokeh.themes.theme import Theme
+
+theme = Theme(
+    json={
+    'attrs' : {
+        'Figure' : {
+            'background_fill_color': '#2F2F2F',
+            'border_fill_color': '#2F2F2F',
+            'outline_line_color': '#444444',
+        },
+        'Grid': {
+            'grid_line_dash': [6, 4],
+            'grid_line_alpha': .3,
+        },
+
+        'Axis': {
+            'major_label_text_color': 'white',
+            'axis_label_text_color': 'white',
+            'major_tick_line_color': 'white',
+            'minor_tick_line_color': 'white',
+            'axis_line_color': "white"
+        }
+    }
+})
+```
+
+Instead of supplying a JSON object, you can also create a Bokeh ``Theme`` object from a [YAML file](https://bokeh.pydata.org/en/latest/docs/reference/themes.html). Once the ``Theme`` object is created, you can apply it by setting it on the ``theme`` parameter of the current Bokeh renderer:
+
+
+```python
+hv.renderer('bokeh').theme = theme
+```
+
+The theme will then be applied to subsequent plots:
+
+
+```python
+xs = np.linspace(0, np.pi*4, 100)
+hv.Curve((xs, np.sin(xs)), label='foo').opts(bgcolor='grey')
+```
+
+You may also supply a name from Bokeh's built-in-themes:
+
+
+```python
+hv.renderer('bokeh').theme = 'light_minimal'
+xs = np.linspace(0, np.pi*4, 100)
+hv.Curve((xs, np.sin(xs)), label='foo')
+```
+
+To disable theming, you can set the ``theme`` parameter on the Bokeh renderer to ``None``.

hvplot_docs/Plotting_with_Matplotlib.md

@@ -0,0 +1,341 @@
+This page demonstrates the use of the **Matplotlib** plotting backend, the equivalent page demonstrating the Plotly backend may be found [here](Plotting_with_Plotly.ipynb)
+
+As we discovered in the [Introduction](Introduction.ipynb), HoloViews allows plotting a variety of data types. Here we will use the sample data module and load the pandas and dask hvPlot API:
+
+
+```python
+import numpy as np
+import hvplot.pandas  # noqa
+import hvplot.dask  # noqa
+
+hvplot.extension('matplotlib')
+```
+
+As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.pyviz.org) app.
+
+HoloViews provides an extensive, very rich set of objects along with a powerful set of operations to apply, as you can find out in the [HoloViews User Guide](https://holoviews.org/user_guide/index.html). But here we will focus on the most essential mechanisms needed to make your data visualizable, without having to worry about the mechanics going on behind the scenes.
+
+We will be focusing on two different datasets:
+
+- A small CSV file of US crime data, broken down by state
+- A larger Parquet-format file of airline flight data
+
+The ``hvplot.sample_data`` module makes these datasets Intake data catalogue, which we can load either using pandas:
+
+
+```python
+from hvplot.sample_data import us_crime, airline_flights
+
+crime = us_crime.read()
+print(type(crime))
+crime.head()
+```
+
+Or using dask as a ``dask.DataFrame``:
+
+
+```python
+flights = airline_flights.to_dask().persist()
+print(type(flights))
+flights.head()
+```
+
+## The plot interface
+
+The ``dask.dataframe.DataFrame.hvplot``, ``pandas.DataFrame.hvplot`` and ``intake.DataSource.plot`` interfaces (and Series equivalents) from HvPlot provide a powerful high-level API to generate complex plots. The ``.hvplot`` API can be called directly or used as a namespace to generate specific plot types.
+
+### The plot method
+
+The most explicit way to use the plotting API is to specify the names of columns to plot on the ``x``- and ``y``-axis respectively:
+
+
+```python
+crime.hvplot.line(x='Year', y='Violent Crime rate')
+```
+
+As you'll see in more detail below, you can choose which kind of plot you want to use for the data:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate', kind='scatter')
+```
+
+To group the data by one or more additional columns, specify an additional ``by`` variable. As an example here we will plot the departure delay ('depdelay') as a function of 'distance', grouping the data by the 'carrier'. There are many available carriers, so we will select only two of them so that the plot is readable:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['OH', 'F9'])]
+flight_subset.hvplot(x='distance', y='depdelay', by='carrier', kind='scatter', alpha=0.2, persist=True)
+```
+
+Here we have specified the `x` axis explicitly, which can be omitted if the Pandas index column is already the desired x axis. Similarly, here we specified the `y` axis; by default all of the non-index columns would be plotted (which would be a lot of data in this case). If you don't specify the 'y' axis, it will have a default label named 'value', but you can then provide a y axis label explicitly using the ``value_label`` option.
+
+Putting all of this together we will plot violent crime, robbery, and burglary rates on the y-axis, specifying 'Year' as the x, and relabel the y-axis to display the 'Rate'.
+
+
+```python
+crime.hvplot(x='Year', y=['Violent Crime rate', 'Robbery rate', 'Burglary rate'],
+             value_label='Rate (per 100k people)')
+```
+
+### The hvplot namespace
+
+Instead of using the ``kind`` argument to the plot call, we can use the ``hvplot`` namespace, which lets us easily discover the range of plot types that are supported. Use tab completion to explore the available plot types:
+
+```python
+crime.hvplot.<TAB>
+```
+
+Plot types available include:
+
+* <a href="#area">``.area()``</a>: Plots a  area chart similar to a line chart except for filling the area under the curve and optionally stacking 
+* <a href="#bars">``.bar()``</a>: Plots a bar chart that can be stacked or grouped
+* <a href="#bivariate">``.bivariate()``</a>: Plots 2D density of a set of points 
+* <a href="#box-whisker-plots">``.box()``</a>: Plots a box-whisker chart comparing the distribution of one or more variables
+* <a href="#heatmap">``.heatmap()``</a>: Plots a heatmap to visualizing a variable across two independent dimensions
+* <a href="#hexbins">``.hexbins()``</a>: Plots hex bins
+* <a href="#histogram">``.hist()``</a>: Plots the distribution of one or histograms as a set of bins
+* <a href="#kde-density">``.kde()``</a>: Plots the kernel density estimate of one or more variables.
+* <a href="#the-plot-method">``.line()``</a>: Plots a line chart (such as for a time series)
+* <a href="#scatter">``.scatter()``</a>: Plots a scatter chart comparing two variables
+* <a href="#step">``.step()``</a>: Plots a step chart akin to a line plot
+* <a href="#tables">``.table()``</a>: Generates a SlickGrid DataTable
+* <a href="#groupby">``.violin()``</a>: Plots a violin plot comparing the distribution of one or more variables using the kernel density estimate
+
+#### Area
+
+Like most other plot types the ``area`` chart supports the three ways of defining a plot outlined above. An area chart is most useful when plotting multiple variables in a stacked chart. This can be achieve by specifying ``x``, ``y``, and ``by`` columns or using the ``columns`` and ``index``/``use_index`` (equivalent to ``x``) options:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+We can also explicitly set ``stacked`` to False and define an ``alpha`` value to compare the values directly:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Aggravated assault', 'Robbery'], stacked=False, alpha=0.4)
+```
+
+Another use for an area plot is to visualize the spread of a value. For instance using the flights dataset we may want to see the spread in mean delay values across carriers. For that purpose we compute the mean delay by day and carrier and then the min/max mean delay for across all carriers. Since the output of ``hvplot`` is just a regular holoviews object, we can use the overlay operator (\*) to place the plots on top of each other.
+
+
+```python
+delay_min_max = flights.groupby(['day', 'carrier'])['carrier_delay'].mean().groupby('day').agg({'min': np.min, 'max': np.max})
+delay_mean = flights.groupby('day')['carrier_delay'].mean()
+
+delay_min_max.hvplot.area(x='day', y='min', y2='max', alpha=0.2) * delay_mean.hvplot()
+```
+
+#### Bars
+
+In the simplest case we can use ``.hvplot.bar`` to plot ``x`` against ``y``. We'll use ``rot=90`` to rotate the tick labels on the x-axis making the years easier to read:
+
+
+```python
+crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90, width=900)
+```
+
+If we want to compare multiple columns instead we can set ``y`` to a list of columns. Using the ``stacked`` option we can then compare the column values more easily:
+
+
+```python
+crime.hvplot.bar(x='Year', y=['Violent crime total', 'Property crime total'],
+                 stacked=True, rot=90, width=900, legend='top_left')
+```
+
+#### Scatter
+
+The scatter plot supports many of the same features as the other chart types we have seen so far but can also be colored by another variable using the ``c`` option. 
+
+
+```python
+crime.hvplot.scatter(x='Violent Crime rate', y='Burglary rate', c='Year')
+```
+
+Anytime that color is being used to represent a dimension, the ``cmap`` option can be used to control the colormap that is used to represent that dimension. Additionally, the colorbar can be disabled using ``colorbar=False``.
+
+#### Step
+
+A step chart is very similar to a line chart but instead of linearly interpolating between samples the step chart visualizes discrete steps. The point at which to step can be controlled via the ``where`` keyword allowing `'pre'`, `'mid'` (default) and `'post'` values:
+
+
+```python
+crime.hvplot.step(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+#### HexBins
+
+You can create hexagonal bin plots with the ``hexbin`` method. Hexbin plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually. Since these data are not regularly distributed, we'll use the ``logz`` option to map z-axis (color) to a log scale colorbar.
+
+
+```python
+# flights.hvplot.hexbin(x='airtime', y='arrdelay', width=600, height=500, logz=True);
+```
+
+<div class="alert alert-warning" role="alert">
+Output suppressed as this is <a href='https://github.com/holoviz/hvplot/pull/653#issuecomment-964056881'>not currently supported</a> with the Matplotlib backend and doesn't display any plot.
+</div>
+
+#### Bivariate
+
+You can create a 2D density plot with the ``bivariate`` method. Bivariate plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually.
+
+
+```python
+crime.hvplot.bivariate(x='Violent Crime rate', y='Burglary rate', width=600, height=500)
+```
+
+#### HeatMap
+
+A ``HeatMap`` lets us view the relationship between three variables, so we specify the 'x' and 'y' variables and an additional 'C' variable. Additionally we can define a ``reduce_function`` that computes the values for each bin from the samples that fall into it. Here we plot the 'depdelay' (i.e. departure delay) for each day of the month and carrier in the dataset:
+
+
+```python
+flights.compute().hvplot.heatmap(x='day', y='carrier', C='depdelay', reduce_function=np.mean).opts(show_values=False)
+```
+
+#### Tables
+
+Unlike all other plot types, a table only supports one signature: either all columns are plotted, or a subset of columns can be selected by defining the ``columns`` explicitly:
+
+
+```python
+crime.hvplot.table(columns=['Year', 'Population', 'Violent Crime rate'], width=400)
+```
+
+### Distributions
+
+Plotting distributions differs slightly from other plots since they plot only one variable in the simple case rather than plotting two or more variables against each other. Therefore when plotting these plot types no ``index`` or ``x`` value needs to be supplied. Instead:
+
+1. Declare a single ``y`` variable, e.g. ``source.plot.hist(variable)``, or
+2. Declare a ``y`` variable and ``by`` variable, e.g. ``source.plot.hist(variable, by='Group')``, or
+3. Declare columns or plot all columns, e.g. ``source.plot.hist()`` or ``source.plot.hist(columns=['A', 'B', 'C'])``
+
+#### Histogram
+
+The Histogram is the simplest example of a distribution; often we simply plot the distribution of a single variable, in this case the 'Violent Crime rate'. Additionally we can define a range over which to compute the histogram and the number of bins using the ``bin_range`` and ``bins`` arguments respectively:
+
+
+```python
+crime.hvplot.hist(y='Violent Crime rate')
+```
+
+Or we can plot the distribution of multiple columns:
+
+
+```python
+columns = ['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.hist(y=columns, bins=50, alpha=0.5, legend='top', height=400)
+```
+
+We can also group the data by another variable. Here we'll use ``subplots`` to split each carrier out into its own plot:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+# flight_subset.hvplot.hist('depdelay', by='carrier', bins=20, bin_range=(-20, 100), width=300, subplots=True);
+```
+
+<div class="alert alert-warning" role="alert">
+Output suppressed as this is <a href='https://github.com/holoviz/holoviews/issues/5111'>not currently supported</a> with the Matplotlib backend and raises an error. Tip: execute <code>flight_subset.compute()</code> before plotting to avoid the error.
+</div>
+
+#### KDE (density)
+
+You can also create density plots using ``hvplot.kde()`` or ``hvplot.density()``:
+
+
+```python
+crime.hvplot.kde(y='Violent Crime rate')
+```
+
+Comparing the distribution of multiple columns is also possible:
+
+
+```python
+columns=['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.kde(y=columns, alpha=0.5, value_label='Rate', legend='top_right')
+```
+
+The ``hvplot.kde`` also supports the ``by`` keyword:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.kde('depdelay', by='carrier', xlim=(-20, 70), width=300, subplots=True)
+```
+
+#### Box-Whisker Plots
+
+Just like the other distribution-based plot types, the box-whisker plot supports plotting a single column:
+
+
+```python
+crime.hvplot.box(y='Violent Crime rate')
+```
+
+It also supports multiple columns and the same options as seen previously (``legend``, ``invert``, ``value_label``):
+
+
+```python
+columns=['Burglary rate', 'Larceny-theft rate', 'Motor vehicle theft rate',
+         'Property crime rate', 'Violent Crime rate']
+crime.hvplot.box(y=columns, group_label='Crime', legend=False, value_label='Rate (per 100k)', invert=True)
+```
+
+Lastly, it also supports using the ``by`` keyword to split the data into multiple subsets:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+# flight_subset.hvplot.box('depdelay', by='carrier', ylim=(-10, 70));
+```
+
+<div class="alert alert-warning" role="alert">
+Output suppressed as this is <a href='https://github.com/holoviz/holoviews/issues/5120'>not currently supported</a> with the Matplotlib backend and displays an empty plot.
+</div>
+
+## Composing Plots
+
+One of the core strengths of HoloViews is the ease of composing
+different plots. Individual plots can be composed using the ``*`` and
+``+`` operators, which overlay and compose plots into layouts
+respectively. For more information on composing objects, see the
+HoloViews [User Guide](https://holoviews.org/user_guide/Composing_Elements.html).
+
+By using these operators we can combine multiple plots into composite plots. A simple example is overlaying two plot types:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate') * crime.hvplot.scatter(x='Year', y='Violent Crime rate', c='k')
+```
+
+We can also lay out different plots and tables together:
+
+
+```python
+(crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90, width=550) +
+ crime.hvplot.table(['Year', 'Population', 'Violent Crime rate'], width=420))
+```
+
+## Large data
+
+The previous examples summarized the fairly large airline dataset using statistical plot types that aggregate the data into a feasible subset for plotting.  We can instead aggregate the data directly into the viewable image using [datashader](https://datashader.org), which provides a rendering of the entire set of raw data available (as far as the resolution of the screen allows). Here we plot the 'airtime' against the 'distance':
+
+
+```python
+flights.hvplot.scatter(x='distance', y='airtime', datashade=True)
+```
+
+## Groupby
+
+Thanks to the ability of HoloViews to explore a parameter space with a set of widgets we can apply a groupby along a particular column or dimension. For example we can view the distribution of departure delays by carrier grouped by day, allowing the user to choose which day to display:
+
+
+```python
+flights.hvplot.violin(y='depdelay', by='carrier', groupby='dayofweek', ylim=(-20, 60), height=500)
+```
+
+This user guide merely provided an overview over the available plot types; to see a detailed description on how to customize plots see the [Customization](Customization.ipynb) user guide.

hvplot_docs/Plotting_with_Plotly.md

@@ -0,0 +1,340 @@
+This page demonstrates the use of the **Plotly** plotting backend, the equivalent page demonstrating the Matplotlib backend may be found [here](Plotting_with_Matplotlib.ipynb)
+
+As we discovered in the [Introduction](Introduction.ipynb), HoloViews allows plotting a variety of data types. Here we will use the sample data module and load the pandas and dask hvPlot API:
+
+
+```python
+import numpy as np
+import hvplot.pandas  # noqa
+import hvplot.dask  # noqa
+```
+
+
+```python
+hvplot.extension('plotly')
+```
+
+As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.holoviz.org) app.
+
+HoloViews provides an extensive, very rich set of objects along with a powerful set of operations to apply, as you can find out in the [HoloViews User Guide](https://holoviews.org/user_guide/index.html). But here we will focus on the most essential mechanisms needed to make your data visualizable, without having to worry about the mechanics going on behind the scenes.
+
+We will be focusing on two different datasets:
+
+- A small CSV file of US crime data, broken down by state
+- A larger Parquet-format file of airline flight data
+
+The ``hvplot.sample_data`` module makes these datasets Intake data catalogue, which we can load either using pandas:
+
+
+```python
+from hvplot.sample_data import us_crime, airline_flights
+
+crime = us_crime.read()
+print(type(crime))
+crime.head()
+```
+
+Or using dask as a ``dask.DataFrame``:
+
+
+```python
+flights = airline_flights.to_dask().persist()
+print(type(flights))
+flights.head()
+```
+
+## The plot interface
+
+The ``dask.dataframe.DataFrame.hvplot``, ``pandas.DataFrame.hvplot`` and ``intake.DataSource.plot`` interfaces (and Series equivalents) from HvPlot provide a powerful high-level API to generate complex plots. The ``.hvplot`` API can be called directly or used as a namespace to generate specific plot types.
+
+### The plot method
+
+The most explicit way to use the plotting API is to specify the names of columns to plot on the ``x``- and ``y``-axis respectively:
+
+
+```python
+crime.hvplot.line(x='Year', y='Violent Crime rate')
+```
+
+As you'll see in more detail below, you can choose which kind of plot you want to use for the data:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate', kind='scatter')
+```
+
+To group the data by one or more additional columns, specify an additional ``by`` variable. As an example here we will plot the departure delay ('depdelay') as a function of 'distance', grouping the data by the 'carrier'. There are many available carriers, so we will select only two of them so that the plot is readable:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['OH', 'F9'])]
+flight_subset.hvplot(x='distance', y='depdelay', by='carrier', kind='scatter', alpha=0.2, persist=True)
+```
+
+Here we have specified the `x` axis explicitly, which can be omitted if the Pandas index column is already the desired x axis. Similarly, here we specified the `y` axis; by default all of the non-index columns would be plotted (which would be a lot of data in this case). If you don't specify the 'y' axis, it will have a default label named 'value', but you can then provide a y axis label explicitly using the ``value_label`` option.
+
+Putting all of this together we will plot violent crime, robbery, and burglary rates on the y-axis, specifying 'Year' as the x, and relabel the y-axis to display the 'Rate'.
+
+
+```python
+crime.hvplot(x='Year', y=['Violent Crime rate', 'Robbery rate', 'Burglary rate'],
+             value_label='Rate (per 100k people)')
+```
+
+### The hvplot namespace
+
+Instead of using the ``kind`` argument to the plot call, we can use the ``hvplot`` namespace, which lets us easily discover the range of plot types that are supported. Use tab completion to explore the available plot types:
+
+```python
+crime.hvplot.<TAB>
+```
+
+Plot types available include:
+
+* <a href="#area">``.area()``</a>: Plots a  area chart similar to a line chart except for filling the area under the curve and optionally stacking 
+* <a href="#bars">``.bar()``</a>: Plots a bar chart that can be stacked or grouped
+* <a href="#bivariate">``.bivariate()``</a>: Plots 2D density of a set of points 
+* <a href="#box-whisker-plots">``.box()``</a>: Plots a box-whisker chart comparing the distribution of one or more variables
+* <a href="#heatmap">``.heatmap()``</a>: Plots a heatmap to visualizing a variable across two independent dimensions
+* <a href="#hexbins">``.hexbins()``</a>: Plots hex bins
+* <a href="#histogram">``.hist()``</a>: Plots the distribution of one or histograms as a set of bins
+* <a href="#kde-density">``.kde()``</a>: Plots the kernel density estimate of one or more variables.
+* <a href="#the-plot-method">``.line()``</a>: Plots a line chart (such as for a time series)
+* <a href="#scatter">``.scatter()``</a>: Plots a scatter chart comparing two variables
+* <a href="#step">``.step()``</a>: Plots a step chart akin to a line plot
+* <a href="#tables">``.table()``</a>: Generates a SlickGrid DataTable
+* <a href="#groupby">``.violin()``</a>: Plots a violin plot comparing the distribution of one or more variables using the kernel density estimate
+
+#### Area
+
+Like most other plot types the ``area`` chart supports the three ways of defining a plot outlined above. An area chart is most useful when plotting multiple variables in a stacked chart. This can be achieve by specifying ``x``, ``y``, and ``by`` columns or using the ``columns`` and ``index``/``use_index`` (equivalent to ``x``) options:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+We can also explicitly set ``stacked`` to False and define an ``alpha`` value to compare the values directly:
+
+
+```python
+crime.hvplot.area(x='Year', y=['Aggravated assault', 'Robbery'], stacked=False, alpha=0.4)
+```
+
+Another use for an area plot is to visualize the spread of a value. For instance using the flights dataset we may want to see the spread in mean delay values across carriers. For that purpose we compute the mean delay by day and carrier and then the min/max mean delay for across all carriers. Since the output of ``hvplot`` is just a regular holoviews object, we can use the overlay operator (\*) to place the plots on top of each other.
+
+
+```python
+delay_min_max = flights.groupby(['day', 'carrier'])['carrier_delay'].mean().groupby('day').agg({'min': np.min, 'max': np.max})
+delay_mean = flights.groupby('day')['carrier_delay'].mean()
+
+delay_min_max.hvplot.area(x='day', y='min', y2='max', alpha=0.2) * delay_mean.hvplot()
+```
+
+#### Bars
+
+In the simplest case we can use ``.hvplot.bar`` to plot ``x`` against ``y``. We'll use ``rot=90`` to rotate the tick labels on the x-axis making the years easier to read:
+
+
+```python
+crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90)
+```
+
+If we want to compare multiple columns instead we can set ``y`` to a list of columns. Using the ``stacked`` option we can then compare the column values more easily:
+
+
+```python
+crime.hvplot.bar(x='Year', y=['Violent crime total', 'Property crime total'],
+                 stacked=True, rot=90, width=800, legend='top_left')
+```
+
+#### Scatter
+
+The scatter plot supports many of the same features as the other chart types we have seen so far but can also be colored by another variable using the ``c`` option. 
+
+
+```python
+crime.hvplot.scatter(x='Violent Crime rate', y='Burglary rate', c='Year')
+```
+
+Anytime that color is being used to represent a dimension, the ``cmap`` option can be used to control the colormap that is used to represent that dimension. Additionally, the colorbar can be disabled using ``colorbar=False``.
+
+#### Step
+
+A step chart is very similar to a line chart but instead of linearly interpolating between samples the step chart visualizes discrete steps. The point at which to step can be controlled via the ``where`` keyword allowing `'pre'`, `'mid'` (default) and `'post'` values:
+
+
+```python
+crime.hvplot.step(x='Year', y=['Robbery', 'Aggravated assault'])
+```
+
+#### HexBins
+
+You can create hexagonal bin plots with the ``hexbin`` method. Hexbin plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually. Since these data are not regularly distributed, we'll use the ``logz`` option to map z-axis (color) to a log scale colorbar.
+
+
+```python
+# flights.hvplot.hexbin(x='airtime', y='arrdelay', width=600, height=500, logz=True)
+```
+
+<div class="alert alert-warning" role="alert">
+    HexBins plots <a href='https://github.com/holoviz/holoviews/issues/5219'>not yet supported</a> with the Plotly backend.
+</div>
+
+#### Bivariate
+
+You can create a 2D density plot with the ``bivariate`` method. Bivariate plots can be a useful alternative to scatter plots if your data are too dense to plot each point individually.
+
+
+```python
+# crime.hvplot.bivariate(x='Violent Crime rate', y='Burglary rate', width=600, height=500)
+```
+
+<div class="alert alert-warning" role="alert">
+Commented as this is <a href='https://github.com/holoviz/holoviews/issues/5220'>not currently supported</a> with the Plotly backend and raises an error.
+</div>
+
+#### HeatMap
+
+A ``HeatMap`` lets us view the relationship between three variables, so we specify the 'x' and 'y' variables and an additional 'C' variable. Additionally we can define a ``reduce_function`` that computes the values for each bin from the samples that fall into it. Here we plot the 'depdelay' (i.e. departure delay) for each day of the month and carrier in the dataset:
+
+
+```python
+flights.compute().hvplot.heatmap(x='day', y='carrier', C='depdelay', reduce_function=np.mean, colorbar=True)
+```
+
+#### Tables
+
+Unlike all other plot types, a table only supports one signature: either all columns are plotted, or a subset of columns can be selected by defining the ``columns`` explicitly:
+
+
+```python
+crime.hvplot.table(columns=['Year', 'Population', 'Violent Crime rate'], width=400)
+```
+
+### Distributions
+
+Plotting distributions differs slightly from other plots since they plot only one variable in the simple case rather than plotting two or more variables against each other. Therefore when plotting these plot types no ``index`` or ``x`` value needs to be supplied. Instead:
+
+1. Declare a single ``y`` variable, e.g. ``source.plot.hist(variable)``, or
+2. Declare a ``y`` variable and ``by`` variable, e.g. ``source.plot.hist(variable, by='Group')``, or
+3. Declare columns or plot all columns, e.g. ``source.plot.hist()`` or ``source.plot.hist(columns=['A', 'B', 'C'])``
+
+#### Histogram
+
+The Histogram is the simplest example of a distribution; often we simply plot the distribution of a single variable, in this case the 'Violent Crime rate'. Additionally we can define a range over which to compute the histogram and the number of bins using the ``bin_range`` and ``bins`` arguments respectively:
+
+
+```python
+crime.hvplot.hist(y='Violent Crime rate')
+```
+
+Or we can plot the distribution of multiple columns:
+
+
+```python
+columns = ['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.hist(y=columns, bins=50, alpha=0.5, legend='top', height=400)
+```
+
+We can also group the data by another variable. Here we'll use ``subplots`` to split each carrier out into its own plot:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.hist('depdelay', by='carrier', bins=20, bin_range=(-20, 100), width=300, subplots=True)
+```
+
+#### KDE (density)
+
+You can also create density plots using ``hvplot.kde()`` or ``hvplot.density()``:
+
+
+```python
+crime.hvplot.kde(y='Violent Crime rate')
+```
+
+Comparing the distribution of multiple columns is also possible:
+
+
+```python
+columns=['Violent Crime rate', 'Property crime rate', 'Burglary rate']
+crime.hvplot.kde(y=columns, alpha=0.5, value_label='Rate', legend='top_right')
+```
+
+The ``hvplot.kde`` also supports the ``by`` keyword:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.kde('depdelay', by='carrier', xlim=(-20, 70), width=300, subplots=True)
+```
+
+#### Box-Whisker Plots
+
+Just like the other distribution-based plot types, the box-whisker plot supports plotting a single column:
+
+
+```python
+crime.hvplot.box(y='Violent Crime rate')
+```
+
+It also supports multiple columns and the same options as seen previously (``legend``, ``invert``, ``value_label``):
+
+
+```python
+columns=['Burglary rate', 'Larceny-theft rate', 'Motor vehicle theft rate',
+         'Property crime rate', 'Violent Crime rate']
+crime.hvplot.box(y=columns, group_label='Crime', legend=False, value_label='Rate (per 100k)', invert=True)
+```
+
+Lastly, it also supports using the ``by`` keyword to split the data into multiple subsets:
+
+
+```python
+flight_subset = flights[flights.carrier.isin(['AA', 'US', 'OH'])]
+flight_subset.hvplot.box('depdelay', by='carrier', ylim=(-10, 70))
+```
+
+## Composing Plots
+
+One of the core strengths of HoloViews is the ease of composing
+different plots. Individual plots can be composed using the ``*`` and
+``+`` operators, which overlay and compose plots into layouts
+respectively. For more information on composing objects, see the
+HoloViews [User Guide](https://holoviews.org/user_guide/Composing_Elements.html).
+
+By using these operators we can combine multiple plots into composite plots. A simple example is overlaying two plot types:
+
+
+```python
+crime.hvplot(x='Year', y='Violent Crime rate') * crime.hvplot.scatter(x='Year', y='Violent Crime rate', c='k')
+```
+
+We can also lay out different plots and tables together:
+
+
+```python
+(crime.hvplot.bar(x='Year', y='Violent Crime rate', rot=90, width=550) +
+ crime.hvplot.table(['Year', 'Population', 'Violent Crime rate'], width=420))
+```
+
+## Large data
+
+The previous examples summarized the fairly large airline dataset using statistical plot types that aggregate the data into a feasible subset for plotting.  We can instead aggregate the data directly into the viewable image using [datashader](https://datashader.org), which provides a rendering of the entire set of raw data available (as far as the resolution of the screen allows). Here we plot the 'airtime' against the 'distance':
+
+
+```python
+flights.hvplot.scatter(x='distance', y='airtime', datashade=True)
+```
+
+## Groupby
+
+Thanks to the ability of HoloViews to explore a parameter space with a set of widgets we can apply a groupby along a particular column or dimension. For example we can view the distribution of departure delays by carrier grouped by day, allowing the user to choose which day to display:
+
+
+```python
+flights.hvplot.violin(y='depdelay', by='carrier', groupby='dayofweek', ylim=(-20, 60), height=500)
+```
+
+This user guide merely provided an overview over the available plot types; to see a detailed description on how to customize plots see the [Customization](Customization.ipynb) user guide.

hvplot_docs/Statistical_Plots.md

@@ -0,0 +1,68 @@
+In addition to the plots available via the plot interface, hvPlot makes a number of more sophisticated, statistical plots available that are modelled on ``pandas.plotting``. To explore these, we will load the iris and stocks datasets from Bokeh:
+
+
+```python
+import pandas as pd
+import hvplot.pandas  # noqa
+
+from bokeh.sampledata import iris, stocks 
+
+iris = iris.flowers
+```
+
+### Scatter Matrix
+
+When working with multi-dimensional data, it is often difficult to understand the relationship between all the different variables. A ``scatter_matrix`` makes it possible to visualize all of the pairwise relationships in a compact format. ``hvplot.scatter_matrix`` is closely modelled on ``pandas.plotting.scatter_matrix``:
+
+
+```python
+hvplot.scatter_matrix(iris, c="species")
+```
+
+Compared to a static Seaborn/Matplotlib-based plot, here it is easy to explore the data interactively thanks to Bokeh's linked zooming, linked panning, and linked brushing (using the ``box_select`` and ``lasso_select`` tools).
+
+### Parallel Coordinates
+
+Parallel coordinate plots provide another way of visualizing multi-variate data. ``hvplot.parallel_coordinates`` provides a simple API to create such a plot, modelled on the API of `pandas.plotting.parallel_coordinates()`:
+
+
+```python
+hvplot.parallel_coordinates(iris, "species")
+```
+
+The plot quickly clarifies the relationship between different variables, highlighting the difference of the "setosa" species in the petal width and length dimensions.
+
+### Andrews Curves
+
+
+Another similar approach is to visualize the dimensions using Andrews curves, which are constructed by generating a Fourier series from the features of each observation, visualizing the aggregate differences between classes. The ``hvplot.andrews_curves()`` function provides a simple API to generate Andrews curves from a datafrom, closely matching the API of ``pandas.plotting.andrews_curves()``:
+
+
+```python
+hvplot.andrews_curves(iris, "species")
+```
+
+Once again we can see the significant difference of the setosa species. However, unlike the parallel coordinate plot, the Andrews plot does not give any real quantitative insight into the features that drive those differences.
+
+### Lag Plot
+
+Lastly, for the analysis of time series hvplot offers a so called lag plot, implemented by the ``hvplot.lag_plot()`` function, modelled on the matching ``pandas.plotting.lag_plot()`` function.
+
+As an example we will compare the closing stock prices of Apple and IBM from 2000-2013 using a lag of 365 days:
+
+
+```python
+index = pd.DatetimeIndex(stocks.AAPL['date'])
+stock_df = pd.DataFrame({'IBM': stocks.IBM['close'], 'AAPL': stocks.AAPL['close']}, index=index)
+
+hvplot.lag_plot(stock_df, lag=365, alpha=0.3)
+```
+
+Using this plot it becomes apparent that Apple was significantly more volatile over the analyzed time scale. In other words, its price at a particular point in time sometimes differed significantly from the price 365 days in the past. This also becomes visible in a simple line chart of the same data:
+
+
+```python
+stock_df.hvplot.line()
+```
+
+These plot types can help you make sense of complex datasets.  See [holoviews.org](https://holoviews.org) for many other plots and tools that can be used alongside those from hvPlot for other purposes.

hvplot_docs/Streaming.md

@@ -0,0 +1,139 @@
+hvPlot supports [streamz](https://github.com/mrocklin/streamz) DataFrame and Series objects, automatically generating streaming plots in a Jupyter notebook or deployed as a [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html). 
+
+All hvPlot methods on streamz objects return HoloViews `DynamicMap` objects that update the plot whenever `streamz` triggers an event. For more information on `DynamicMap` and HoloViews dynamic plotting support, see the [HoloViews User Guide](https://holoviews.org/user_guide); here we will focus on using the simple, high-level hvPlot API rather than on the details of how events and data flow behind the scenes.
+
+**All plots generated by the streamz plotting interface dynamically stream data from Python into the web browser.  The web version for this page includes *screen captures* of the streaming visualizations, not live streaming data.**
+
+As for any of the data backends, we start by patching the streamz library with the plotting API:
+
+
+```python
+import hvplot.streamz  # noqa
+```
+
+## Basic plotting
+
+Throughout this section we will be using the ``Random`` object from streamz, which provides an easy way of generating a DataFrame of random streaming data but which could be substituted with any streamz ``DataFrame`` or ``Series`` driven by a live, external data source instead. To stop the ``Random`` stream you can call ``df.stop()`` at any point.
+
+
+```python
+from streamz.dataframe import Random
+df = Random(interval='200ms', freq='50ms')
+```
+
+<img src='https://assets.holoviews.org/hvplot/gifs/df_streamz.gif' width=400px></img>
+
+The plot method on Series and DataFrame is a simple wrapper around a
+line plot, which will plot all columns:
+
+
+```python
+df.hvplot()
+```
+
+<center><img src='https://assets.holoviews.org/hvplot/gifs/df_plot.gif' width=700px></img></center>
+
+The plot method can also be called on a Series, plotting a specific column:
+
+
+```python
+df.z.cumsum().hvplot()
+```
+
+<center><img src='https://assets.holoviews.org/hvplot/gifs/df_curve.gif' width=700px></img></center>
+
+Actually, *all* the functionality described in the [Plotting](Plotting.ipynb) user guide should work just the same as it does for a regular (non-streaming) dask or pandas DataFrame or Series, but will now update as new data appears.
+
+## Controlling the backlog
+
+The main difference when using a streaming DataFrame is that a only a certain amount of data will be buffered and displayed. The number of rows of data that will be buffered can be controlled by the ``backlog`` parameter. Here, let's buffer and display 10 rows of our streaming DataFrame as a table:
+
+
+```python
+df.hvplot.table(width=400, backlog=10)
+```
+
+<center><img src='https://assets.holoviews.org/hvplot/gifs/df_table.gif' width=400px></img></center>
+
+This of course only has an effect when we are directly streaming data point by point. When we have an aggregate DataFrame, the plot will continuously accumulate updates:
+
+
+```python
+df.groupby('y').sum().hvplot.bar(x='y')
+```
+
+<center><img src='https://assets.holoviews.org/hvplot/gifs/df_bars.gif' width=700px></img></center>
+
+## Composing Plots
+
+hvPlot is a convenient API for generating HoloViews objects. One of the core strengths of HoloViews objects is the ease with which they can be composed, which works with streaming plots just as with static ones. Individual plots can be composed using the ``*`` and ``+`` operators, which overlay and compose plots into layouts respectively. For more information on composing objects see the HoloViews [User Guide](https://holoviews.org/user_guide/Composing_Elements.html).
+
+By using these operators we can combine multiple plots into composite Overlay and Layout objects, and lay them out in two columns using the ``Layout.cols`` method:
+
+
+```python
+(df.hvplot.line(width=400, backlog=100) * df.hvplot.scatter(width=400, backlog=100) +
+ df.groupby('y').sum().hvplot.bar('y', 'x', width=400) +
+ df.hvplot.box(width=400) + df.x.hvplot.kde(width=400, shared_axes=False)).cols(2)
+```
+
+<center><img src='https://assets.holoviews.org/hvplot/gifs/df_composite.gif' width=700px></img></center>
+
+## Deployment as Bokeh apps
+
+HoloViews objects automatically render themselves in Jupyter notebook cells, but when deploying a bokeh app the plot has to be rendered explicitly. Deploying as a Bokeh Server app allows you to share live, dynamically updated visualizations like those for streaming data, backed by a running Python process.
+
+The following example describes how to set up a streaming DataFrame, declare some plots, compose them, set up a callback to update the plot and finally convert the composite plot to a bokeh Document, which can be served from a script using ``bokeh serve`` on the commandline.
+
+```python
+
+import numpy as np
+import pandas as pd
+import hvplot.streamz
+import holoviews as hv
+
+from streamz import Stream
+from streamz.dataframe import DataFrame
+
+renderer = hv.renderer('bokeh')
+
+# Set up streaming DataFrame
+stream = Stream()
+index = pd.DatetimeIndex([])
+example = pd.DataFrame({'x': [], 'y': [], 'z': []},
+                       columns=['x', 'y', 'z'], index=[])
+df = DataFrame(stream, example=example)
+cumulative = df.cumsum()[['x', 'z']]
+
+# Declare plots
+line = cumulative.hvplot.line(width=400)
+scatter = cumulative.hvplot.scatter(width=400)
+bars = df.groupby('y').sum().hvplot.bar(width=400)
+box = df.hvplot.box(width=400)
+kde = df.x.hvplot.kde(width=400)
+
+# Compose plots
+layout = (line * scatter + bars + box + kde).cols(2)
+
+# Set up callback with streaming data
+def emit():
+    now = pd.datetime.now()
+    delta = np.timedelta64(500, 'ms')
+    index = pd.date_range(np.datetime64(now)-delta, now, freq='100ms')
+    df = pd.DataFrame({'x': np.random.randn(len(index)),
+                       'y': np.random.randint(0, 10, len(index)),
+                       'z': np.random.randn(len(index))},
+                      columns=['x', 'y', 'z'], index=index)
+    stream.emit(df)
+
+# Render layout to bokeh server Document and attach callback
+doc = renderer.server_doc(layout)
+doc.title = 'Streamz HoloViews based Plotting API Bokeh App Demo'
+doc.add_periodic_callback(emit, 500)
+```
+
+For more details on deploying Bokeh apps see the HoloViews [User Guide](https://holoviews.org/user_guide/Deploying_Bokeh_Apps.html).
+
+## Using HoloViews directly
+
+HoloViews itself includes first class support for streamz DataFrame and Series; for more details see the [Streaming Data section](https://holoviews.org/user_guide/Streaming_Data.html) in the HoloViews documentation.

hvplot_docs/Subplots.md

@@ -0,0 +1,70 @@
+## Subplots
+
+When plotting multiple columns, hvPlot will overlay the plots onto one axis by default so that they can be compared easily in a compact format:
+
+
+```python
+import xarray as xr
+import hvplot.pandas  # noqa
+import hvplot.xarray  # noqa
+
+from hvplot.sample_data import airline_flights, us_crime
+
+us_crime.hvplot(x='Year', y=['Burglary rate', 'Violent Crime rate', 'Robbery rate'], value_label='Rate')
+```
+
+If you wish, you can instead set `subplots=True` to split each column into its own separate plot:
+
+
+```python
+us_crime.hvplot(x='Year', y=['Burglary rate', 'Violent Crime rate', 'Robbery rate'],
+                value_label='Rate', subplots=True, width=300, height=200)
+```
+
+By default, the subplots will have linked, normalized axes, to facilitate comparing the numerical values across plots (try panning or zooming in any one of the plots, to see how the others change.) 
+
+However, if the data covers widely different numerical ranges, you can specify `shared_axes=False` to give each plot its own range:
+
+
+```python
+us_crime.hvplot(x='Year', y=['Robbery',  'Robbery rate', 'Burglary', 'Burglary rate'], 
+                width=350, height=300, subplots=True, shared_axes=False).cols(2)
+```
+
+(Notice the very different y axis ranges between the plots.) Here we also specified `.cols(2)` to allow up to two plots per line, wrapping the rest onto subsequent rows.
+ 
+You can use the `subplots=True` (and `shared_axes` if desired) arguments when using the ``by`` keyword as well, if you want to group the data along a dimension: 
+
+
+```python
+flights = airline_flights.read()
+
+flight_subset = flights[flights.carrier.isin(['OH', 'F9', 'US'])].sample(2000)
+
+flight_subset.hvplot.scatter(x='arrdelay', y='depdelay', by='carrier',
+                             subplots=True, width=250, height=250, alpha=0.1)
+```
+
+## Grids
+
+
+`subplot=True` lays out plots sequentially, breaking lines if requested with the `.cols()` method but otherwise formatting each plot independently. You can instead arrange multidimensional data into an explicit 1D row of plots or a 2D grid of plots with shared axes, to allow easier comparisons across large numbers of plots.  To make a row or grid plot, just specify the ``col`` keyword and add a ``row`` keyword if you want a grid:
+
+
+```python
+flight_subset.sort_values('dayofweek').hvplot.scatter(x='arrdelay', y='depdelay', 
+    row='dayofweek', col='carrier', alpha=0.2)
+```
+
+(Just declaring `row` to get a single column is not currently supported.) Here you can see that compared to the subplot versions above, the axis ticks and labels are shared to save space and make comparisons easier.
+
+If you do not require an x axis and y axis for each plot at all, you can disable it with the ``xaxis`` and ``yaxis`` options:
+
+
+```python
+air_ds = xr.tutorial.open_dataset('air_temperature').load()
+
+air_ds.air.isel(time=slice(0, 5)).hvplot(col='time', xaxis=False, yaxis=False, colorbar=False)
+```
+
+Using subplots and grids in this way is supported throughout the hvPlot API, making it simple to determine how you want your data laid out and overlaid.

hvplot_docs/Timeseries_Data.md

@@ -0,0 +1,103 @@
+Almost all the other sections in the user guide mention timeseries. This section demonstrates the special functionality that hvPlot provides specifically for dealing with time. 
+
+
+```python
+import hvplot.pandas  # noqa
+from bokeh.sampledata.sea_surface_temperature import sea_surface_temperature as sst
+
+sst.hvplot()
+```
+
+By default, the index will be used as the x-axis when plotting tabular data. If the index is composed of datetimes, and they are not in chronological order, hvPlot will try to sort them before plotting (unless you set ``sort_date=False``).
+
+
+```python
+scrampled = sst.sample(frac=1)
+scrampled.hvplot()
+```
+
+### Tickers
+
+The datetime tickers will be set to a default that is meant to fit in the allotted space. If you'd rather use a different format, then you can declare an explicit date ticker according to the rules on [Bokeh DatetimeTickFormatter](https://bokeh.pydata.org/en/latest/docs/reference/models/formatters.html#bokeh.models.formatters.DatetimeTickFormatter).
+
+
+```python
+from bokeh.models.formatters import DatetimeTickFormatter
+
+formatter = DatetimeTickFormatter(months='%b %Y')
+sst.hvplot(xformatter=formatter)
+```
+
+### Auto-range
+
+*(Available with HoloViews >= 1.16)*
+
+Automatic ranging, aka auto-ranging, on the data in x or y is supported, making it easy to scale the given axes and fit the entire visible curve after a zoom or pan. Try zooming in on the plot and panning around, the y range nicely adapt to fit the curve. 
+
+
+```python
+sst.hvplot(autorange="y")
+```
+
+### Pandas datetime features
+
+hvPlot takes advantage of datetime features to make it trivial to produce plots that are aggregated on some feature of the date. For instance in the case of temperature data, it might be interesting to examine the monthly temperature distribution. We can easily do that by setting ``by='index.month'``.
+
+
+```python
+sst.hvplot.violin(by='index.month')
+```
+
+We can also use these datetime features as the ``x`` and ``y``. Here we'll look at the mean temperature at each hour of the day for each month in our dataset. 
+
+
+```python
+sst.hvplot.heatmap(x='index.hour', y='index.month', C='temperature', cmap='reds')
+```
+
+Combining this with the information from the [section on widgets](Widgets.ipynb), we can even use the datetime features to produce a plot that steps through each month in the data.
+
+
+```python
+sst.hvplot(groupby=['index.year', 'index.month'], widget_type='scrubber', widget_location='bottom')
+```
+
+### Xarray datetime features
+
+The same datetime features can be used with xarray data as well, although for now, the functionality is only supported for non-gridded output. 
+
+
+```python
+import xarray as xr
+import hvplot.xarray  # noqa
+
+air_ds = xr.tutorial.open_dataset('air_temperature').load()
+air_ds
+```
+
+Similar to how we did for sea surface temperature above, we can get the distribution of air temperature by month.
+
+
+```python
+air_ds.hvplot.violin(y='air', by='time.month')
+```
+
+Once we reduce the dimensionality (by taking the mean over 'lat' and 'lon'), we can groupby various datetime features.
+
+
+```python
+air_ds.mean(dim=['lat', 'lon']).hvplot(by='time.hour', groupby=['time.year', 'time.month'])
+```
+
+Note that xarray supports grouping and aggregation using a similar syntax. To learn more about timeseries in xarray, see the [xarray timeseries docs](https://xarray.pydata.org/en/stable/time-series.html).
+
+### Downsample time series
+
+*(Available with HoloViews >= 1.16)*
+
+An option when working with large time series is to downsample the data before plotting it. This can be done with `downsample=True`, which applies the `lttb` (Largest Triangle Three Buckets) algorithm to the data.
+
+
+```python
+sst.hvplot(label="original") * sst.hvplot(downsample=True, label="downsampled")
+```

hvplot_docs/Viewing.md

@@ -0,0 +1,90 @@
+hvPlot is written to work well inside a Jupyter notebook, from the interactive Python command prompt, or inside a Python batch script. In this user guide we will discover how to use hvPlot to view plots in each of these cases and how to save the plots to a separate file.
+
+## Using hvPlot in different contexts
+
+### Notebook
+
+In a Jupyter notebook, hvPlot will return HoloViews objects that display themselves, as long as the plotting library has been loaded. The easiest way of loading the plotting library is to import one of the plotting accessors such as pandas' one with `hvplot.pandas`:
+
+
+```python
+import hvplot.pandas  # noqa
+```
+
+The above import statement triggers the loading of the default plotting library, i.e. Bokeh.
+
+Here we will load some of the sample data and then compose the HoloViews objects into a layout:
+
+
+```python
+from hvplot.sample_data import airline_flights, us_crime
+
+violent_crime = us_crime.hvplot(x='Year', y='Violent Crime rate', width=400)
+burglaries    = us_crime.hvplot(x='Year', y='Burglary rate', width=400)
+
+violent_crime + burglaries
+```
+
+### Using Panel
+
+To display the object from inside a function it's recommended that you use [Panel](https://panel.holoviz.org). Panel can also be used to create more complicated layouts, to add additional interactivity, and to deploy servers.
+
+
+```python
+import panel as pn
+
+pane = pn.panel(violent_crime)
+pane
+```
+
+This ``pane`` can be updated with another HoloViews object replacing the plot:
+
+
+```python
+pane.object = burglaries
+```
+
+Or the object can be updated inplace:
+
+
+```python
+pane.object *= violent_crime 
+```
+
+### Python Command Prompt & Scripts
+
+When working outside the notebook we can instead use the ``hvplot.show`` function, which will open the plot in a new browser window:
+
+<img src="../assets/console.png" style="display: table; margin: 0 auto;"></img>
+
+For static plots this will simply save a temporary file and open it, however for dynamic and [datashaded](https://datashader.org) plots it will automatically launch a Bokeh server, enabling all the dynamic features.
+
+<img src="../assets/console_server.gif" style="display: table; margin: 0 auto;"></img>
+
+## Saving plots
+
+When looking at any Bokeh plot in a web browser, you can use the toolbar's "Save" tool to export the plot as a PNG (try it on one of the plots above!).
+
+hvPlot also provides a convenient ``save`` function to export HoloViews objects to a file. By default it will save the plot as HTML:
+
+
+```python
+plot = airline_flights.hvplot.hexbin(x='airtime', y='arrdelay', colorbar=True, width=600, height=500, logz=True)
+
+hvplot.save(plot, 'test.html')
+```
+
+By default, the HTML file generated will depend on loading JavaScript code for BokehJS from the online CDN repository, to reduce the file size.  If you need to work in an airgapped or no-network environment, you can declare that `INLINE` resources should be used instead of `CDN`:
+
+
+```python
+from bokeh.resources import INLINE
+hvplot.save(plot, 'test.html', resources=INLINE)
+```
+
+Finally, if a 'png' file extension is specified, the exported plot will be rendered as a PNG, which currently requires Selenium and PhantomJS to be installed:
+
+
+```python
+hvplot.save(plot, 'test.png')
+```

hvplot_docs/Widgets.md

@@ -0,0 +1,92 @@
+As we have seen in previous sections, hvPlot bakes in interactivity by automatically creating widgets when using ``groupby``. These widgets can be refined using [Panel](https://panel.holoviz.org). Panel allows you to customize the interactivity of your hvPlot output and provides more fine-grained control over the layout.
+
+<div class="alert alert-warning" role="alert">
+  When viewing on a static website, the widgets will be inoperable. To explore this functionality fully, download the notebook and run it!
+</div>
+
+
+```python
+import panel as pn
+import hvplot.pandas  # noqa
+
+from bokeh.sampledata.iris import flowers
+
+```
+
+When ``groupby`` is used, the default widget is selected for the data type of the column. In this case since 'species' is composed of strings, the widget an instance of the class ``pn.widgets.Select``.
+
+
+```python
+flowers.hvplot.bivariate(x='sepal_width', y='sepal_length', width=600, 
+                         groupby='species')
+```
+
+### Customizing Widgets
+
+We can change where the widget is shown using the ``widget_location`` option.
+
+
+```python
+flowers.hvplot.bivariate(x='sepal_width', y='sepal_length', width=600, 
+                         groupby='species', widget_location='left_top')
+```
+
+We can also change what the class of the widget is, using the ``widgets`` dict. For instance if we want to use a slider instead of a selector we can specify that.
+
+
+```python
+flowers.hvplot.bivariate(x='sepal_width', y='sepal_length', width=600, 
+                         groupby='species', widgets={'species': pn.widgets.DiscreteSlider})
+```
+
+### Using widgets as arguments
+
+So far we have only been dealing with widgets that are produced when using the ``groupby`` key word. But panel provides many other ways of expanding the interactivity of hvplot objects. For instance we might want to allow the user to select which fields to plot on the ``x`` and ``y`` axes. Or even what ``kind`` of plot to produce.
+
+
+```python
+x = pn.widgets.Select(name='x', options=['sepal_width', 'petal_width'])
+y = pn.widgets.Select(name='y', options=['sepal_length', 'petal_length'])
+kind = pn.widgets.Select(name='kind', value='scatter', options=['bivariate', 'scatter'])
+
+plot = flowers.hvplot(x=x, y=y, kind=kind, colorbar=False, width=600)
+pn.Row(pn.WidgetBox(x, y, kind), plot)
+```
+
+### Using functions
+
+In addition to using widgets directly as arguments, we can also use functions that have been decorated with ``pn.depends``
+
+
+```python
+x = pn.widgets.Select(name='x', options=['sepal_width', 'petal_width'])
+y = pn.widgets.Select(name='y', options=['sepal_length', 'petal_length'])
+kind = pn.widgets.Select(name='kind', value='scatter', options=['bivariate', 'scatter'])
+by_species = pn.widgets.Checkbox(name='By species')
+color = pn.widgets.ColorPicker(value='#ff0000')
+
+@pn.depends(by_species, color)
+def by_species_fn(by_species, color):
+    return 'species' if by_species else color
+
+plot = flowers.hvplot(x=x, y=y, kind=kind, c=by_species_fn, colorbar=False, width=600, legend='top_right')
+
+pn.Row(pn.WidgetBox(x, y, kind, color, by_species), plot)
+```
+
+We can keep even add a callback to disable the color options when 'bivariate' is selected. After running the cell below, try changing 'kind' above and notice how the color and 'By species' areas turn grey to indicate that they are disabled.
+
+
+```python
+def update(event):
+    if kind.value == 'bivariate':
+        color.disabled = True
+        by_species.disabled = True
+    else:
+        color.disabled = False
+        by_species.disabled = False
+
+kind.param.watch(update, 'value');
+```
+
+To learn more about Panel and how to use it with output from hvPlot, see the [Panel docs on the HoloViews pane](https://panel.pyviz.org/reference/panes/HoloViews.html). To learn more about available widgets, see the Widgets' section of the [Panel Reference Gallery](https://panel.pyviz.org/reference/index.html).

hvplot_docs/plot.html

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en" >
+  <head>
+    <meta charset="utf-8">
+    <title>plot</title>
+    <link rel="apple-touch-icon" sizes="180x180" href="https://cdn.holoviz.org/panel/1.3.6/dist/images/apple-touch-icon.png">
+ <link rel="icon" type="image/png" sizes="32x32" href="https://cdn.holoviz.org/panel/1.3.6/dist/images/favicon.ico">     <style>
+      html, body {
+	display: flow-root;
+        box-sizing: border-box;
+        height: 100%;
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+<script type="text/javascript" src="https://cdn.bokeh.org/bokeh/release/bokeh-3.3.2.min.js"></script>
+<script type="text/javascript" src="https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.3.2.min.js"></script>
+<script type="text/javascript" src="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.3.2.min.js"></script>
+<script type="text/javascript" src="https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.3.2.min.js"></script>
+<script type="text/javascript" src="https://cdn.holoviz.org/panel/1.3.6/dist/panel.min.js"></script>
+
+<script type="text/javascript">
+  Bokeh.set_log_level("info");
+</script>  </head>
+  <body>
+    <div id="bc2d23bf-3023-4b2e-9825-bb0daf9fdc45" data-root-id="p1579" style="display: contents;"></div>
+  
+    <script type="application/json" id="p1678">
+      {"8d93a4b1-0241-4312-97a2-9d7e8cf602d5":{"version":"3.3.2","title":"Bokeh Application","roots":[{"type":"object","name":"Row","id":"p1579","attributes":{"name":"Row01837","tags":["embedded"],"stylesheets":["\n:host(.pn-loading.pn-arc):before, .pn-loading.pn-arc:before {\n  background-image: url(\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHN0eWxlPSJtYXJnaW46IGF1dG87IGJhY2tncm91bmQ6IG5vbmU7IGRpc3BsYXk6IGJsb2NrOyBzaGFwZS1yZW5kZXJpbmc6IGF1dG87IiB2aWV3Qm94PSIwIDAgMTAwIDEwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQiPiAgPGNpcmNsZSBjeD0iNTAiIGN5PSI1MCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYzNjM2MzIiBzdHJva2Utd2lkdGg9IjEwIiByPSIzNSIgc3Ryb2tlLWRhc2hhcnJheT0iMTY0LjkzMzYxNDMxMzQ2NDE1IDU2Ljk3Nzg3MTQzNzgyMTM4Ij4gICAgPGFuaW1hdGVUcmFuc2Zvcm0gYXR0cmlidXRlTmFtZT0idHJhbnNmb3JtIiB0eXBlPSJyb3RhdGUiIHJlcGVhdENvdW50PSJpbmRlZmluaXRlIiBkdXI9IjFzIiB2YWx1ZXM9IjAgNTAgNTA7MzYwIDUwIDUwIiBrZXlUaW1lcz0iMDsxIj48L2FuaW1hdGVUcmFuc2Zvcm0+ICA8L2NpcmNsZT48L3N2Zz4=\");\n  background-size: auto calc(min(50%, 400px));\n}",{"type":"object","name":"ImportedStyleSheet","id":"p1669","attributes":{"url":"https://cdn.holoviz.org/panel/1.3.6/dist/css/loading.css"}},{"type":"object","name":"ImportedStyleSheet","id":"p1670","attributes":{"url":"https://cdn.holoviz.org/panel/1.3.6/dist/css/listpanel.css"}},{"type":"object","name":"ImportedStyleSheet","id":"p1667","attributes":{"url":"https://cdn.holoviz.org/panel/1.3.6/dist/bundled/theme/default.css"}},{"type":"object","name":"ImportedStyleSheet","id":"p1668","attributes":{"url":"https://cdn.holoviz.org/panel/1.3.6/dist/bundled/theme/native.css"}}],"min_height":400,"margin":0,"sizing_mode":"stretch_both","align":"start","children":[{"type":"object","name":"Figure","id":"p1593","attributes":{"width":null,"height":null,"min_height":400,"margin":[5,10],"sizing_mode":"stretch_both","align":"start","x_range":{"type":"object","name":"Range1d","id":"p1580","attributes":{"tags":[[["bill_length_mm","bill_length_mm",null]],[]],"start":29.35,"end":62.35,"reset_start":29.35,"reset_end":62.35}},"y_range":{"type":"object","name":"Range1d","id":"p1581","attributes":{"tags":[[["bill_depth_mm","bill_depth_mm",null]],{"type":"map","entries":[["invert_yaxis",false],["autorange",false]]}],"start":12.26,"end":22.34,"reset_start":12.26,"reset_end":22.34}},"x_scale":{"type":"object","name":"LinearScale","id":"p1603"},"y_scale":{"type":"object","name":"LinearScale","id":"p1604"},"title":{"type":"object","name":"Title","id":"p1596","attributes":{"text":"Penguins Scatter","text_color":"black","text_font_size":"12pt"}},"renderers":[{"type":"object","name":"GlyphRenderer","id":"p1633","attributes":{"name":"Adelie","data_source":{"type":"object","name":"ColumnDataSource","id":"p1624","attributes":{"selected":{"type":"object","name":"Selection","id":"p1625","attributes":{"indices":[],"line_indices":[]}},"selection_policy":{"type":"object","name":"UnionRenderers","id":"p1626"},"data":{"type":"map","entries":[["bill_length_mm",{"type":"ndarray","array":{"type":"bytes","data":"zczMzMyMQ0AAAAAAAMBDQGZmZmZmJkRAAAAAAAAA+H+amZmZmVlCQGZmZmZmpkNAMzMzMzNzQ0CamZmZmZlDQM3MzMzMDEFAAAAAAAAARUBmZmZmZuZCQGZmZmZm5kJAzczMzMyMREDNzMzMzExDQM3MzMzMTEFAzczMzMxMQkCamZmZmVlDQAAAAAAAQEVAMzMzMzMzQUAAAAAAAABHQGZmZmZm5kJAmpmZmZnZQkAzMzMzM/NBQJqZmZmZGUNAZmZmZmZmQ0BmZmZmZqZBQM3MzMzMTERAAAAAAABAREAzMzMzM/NCQAAAAAAAQERAAAAAAADAQ0CamZmZmZlCQAAAAAAAwENAMzMzMzNzREAzMzMzMzNCQJqZmZmZmUNAZmZmZmZmQ0CamZmZmRlFQM3MzMzMzEJAZmZmZmbmQ0AAAAAAAEBCQGZmZmZmZkRAAAAAAAAAQkDNzMzMzAxGQAAAAAAAgEJAzczMzMzMQ0DNzMzMzIxEQAAAAAAAwEJAAAAAAAAAQkBmZmZmZiZFQM3MzMzMzENAzczMzMwMREAAAAAAAIBBQAAAAAAAAEVAAAAAAABAQUAzMzMzM7NEQAAAAAAAgENAzczMzMxMREAAAAAAAEBCQM3MzMzMzEJAmpmZmZnZQUBmZmZmZqZEQM3MzMzMzEJAzczMzMyMREAzMzMzMzNCQM3MzMzMzERAAAAAAADAQUDNzMzMzIxEQDMzMzMz80FAZmZmZmbmREAAAAAAAMBAQJqZmZmZ2UNAzczMzMzMQ0BmZmZmZuZGQAAAAAAAwEFAZmZmZmZmRUAzMzMzM3NEQJqZmZmZmUJAmpmZmZkZQkDNzMzMzAxFQM3MzMzMTEFAMzMzMzNzRUCamZmZmVlCQM3MzMzMjEFAZmZmZmamQkBmZmZmZqZEQGZmZmZmJkJAMzMzMzNzQkBmZmZmZiZDQDMzMzMzc0NAmpmZmZnZQUDNzMzMzIxEQAAAAAAAAEFAzczMzMzMQ0CamZmZmRlCQGZmZmZmZkRAzczMzMwMQ0BmZmZmZiZEQM3MzMzMjEBAmpmZmZmZRUAAAAAAAIBBQAAAAAAAgERAmpmZmZnZQkBmZmZmZuZCQDMzMzMz80JAmpmZmZnZQ0DNzMzMzExDQJqZmZmZGUNAzczMzMwMQ0CamZmZmZlFQM3MzMzMDENAzczMzMzMRkCamZmZmdlDQJqZmZmZGUVAzczMzMzMQ0CamZmZmVlFQM3MzMzMTENAZmZmZmamQkCamZmZmdlBQM3MzMzMjERAmpmZmZkZQkCamZmZmdlCQJqZmZmZGURAMzMzMzOzRECamZmZmZlBQM3MzMzMTERAZmZmZmZmQ0AAAAAAAMBEQAAAAAAAgENAzczMzMwMRkAAAAAAAEBDQM3MzMzMjEVAZmZmZmZmQkAAAAAAAMBCQM3MzMzMDENAzczMzMyMREDNzMzMzMxBQJqZmZmZGURAAAAAAACAQkCamZmZmdlDQJqZmZmZGURAzczMzMxMREDNzMzMzAxAQJqZmZmZWURAZmZmZmamQkAAAAAAAIBDQJqZmZmZmUNAzczMzMxMQkAAAAAAAABCQGZmZmZm5kJAAAAAAAAAQkAAAAAAAMBEQA=="},"shape":[152],"dtype":"float64","order":"little"}],["bill_depth_mm",{"type":"ndarray","array":{"type":"bytes","data":"MzMzMzOzMkBmZmZmZmYxQAAAAAAAADJAAAAAAAAA+H/NzMzMzEwzQJqZmZmZmTRAzczMzMzMMUCamZmZmZkzQJqZmZmZGTJAMzMzMzMzNECamZmZmRkxQM3MzMzMTDFAmpmZmZmZMUAzMzMzMzM1QJqZmZmZGTVAzczMzMzMMUAAAAAAAAAzQDMzMzMzszRAZmZmZmZmMkAAAAAAAIA1QM3MzMzMTDJAMzMzMzOzMkAzMzMzMzMzQJqZmZmZGTJAMzMzMzMzMUBmZmZmZuYyQJqZmZmZmTJAZmZmZmbmMUCamZmZmZkyQGZmZmZm5jJAMzMzMzOzMECamZmZmRkyQM3MzMzMzDFAZmZmZmbmMkAAAAAAAAAxQJqZmZmZGTVAAAAAAAAANEAAAAAAAIAyQM3MzMzMTDNAmpmZmZkZM0AAAAAAAAAyQGZmZmZmZjJAAAAAAACAMkAzMzMzM7MzQGZmZmZm5jBAzczMzMzMMkAAAAAAAAAzQGZmZmZm5jJAZmZmZmbmMUAzMzMzMzM1QDMzMzMzszFAZmZmZmbmMkBmZmZmZuYxQAAAAAAAgDNAmpmZmZkZMkCamZmZmZkyQAAAAAAAgDFAzczMzMzMMkCamZmZmZkwQJqZmZmZGTNAZmZmZmbmMECamZmZmRk1QAAAAAAAADFAMzMzMzMzMkCamZmZmRkxQAAAAAAAADJAMzMzMzMzMECamZmZmRkzQJqZmZmZmTBAZmZmZmZmM0AAAAAAAAAzQGZmZmZmZjJAMzMzMzMzMUBmZmZmZuYyQAAAAAAAgDFAAAAAAACAMkDNzMzMzMwwQGZmZmZmZjNAmpmZmZkZMECamZmZmRkzQDMzMzMzMzFAmpmZmZmZMUDNzMzMzMwyQGZmZmZmZjNAzczMzMzMMUDNzMzMzEw0QAAAAAAAgDNAmpmZmZmZMkAzMzMzMzMzQM3MzMzMzDJAAAAAAAAAMkCamZmZmRkyQJqZmZmZGTFAmpmZmZkZMkDNzMzMzEwxQGZmZmZm5jJAmpmZmZmZMkAAAAAAAIAyQJqZmZmZGTBAAAAAAACAMkBmZmZmZuYxQAAAAAAAADRAAAAAAAAAMEAAAAAAAAA0QJqZmZmZmTJAZmZmZmbmMkAzMzMzMzMxQAAAAAAAADRAAAAAAAAAMUAAAAAAAAAzQAAAAAAAgDBAzczMzMxMNEAzMzMzM7MxQAAAAAAAgDNAMzMzMzOzNEDNzMzMzEwyQAAAAAAAADFAAAAAAACANEAAAAAAAAAxQJqZmZmZmTJAMzMzMzMzMUDNzMzMzMwzQAAAAAAAADFAAAAAAACAMkDNzMzMzMwvQAAAAAAAADNAmpmZmZmZMUDNzMzMzEwyQJqZmZmZGTFAAAAAAAAAMkBmZmZmZuYxQDMzMzMzMzNAAAAAAACAMkAAAAAAAIAyQJqZmZmZmTFAAAAAAACAMUAAAAAAAIAxQJqZmZmZGTRAAAAAAACAMEBmZmZmZuYxQJqZmZmZGTFAMzMzMzMzMUAAAAAAAAAvQAAAAAAAADFAzczMzMzMMEAzMzMzM7MyQJqZmZmZmTJAZmZmZmZmMkDNzMzMzMwxQJqZmZmZGTJAmpmZmZkZMUAAAAAAAIAyQA=="},"shape":[152],"dtype":"float64","order":"little"}],["species",["Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie","Adelie"]]]}}},"view":{"type":"object","name":"CDSView","id":"p1634","attributes":{"filter":{"type":"object","name":"AllIndices","id":"p1635"}}},"glyph":{"type":"object","name":"Scatter","id":"p1630","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#30a2da"},"fill_color":{"type":"value","value":"#30a2da"},"hatch_color":{"type":"value","value":"#30a2da"}}},"selection_glyph":{"type":"object","name":"Scatter","id":"p1638","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"angle":{"type":"value","value":0.0},"line_color":{"type":"value","value":"#30a2da"},"line_alpha":{"type":"value","value":1},"line_width":{"type":"value","value":1},"line_join":{"type":"value","value":"bevel"},"line_cap":{"type":"value","value":"butt"},"line_dash":{"type":"value","value":[]},"line_dash_offset":{"type":"value","value":0},"fill_color":{"type":"value","value":"#30a2da"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#30a2da"},"hatch_alpha":{"type":"value","value":1.0},"hatch_scale":{"type":"value","value":12.0},"hatch_pattern":{"type":"value","value":null},"hatch_weight":{"type":"value","value":1.0},"marker":{"type":"value","value":"circle"}}},"nonselection_glyph":{"type":"object","name":"Scatter","id":"p1631","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#30a2da"},"line_alpha":{"type":"value","value":1},"fill_color":{"type":"value","value":"#30a2da"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#30a2da"},"hatch_alpha":{"type":"value","value":0.1}}},"muted_glyph":{"type":"object","name":"Scatter","id":"p1632","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#30a2da"},"line_alpha":{"type":"value","value":0.2},"fill_color":{"type":"value","value":"#30a2da"},"fill_alpha":{"type":"value","value":0.2},"hatch_color":{"type":"value","value":"#30a2da"},"hatch_alpha":{"type":"value","value":0.2}}}}},{"type":"object","name":"GlyphRenderer","id":"p1648","attributes":{"name":"Chinstrap","data_source":{"type":"object","name":"ColumnDataSource","id":"p1639","attributes":{"selected":{"type":"object","name":"Selection","id":"p1640","attributes":{"indices":[],"line_indices":[]}},"selection_policy":{"type":"object","name":"UnionRenderers","id":"p1641"},"data":{"type":"map","entries":[["bill_length_mm",{"type":"ndarray","array":{"type":"bytes","data":"AAAAAABAR0AAAAAAAABJQGZmZmZmpklAMzMzMzOzRkCamZmZmVlKQJqZmZmZmUZAzczMzMwMR0BmZmZmZqZJQAAAAAAAAEdAZmZmZmamSUDNzMzMzExHQJqZmZmZ2UlAAAAAAACAR0AAAAAAAABKQDMzMzMz80ZAAAAAAABASUBmZmZmZiZJQAAAAAAAAE1AMzMzMzMzR0CamZmZmZlIQDMzMzMzM0VAAAAAAABASECamZmZmZlFQM3MzMzMTElAmpmZmZlZR0AAAAAAAABKQAAAAAAAQElAAAAAAADASEAzMzMzMzNHQGZmZmZmZkpAMzMzMzNzRECamZmZmRlLQAAAAAAAQEVAAAAAAACASUCamZmZmdlIQAAAAAAAwEdAzczMzMzMR0AAAAAAAABKQDMzMzMzc0dAAAAAAADASkAAAAAAAIBIQJqZmZmZGUdAMzMzMzNzSUAAAAAAAMBGQDMzMzMzc0lAZmZmZmZmSUDNzMzMzAxJQAAAAAAAgEhAAAAAAADASUBmZmZmZuZIQM3MzMzMDEhAMzMzMzOzSUCamZmZmdlGQJqZmZmZWUlAAAAAAABARUCamZmZmRlKQJqZmZmZmUZAZmZmZmamSECamZmZmRlJQM3MzMzMzEZAMzMzMzPzSUBmZmZmZmZHQJqZmZmZ2UZAZmZmZmbmS0AAAAAAAMBFQM3MzMzMzEhAZmZmZmZmSUCamZmZmRlJQA=="},"shape":[68],"dtype":"float64","order":"little"}],["bill_depth_mm",{"type":"ndarray","array":{"type":"bytes","data":"ZmZmZmbmMUAAAAAAAIAzQDMzMzMzMzNAMzMzMzOzMkDNzMzMzMwzQM3MzMzMzDFAMzMzMzMzMkAzMzMzMzMyQGZmZmZm5jJAZmZmZmbmM0DNzMzMzMwxQM3MzMzMTDRAzczMzMxMMUCamZmZmRkyQJqZmZmZGTFAmpmZmZmZM0AAAAAAAAA0QM3MzMzMzDFAmpmZmZmZMkAzMzMzMzMyQM3MzMzMTDFAAAAAAACAMUCamZmZmZkwQGZmZmZmZjNAZmZmZmbmMUAAAAAAAAAzQGZmZmZmZjJAAAAAAAAAM0DNzMzMzMwxQAAAAAAAADRAmpmZmZmZMEDNzMzMzMw0QDMzMzMzszBAzczMzMzMMkCamZmZmZkyQM3MzMzMzDBAzczMzMxMMkAzMzMzM7M0QJqZmZmZmTBAZmZmZmbmM0AAAAAAAIAzQAAAAAAAgDFAmpmZmZkZM0AAAAAAAAAxQGZmZmZm5jFAAAAAAACAMkBmZmZmZuYxQJqZmZmZmTNAMzMzMzOzMkDNzMzMzEwxQGZmZmZmZjBAAAAAAAAAM0DNzMzMzEwxQDMzMzMzszNAzczMzMxMMUDNzMzMzMwyQJqZmZmZmTBAZmZmZmbmM0DNzMzMzMwyQGZmZmZmZjNAAAAAAACAM0AAAAAAAIAwQAAAAAAAADFAzczMzMzMM0CamZmZmRkyQDMzMzMzMzJAAAAAAAAAM0AzMzMzM7MyQA=="},"shape":[68],"dtype":"float64","order":"little"}],["species",["Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap","Chinstrap"]]]}}},"view":{"type":"object","name":"CDSView","id":"p1649","attributes":{"filter":{"type":"object","name":"AllIndices","id":"p1650"}}},"glyph":{"type":"object","name":"Scatter","id":"p1645","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#fc4f30"},"fill_color":{"type":"value","value":"#fc4f30"},"hatch_color":{"type":"value","value":"#fc4f30"}}},"selection_glyph":{"type":"object","name":"Scatter","id":"p1652","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"angle":{"type":"value","value":0.0},"line_color":{"type":"value","value":"#fc4f30"},"line_alpha":{"type":"value","value":1},"line_width":{"type":"value","value":1},"line_join":{"type":"value","value":"bevel"},"line_cap":{"type":"value","value":"butt"},"line_dash":{"type":"value","value":[]},"line_dash_offset":{"type":"value","value":0},"fill_color":{"type":"value","value":"#fc4f30"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#fc4f30"},"hatch_alpha":{"type":"value","value":1.0},"hatch_scale":{"type":"value","value":12.0},"hatch_pattern":{"type":"value","value":null},"hatch_weight":{"type":"value","value":1.0},"marker":{"type":"value","value":"circle"}}},"nonselection_glyph":{"type":"object","name":"Scatter","id":"p1646","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#fc4f30"},"line_alpha":{"type":"value","value":1},"fill_color":{"type":"value","value":"#fc4f30"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#fc4f30"},"hatch_alpha":{"type":"value","value":0.1}}},"muted_glyph":{"type":"object","name":"Scatter","id":"p1647","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#fc4f30"},"line_alpha":{"type":"value","value":0.2},"fill_color":{"type":"value","value":"#fc4f30"},"fill_alpha":{"type":"value","value":0.2},"hatch_color":{"type":"value","value":"#fc4f30"},"hatch_alpha":{"type":"value","value":0.2}}}}},{"type":"object","name":"GlyphRenderer","id":"p1662","attributes":{"name":"Gentoo","data_source":{"type":"object","name":"ColumnDataSource","id":"p1653","attributes":{"selected":{"type":"object","name":"Selection","id":"p1654","attributes":{"indices":[],"line_indices":[]}},"selection_policy":{"type":"object","name":"UnionRenderers","id":"p1655"},"data":{"type":"map","entries":[["bill_length_mm",{"type":"ndarray","array":{"type":"bytes","data":"zczMzMwMR0AAAAAAAABJQJqZmZmZWUhAAAAAAAAASUDNzMzMzMxHQAAAAAAAQEdAMzMzMzOzRkCamZmZmVlHQGZmZmZmpkVAZmZmZmZmR0AzMzMzM3NEQAAAAAAAgEhAAAAAAADARkAzMzMzMzNIQGZmZmZm5kZAZmZmZmamSEAAAAAAAABFQJqZmZmZmUhAmpmZmZkZR0CamZmZmVlIQJqZmZmZGUlAzczMzMyMRkAAAAAAAEBHQGZmZmZmJkdAMzMzMzNzRUDNzMzMzAxHQAAAAAAAQEZAZmZmZmbmR0CamZmZmRlIQAAAAAAAAElAZmZmZmamR0BmZmZmZmZFQM3MzMzMjEZAzczMzMzMTUDNzMzMzIxIQDMzMzMzM0hAzczMzMxMRUAzMzMzMzNGQAAAAAAAAEZAmpmZmZlZSECamZmZmVlFQM3MzMzMzEhAZmZmZmamRkDNzMzMzMxIQAAAAAAAQElAzczMzMzMRUAAAAAAAMBGQAAAAAAAQElAMzMzMzNzRkCamZmZmZlGQM3MzMzMTEdAAAAAAABASEDNzMzMzIxGQM3MzMzMDElAAAAAAABAR0AAAAAAAIBGQGZmZmZm5kVAAAAAAADARkCamZmZmZlFQDMzMzMzM0lAZmZmZmamRkCamZmZmRlHQJqZmZmZ2UZAZmZmZmYmS0BmZmZmZuZGQGZmZmZm5khAmpmZmZkZR0AAAAAAAMBIQAAAAAAAwEVAmpmZmZlZSUCamZmZmdlHQDMzMzMzM0dAmpmZmZkZSEAAAAAAAEBHQDMzMzMzM0dAzczMzMxMSEAAAAAAAMBHQM3MzMzMjElAmpmZmZmZRkCamZmZmZlGQM3MzMzMjEhAAAAAAABASkAzMzMzM7NHQAAAAAAAAElAMzMzMzNzRkBmZmZmZmZJQDMzMzMzs0VAZmZmZmamSUAAAAAAAMBHQM3MzMzMDEpAAAAAAADAR0CamZmZmRlKQAAAAAAAwEZAAAAAAADASEAAAAAAAEBGQGZmZmZmZklAMzMzMzOzSEAzMzMzM3NHQDMzMzMzM0hAzczMzMyMSUAAAAAAAEBIQDMzMzMz80tAmpmZmZmZR0DNzMzMzIxIQGZmZmZmpkdAZmZmZmZmR0CamZmZmdlEQDMzMzMzs0pAZmZmZmamRUDNzMzMzAxIQAAAAAAAQElAZmZmZmbmSEAAAAAAAMBFQAAAAAAAwElAmpmZmZkZR0DNzMzMzIxLQAAAAAAAQEZAZmZmZmZmSECamZmZmZlHQAAAAAAAAPh/ZmZmZmZmR0AzMzMzMzNJQJqZmZmZmUZAMzMzMzPzSEA="},"shape":[124],"dtype":"float64","order":"little"}],["bill_depth_mm",{"type":"ndarray","array":{"type":"bytes","data":"ZmZmZmZmKkDNzMzMzEwwQDMzMzMzMyxAZmZmZmZmLkAAAAAAAAAtQAAAAAAAACtAMzMzMzMzLUCamZmZmZkuQM3MzMzMzCpAzczMzMzMLkBmZmZmZmYrQJqZmZmZGTBAZmZmZmZmK0AzMzMzMzMtQDMzMzMzMy1AZmZmZmZmL0AAAAAAAAArQGZmZmZmZi5AAAAAAAAALUAzMzMzMzMuQJqZmZmZmSxAAAAAAAAALUAAAAAAAAAtQJqZmZmZmS9AMzMzMzMzKkAzMzMzMzMuQJqZmZmZmSxAAAAAAAAALkCamZmZmZksQJqZmZmZmS5AmpmZmZmZLkBmZmZmZmYsQAAAAAAAAC1AAAAAAAAAMUCamZmZmZktQM3MzMzMTDBAZmZmZmZmK0DNzMzMzEwxQDMzMzMzMytAZmZmZmZmL0BmZmZmZmYrQAAAAAAAADBAZmZmZmZmK0AAAAAAAAAuQM3MzMzMzC9AzczMzMzMK0DNzMzMzMwrQM3MzMzMzC9AmpmZmZmZKkCamZmZmZkvQGZmZmZmZixAMzMzMzMzLEDNzMzMzMwsQAAAAAAAAC5AzczMzMzMLEDNzMzMzMwuQM3MzMzMzCtAAAAAAAAALkAAAAAAAAAtQJqZmZmZmS5AmpmZmZmZK0DNzMzMzMwtQM3MzMzMzCtAZmZmZmZmL0BmZmZmZmYsQM3MzMzMzDBAzczMzMzMLEAzMzMzMzMwQGZmZmZmZixAAAAAAAAALkAAAAAAAAAuQDMzMzMzMy9AMzMzMzMzL0CamZmZmZktQAAAAAAAAC5AAAAAAAAAMEBmZmZmZmYsQM3MzMzMTDBAmpmZmZmZK0BmZmZmZmYwQAAAAAAAAC1AMzMzMzMzL0AzMzMzMzMtQM3MzMzMzC9AmpmZmZmZK0DNzMzMzEwxQM3MzMzMzCxAZmZmZmZmLEAAAAAAAAAsQAAAAAAAADFAAAAAAAAALkCamZmZmRkxQAAAAAAAAC1AmpmZmZkZMEBmZmZmZmYtQGZmZmZmZi9AmpmZmZmZL0AzMzMzMzMtQM3MzMzMzCxAAAAAAACAMEAAAAAAAAAuQAAAAAAAADFAAAAAAAAAL0AAAAAAAAAuQJqZmZmZmStAmpmZmZkZMEBmZmZmZmYtQJqZmZmZmS9AAAAAAAAALEAzMzMzMzMuQGZmZmZmZi5AzczMzMzML0BmZmZmZmYuQM3MzMzMTDBAMzMzMzMzLEAAAAAAAAAwQGZmZmZmZi9AMzMzMzMzMEBmZmZmZmYrQAAAAAAAAPh/mpmZmZmZLEBmZmZmZmYvQJqZmZmZmS1AmpmZmZkZMEA="},"shape":[124],"dtype":"float64","order":"little"}],["species",["Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo","Gentoo"]]]}}},"view":{"type":"object","name":"CDSView","id":"p1663","attributes":{"filter":{"type":"object","name":"AllIndices","id":"p1664"}}},"glyph":{"type":"object","name":"Scatter","id":"p1659","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#e5ae38"},"fill_color":{"type":"value","value":"#e5ae38"},"hatch_color":{"type":"value","value":"#e5ae38"}}},"selection_glyph":{"type":"object","name":"Scatter","id":"p1666","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"angle":{"type":"value","value":0.0},"line_color":{"type":"value","value":"#e5ae38"},"line_alpha":{"type":"value","value":1},"line_width":{"type":"value","value":1},"line_join":{"type":"value","value":"bevel"},"line_cap":{"type":"value","value":"butt"},"line_dash":{"type":"value","value":[]},"line_dash_offset":{"type":"value","value":0},"fill_color":{"type":"value","value":"#e5ae38"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#e5ae38"},"hatch_alpha":{"type":"value","value":1.0},"hatch_scale":{"type":"value","value":12.0},"hatch_pattern":{"type":"value","value":null},"hatch_weight":{"type":"value","value":1.0},"marker":{"type":"value","value":"circle"}}},"nonselection_glyph":{"type":"object","name":"Scatter","id":"p1660","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#e5ae38"},"line_alpha":{"type":"value","value":1},"fill_color":{"type":"value","value":"#e5ae38"},"fill_alpha":{"type":"value","value":1},"hatch_color":{"type":"value","value":"#e5ae38"},"hatch_alpha":{"type":"value","value":0.1}}},"muted_glyph":{"type":"object","name":"Scatter","id":"p1661","attributes":{"tags":["apply_ranges"],"x":{"type":"field","field":"bill_length_mm"},"y":{"type":"field","field":"bill_depth_mm"},"size":{"type":"value","value":5.477225575051661},"line_color":{"type":"value","value":"#e5ae38"},"line_alpha":{"type":"value","value":0.2},"fill_color":{"type":"value","value":"#e5ae38"},"fill_alpha":{"type":"value","value":0.2},"hatch_color":{"type":"value","value":"#e5ae38"},"hatch_alpha":{"type":"value","value":0.2}}}}}],"toolbar":{"type":"object","name":"Toolbar","id":"p1602","attributes":{"tools":[{"type":"object","name":"WheelZoomTool","id":"p1585","attributes":{"tags":["hv_created"],"renderers":"auto","zoom_together":"none"}},{"type":"object","name":"HoverTool","id":"p1586","attributes":{"tags":["hv_created"],"renderers":[{"id":"p1633"},{"id":"p1648"},{"id":"p1662"}],"tooltips":[["species","@{species}"],["bill_length_mm","@{bill_length_mm}"],["bill_depth_mm","@{bill_depth_mm}"]]}},{"type":"object","name":"SaveTool","id":"p1615"},{"type":"object","name":"PanTool","id":"p1616"},{"type":"object","name":"BoxZoomTool","id":"p1617","attributes":{"overlay":{"type":"object","name":"BoxAnnotation","id":"p1618","attributes":{"syncable":false,"level":"overlay","visible":false,"left":{"type":"number","value":"nan"},"right":{"type":"number","value":"nan"},"top":{"type":"number","value":"nan"},"bottom":{"type":"number","value":"nan"},"left_units":"canvas","right_units":"canvas","top_units":"canvas","bottom_units":"canvas","line_color":"black","line_alpha":1.0,"line_width":2,"line_dash":[4,4],"fill_color":"lightgrey","fill_alpha":0.5}}}},{"type":"object","name":"ResetTool","id":"p1623"}],"active_drag":{"id":"p1616"},"active_scroll":{"id":"p1585"}}},"left":[{"type":"object","name":"LinearAxis","id":"p1610","attributes":{"ticker":{"type":"object","name":"BasicTicker","id":"p1611","attributes":{"mantissas":[1,2,5]}},"formatter":{"type":"object","name":"BasicTickFormatter","id":"p1612"},"axis_label":"bill_depth_mm","major_label_policy":{"type":"object","name":"AllLabels","id":"p1613"}}}],"right":[{"type":"object","name":"Legend","id":"p1636","attributes":{"location":[0,0],"title":"species","click_policy":"mute","items":[{"type":"object","name":"LegendItem","id":"p1637","attributes":{"label":{"type":"value","value":"Adelie"},"renderers":[{"id":"p1633"}]}},{"type":"object","name":"LegendItem","id":"p1651","attributes":{"label":{"type":"value","value":"Chinstrap"},"renderers":[{"id":"p1648"}]}},{"type":"object","name":"LegendItem","id":"p1665","attributes":{"label":{"type":"value","value":"Gentoo"},"renderers":[{"id":"p1662"}]}}]}}],"below":[{"type":"object","name":"LinearAxis","id":"p1605","attributes":{"ticker":{"type":"object","name":"BasicTicker","id":"p1606","attributes":{"mantissas":[1,2,5]}},"formatter":{"type":"object","name":"BasicTickFormatter","id":"p1607"},"axis_label":"bill_length_mm","major_label_policy":{"type":"object","name":"AllLabels","id":"p1608"}}}],"center":[{"type":"object","name":"Grid","id":"p1609","attributes":{"axis":{"id":"p1605"},"grid_line_color":null}},{"type":"object","name":"Grid","id":"p1614","attributes":{"dimension":1,"axis":{"id":"p1610"},"grid_line_color":null}}],"min_border_top":10,"min_border_bottom":10,"min_border_left":10,"min_border_right":10,"output_backend":"webgl"}}]}}],"defs":[{"type":"model","name":"ReactiveHTML1"},{"type":"model","name":"FlexBox1","properties":[{"name":"align_content","kind":"Any","default":"flex-start"},{"name":"align_items","kind":"Any","default":"flex-start"},{"name":"flex_direction","kind":"Any","default":"row"},{"name":"flex_wrap","kind":"Any","default":"wrap"},{"name":"justify_content","kind":"Any","default":"flex-start"}]},{"type":"model","name":"FloatPanel1","properties":[{"name":"config","kind":"Any","default":{"type":"map"}},{"name":"contained","kind":"Any","default":true},{"name":"position","kind":"Any","default":"right-top"},{"name":"offsetx","kind":"Any","default":null},{"name":"offsety","kind":"Any","default":null},{"name":"theme","kind":"Any","default":"primary"},{"name":"status","kind":"Any","default":"normalized"}]},{"type":"model","name":"GridStack1","properties":[{"name":"mode","kind":"Any","default":"warn"},{"name":"ncols","kind":"Any","default":null},{"name":"nrows","kind":"Any","default":null},{"name":"allow_resize","kind":"Any","default":true},{"name":"allow_drag","kind":"Any","default":true},{"name":"state","kind":"Any","default":[]}]},{"type":"model","name":"drag1","properties":[{"name":"slider_width","kind":"Any","default":5},{"name":"slider_color","kind":"Any","default":"black"},{"name":"value","kind":"Any","default":50}]},{"type":"model","name":"click1","properties":[{"name":"terminal_output","kind":"Any","default":""},{"name":"debug_name","kind":"Any","default":""},{"name":"clears","kind":"Any","default":0}]},{"type":"model","name":"copy_to_clipboard1","properties":[{"name":"fill","kind":"Any","default":"none"},{"name":"value","kind":"Any","default":null}]},{"type":"model","name":"FastWrapper1","properties":[{"name":"object","kind":"Any","default":null},{"name":"style","kind":"Any","default":null}]},{"type":"model","name":"NotificationAreaBase1","properties":[{"name":"js_events","kind":"Any","default":{"type":"map"}},{"name":"position","kind":"Any","default":"bottom-right"},{"name":"_clear","kind":"Any","default":0}]},{"type":"model","name":"NotificationArea1","properties":[{"name":"js_events","kind":"Any","default":{"type":"map"}},{"name":"notifications","kind":"Any","default":[]},{"name":"position","kind":"Any","default":"bottom-right"},{"name":"_clear","kind":"Any","default":0},{"name":"types","kind":"Any","default":[{"type":"map","entries":[["type","warning"],["background","#ffc107"],["icon",{"type":"map","entries":[["className","fas fa-exclamation-triangle"],["tagName","i"],["color","white"]]}]]},{"type":"map","entries":[["type","info"],["background","#007bff"],["icon",{"type":"map","entries":[["className","fas fa-info-circle"],["tagName","i"],["color","white"]]}]]}]}]},{"type":"model","name":"Notification","properties":[{"name":"background","kind":"Any","default":null},{"name":"duration","kind":"Any","default":3000},{"name":"icon","kind":"Any","default":null},{"name":"message","kind":"Any","default":""},{"name":"notification_type","kind":"Any","default":null},{"name":"_destroyed","kind":"Any","default":false}]},{"type":"model","name":"TemplateActions1","properties":[{"name":"open_modal","kind":"Any","default":0},{"name":"close_modal","kind":"Any","default":0}]},{"type":"model","name":"BootstrapTemplateActions1","properties":[{"name":"open_modal","kind":"Any","default":0},{"name":"close_modal","kind":"Any","default":0}]},{"type":"model","name":"MaterialTemplateActions1","properties":[{"name":"open_modal","kind":"Any","default":0},{"name":"close_modal","kind":"Any","default":0}]}]}}
+    </script>
+    <script type="text/javascript">
+      (function() {
+        const fn = function() {
+          Bokeh.safely(function() {
+            (function(root) {
+              function embed_document(root) {
+              const docs_json = document.getElementById('p1678').textContent;
+              const render_items = [{"docid":"8d93a4b1-0241-4312-97a2-9d7e8cf602d5","roots":{"p1579":"bc2d23bf-3023-4b2e-9825-bb0daf9fdc45"},"root_ids":["p1579"]}];
+              root.Bokeh.embed.embed_items(docs_json, render_items);
+              }
+              if (root.Bokeh !== undefined) {
+                embed_document(root);
+              } else {
+                let attempts = 0;
+                const timer = setInterval(function(root) {
+                  if (root.Bokeh !== undefined) {
+                    clearInterval(timer);
+                    embed_document(root);
+                  } else {
+                    attempts++;
+                    if (attempts > 100) {
+                      clearInterval(timer);
+                      console.log("Bokeh: ERROR: Unable to run BokehJS code because BokehJS library is missing");
+                    }
+                  }
+                }, 10, root)
+              }
+            })(window);
+          });
+        };
+        if (document.readyState != "loading") fn();
+        else document.addEventListener("DOMContentLoaded", fn);
+      })();
+    </script>
+  </body>
+</html>