Elements are the basic building blocks for any HoloViews visualization. These are the objects that can be composed together using the various Container types. Here in this overview, we show an example of how to build each of these Elements directly out of Python or Numpy data structures. An even more powerful way to use them is by collecting similar Elements into a HoloMap, as described in Exploring Data, so that you can explore, select, slice, and animate them flexibly, but here we focus on having small, self-contained examples. Complete reference material for each type can be accessed using our documentation system. This tutorial uses the default matplotlib plotting backend; see the Bokeh Elements tutorial for the corresponding bokeh plots.

Element types¶

This class hierarchy shows each of the Element types. Each type is named for the default or expected way that the underlying data can be visualized. E.g., if your data is wrapped into a Surface object, it will display as a 3D surface by default, whereas the same data embedded in an Image object will display as a 2D raster image. But please note that the specification and implementation for each Element type does not actually include any such visualization -- the name merely serves as a semantic indication that you ordinarily think of the data as being laid out visually in that way. The actual plotting is done by a separate plotting subsystem, while the objects themselves focus on storing your data and the metadata needed to describe and use it.

This separation of data and visualization is described in detail in the Options tutorial, which describes all about how to find out the options available for each Element type and change them if necessary, from either Python or IPython Notebook. When using this tutorial interactively in an IPython/Jupyter notebook session, we suggest adding %output info=True after the call to notebook_extension below, which will pop up a detailed list and explanation of the available options for visualizing each Element type, after that notebook cell is executed. Then, to find out all the options for any of these Element types, just press <Shift-Enter> on the corresponding cell in the live notebook.

The types available:

Element

The base class of all Elements.

Charts:¶

Curve

A continuous relation between a dependent and an independent variable.

ErrorBars

A collection of x-/y-coordinates with associated error magnitudes.

Spread

Continuous version of ErrorBars.

Area

Bars

Data collected and binned into categories.

Histogram

Data collected and binned in a continuous space using specified bin edges.

BoxWhisker

Distributions of data varying by 0-N key dimensions.

Scatter

Discontinuous collection of points indexed over a single dimension.

Points

Discontinuous collection of points indexed over two dimensions.

VectorField

Cyclic variable (and optional auxiliary data) distributed over two-dimensional space.

Spikes

A collection of horizontal or vertical lines at various locations with fixed height (1D) or variable height (2D).

SideHistogram

Histogram binning data contained by some other Element.

Chart3D Elements:¶

Surface

Continuous collection of points in a three-dimensional space.

Scatter3D

Discontinuous collection of points in a three-dimensional space.

TriSurface

Continuous but irregular collection of points interpolated into a Surface using Delaunay triangulation.

Raster Elements:¶

Raster

The base class of all rasters containing two-dimensional arrays.

QuadMesh

Raster type specifying 2D bins with two-dimensional array of values.

HeatMap

Raster displaying sparse, discontinuous data collected in a two-dimensional space.

Image

Raster containing a two-dimensional array covering a continuous space (sliceable).

RGB

Image with 3 (R,G,B) or 4 (R,G,B,Alpha) color channels.

HSV

Image with 3 (Hue, Saturation, Value) or 4 channels.

Tabular Elements:¶

ItemTable

Ordered collection of key-value pairs (ordered dictionary).

Table

Collection of arbitrary data with arbitrary key and value dimensions.

Annotations:¶

VLine

Vertical line annotation.

HLine

Horizontal line annotation.

Spline

Bezier spline (arbitrary curves).

Text

Text annotation on an Element.

Arrow

Arrow on an Element with optional text label.

Paths:¶

Path

Collection of paths.

Contours

Collection of paths, each with an associated value.

Polygons

Collection of filled, closed paths with an associated value.

Bounds

Box specified by corner positions.

Box

Box specified by center position, radius, and aspect ratio.

Ellipse

Ellipse specified by center position, radius, and aspect ratio.

Element ¶

The basic or fundamental types of data that can be visualized.

Element is the base class for all the other HoloViews objects shown in this section.

All Element objects accept data as the first argument to define the contents of that element. In addition to its implicit type, each element object has a group string defining its category, and a label naming this particular item, as described in the Introduction.

When rich display is off, or if no visualization has been defined for that type of Element, the Element is presented with a default textual representation:

In addition, Element has key dimensions (kdims), value dimensions (vdims), and constant dimensions (cdims) to describe the semantics of indexing within the Element, the semantics of the underlying data contained by the Element, and any constant parameters associated with the object, respectively. Dimensions are described in the Introduction.

The remaining Element types each have a rich, graphical display as shown below.

Chart Elements ¶

Visualization of a dependent variable against an independent variable

