Upload 5 files

hvplot_docs/02-Composing_Elements.md

@@ -0,0 +1,203 @@
+# Composing Objects
+
+
+```python
+import numpy as np
+import holoviews as hv
+hv.extension('bokeh')
+```
+
+Instantly viewable HoloViews objects include elements (discussed already) and containers (collections of elements or other containers).  Here we'll introduce two types of containers for collecting viewable objects, each typically created from the existing objects using a convenient operator syntax:
+
+   1. ** [``Layout``](../reference/containers/bokeh/Layout.ipynb) (``+``):** A collection of any HoloViews objects to be displayed side by side. 
+   2. **[``Overlay``](../reference/containers/bokeh/Overlay.ipynb) (``*``):** A collection of HoloViews objects to be displayed overlaid on one another with the same axes.
+
+The Layout and Overlay containers allow you to mix types in any combination, and have an ordering but no numerical or categorical key dimension with which to index the objects.  In contrast, the [Dimensioned containers](./05-Dimensioned_Containers.ipynb) discussed later, such as [``HoloMap``](../reference/containers/bokeh/HoloMap.ipynb) , [``GridSpace``](../reference/containers/bokeh/GridSpace.ipynb), [``NdOverlay``](../reference/containers/bokeh/NdOverlay.ipynb), and [``NdLayout``](../reference/containers/bokeh/NdLayout.ipynb), do not allow mixed types, and each item has an associated numerical or categorical index (key).
+
+Because you can compose a mix of any HoloViews elements into layouts and overlays, these types of container are very common, which is why they have dedicated composition operators. This user guide describes how you can build and organize your data using these two types of composition.
+
+To show how layouts and overlays work with heterogeneous types, we will use these two elements throughout this notebook:
+
+
+```python
+xs = [0.1* i for i in range(100)]
+curve =  hv.Curve((xs, [np.sin(x) for x in xs]))
+scatter =  hv.Scatter((xs[::5], np.linspace(0,1,20)))
+```
+
+## 1. ``Layout``
+
+A ``Layout`` can contain any HoloViews object except an ``NdLayout``. (See [Building Composite Objects](06-Building_Composite_Objects.ipynb) for the full details about the ways containers can be composed.)
+
+You can build a ``Layout`` from two or more HoloViews objects of any type by using the ``+`` operator:
+
+
+```python
+curve + scatter
+```
+
+In this example, we have a ``Layout`` composed of a ``Curve`` element and a ``Scatter`` element, and they happen to share the same ``x`` and ``y`` dimensions. 
+
+### Building a ``Layout`` from a list
+
+If the ``+`` syntax is not convenient, you can also build a ``Layout`` using its constructor directly, which is useful if you want to create a ``Layout`` of an arbitrary length:
+
+
+```python
+curve_list   = [hv.Curve((xs, [np.sin(f*x) for x in xs])) for f in [0.5, 0.75]]
+scatter_list = [hv.Scatter((xs[::5], f*np.linspace(0,1,20))) for f in [-0.5, 0.5]]
+
+layout = hv.Layout(curve_list + scatter_list).cols(2)
+layout
+```
+
+Note the use of the ``.cols`` method to specify the number of columns, wrapping to the next row in scanline order (left to right, then top to bottom).
+
+### A ``Layout`` has two-level attribute access
+
+``Layout`` and ``Overlay`` are tree-based data structures that can hold arbitrarily heterogeneous collections of HoloViews objects, and are quite different from the dictionary-like dimensioned containers (which will be described in later guides).
+
+As mentioned previously in [Annotating Data](01-Annotating_Data.ipynb), HoloViews objects have string ``group`` and ``label`` parameters, which can be used to select objects in the ``Layout`` using two-level attribute access. First let us see how to index the above example, where the ``group`` and ``label`` parameters were left unspecified on creation:
+
+
+```python
+print(layout)
+```
+
+As you can see, the ``layout`` object consists of four different elements, each mapping from ``x`` to ``y``.  You can use the "dot" syntax shown in the repr to select individual elements from the layout:
+
+
+```python
+layout2 = layout.Curve.I + layout.Scatter.II
+layout2
+```
+
+Here we create a second layout by indexing two elements from our earlier ``layout`` object and using ``+`` between them. We see that the first level of indexing is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to an automatically generated Roman numeral (I,II,III,IV, etc.). 
+
+As group and label were again not specified, our new ``Layout`` will also use ``Curve.I`` for the curve, but as there is only one scatter element, it will have ``Scatter.I`` to index the scatter:
+
+
+```python
+layout2.Scatter.I
+```
+
+### Using ``group`` and ``label`` with ``Layout``
+
+Now let's return to the first simple layout example, this time setting a group and label as introduced in the [Annotating Data](./01-Annotating_Data.ipynb) guide:
+
+
+```python
+xs = [0.1* i for i in range(100)]
+
+low_freq  = hv.Curve((xs, [np.sin(x) for x in xs]),    group='Sinusoid',      label='Low Frequency')
+linpoints = hv.Scatter((xs[::5], np.linspace(0,1,20)), group='Linear Points', label='Demo')
+
+labelled = low_freq + linpoints
+labelled
+```
+
+As you can see, the group and label are used for titling the plots.  They also determine how the objects are accessed:
+
+
+```python
+labelled.Linear_Points.Demo + labelled.Sinusoid.Low_Frequency
+```
+
+You are encouraged to use the group and label names as appropriate for organizing your own data.  They should let you easily refer to groups of data that are meaningful to your domain, e.g. for [Applying Customizations](./03-Applying_Customizations.ipynb).
+
+## 2. ``Overlay``
+
+An ``Overlay`` can contain any HoloViews elements, but the only container type it can contain is ``NdOverlay``. [Building Composite Objects](06-Building_Composite_Objects.ipynb) provides the full details on how containers can be composed.
+
+Other than being composed with ``*`` and displaying elements together in the same space, ``Overlay`` shares many of the same concepts as layout. The rest of this section will show the overlay equivalents of the manipulations shown above for layout. 
+
+First, composition with ``*`` instead of ``+`` results in a single overlaid plot, rather than side-by-side plots:
+
+
+```python
+curve * scatter
+```
+
+### Building ``Overlay`` from a list
+
+An ``Overlay`` can be built explicitly from a list, just like a ``Layout``:
+
+
+```python
+curve_list   = [hv.Curve((xs, [np.sin(f*x) for x in xs])) for f in [0.5, 0.75]]
+scatter_list = [hv.Scatter((xs[::5], f*np.linspace(0,1,20))) for f in [-0.5, 0.5]]
+overlay = hv.Overlay(curve_list + scatter_list)
+overlay
+```
+
+As you can see, a special feature of ``Overlay`` compared to ``Layout`` is that overlays use *color cycles* to help keep the overlaid plots distinguishable, which you can learn about in [Applying Customization](./03-Applying_Customization.ipynb).
+
+### ``Overlay`` also has two-level attribute access
+
+Like ``Layout``, ``Overlay`` is fundamentally a tree structure holding arbitrarily heterogeneous HoloViews objects, unlike the dimensioned containers. ``Overlay`` objects also make use of the ``group`` and ``label`` parameters, introduced in [Annotating Data](01-Annotating_Data.ipynb), for two-level attribute access.
+
+Once again, let us see how to index the above example where the ``group`` and ``label`` parameters were left unspecified:
+
+
+```python
+print(overlay)
+```
+
+
+```python
+overlay.Curve.I * overlay.Scatter.II
+```
+
+Here we create a second overlay by indexing two elements from our earlier ``overlay`` object and using ``*`` between them. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a Roman numeral.
+
+### Using ``group`` and ``label`` with ``Overlay``
+
+Now let's return to the first simple overlay example, this time setting ``group`` and ``label`` as introduced in the [Annotating Data](./01-Annotating_Data.ipynb) guide:
+
+
+```python
+high_freq =  hv.Curve((xs, [np.sin(2*x) for x in xs]), group='Sinusoid', label='High Frequency')
+labelled = low_freq * high_freq * linpoints
+labelled
+```
+
+Once again, this example follows the corresponding ``Layout`` example, although this time we added a high-frequency curve to demonstrate how ``group`` and ``label`` are now used to generate the legend (as opposed to the title, as it was for ``Layout``).
+
+The following example shows how ``group`` and ``label`` affect access:
+
+
+```python
+labelled.Linear_Points.Demo * labelled.Sinusoid.High_Frequency * labelled.Sinusoid.Low_Frequency
+```
+
+This new re-ordered ``Overlay`` switches the z-ordering as well as the legend color of the two sinusoidal curves. The colors and other plot options can be set for specific groups and labels as described in 
+[Applying Customizations](./03-Applying_Customizations.ipynb).
+
+
+## Layouts of overlays
+
+Of course, layouts work with both elements and overlays:
+
+
+```python
+overlay + labelled + labelled.Sinusoid.Low_Frequency
+```
+
+## Tab completion
+
+Both ``Layout`` and ``Overlay`` are designed to be easy to explore and inspect with tab completion. Try running:
+
+```python
+overlay.[tab]
+```
+
+or
+
+```python
+layout.[tab]
+```
+
+
+In a code cell and you should see the first levels of indexing (``Curve`` and ``Scatter``) conveniently listed at the top. If this is not the case, you may need to enable improved tab-completion as described in [Configuring HoloViews](./Installing_and_Configuring.ipynb).
+
+Having seen how to compose viewable objects, the next section shows how to [apply customizations](./03-Applying_Customizations.ipynb).

