Applying Customizations

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 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).

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 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).

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 guide (which might be helpful to review first).

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:

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, we saw that we can print the string representation of HoloViews objects such as layout:

print(layout)

In the Customization getting-started guide, the .opts.info() method was introduced that lets you see the options associated with (though not stored on) the objects:

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 guide also introduces the notion of option builders. One of the option builders in the visualization shown above is:

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?

The option builder specifies which type of HoloViews object the options are for, which is important because each type accepts different options.
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.
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:

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, we will see how this can also specify the group and label.
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:

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:

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.

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:

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:

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.

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

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

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

declaration of the data
declaration of the elements, including .opts to distinguish between elements of the same type if necessary
composition with + and * into layouts and overlays, and
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.

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 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() utilities for explicitly creating output in those other contexts.

To start with hv.output, let us define a Path object:

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:

hv.output(backend='matplotlib', fig='svg')

We can now display our path object with some option customization:

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():

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:

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:

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.

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 (not recommended because they are Jupyter-specific) and literal (nested dictionary) formats useful for developers, as detailed in the 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 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 (for developers) whereas .options does not.

When should I use `clone=True`?

The 'Persistent styles' section of the customization 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:

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:

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:

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:

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. 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':

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:

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:

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:

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 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, bokeh) for the details of their use. For listing available options, see the hv.help as described in the 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 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. 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 as follows:

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, where you will learn of the dim object as well as about the Cycle and Palette objects.