The first large class of Elements is the Chart elements. These objects have at least one fully indexable, sliceable key dimension (typically the x axis in a plot), and usually have one or more value dimension(s) (often the y axis) that may or may not be indexable depending on the implementation. The key dimensions are normally the parameter settings for which things are measured, and the value dimensions are the data points recorded at those settings.

As described in the Columnar Data tutorial, the data can be stored in several different internal formats, such as a NumPy array of shape (N, D), where N is the number of samples and D the number of dimensions. A somewhat larger list of formats can be accepted, including any of the supported internal formats, or

1. As a list of length N containing tuples of length D.
2. As a tuple of length D containing iterables of length N.

Curve ¶

A Curve is a set of values provided for some set of keys from a continuously indexable 1D coordinate system, where the plotted values will be connected up because they are assumed to be samples from a continuous relation.

ErrorBars ¶

ErrorBars is a set of x-/y-coordinates with associated error values. Error values may be either symmetric or asymmetric, and thus can be supplied as an Nx3 or Nx4 array (or any of the alternative constructors Chart Elements allow).

Spread ¶

Spread elements have the same data format as the ErrorBars element, namely x- and y-values with associated symmetric or asymmetric errors, but are interpreted as samples from a continuous distribution (just as Curve is the continuous version of Scatter). These are often paired with an overlaid Curve to show both the mean (as a curve) and the spread of values; see the Columnar Data tutorial for examples.

Symmetric¶

Asymmetric¶

Area ¶

Area under the curve

By default the Area Element draws just the area under the curve, i.e. the region between the curve and the origin.

Area between curves

When supplied a second value dimension the area is defined as the area between two curves.

Stacked areas¶

Areas are also useful to visualize multiple variables changing over time, but in order to be able to compare them the areas need to be stacked. Therefore the operation module provides the stack_area operation which makes it trivial to stack multiple Area in an (Nd)Overlay.

In this example we will generate a set of 5 arrays representing percentages and create an Overlay of them. Then we simply call the stack_area operation on the Overlay to get a stacked area chart.

Bars ¶

Bars is an NdElement type, so by default it is sorted. To preserve the initial ordering specify the Dimension with values set to 'initial', or you can supply an explicit list of valid dimension keys.

Bars support up to three key dimensions which can be laid by 'group', 'category', and 'stack' dimensions. By default the key dimensions are mapped onto the first, second, and third Dimension of the Bars object, but this behavior can be overridden via the group_index, category_index, and stack_index options. You can also style each bar the way you want by creating style groups for any combination of the three dimensions. Here we color_by 'category' and 'stack', so that a given color represents some combination of those two values (according to the key shown).

BoxWhisker ¶

The BoxWhisker Element allows representing distributions of data varying by 0-N key dimensions. To represent the distribution of a single variable, we can create a BoxWhisker Element with no key dimensions and a single value dimension:

BoxWhisker Elements support any number of dimensions and may also be rotated. To style the boxes and whiskers, supply boxprops, whiskerprops, and flierprops.

BoxWhisker Elements may also be used to represent a distribution as a marginal plot by adjoining it using <<.

Histogram ¶

Histograms partition the x axis into discrete (but not necessarily regular) bins, showing counts in each as a bar.

Almost all Element types, including Histogram, may be projected onto a polar axis by supplying projection='polar' as a plot option.

Scatter ¶

Scatter is the discrete equivalent of Curve, showing y values for discrete x values selected. See Points for more information.

The marker shape specified above can be any supported by matplotlib, e.g. s, d, or o; the other options select the color and size of the marker. For convenience with the bokeh backend, the matplotlib marker options are supported using a compatibility function in HoloViews.

Points ¶

As you can see, Points is very similar to Scatter, and can produce some plots that look identical. However, the two Elements are very different semantically. For Scatter, the dots each show a dependent variable y for some x, such as in the Scatter example above where we selected regularly spaced values of x and then created a random number as the corresponding y. I.e., for Scatter, the y values are the data; the xs are just where the data values are located. For Points, both x and y are independent variables, known as key_dimensions in HoloViews:

The Scatter object expresses a dependent relationship between x and y, making it useful for combining with other similar Chart types, while the Points object expresses the relationship of two independent keys x and y with optional vdims (zero in this case), which makes Points objects meaningful to combine with the Raster types below.

Of course, the vdims need not be empty for Points; here is an example with two additional quantities for each point, as value_dimensions z and α visualized as the color and size of the dots, respectively. The point sizes can be tweaked using the option scaling_factor, which determines the amount by which each point width or area is scaled, depending on the value of scaling_method.