hvplot_docs/03-Applying_Customizations.md

@@ -0,0 +1,470 @@
+# Applying Customizations
+
+
+```python
+import pandas as pd
+import numpy as np
+import holoviews as hv
+from holoviews import opts
+hv.extension('bokeh', 'matplotlib')
+```
+
+As introduced in the [Customization](../getting_started/2-Customization.ipynb) section of the 'Getting Started' guide, HoloViews maintains a strict separation between your content (your data and declarations about your data) and its presentation (the details of how this data is represented visually). This separation is achieved by maintaining sets of keyword values ("options") that specify how elements are to appear, stored outside of the element itself. Option keywords can be specified for individual element instances, for all elements of a particular type, or for arbitrary user-defined sets of elements that you give a certain ``group`` and ``label`` (see [Annotating Data](../user_guide/01-Annotating_Data.ipynb)).
+
+The options system controls how individual plots appear, but other important settings are made more globally using the "output" system, which controls HoloViews plotting and rendering code (see the [Plots and Renderers](Plots_and_Renderers.ipynb) user guide). In this guide we will show how to customize the visual styling with the options and output systems, focusing on the mechanisms rather than the specific choices available (which are covered in other guides such as [Style Mapping](04-Style_Mapping.ipynb)).
+
+## Core concepts
+
+This section offers an overview of some core concepts for customizing visual representation, focusing on how HoloViews keeps content and presentation separate. To start, we will revisit the simple introductory example in the [Customization](../getting_started/2-Customization.ipynb) getting-started guide (which might be helpful to review first).
+
+
+```python
+spike_train = pd.read_csv('../assets/spike_train.csv.gz')
+curve  = hv.Curve(spike_train, 'milliseconds', 'Hertz')
+spikes = hv.Spikes(spike_train, 'milliseconds', [])
+```
+
+And now we display the ``curve`` and a ``spikes`` elements together in a layout as we did in the getting-started guide:
+
+
+```python
+curve  = hv.Curve( spike_train, 'milliseconds', 'Hertz')
+spikes = hv.Spikes(spike_train, 'milliseconds', [])
+layout = curve + spikes
+
+layout.opts(
+    opts.Curve( height=200, width=900, xaxis=None, line_width=1.50, color='red', tools=['hover']),
+    opts.Spikes(height=150, width=900, yaxis=None, line_width=0.25, color='grey')).cols(1)
+```
+
+This example illustrates a number of key concepts, as described below.
+
+### Content versus presentation
+
+In the getting-started guide [Introduction](../getting_started/1-Introduction.ipynb), we saw that we can print the string representation of HoloViews objects such as `layout`:
+
+
+```python
+print(layout)
+```
+
+In the [Customization](../getting_started/2-Customization.ipynb) getting-started guide, the `.opts.info()` method was introduced that lets you see the options *associated* with (though not stored on) the objects:
+
+
+```python
+layout.opts.info()
+```
+
+If you inspect all the state of the `Layout`, `Curve`, or `Spikes` objects you will not find any of these keywords, because they are stored in an entirely separate data structure.  HoloViews assigns a unique ID per HoloViews object that lets arbitrarily specific customization be associated with that object if needed, while also making it simple to define options that apply to entire classes of objects by type (or group and label if defined). The HoloViews element is thus *always* a thin wrapper around your data, without any visual styling information or plotting state, even though it *seems* like the object includes the styling information. This separation between content and presentation is by design, so that you can work with your data and with its presentation entirely independently.
+
+If you wish to clear the options that have been associated with an object `obj`, you can call `obj.opts.clear()`.
+
+## Option builders
+
+The [Customization](../getting_started/2-Customization.ipynb) getting-started guide also introduces the notion of *option builders*. One of the option builders in the visualization shown above is:
+
+
+```python
+opts.Curve( height=200, width=900, xaxis=None, line_width=1.50, color='red', tools=['hover'])
+```
+
+An *option builder* takes a collection of keywords and returns an `Options` object that stores these keywords together. Why should you use option builders and how are they different from a vanilla dictionary?
+
+1. The option builder specifies which type of HoloViews object the options are for, which is important because each type accepts different options.
+2. Knowing the type, the options builder does *validation* against that type for the currently loaded plotting extensions. Try introducing a typo into one of the keywords above; you should get a helpful error message. Separately, try renaming `line_width` to `linewidth`, and you'll get a different message because the latter is a valid matplotlib keyword.
+3. The option builder allows *tab-completion* in the notebook. This is useful for discovering available keywords for that type of object, which helps prevent mistakes and makes it quicker to specify a set of keywords.
+
+In the cell above, the specified options are applicable to `Curve` elements, and different validation and tab completion will be available for other types. 
+
+The returned `Options` object is different from a dictionary in the following ways:
+
+1. An optional *spec* is recorded, where this specification is normally just the element name. Above this is simply 'Curve'. Later, in section [Using `group` and `label`](#Using-group-and-label), we will see how this can also specify the `group` and `label`.
+2. The keywords are alphanumerically sorted, making it easier to compare `Options` objects.
+
+## Inlining options
+
+When customizing a single element, the use of an option builder is not mandatory. If you have a small number of keywords that are common (e.g `color`, `cmap`, `title`, `width`, `height`) it can be clearer to inline them into the `.opts` method call if tab-completion and validation isn't required:
+
+
+```python
+np.random.seed(42)
+array = np.random.random((10,10))
+im1 = hv.Image(array).opts(opts.Image(cmap='Reds')) # Using an option builder
+im2 = hv.Image(array).opts(cmap='Blues')            # Without an option builder
+im1 + im2
+```
+
+You cannot inline keywords for composite objects such as `Layout` or `Overlay` objects. For instance, the `layout` object is:
+
+
+```python
+print(layout)
+```
+
+To customize this layout, you need to use an option builder to associate your keywords with either the `Curve` or the `Spikes` object, or else you would have had to apply the options to the individual elements before you built the composite object. To illustrate setting by type, note that in the first example, both the `Curve` and the `Spikes` have different `height` values provided.
+
+You can also target options by the `group` and `label` as described in section on [using `group` and `label`](#Using-group-and-label).
+
+## Session-specific options
+
+One other common need is to set some options for a Python session, whether using Jupyter notebook or not. For this you can set the default options that will apply to all objects created subsequently:
+
+
+```python
+opts.defaults(
+    opts.HeatMap(cmap='Summer', colorbar=True, toolbar='above'))
+```
+
+The `opts.defaults` method has now set the style used for all `HeatMap` elements used in this session:
+
+
+```python
+data = [(chr(65+i), chr(97+j),  i*j) for i in range(5) for j in range(5) if i!=j]
+heatmap = hv.HeatMap(data).sort()
+heatmap
+```
+
+## Discovering options
+
+Using tab completion in the option builders is one convenient and easy way of discovering the available options for an element. Another approach is to use `hv.help`.
+
+For instance, if you run `hv.help(hv.Curve)` you will see a list of the 'style' and 'plot' options applicable to `Curve`. The distinction between these two types of options can often be ignored for most purposes, but the interested reader is encouraged to read more about them in more detail [below](#Split-into-style,-plot-and-norm-options).
+
+For the purposes of discovering the available options, the keywords listed under the 'Style Options' section of the help output is worth noting. These keywords are specific to the active plotting extension and are part of the API for that plotting library. For instance, running `hv.help(hv.Curve)` in the cell below would give you the keywords in the Bokeh documentation that you can reference for customizing the appearance of `Curve` objects.
+
+
+
+## Maximizing readability
+
+There are many ways to specify options in your code using the above tools, but for creating readable, maintainable code, we recommend making the separation of content and presentation explicit. Someone reading your code can then understand your visualizations in two steps 1) what your data *is* in terms of the applicable elements and containers 2) how this data is to be presented visually.
+
+The following guide details the approach we have used through out the examples and guides on holoviews.org. We have found that following these rules makes code involving holoviews easier to read and more consistent.
+
+The core principle is as follows: ***avoid mixing declarations of data, elements and containers with details of their visual appearance***.
+
+### Two contrasting examples
+
+One of the best ways to do this is to declare all your elements, compose them and then apply all the necessary styling with the `.opts` method before the visualization is rendered to disk or to the screen. For instance, the example from the getting-started guide could have been written sub-optimally as follows:
+
+***Sub-optimal***
+```python
+curve = hv.Curve( spike_train, 'milliseconds', 'Hertz').opts(
+    height=200, width=900, xaxis=None, line_width=1.50, color='red', tools=['hover'])
+spikes = hv.Spikes(spike_train, 'milliseconds', vdims=[]).opts(
+height=150, width=900, yaxis=None, line_width=0.25, color='grey')
+(curve + spikes).cols(1)
+```
+
+Code like that is very difficult to read because it mixes declarations of the data and its dimensions with details about how to present it.  The recommended version declares the `Layout`, then separately applies all the options together where it's clear that they are just hints for the visualization:
+
+***Recommended***
+```python
+curve  = hv.Curve( spike_train, 'milliseconds', 'Hertz')
+spikes = hv.Spikes(spike_train, 'milliseconds', [])
+layout = curve + spikes
+
+layout.opts(
+    opts.Curve( height=200, width=900, xaxis=None, line_width=1.50, color='red', tools=['hover']),
+    opts.Spikes(height=150, width=900, yaxis=None, line_width=0.25, color='grey')).cols(1)
+```
+
+
+By grouping the options in this way and applying them at the end, you can see the definition of `layout` without being distracted by visual concerns declared later. Conversely, you can modify the visual appearance of `layout` easily without needing to know exactly how it was defined. The [coding style guide](#Coding-style-guide) section below offers additional advice for keeping things readable and consistent.
+
+### When to use multiple`.opts` calls
+
+The above coding style applies in many case, but sometimes you have multiple elements of the same type that you need to distinguish visually. For instance, you may have a set of curves where using the `dim` or `Cycle` objects (described in the [Style Mapping](04-Style_Mapping.ipynb) user guide) is not appropriate and you want to customize the appearance of each curve individually. Alternatively, you may be generating elements in a list comprehension for use in `NdOverlay` and have a specific style to apply to each one.
+
+In these situations, it is often appropriate to use the inline style of `.opts` locally. In these instances, it is often best to give the individually styled objects a suitable named handle as illustrated by the  [legend example](../gallery/demos/bokeh/legend_example.ipynb) of the gallery.
+
+### General advice
+
+As HoloViews is highly compositional by design, you can always build long expressions mixing the data and element declarations, the composition of these elements, and their customization. Even though such expressions can be terse they can also be difficult to read.
+
+The simplest way to avoid long expressions is to keep some level of separation between these stages:
+
+1. declaration of the data
+2. declaration of the elements, including `.opts` to distinguish between elements of the same type if necessary 
+3. composition with `+` and `*` into layouts and overlays, and 
+4. customization of the composite object, either with a final call to the `.opts` method, or by declaring such settings as the default for your entire session as described [above](#Session-specific-options).
+
+When stages are simple enough, it can be appropriate to combine them. For instance, if the declaration of the data is simple enough, you can fold in the declaration of the element. In general, any expression involving three or more of these stages will benefit from being broken up into several steps.
+
+These general principles will help you write more readable code. Maximizing readability will always require some level of judgement, but you can maximize consistency by consulting the [coding style guide](#Coding-style-guide) section for more tips.
+
+# Customizing display output
+
+
+The options system controls most of the customizations you might want to do, but there are a few settings that are controlled at a more general level that cuts across all HoloViews object types: the active plotting extension (e.g. Bokeh or Matplotlib), the output display format (PNG, SVG, etc.), the output figure size, and other similar options. The `hv.output` utility allows you to modify these more global settings, either for all subsequent objects or for one particular object:
+
+* `hv.output(**kwargs)`: Customize how the output appears for the rest of the notebook session.
+* `hv.output(obj, **kwargs)`: Temporarily affect the display of an object `obj` using the keyword `**kwargs`.
+
+The `hv.output` utility only has an effect in contexts where HoloViews objects can be automatically displayed, which currently is limited to the Jupyter Notebook (in either its classic or JupyterLab variants). In any other Python context, using `hv.output` has no effect, as there is no automatically displayed output; see the [hv.save() and hv.render()](Plots_and_Renderers.ipynb#Saving-and-rendering) utilities for explicitly creating output in those other contexts.
+
+To start with `hv.output`, let us define a `Path` object:
+
+
+```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(color='purple', line_width=3, line_dash='dotted'))
+```
+
+Now, to illustrate, let's use `hv.output` to switch our plotting extension to matplotlib:
+
+
+```python
+hv.output(backend='matplotlib', fig='svg')
+```
+
+We can now display our `path` object with some option customization:
+
+
+```python
+path.opts(opts.Path(linewidth=2, color='red', linestyle='dotted'))
+```
+
+Our plot is now rendered with Matplotlib, in SVG format (try right-clicking the image in the web browser and saving it to disk to confirm). Note that the `opts.Path` option builder now tab completes *Matplotlib* keywords because we activated the Matplotlib plotting extension beforehand. Specifically, `linewidth` and `linestyle` don't exist in Bokeh, where the corresponding options are called `line_width` and `line_dash` instead.
+
+You can see the custom output options that are currently active using `hv.output.info()`:
+
+
+```python
+hv.output.info()
+```
+
+The info method will always show which backend is active as well as any other custom settings you have specified. These settings apply to the subsequent display of all objects unless you customize the output display settings for a single object.
+
+
+To illustrate how settings are kept separate, let us switch back to Bokeh in this notebook session:
+
+
+```python
+hv.output(backend='bokeh')
+hv.output.info()
+```
+
+With Bokeh active, we can now declare options on `path` that we want to apply only to matplotlib:
+
+
+```python
+path = path.opts(
+    opts.Path(linewidth=3, color='blue', backend='matplotlib'))
+path
+```
+
+Now we can supply `path` to `hv.output` to customize how it is displayed, while activating matplotlib to generate that display. In the next cell, we render our path at 50% size as an SVG using matplotlib.
+
+
+```python
+hv.output(path, backend='matplotlib', fig='svg', size=50)
+```
+
+Passing `hv.output` an object will apply the specified settings only for the subsequent display. If you were to view `path` now in the usual way, you would see that it is still being displayed with Bokeh with purple dotted lines.
+
+One thing to note is that when we set the options with `backend='matplotlib'`, the active plotting extension was Bokeh. This means that `opts.Path` will tab complete *bokeh* keywords, and not the matplotlib ones that were specified. In practice you will want to set the backend appropriately before building your options settings, to ensure that you get the most appropriate tab completion.
+
+### Available `hv.output` settings
+
+You can see the available settings using `help(hv.output)`. For reference, here are the most commonly used ones:
+
+* **backend**: *The backend used by HoloViews*. If the necessary libraries are installed this can be `'bokeh'`, `'matplotlib'` or `'plotly'`.
+* **fig** : *The static figure format*. The most common options are `'svg'` and `'png'`.
+* **holomap**: *The display type for holomaps*. With matplotlib and the necessary support libraries, this may be `'gif'` or `'mp4'`. The JavaScript `'scrubber'` widgets as well as the regular `'widgets'` are always supported.
+* **fps**: *The frames per second used for animations*. This setting is used for GIF output and by the scrubber widget.
+* **size**: *The percentage size of displayed output*. Useful for making all display larger or smaller.
+* **dpi**: *The rendered dpi of the figure*. This setting affects raster output such as PNG images.
+
+In `help(hv.output)` you will see a few other, less common settings. The `filename` setting particular is not recommended and will be deprecated in favor of `hv.save` in future.
+
+## Coding style guide
+
+Using `hv.output` plus option builders with the `.opts` method and `opts.default` covers the functionality required for most HoloViews code written by users. In addition to these recommended tools, HoloViews supports [Notebook Magics](Notebook_Magics.ipynb) (not recommended because they are Jupyter-specific) and literal (nested dictionary) formats useful for developers, as detailed in the [Extending HoloViews](#Extending-HoloViews) section. 
+
+This section offers further recommendations for how users can structure their code. These are generally tips based on the important principles described in the [maximizing readability](#Maximizing-readability) section that are often helpful but optional.
+
+* Use as few `.opts` calls as necessary to style the object the way you want.
+* You can inline keywords without an option builder if you only have a few common keywords. For instance, `hv.Image(...).opts(cmap='Reds')` is clearer to read than `hv.Image(...).opts(opts.Image(cmap='Reds'))`.
+* Conversely, you *should* use an option builder if you have more than four keywords.
+* When you have multiple option builders, it is often clearest to list them on separate lines with a single indentation in both `.opts` and `opts.defaults`:
+  
+**Not recommended**
+
+```
+layout.opts(opts.VLine(color='white'), opts.Image(cmap='Reds'), opts.Layout(width=500), opts.Curve(color='blue'))
+```
+
+**Recommended**
+
+```
+layout.opts(
+    opts.Curve(color='blue'),
+    opts.Image(cmap='Reds'),
+    opts.Layout(width=500),
+    opts.VLine(color='white'))
+```   
+     
+* The latter is recommended for another reason: if possible, list your element option builders in alphabetical order, before your container option builders in alphabetical order.
+
+* Keep the expression before the `.opts` method simple so that the overall expression is readable.
+* Don't mix `hv.output` and use of the `.opts` method in the same expression.
+
+## What is  `.options`?
+
+
+If you tab complete a HoloViews object, you'll notice there is an `.options` method as well as a `.opts` method. So what is the difference?
+
+The `.options` method was introduced in HoloViews 1.10 and was the first time HoloViews allowed users to ignore the distinction between 'style', 'plot' and 'norm' options described in the next section. It is largely equivalent to the `.opts` method except that it applies the options on a returned clone of the object.
+
+In other words, you have `clone = obj.options(**kwargs)` where `obj` is unaffected by the keywords supplied while `clone` will be customized. Both `.opts` and `.options` support an explicit `clone` keyword, so:
+
+* `obj.opts(**kwargs, clone=True)` is equivalent to `obj.options(**kwargs)`, and conversely
+* `obj.options(**kwargs, clone=False)` is equivalent to `obj.opts(**kwargs)`
+
+For this reason, users only ever need to use `.opts` and occasionally supply `clone=True` if required. The only other difference between these methods is that `.opts` supports the full literal specification that allows splitting into [style, plot and norm options](#Split-into-style,-plot-and-norm-options) (for developers) whereas `.options` does not.
+
+## When should I use `clone=True`?
+
+The 'Persistent styles' section of the [customization](../getting_started/2-Customization.ipynb) user guide shows how HoloViews remembers options set for an object (per plotting extension). For instance, we never customized the `spikes` object defined at the start of the notebook but we did customize it when it was part of a `Layout` called `layout`. Examining this `spikes` object, we see the options were applied to the underlying object, not just a copy of it in the layout:
+
+
+
+```python
+spikes
+```
+
+This is because `clone=False` by default in the `.opts` method. To illustrate `clone=True`, let's view some purple spikes *without* affecting the original `spikes` object:
+
+
+```python
+purple_spikes = spikes.opts(color='purple', clone=True)
+purple_spikes
+```
+
+Now if you were to look at `spikes` again, you would see it is still looks like the grey version above and only `purple_spikes` is purple. This means that `clone=True` is useful when you want to keep different styles for some HoloViews object (by making styled clones of it) instead of overwriting the options each time you call `.opts`.
+
+## Extending HoloViews
+
+In addition to the formats described above for use by users, additional option formats are supported that are less user friendly for data exploration but may be more convenient for library authors building on HoloViews.
+
+The first of these is the *`Option` list syntax* which is typically most useful outside of notebooks, a *literal syntax* that avoids the need to import `opts`, and then finally a literal syntax that keeps *style* and *plot* options separate.
+
+### `Option` list syntax
+
+If you find yourself using `obj.opts(*options)` where `options` is a list of `Option` objects, use `obj.opts(options)` instead as list input is also supported:
+
+
+```python
+options = [
+    opts.Curve( height=200, width=900, xaxis=None, line_width=1.50, color='grey', tools=['hover']),
+    opts.Spikes(height=150, width=900, yaxis=None, line_width=0.25, color='orange')]
+    
+layout.opts(options).cols(1)
+```
+
+This approach is often best in regular Python code where you are dynamically building up a list of options to apply. Using the option builders early also allows for early validation before use in the `.opts` method.
+
+### Literal syntax
+
+This syntax has the advantage of being a pure Python literal but it is harder to work with directly (due to nested dictionaries), is less readable, lacks tab completion support and lacks validation at the point where the keywords are defined:
+
+
+
+```python
+layout.opts(
+    {'Curve':  dict(height=200, width=900, xaxis=None, line_width=2, color='blue', tools=['hover']),
+     'Spikes': dict(height=150, width=900, yaxis=None, line_width=0.25, color='green')}).cols(1)
+```
+
+The utility of this format is you don't need to import `opts` and it is easier to dynamically add or remove keywords using Python or if you are storing options in a text file like YAML or JSON and only later applying them in Python code. This format should be avoided when trying to maximize readability or make the available keyword options easy to explore.
+
+### Using `group` and `label`
+
+The notion of an element `group` and `label` was introduced in [Annotating Data](./01-Annotating_Data.ipynb). This type of metadata is helpful for organizing large collections of elements with shared styling, such as automatically generated objects from some external software (e.g. a simulator). If you have a large set of elements with semantically meaningful `group` and `label` parameters set, you can use this information to appropriately customize large numbers of visualizations at once.
+
+To illustrate, here are four overlaid curves where three have the `group` of 'Sinusoid' and one of these also has the label 'Squared':
+
+
+```python
+xs = np.linspace(-np.pi,np.pi,100)
+curve = hv.Curve((xs, xs/3))
+group_curve1 = hv.Curve((xs, np.sin(xs)), group='Sinusoid')
+group_curve2 = hv.Curve((xs, np.sin(xs+np.pi/4)), group='Sinusoid')
+label_curve = hv.Curve((xs, np.sin(xs)**2), group='Sinusoid', label='Squared')
+curves = curve * group_curve1 * group_curve2 * label_curve
+curves
+```
+
+We can now use the `.opts` method to make all curves blue unless they are in the 'Sinusoid' group in which case they are red. Additionally, if a curve in the 'Sinusoid' group also has the label 'Squared', we can make sure that curve is green with a custom interpolation option:
+
+
+```python
+curves.opts(
+    opts.Curve(color='blue'),
+    opts.Curve('Sinusoid', color='red'),
+    opts.Curve('Sinusoid.Squared', interpolation='steps-mid', color='green'))
+```
+
+By using `opts.defaults` instead of the `.opts` method, we can use this type of customization to apply options to many elements, including elements that haven't even been created yet. For instance, if we run:
+
+
+```python
+opts.defaults(opts.Area('Error', alpha=0.5, color='grey'))
+```
+
+Then any `Area` element with a `group` of 'Error' will then be displayed as a semi-transparent grey:
+
+
+```python
+X  = np.linspace(0,2,10)
+hv.Area((X, np.random.rand(10), -np.random.rand(10)), vdims=['y', 'y2'], group='Error')
+```
+
+## Split into `style`, `plot` and `norm` options
+
+In `HoloViews`, an element such as `Curve` actually has three semantic distinct categories of options: `style`, `plot`, and `norm` options. Normally, a user doesn't need to worry about the distinction if they spend most of their time working with a single plotting extension.
+
+When trying to build a system that consistently needs to generate visualizations across different plotting libraries, it can be useful to make this distinction explicit:
+
+##### ``style`` options:
+
+``style`` options are passed directly to the underlying rendering backend that actually draws the plots, allowing you to control the details of how it behaves.  Each backend has its own options (e.g. the [``bokeh``](Bokeh_Backend) or plotly backends).
+
+For whichever backend has been selected, HoloViews can tell you which options are supported, but you will need to read the corresponding documentation (e.g. [matplotlib](http://matplotlib.org/contents.html), [bokeh](http://bokeh.pydata.org)) for the details of their use. For listing available options, see the ``hv.help`` as described in the [Discovering options](#Discovering-options) section.
+
+HoloViews has been designed to be easily extensible to additional backends in the future and each backend would have its own set of style options.
+
+##### ``plot`` options:
+
+Each of the various HoloViews plotting classes declares various [Parameters](http://param.pyviz.org) that control how HoloViews builds the visualization for that type of object, such as plot sizes and labels.  HoloViews uses these options internally; they are not simply passed to the underlying backend.  HoloViews documents these options fully in its online help and in the [Reference Manual](http://holoviews.org/Reference_Manual).  These options may vary for different backends in some cases, depending on the support available both in that library and in the HoloViews interface to it, but we try to keep any options that are meaningful for a variety of backends the same for all of them. For listing available options, see the output of ``hv.help``.
+
+##### ``norm`` options:
+
+``norm`` options are a special type of plot option that are applied orthogonally to the above two types, to control normalization.  Normalization refers to adjusting the properties of one plot relative to those of another.  For instance, two images normalized together would appear with relative brightness levels, with the brightest image using the full range black to white, while the other image is scaled proportionally.  Two images normalized independently would both cover the full range from black to white.  Similarly, two axis ranges normalized together are effectively linked and will expand to fit the largest range of either axis, while those normalized separately would cover different ranges. For listing available options, see the output of ``hv.help``.
+
+You can preserve the semantic distinction between these types of option in an augmented form of the [Literal syntax](#Literal-syntax) as follows:
+
+
+```python
+full_literal_spec = {
+    'Curve': {'style':dict(color='orange')}, 
+    'Curve.Sinusoid': {'style':dict(color='grey')}, 
+    'Curve.Sinusoid.Squared': {'style':dict(color='black'),
+                                'plot':dict(interpolation='steps-mid')}}
+hv.opts.apply_groups(curves, full_literal_spec)
+```
+
+This specification is what HoloViews uses internally, but it is awkward for people to use and is not ever recommended for normal users. That said, it does offer the maximal amount of flexibility and power for integration with other software.
+
+For instance, a simulator that can output visualization using either Bokeh or Matplotlib via HoloViews could use this format. By keeping the 'plot' and 'style' options separate, the 'plot' options could be set regardless of the plotting library while the 'style' options would be conditional on the backend.
+
+## Onwards
+
+This section of the user guide has described how you can discover and set customization options in HoloViews. Using `hv.help` and the option builders, you should be able to find the options available for any given object you want to display.
+
+What *hasn't* been explored are some of the facilities HoloViews offers to map the dimensions of your data to style options. This important topic is explored in the next user guide [Style Mapping](04-Style_Mapping.ipynb), where you will learn of the `dim` object as well as about the `Cycle` and `Palette` objects.

hvplot_docs/04-Style_Mapping.md

@@ -0,0 +1,411 @@
+# Style Mapping
+
+
+```python
+import numpy as np
+import holoviews as hv
+from holoviews import dim, opts
+
+hv.extension('bokeh')
+```
+
+One of the major benefits of HoloViews is the fact that Elements are simple, declarative wrappers around your data, with clearly defined semantics describing how the dimensions of the data map to the screen. Usually the key dimensions (kdims) and value dimensions map to coordinates of the plot axes and/or the colormapped intensity. However there are a huge number of ways to augment the visual representation of an element by mapping dimensions to visual attributes. In this section we will explore how we can declare such mappings including complex transforms specified by so called ``dim`` objects.
+
+To illustrate this point let us create a set of three points with x/y-coordinates and alpha, color, marker and size values and then map each of those value dimensions to a visual attribute by name. Note that by default kdims is x,y. However, in this example we also show that the names of the dimensions can be changed and we use 'x values' and 'y values' to represent the data series names.
+
+
+```python
+data = {
+    'x values': [0, 1, 0.5],
+    'y values': [1, 0, 0.5],
+    'alpha': [0.5, 1, 0.3],
+    'color': ['red', 'blue', 'green'],
+    'marker': ['circle', 'triangle', 'diamond'],
+    'size': [15, 25, 40]
+}
+
+opts.defaults(opts.Points(size=8, line_color='black'))
+
+hv.Points(data, kdims=['x values','y values'] , vdims=['alpha', 'color', 'marker', 'size']).opts(
+    alpha='alpha', color='color', marker='marker', size='size')
+```
+
+This is the simplest approach to style mapping, dimensions can be mapped to visual attributes directly by name. However often columns in the data will not directly map to a visual property, e.g. we might want to normalize values before mapping them to the alpha, or apply a scaling factor to some values before mapping them to the point size; this is where ``dim`` transforms come in. Below are a few examples of using ``dim`` transforms to map a dimension in the data to the visual style in the plot:
+
+
+```python
+points = hv.Points(np.random.rand(400, 4))
+
+bins   = [0, .25, 0.5, .75, 1]
+labels = ['circle', 'triangle', 'diamond', 'square']
+
+layout = hv.Layout([
+    points.relabel('Alpha' ).opts(alpha =dim('x').norm()),
+    points.relabel('Angle' ).opts(angle =dim('x').norm()*360, marker='dash'),
+    points.relabel('Color' ).opts(color =dim('x')),
+    points.relabel('Marker').opts(marker=dim('x').bin(bins, labels)),
+    points.relabel('Size'  ).opts(size  =dim('x')*10)
+])
+
+layout.opts(opts.Points(width=250, height=250, xaxis=None, yaxis=None)).cols(5)
+```
+
+### What are dim transforms?
+
+In the above example we saw how to use an ``dim`` to define a transform from a dimension in your data to the visual property on screen. A ``dim`` therefore is a simple way to declare a deferred transform of your data. In the simplest case an ``dim`` simply returns the data for a dimension without transforming it, e.g. to look up the ``'alpha'`` dimension on the points object we can create an ``dim`` and use the ``apply`` method to evaluate the expression:
+
+
+```python
+from holoviews import dim
+
+ds = hv.Dataset(np.random.rand(10, 4)*10, ['x', 'y'], ['alpha', 'size'])
+
+dim('alpha').apply(ds)
+```
+
+#### Mathematical operators
+
+An ``dim`` declaration allow arbitrary mathematical operations to be performed, e.g. let us declare that we want to subtract 5 from the 'alpha' dimension and then compute the ``min``:
+
+
+```python
+math_op = (dim('alpha')-5).min()
+math_op
+```
+
+Printing the repr of the ``math_op`` we can see that it builds up an nested expression. To see the transform in action we will once again ``apply`` it on the points:
+
+
+```python
+math_op.apply(ds)
+```
+
+ ``dim`` objects implement most of the NumPy API, supports all standard mathematical operators and also support NumPy ufuncs.
+
+#### Custom functions
+
+In addition to standard mathematical operators it is also possible to declare custom functions which can be applied by name. By default HoloViews ships with three commonly useful functions.
+
+##### **``norm``**
+
+Unity based normalization or features scaling normalizing the values to a range between 0-1 (optionally accepts ``min``/``max`` values as ``limits``, which are usually provided by the plotting system) using the expression:
+
+    (values - min) / (max-min)
+    
+for example we can rescale the alpha values into a 0-1 range:
+
+
+```python
+dim('alpha').norm().apply(ds)
+```
+
+##### **``bin``**
+
+Bins values using the supplied bins specified as the edges of each bin:
+
+
+```python
+bin_op = dim('alpha').bin([0, 5, 10])
+
+bin_op.apply(ds)
+```
+
+It is also possible to provide explicit labels for each bin which will replace the bin center value:
+
+
+```python
+dim('alpha').bin([0, 5, 10], ['Bin 1', 'Bin 2']).apply(ds)
+```
+
+##### **``categorize``**
+
+Maps a number of discrete values onto the supplied list of categories, e.g. having binned the data into 2 discrete bins we can map them to two discrete marker types 'circle' and 'triangle':
+
+
+```python
+dim(bin_op).categorize({2.5: 'circle', 7.5: 'square'}).apply(ds)
+```
+
+This can be very useful to map discrete categories to markers or colors.
+
+### Style mapping with ``dim`` transforms
+
+This allows a huge amount of flexibility to express how the data should be mapped to visual style without directly modifying the data. To demonstrate this we will use some of the more complex:
+
+
+```python
+points.opts(
+    alpha =(dim('x')+0.2).norm(),
+    angle =np.sin(dim('y'))*360,
+    color =dim('x')**2,
+    marker=dim('y').bin(bins, labels),
+    size  =dim('x')**dim('y')*20, width=500, height=500)
+```
+
+Let's summarize the style transforms we have applied:
+    
+* **alpha**=``(dim('x')+0.2).norm()``: The alpha are mapped to the x-values offset by 0.2 and normalized.
+* **angle**=``np.sin(dim('x'))*360``: The angle of each marker is the sine of the y-values, multiplied by 360
+* **color**=``'x'``: The points are colormapped by square of their x-values.
+* **marker**=``dim('y').bin(bins, labels)``: The y-values are binned and each bin is assignd a unique marker.
+* **size**=``dim('x')**dim('y')*20``: The size of the points is mapped to the x-values exponentiated with the y-values and scaled by 20
+
+These are simply illustrative examples, transforms can be chained in arbitrarily complex ways to achieve almost any mapping from dimension values to visual style.
+
+## Colormapping
+
+Color cycles and styles are useful for categorical plots and when overlaying multiple subsets, but when we want to map data values to a color it is better to use HoloViews' facilities for color mapping. Certain image-like types will apply colormapping automatically; e.g. for ``Image``, ``QuadMesh`` or ``HeatMap`` types the first value dimension is automatically mapped to the color. In other cases the values to colormap can be declared by providing a ``color`` style option that specifies which dimension to map into the color value.
+
+#### Named colormaps
+
+HoloViews accepts colormaps specified either as an explicit list of hex or HTML colors, as a Matplotlib colormap object, or as the name of a bokeh, matplotlib, and colorcet palettes/colormap (which are available when the respective library is imported).  The named colormaps available are listed here (suppressing the `_r` versions) and illustrated in detail in the separate [Colormaps](Colormaps.ipynb) user guide:
+
+
+```python
+def format_list(l):
+    print(' '.join(sorted([k for k in l if not k.endswith('_r')])))
+
+format_list(hv.plotting.list_cmaps())
+```
+
+To use one of these colormaps simply refer to it by name with the ``cmap`` style option:
+
+
+```python
+ls = np.linspace(0, 10, 400)
+xx, yy = np.meshgrid(ls, ls)
+bounds=(-1,-1,1,1)   # Coordinate system: (left, bottom, right, top)
+img = hv.Image(np.sin(xx)*np.cos(yy), bounds=bounds).opts(colorbar=True, width=400)
+
+img.relabel('PiYG').opts(cmap='PiYG') + img.relabel('PiYG_r').opts(cmap='PiYG_r')
+```
+
+#### Custom colormaps
+
+You can make your own custom colormaps by providing a list of hex colors:
+
+
+```python
+img.relabel('Listed colors').opts(cmap=['#0000ff', '#8888ff', '#ffffff', '#ff8888', '#ff0000'], colorbar=True, width=400)
+```
+
+#### Discrete color levels
+
+Lastly, existing colormaps can be made discrete by defining an integer number of ``color_levels``:
+
+
+```python
+img.relabel('5 color levels').opts(cmap='PiYG', color_levels=5) + img.relabel('11 color levels').opts(cmap='PiYG', color_levels=11) 
+```
+
+### Explicit color mapping
+
+Some elements work through implicit colormapping, the prime example being the ``Image`` type. However, other elements can be colormapped using style mapping instead, by setting the color to an existing dimension.
+
+#### Continuous values
+
+If we provide a continuous value for the ``color`` style option along with a continuous colormap, we can also enable a ``colorbar``:
+
+
+```python
+polygons = hv.Polygons([{('x', 'y'): hv.Ellipse(0, 0, (i, i)).array(), 'z': i} for i in range(1, 10)[::-1]], vdims='z')
+
+polygons.opts(color='z', colorbar=True, width=380)
+```
+
+#### Categorical values
+
+Conversely, when mapping a categorical value into a set of colors, we automatically get a legend (which can be disabled using the ``show_legend`` option):
+
+
+```python
+categorical_points = hv.Points((np.random.rand(100), 
+                                np.random.rand(100), 
+                                np.random.choice(list('ABCD'), 100)), vdims='Category')
+
+categorical_points.sort('Category').opts(
+    color='Category', cmap='Category20', size=8, legend_position='left', width=500)
+```
+
+#### Explicit color mapping
+
+Instead of using a listed colormap, you can provide an explicit mapping from category to color. Here we will map the categories 'A', 'B', 'C' and 'D' to specific colors:
+
+
+```python
+explicit_mapping = {'A': 'blue', 'B': 'red', 'C': 'green', 'D': 'purple'}
+
+categorical_points.sort('Category').opts(color='Category', cmap=explicit_mapping, size=8)
+```
+
+#### Custom color intervals
+
+In addition to a simple integer defining the number of discrete levels, the ``color_levels`` option also allows defining a set of custom intervals. This can be useful for defining a fixed scale, such as the Saffir-Simpson hurricane wind scale. Below we declare the color levels along with a list of colors, declaring the scale. Note that the levels define the intervals to map each color to, so if there are N colors we have to define N+1 levels.
+
+Having defined the scale we can generate a theoretical hurricane path with wind speed values and use the ``color_levels`` and ``cmap`` to supply the custom color scale:
+
+
+```python
+levels = [0, 38, 73, 95, 110, 130, 156, 999]  
+colors = ['#5ebaff', '#00faf4', '#ffffcc', '#ffe775', '#ffc140', '#ff8f20', '#ff6060']
+
+path = [
+    (-75.1, 23.1, 0),   (-76.2, 23.8, 0),   (-76.9, 25.4, 0),   (-78.4, 26.1, 39),  (-79.6, 26.2, 39),
+    (-80.3, 25.9, 39),  (-82.0, 25.1, 74),  (-83.3, 24.6, 74),  (-84.7, 24.4, 96),  (-85.9, 24.8, 111),
+    (-87.7, 25.7, 111), (-89.2, 27.2, 131), (-89.6, 29.3, 156), (-89.6, 30.2, 156), (-89.1, 32.6, 131),
+    (-88.0, 35.6, 111), (-85.3, 38.6, 96)
+]
+
+hv.Path([path], vdims='Wind Speed').opts(
+    color='Wind Speed', color_levels=levels, cmap=colors, line_width=8, colorbar=True, width=450
+)
+```
+
+#### Setting color ranges
+
+For an image-like element, color ranges are determined by the range of the `z` value dimension, and they can thus be controlled using the ``.redim.range`` method with `z`. As an example, let's set some values in the image array to NaN and then set the range to clip the data at 0 and 0.9. By declaring the ``clipping_colors`` option we can control what colors are used for NaN values and for values above and below the defined range:
+
+
+```python
+clipping = {'min': 'red', 'max': 'green', 'NaN': 'gray'}
+options = dict(cmap='Blues', colorbar=True, width=300, height=230, axiswise=True)
+
+arr = np.sin(xx)*np.cos(yy)
+arr[:190, :127] = np.nan
+
+original = hv.Image(arr, bounds=bounds).opts(**options)
+colored  = original.opts(clipping_colors=clipping, clone=True)
+clipped  = colored.redim.range(z=(0, 0.9))
+
+original + colored + clipped
+```
+
+By default (left plot above), the min and max values in the array map to the first color (white) and last color (dark blue) in the colormap, and NaNs are ``'transparent'`` (an RGBA tuple of (0, 0, 0, 0)), revealing the underlying plot background.  When the specified `clipping_colors` are supplied (middle plot above), NaN values are now colored gray, but the plot is otherwise the same because the autoranging still ensures that no value is mapped outside the available color range.  Finally, when the `z` range is reduced (right plot above), the color range is mapped from a different range of numerical `z` values, and some values now fall outside the range and are thus clipped to red or green as specified.
+
+
+#### Normalization modes
+
+When using a colormap, there are three available color normalization or `cnorm` options to determine how numerical values are mapped to the range of colors in the colorbar:
+
+* `linear`: Simple linear mapping (used by default)
+* `log`: Logarithmic mapping
+* `eq_hist`: Histogram-equalized mapping
+
+The following cell defines an `Image` containing random samples drawn from a normal distribution (mean of 3) with a square of constant value 100 in the middle, shown with the three `cnorm` modes:
+
+
+```python
+np.random.seed(42)
+data = np.random.normal(loc=3, scale=0.3, size=(100,100))
+print("Mean value of random samples is {mean:.3f}, ".format(mean=np.mean(data))
+     + "which is much lower\nthan the black square in the center (value 100).")
+data[45:55,45:55] = 100
+
+imopts=dict(colorbar=True, xaxis='bare', yaxis='bare', height=160, width=200)
+pattern = hv.Image(data)
+
+(  pattern.options(cnorm='linear',  title='linear',  **imopts) 
+ + pattern.options(cnorm='log',     title='log',     **imopts)
+ + pattern.options(cnorm='eq_hist', title='eq_hist', **imopts))
+```
+
+The `'linear'` mode is very easy to interpret numerically, with colors mapped to numerical values linearly as indicated. However, as you can see in this case, high-value outliers like the square here can make it difficult to see any structure in the remaining values. The Gaussian noise values all map to the first few colors at the bottom of the colormap, resulting in a background that is almost uniformly yellow even though we know the data includes a variety of different values in the background area.
+
+In the `'log'` mode, the random values are a little easier to see but these samples still use a small portion of the colormap. Logarithmic colormaps are most useful when you know that you are plotting data with an approximately logarithmic distribution.
+
+In the `'eq_hist'` mode, colors are nonlinearly mapped according to the actual distribution of values in the plot, such that each color in the colormap represents an approximately equal number of values in the plot (here with few or no colors reserved for the nearly empty range between 10 and 100). In this mode both the outliers and the overall low-amplitude noise can be seen clearly, but the non-linear distortion can make the colors more difficult to interpret as numerical values.
+
+When working with unknown data distributions, it is often a good idea to try all three of these modes, using `eq_hist` to be sure that you are seeing all of the patterns in the data, then either `log` or `linear` (depending on which one is a better match to your distribution) with the values clipped to the range of values you want to show.
+
+## Other colormapping options
+
+* ``clim_percentile``: Percentile value to compute colorscale robust to outliers. If `True`, uses 2nd and 98th percentile; otherwise uses the specified percentile value. 
+* ``cnorm``: Color normalization to be applied during colormapping. Allows switching between 'linear', 'log', and 'eq_hist'.
+* ``logz``: Enable logarithmic color scale (same as `cnorm='log'`; to be deprecated at some point)
+* ``symmetric``: Ensures that the color scale is centered on zero (e.g. ``symmetric=True``)
+
+## Cycles and Palettes
+
+Frequently we want to plot multiple subsets of data, which is made easy by using ``Overlay`` and ``NdOverlay`` objects. When overlaying multiple elements of the same type they will need to be distinguished visually, and HoloViews provides two mechanisms for styling the different subsets automatically in those cases:
+
+* ``Cycle``: A Cycle defines a list of discrete styles
+* ``Palette``: A Palette defines a continuous color space which will be sampled discretely
+
+### Cycle
+
+A ``Cycle`` can be applied to any of the style options on an element. By default, most elements define a ``Cycle`` on the color property. Here we will create an overlay of three ``Points`` objects using the default cycles, then display it using the default cycles along with a copy where we changed the dot color and size using a custom ``Cycle``:
+
+
+```python
+points = (
+    hv.Points(np.random.randn(50, 2)      ) *
+    hv.Points(np.random.randn(50, 2) + 1  ) *
+    hv.Points(np.random.randn(50, 2) * 0.5)
+)
+
+color_cycle = hv.Cycle(['red', 'green', 'blue'])
+points + points.opts(opts.Points(color=color_cycle), clone=True)
+```
+
+Here color has been changed to cycle over the three provided colors, while size has been specified as a constant (though a cycle like `hv.Cycle([2,5,10])` could just as easily have been used for the size as well).
+
+#### Defaults
+
+In addition to defining custom color cycles by explicitly defining a list of colors, ``Cycle`` also defines a list of default Cycles generated from bokeh Palettes and matplotlib colormaps:
+
+
+```python
+format_list(hv.Cycle.default_cycles.keys())
+```
+
+(Here some of these Cycles have a reversed variant ending in `_r` that is not shown.)
+
+To use one of these default Cycles simply construct the Cycle with the corresponding key:
+
+
+```python
+xs = np.linspace(0, np.pi*2)
+curves = hv.Overlay([hv.Curve(np.sin(xs+p)) for p in np.linspace(0, np.pi, 10)])
+
+curves.opts(opts.Curve(color=hv.Cycle('Category20'), width=600))
+```
+
+#### Markers and sizes
+
+The above examples focus on color Cycles, but Cycles may be used to define any style option. Here let's use them to cycle over a number of marker styles and sizes, which will be expanded by cycling over each item independently. In this case we are cycling over three Cycles, resulting in the following style combinations:
+
+1. ``{'color': '#30a2da', 'marker': 'x', 'size': 10}``
+2. ``{'color': '#fc4f30', 'marker': '^', 'size': 5}``
+3. ``{'color': '#e5ae38', 'marker': '+', 'size': 10}``
+
+
+```python
+color = hv.Cycle(['#30a2da', '#fc4f30', '#e5ae38'])
+markers = hv.Cycle(['x', '^', '+'])
+sizes = hv.Cycle([10, 5])
+points.opts(opts.Points(line_color=color, marker=markers, size=sizes))
+```
+
+### Palettes
+
+Palettes are similar to cycles, but treat a set of colors as a continuous colorspace to be sampled at regularly spaced intervals. Again they are made automatically available from existing colormaps (with `_r` versions also available):
+
+
+```python
+format_list(hv.Palette.colormaps.keys())
+```
+
+(Here each colormap `X` has a corresponding version `X_r` with the values reversed; the `_r` variants are suppressed above.)
+
+As a simple example we will create a Palette from the Spectral colormap and apply it to an Overlay of 6 Ellipses. Comparing it to the Spectral ``Cycle``  we can immediately see that the Palette covers the entire color space spanned by the Spectral colormap, while the Cycle instead uses the first 6 colors of the Spectral colormap:
+
+
+```python
+ellipses = hv.Overlay([hv.Ellipse(0, 0, s) for s in range(6)])
+
+ellipses.relabel('Palette').opts(opts.Ellipse(color=hv.Palette('Spectral'), line_width=5), clone=True) +\
+ellipses.relabel('Cycle'  ).opts(opts.Ellipse(color=hv.Cycle(  'Spectral'), line_width=5), clone=True)
+```
+
+Thus if you want to have have a discrete set of distinguishable colors starting from a list of colors that vary slowly and continuously, you should usually supply it as a Palette, not a Cycle.  Conversely, you should use a Cycle when you want to iterate through a specific list of colors, in order, without skipping around the list like a Palette will.
+

hvplot_docs/kwargs.md

@@ -0,0 +1,166 @@
+Generic options
+---------------
+autorange (default=None): Literal['x', 'y'] | None
+    Whether to enable auto-ranging along the x- or y-axis when
+    zooming. Requires HoloViews >= 1.16.
+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.
+rescale_discrete_levels (default=True): boolean
+    If `cnorm='eq_hist'` and there are only a few discrete values,
+    then `rescale_discrete_levels=True` (the default) decreases
+    the lower limit of the autoranged span so that the values are
+    rendering towards the (more visible) top of the `cmap` range,
+    thus avoiding washout of the lower values.  Has no effect if
+    `cnorm!=`eq_hist`.
+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.
+
+Resampling options
+------------------
+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 (colormapping) using
+    the Datashader library, returning an RGB object instead of
+    individual points
+downsample (default=False):
+    Whether to apply LTTB (Largest Triangle Three Buckets)
+    downsampling to the element (note this is only well behaved for
+    timeseries data). Requires HoloViews >= 1.16.
+dynspread (default=False):
+    For plots generated with datashade=True or rasterize=True,
+    automatically increase the point size when the data is sparse
+    so that individual points become more visible
+rasterize (default=False):
+    Whether to apply rasterization using the Datashader library,
+    returning an aggregated Image (to be colormapped by the
+    plotting backend) instead of individual points
+resample_when (default=None):
+    Applies a resampling operation (datashade, rasterize or downsample) if
+    the number of individual data points present in the current zoom range
+    is above this threshold. The raw plot is displayed otherwise.
+x_sampling/y_sampling (default=None):
+    Specifies the smallest allowed sampling interval along the x/y axis.
+
+Geographic 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 (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).
+projection (default=None): str or Cartopy CRS
+    Coordinate reference system of the plot specified as Cartopy
+    CRS object or class name.
+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'.