Styling Mapping ¶

Mapping dimensions to style attributes ¶

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:

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:

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:

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 :

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:

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 ¶

Normalize values to a range between 0-1 (optionally accepts min / max values, which are provided by the plotting system):

bin ¶

Bins values using the supplied bins, labeling each value with the bin center by default:

Can also supply a list of explicit labels for each bin:

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

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. In this example we will again map the x and y-values to the visual attributes but demonstrate that we can do all this in a single plot and then summarize what exactly we did:

Let's summarize the style transforms we have applied:

• alpha = (dim('alpha')+0.2).norm() : The alpha are mapped to the x-values offset by 0.2 and normalized.
• 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')*10 : The size of the points is mapped to the x-values exponentiated with the y-values and scaled by 10

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

To use one of these colormaps simply refer to it by name with the cmap style option:

Custom colormaps ¶

You can make your own custom colormaps by providing a list of hex colors:

Discrete color levels ¶

Lastly, existing colormaps can be made discrete by defining an integer number of color_levels :

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 :

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

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:

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:

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:

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.

Other options ¶

• logz : Enable logarithmic color scale (e.g. logz=True )
• 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 a 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 :

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:

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

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}

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

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

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.