Such a plot wouldn't be meaningful for Scatter, but is a valid use for Points, where the x and y locations are independent variables representing coordinates, and the "data" is conveyed by the size and color of the dots.

Spikes ¶

Spikes represent any number of horizontal or vertical line segments with fixed or variable heights. There are a number of disparate uses for this type. First of all, they may be used as a rugplot to give an overview of a one-dimensional distribution. They may also be useful in more domain-specific cases, such as visualizing spike trains for neurophysiology or spectrograms in physics and chemistry applications.

In the simplest case, a Spikes object represents coordinates in a 1D distribution:

When supplying two dimensions to the Spikes object, the second dimension will be mapped onto the line height. Optionally, you may also supply a cmap and color_index to map color onto one of the dimensions. This way we can, for example, plot a mass spectrogram:

Another possibility is to draw a number of spike trains as you would encounter in neuroscience. Here we generate 10 separate random spike trains and distribute them evenly across the space by setting their position. By also declaring some yticks, each spike train can be labeled individually:

Finally, we may use Spikes to visualize marginal distributions as adjoined plots using the << adjoin operator:

VectorField ¶

As you can see above, here the x and y positions are chosen to make a regular grid. The arrow angles follow a sinsoidal ring pattern, and the arrow lengths fall off exponentially from the center, so this plot has four dimensions of data (direction and length for each x,y position).

Using the IPython %%opts cell-magic (described in the Options tutorial, along with the Python equivalent), we can also use color as a redundant indicator to the direction or magnitude:

The vector fields above were sampled on a regular grid, but any collection of x,y values is allowed:

SideHistogram ¶

The .hist method conveniently adjoins a histogram to the side of any Chart, Surface, or Raster component, as well as many of the container types (though it would be reporting data from one of these underlying Element types). For a Raster using color or grayscale to show values (see Raster section below), the side histogram doubles as a color bar or key.

Chart3D Elements ¶

Surface ¶

Surface is used for a set of gridded points whose associated value dimension represents samples from a continuous surface; it is the equivalent of a Curve but with two key dimensions instead of just one.

Scatter3D ¶

Scatter3D is the equivalent of Scatter but for two key dimensions, rather than just one.

TriSurface ¶

The TriSurface Element renders any collection of 3D points as a Surface by applying Delaunay triangulation. It thus supports arbitrary, non-gridded data, but it does not support indexing to find data values, since finding the closest ones would require a search.

Raster Elements ¶

A collection of raster image types

The second large class of Elements is the raster elements. Like Points and unlike the other Chart elements, Raster Elements live in a 2D key-dimensions space. For the Image, RGB, and HSV elements, the coordinates of this two-dimensional key space are defined in a continuously indexable coordinate system. We can use np.meshgrid to define the appropriate sampling along the x and y dimensions:

Raster ¶

A Raster is the base class for image-like Elements, but may be used directly to visualize 2D arrays using a color map. The coordinate system of a Raster is the raw indexes of the underlying array, with integer values always starting from (0,0) in the top left, with default extents corresponding to the shape of the array. The Image subclass visualizes similarly, but using a continuous Cartesian coordinate system suitable for an array that represents some underlying continuous region.

QuadMesh ¶

The basic QuadMesh is a 2D grid of bins specified as x-/y-values specifying a regular sampling or edges, with arbitrary sampling and an associated 2D array containing the bin values. The coordinate system of a QuadMesh is defined by the bin edges, therefore any index falling into a binned region will return the appropriate value. Unlike Image objects, slices must be inclusive of the bin edges.

QuadMesh may also be used to represent an arbitrary mesh of quadrilaterals by supplying three separate 2D arrays representing the coordinates of each quadrilateral in a 2D space. Note that when using QuadMesh in this mode, slicing and indexing semantics and most operations will currently not work.

HeatMap ¶

A HeatMap displays like a typical raster image, but the input is a dictionary indexed with two-dimensional keys, not a Numpy array or Pandas dataframe. As many rows and columns as required will be created to display the values in an appropriate grid format. Values unspecified are left blank, and the keys can be any Python datatype (not necessarily numeric). One typical usage is to show values from a set of experiments, such as a parameter space exploration, and many other such visualizations are shown in the Containers and Exploring Data tutorials. Each value in a HeatMap is labeled explicitly by default, and so this component is not meant for very large numbers of samples. With the default color map, high values (in the upper half of the range present) are colored orange and red, while low values (in the lower half of the range present) are colored shades of blue.

Image ¶

Like Raster, a HoloViews Image allows you to view 2D arrays using an arbitrary color map. Unlike Raster, an Image is associated with a 2D coordinate system in continuous space, which is appropriate for values sampled from some underlying continuous distribution (as in a photograph or other measurements from locations in real space). Slicing, sampling, etc. on an Image all use this continuous space, whereas the corresponding operations on a Raster work on the raw array coordinates.

To make the coordinate system clear, we'll define two arrays called xs and ys with a non-square aspect and map them through a simple function that illustrate how these inputs relate to the coordinate system:

Notice how, because our declared coordinate system is continuous, we can slice with any floating-point value we choose. The appropriate range of the samples in the input numpy array will always be displayed, whether or not there are samples at those specific floating-point values.

It is also worth noting that the name Image can clash with other common libraries, which is one reason to avoid unqualified imports like from holoviews import *. For instance, the Python Imaging Libray provides an Image module, and IPython itself supplies an Image class in IPython.display. Python namespaces allow you to avoid such problems, e.g. using from PIL import Image as PILImage or using import holoviews as hv and then hv.Image(), as we do in these tutorials.

RGB ¶

The RGB element is an Image that supports red, green, blue channels:

You can see how the RGB object is created from the original channels:

RGB also supports an optional alpha channel, which will be used as a mask revealing or hiding any Elements it is overlaid on top of:

HSV ¶

HoloViews makes it trivial to work in any color space that can be converted to RGB by making a simple subclass of RGB as appropriate. For instance, we also provide the HSV (hue, saturation, value) color space, which is useful for plotting cyclic data (as the Hue) along with two additional dimensions (controlling the saturation and value of the color, respectively):

You can see how this is created from the original channels:

Tabular Elements ¶

General data structures for holding arbitrary information

ItemTable ¶

An ItemTable is an ordered collection of key, value pairs. It can be used to directly visualize items in a tabular format where the items may be supplied as an OrderedDict or a list of (key,value) pairs. A standard Python dictionary can be easily visualized using a call to the .items() method, though the entries in such a dictionary are not kept in any particular order, and so you may wish to sort them before display. One typical usage for an ItemTable is to list parameter values or measurements associated with an adjacent Element.

Table ¶

A table is more general than an ItemTable, as it allows multi-dimensional keys and multidimensional values.

Note that you can use select using tables, and once you select using a full, multidimensional key, you get an ItemTable (shown on the right):

The Table is used as a common data structure that may be converted to any other HoloViews data structure using the TableConversion class.

The functionality of the TableConversion class may be conveniently accessed using the .to property. For more extended usage of table conversion see the Columnar Data and Pandas Conversion Tutorials.

Annotation Elements ¶

Useful information that can be overlaid onto other components

Annotations are components designed to be overlaid on top of other Element objects. To demonstrate annotation and paths, we will be drawing many of our elements on top of an RGB Image:

VLine and HLine ¶

Spline ¶

The Spline annotation is used to draw Bezier splines using the same semantics as matplotlib splines. In the overlay below, the spline is in dark blue and the control points are in light blue.

Text and Arrow ¶

Paths ¶

Line-based components that can be overlaid onto other components

Paths are a subclass of annotations that involve drawing line-based components on top of other elements. Internally, Path Element types hold a list of Nx2 arrays, specifying the x/y-coordinates along each path. The data may be supplied in a number of ways, including:

1. A list of Nx2 numpy arrays.
2. A list of lists containing x/y coordinate tuples.
3. A tuple containing an array of length N with the x-values and a second array of shape NxP, where P is the number of paths.
4. A list of tuples each containing separate x and y values.

Path ¶

A Path object is actually a collection of paths which can be arbitrarily specified. Although there may be multiple unconnected paths in a single Path object, they will all share the same style. Only by overlaying multiple Path objects do you iterate through the defined color cycle (or any other style options that have been defined).

Contours ¶

A Contours object is similar to Path object except each of the path elements is associated with a numeric value, called the level. Sadly, our penguins are too complicated to give a simple example so instead we will simply mark the first couple of rings of our earlier ring pattern:

Polygons ¶

A Polygons object is similar to a Contours object except that each supplied path is closed and filled. Just like Contours, optionally a level may be supplied; the Polygons will then be colored according to the supplied cmap. Non-finite values such as np.NaN or np.inf will default to the supplied facecolor.

Polygons with values can be used to build heatmaps with arbitrary shapes.

Polygons without a value are useful as annotation, but also allow us to draw arbitrary shapes.

Bounds ¶

A bounds is a rectangular area specified as a tuple in (left, bottom, right, top) format. It is useful for denoting a region of interest defined by some bounds, whereas Box (below) is useful for drawing a box at a specific location.

Box and Ellipse ¶

A Box is similar to a Bounds except you specify the box position, width, and aspect ratio instead of the coordinates of the box corners. An Ellipse is specified just as for Box, but has a rounded shape.