holoviews.core.overlay module#

Supplies Layer and related classes that allow overlaying of Views, including Overlay. A Layer is the final extension of View base class that allows Views to be overlaid on top of each other.

Also supplies ViewMap which is the primary multi-dimensional Map type for indexing, slicing and animating collections of Views.

class holoviews.core.overlay.AdjointLayout(data, **params)[source]#

Bases: Layoutable, Dimensioned

An AdjointLayout provides a convenient container to lay out some marginal plots next to a primary plot. This is often useful to display the marginal distributions of a plot next to the primary plot. AdjointLayout accepts a list of up to three elements, which are laid out as follows with the names ‘main’, ‘top’ and ‘right’:

3 | |

|___________|___| | | | 1: main | | | 2: right | 1 | 2 | 3: top | | | |___________|___|

Parameter Definitions

Parameters inherited from:

kdims = List(bounds=(0, None), constant=True, default=[Dimension('AdjointLayout')], label='Kdims')

The key dimensions defined as list of dimensions that may be used in indexing (and potential slicing) semantics. The order of the dimensions listed here determines the semantics of each component of a multi-dimensional indexing operation. Aliased with key_dimensions.

property ddims#

The list of deep dimensions

dimension_values(dimension, expanded=True, flat=True)[source]#

Return the values along the requested dimension.

Applies to the main object in the AdjointLayout.

Parameters#

dimension

The dimension to return values for

expandedbool, optional

Whether to expand values Whether to return the expanded values, behavior depends on the type of data:

  • Columnar: If false returns unique values

  • Geometry: If false returns scalar values per geometry

  • Gridded: If false returns 1D coordinates

flatbool, optional

Whether to flatten array

Returns#

NumPy array of values along the requested dimension

get(key, default=None)[source]#

Returns the viewable corresponding to the supplied string or integer based key.

Parameters#

keyNumeric or string index

0: ‘main’ 1: ‘right’ 2: ‘top’

default

Value returned if key not found

Returns#

Indexed value or supplied default

property group#

Group inherited from main element

property label#

Label inherited from main element

property main#

Returns the main element in the AdjointLayout

relabel(label=None, group=None, depth=1)[source]#

Clone object and apply new group and/or label.

Applies relabeling to child up to the supplied depth.

Parameters#

labelstr, optional

New label to apply to returned object

groupstr, optional

New group to apply to returned object

depthint, optional

Depth to which relabel will be applied If applied to container allows applying relabeling to contained objects up to the specified depth

Returns#

Returns relabelled object

property right#

Returns the right marginal element in the AdjointLayout

property top#

Returns the top marginal element in the AdjointLayout

class holoviews.core.overlay.CompositeOverlay(data, kdims=None, vdims=None, **params)[source]#

Bases: ViewableElement, Composable

CompositeOverlay provides a common baseclass for Overlay classes.

Parameter Definitions

Parameters inherited from:

dimension_values(dimension, expanded=True, flat=True)[source]#

Return the values along the requested dimension.

Parameters#

dimension

The dimension to return values for

expandedbool, optional

Whether to expand values Whether to return the expanded values, behavior depends on the type of data:

  • Columnar: If false returns unique values

  • Geometry: If false returns scalar values per geometry

  • Gridded: If false returns 1D coordinates

flatbool, optional

Whether to flatten array

Returns#

NumPy array of values along the requested dimension

hist(dimension=None, num_bins=20, bin_range=None, adjoin=True, index=None, show_legend=False, **kwargs)[source]#

Computes and adjoins histogram along specified dimension(s).

Defaults to first value dimension if present otherwise falls back to first key dimension.

Parameters#

dimension

Dimension(s) to compute histogram on, Falls back the plot dimensions by default.

num_binsint, optional

Number of bins

bin_rangetuple, optional

Lower and upper bounds of bins

adjoinbool, optional

Whether to adjoin histogram

indexint, optional

Index of layer to apply hist to

show_legendbool, optional

Show legend in histogram (don’t show legend by default).

Returns#

AdjointLayout of element and histogram or just the histogram

class holoviews.core.overlay.Dimensioned(data, kdims=None, vdims=None, **params)[source]#

Bases: LabelledData

Dimensioned is a base class that allows the data contents of a class to be associated with dimensions. The contents associated with dimensions may be partitioned into one of three types

  • key dimensions

    These are the dimensions that can be indexed via the __getitem__ method. Dimension objects supporting key dimensions must support indexing over these dimensions and may also support slicing. This list ordering of dimensions describes the positional components of each multi-dimensional indexing operation.

    For instance, if the key dimension names are ‘weight’ followed by ‘height’ for Dimensioned object ‘obj’, then obj[80,175] indexes a weight of 80 and height of 175.

    Accessed using either kdims.

  • value dimensions

    These dimensions correspond to any data held on the Dimensioned object not in the key dimensions. Indexing by value dimension is supported by dimension name (when there are multiple possible value dimensions); no slicing semantics is supported and all the data associated with that dimension will be returned at once. Note that it is not possible to mix value dimensions and deep dimensions.

    Accessed using either vdims.

  • deep dimensions

    These are dynamically computed dimensions that belong to other Dimensioned objects that are nested in the data. Objects that support this should enable the _deep_indexable flag. Note that it is not possible to mix value dimensions and deep dimensions.

    Accessed using either ddims.

Dimensioned class support generalized methods for finding the range and type of values along a particular Dimension. The range method relies on the appropriate implementation of the dimension_values methods on subclasses.

The index of an arbitrary dimension is its positional index in the list of all dimensions, starting with the key dimensions, followed by the value dimensions and ending with the deep dimensions.

Parameter Definitions

Parameters inherited from:

group = String(constant=True, default='Dimensioned', label='Group')

A string describing the data wrapped by the object.

cdims = Dict(class_=<class 'dict'>, default={}, label='Cdims')

The constant dimensions defined as a dictionary of Dimension:value pairs providing additional dimension information about the object. Aliased with constant_dimensions.

kdims = List(bounds=(0, None), constant=True, default=[], label='Kdims')

The key dimensions defined as list of dimensions that may be used in indexing (and potential slicing) semantics. The order of the dimensions listed here determines the semantics of each component of a multi-dimensional indexing operation. Aliased with key_dimensions.

vdims = List(bounds=(0, None), constant=True, default=[], label='Vdims')

The value dimensions defined as the list of dimensions used to describe the components of the data. If multiple value dimensions are supplied, a particular value dimension may be indexed by name after the key dimensions. Aliased with value_dimensions.

property ddims#

The list of deep dimensions

dimension_values(dimension, expanded=True, flat=True)[source]#

Return the values along the requested dimension.

Parameters#

dimension

The dimension to return values for

expandedbool, optional

Whether to expand values Whether to return the expanded values, behavior depends on the type of data:

  • Columnar

    If false returns unique values

  • Geometry

    If false returns scalar values per geometry

  • Gridded

    If false returns 1D coordinates

flatbool, optional

Whether to flatten array

Returns#

NumPy array of values along the requested dimension

dimensions(selection='all', label=False)[source]#

Lists the available dimensions on the object

Provides convenient access to Dimensions on nested Dimensioned objects. Dimensions can be selected by their type, i.e. ‘key’ or ‘value’ dimensions. By default ‘all’ dimensions are returned.

Parameters#

selectionType of dimensions to return

The type of dimension, i.e. one of ‘key’, ‘value’, ‘constant’ or ‘all’.

labelWhether to return the name, label or Dimension

Whether to return the Dimension objects (False), the Dimension names (True/’name’) or labels (‘label’).

Returns#

List of Dimension objects or their names or labels

get_dimension(dimension, default=None, strict=False) → Dimension | None[source]#

Get a Dimension object by name or index.

Parameters#

dimension : Dimension to look up by name or integer index default : optional

Value returned if Dimension not found

strictbool, optional

Raise a KeyError if not found

Returns#

Dimension object for the requested dimension or default

get_dimension_index(dimension)[source]#

Get the index of the requested dimension.

Parameters#

dimension

Dimension to look up by name or by index

Returns#

Integer index of the requested dimension

get_dimension_type(dim)[source]#

Get the type of the requested dimension.

Type is determined by Dimension.type attribute or common type of the dimension values, otherwise None.

Parameters#

dimension

Dimension to look up by name or by index

Returns#

Declared type of values along the dimension

options(*args, clone=True, **kwargs)[source]#

Applies simplified option definition returning a new object.

Applies options on an object or nested group of objects in a flat format returning a new object with the options applied. If the options are to be set directly on the object a simple format may be used, e.g.:

obj.options(cmap=’viridis’, show_title=False)

If the object is nested the options must be qualified using a type[.group][.label] specification, e.g.:

obj.options(‘Image’, cmap=’viridis’, show_title=False)

or using:

obj.options({‘Image’: dict(cmap=’viridis’, show_title=False)})

Identical to the .opts method but returns a clone of the object by default.

Parameters#

*args: Sets of options to apply to object

Supports a number of formats including lists of Options objects, a type[.group][.label] followed by a set of keyword options to apply and a dictionary indexed by type[.group][.label] specs.

backendoptional

Backend to apply options to Defaults to current selected backend

clonebool, optional

Whether to clone object Options can be applied inplace with clone=False

**kwargs: Keywords of options

Set of options to apply to the object

Returns#

Returns the cloned object with the options applied

range(dimension, data_range=True, dimension_range=True)[source]#

Return the lower and upper bounds of values along dimension.

Parameters#

dimension

The dimension to compute the range on.

data_rangebool

Compute range from data values

dimension_rangebool

Include Dimension ranges Whether to include Dimension range and soft_range in range calculation

Returns#

Tuple containing the lower and upper bound

select(selection_specs=None, **kwargs)[source]#

Applies selection by dimension name

Applies a selection along the dimensions of the object using keyword arguments. The selection may be narrowed to certain objects using selection_specs. For container objects the selection will be applied to all children as well.

Selections may select a specific value, slice or set of values:

  • value

    Scalar values will select rows along with an exact match, e.g.:

    ds.select(x=3)

  • slice

    Slices may be declared as tuples of the upper and lower bound, e.g.:

    ds.select(x=(0, 3))

  • values

    A list of values may be selected using a list or set, e.g.:

    ds.select(x=[0, 1, 2])

Parameters#

selection_specsList of specs to match on

A list of types, functions, or type[.group][.label] strings specifying which objects to apply the selection on.

**selection: Dictionary declaring selections by dimension

Selections can be scalar values, tuple ranges, lists of discrete values and boolean arrays

Returns#

Returns an Dimensioned object containing the selected data or a scalar if a single value was selected

class holoviews.core.overlay.Layout(items=None, identifier=None, parent=None, **kwargs)[source]#

Bases: Layoutable, ViewableTree

A Layout is an ViewableTree with ViewableElement objects as leaf values.

Unlike ViewableTree, a Layout supports a rich display, displaying leaf items in a grid style layout. In addition to the usual ViewableTree indexing, Layout supports indexing of items by their row and column index in the layout.

The maximum number of columns in such a layout may be controlled with the cols method.

Parameter Definitions

Parameters inherited from:

group = String(constant=True, default='Layout', label='Group')

A string describing the data wrapped by the object.

clone(*args, **overrides)[source]#

Clones the Layout, overriding data and parameters.

Parameters#

data

New data replacing the existing data

shared_databool, optional

Whether to use existing data

new_typeoptional

Type to cast object to

*args

Additional arguments to pass to constructor

**overrides

New keyword arguments to pass to constructor

Returns#

Cloned Layout object

cols(ncols)[source]#

Sets the maximum number of columns in the NdLayout.

Any items beyond the set number of cols will flow onto a new row. The number of columns control the indexing and display semantics of the NdLayout.

Parameters#

ncolsint

Number of columns to set on the NdLayout

decollate()[source]#

Packs Layout of DynamicMaps into a single DynamicMap that returns a Layout

Decollation allows packing a Layout of DynamicMaps into a single DynamicMap that returns a Layout of simple (non-dynamic) elements. All nested streams are lifted to the resulting DynamicMap, and are available in the streams property. The callback property of the resulting DynamicMap is a pure, stateless function of the stream values. To avoid stream parameter name conflicts, the resulting DynamicMap is configured with positional_stream_args=True, and the callback function accepts stream values as positional dict arguments.

Returns#

DynamicMap that returns a Layout

relabel(label=None, group=None, depth=1)[source]#

Clone object and apply new group and/or label.

Applies relabeling to children up to the supplied depth.

Parameters#

labelstr, optional

New label to apply to returned object

groupstr, optional

New group to apply to returned object

depthint, optional

Depth to which relabel will be applied If applied to container allows applying relabeling to contained objects up to the specified depth

Returns#

Returns relabelled object

property shape#

Tuple indicating the number of rows and columns in the Layout.

class holoviews.core.overlay.NdOverlay(overlays=None, kdims=None, **params)[source]#

Bases: Overlayable, UniformNdMapping, CompositeOverlay

An NdOverlay allows a group of NdOverlay to be overlaid together. NdOverlay can be indexed out of an overlay and an overlay is an iterable that iterates over the contained layers.

Parameter Definitions

Parameters inherited from:

kdims = List(bounds=(0, None), constant=True, default=[Dimension('Element')], label='Kdims')

List of dimensions the NdOverlay can be indexed by.

decollate()[source]#

Packs NdOverlay of DynamicMaps into a single DynamicMap that returns an NdOverlay

Decollation allows packing a NdOverlay of DynamicMaps into a single DynamicMap that returns an NdOverlay of simple (non-dynamic) elements. All nested streams are lifted to the resulting DynamicMap, and are available in the streams property. The callback property of the resulting DynamicMap is a pure, stateless function of the stream values. To avoid stream parameter name conflicts, the resulting DynamicMap is configured with positional_stream_args=True, and the callback function accepts stream values as positional dict arguments.

Returns#

DynamicMap that returns an NdOverlay

class holoviews.core.overlay.Overlay(items=None, group=None, label=None, **params)[source]#

Bases: ViewableTree, CompositeOverlay, Layoutable, Overlayable

An Overlay consists of multiple Elements (potentially of heterogeneous type) presented one on top each other with a particular z-ordering.

Overlays along with elements constitute the only valid leaf types of a Layout and in fact extend the Layout structure. Overlays are constructed using the * operator (building an identical structure to the + operator).

Parameter Definitions

Parameters inherited from:

clone(data=None, shared_data=True, new_type=None, link=True, **overrides)[source]#

Clones the object, overriding data and parameters.

Parameters#

data

New data replacing the existing data

shared_databool, optional

Whether to use existing data

new_typeoptional

Type to cast object to

linkbool, optional

Whether clone should be linked Determines whether Streams and Links attached to original object will be inherited.

*args

Additional arguments to pass to constructor

**overrides

New keyword arguments to pass to constructor

Returns#

Cloned object

collate()[source]#

Collates any objects in the Overlay resolving any issues the recommended nesting structure.

property ddims#

The list of deep dimensions

decollate()[source]#

Packs Overlay of DynamicMaps into a single DynamicMap that returns an Overlay

Decollation allows packing an Overlay of DynamicMaps into a single DynamicMap that returns an Overlay of simple (non-dynamic) elements. All nested streams are lifted to the resulting DynamicMap, and are available in the streams property. The callback property of the resulting DynamicMap is a pure, stateless function of the stream values. To avoid stream parameter name conflicts, the resulting DynamicMap is configured with positional_stream_args=True, and the callback function accepts stream values as positional dict arguments.

Returns#

DynamicMap that returns an Overlay

get(identifier, default=None)[source]#

Get a layer in the Overlay.

Get a particular layer in the Overlay using its path string or an integer index.

Parameters#

identifier

Index or path string of the item to return

default

Value to return if no item is found

Returns#

The indexed layer of the Overlay

property group#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

property label#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class holoviews.core.overlay.Overlayable[source]#

Bases: object

Overlayable provides a mix-in class to support the mul operation for overlaying multiple elements.

class holoviews.core.overlay.UniformNdMapping(initial_items=None, kdims=None, group=None, label=None, **params)[source]#

Bases: NdMapping

A UniformNdMapping is a map of Dimensioned objects and is itself indexed over a number of specified dimensions. The dimension may be a spatial dimension (i.e., a ZStack), time (specifying a frame sequence) or any other combination of Dimensions.

UniformNdMapping objects can be sliced, sampled, reduced, overlaid and split along its and its containing Element’s dimensions. Subclasses should implement the appropriate slicing, sampling and reduction methods for their Dimensioned type.

Parameter Definitions

Parameters inherited from:

clone(data=None, shared_data=True, new_type=None, link=True, *args, **overrides)[source]#

Clones the object, overriding data and parameters.

Parameters#

data

New data replacing the existing data

shared_databool, optional

Whether to use existing data

new_typeoptional

Type to cast object to

linkbool, optional

Whether clone should be linked Determines whether Streams and Links attached to original object will be inherited.

*args

Additional arguments to pass to constructor

**overrides

New keyword arguments to pass to constructor

Returns#

Cloned object

collapse(dimensions=None, function=None, spreadfn=None, **kwargs)[source]#

Concatenates and aggregates along supplied dimensions

Useful to collapse stacks of objects into a single object, e.g. to average a stack of Images or Curves.

Parameters#

dimensions

Dimension(s) to collapse Defaults to all key dimensions

function

Aggregation function to apply, e.g. numpy.mean

spreadfn

Secondary reduction to compute value spread Useful for computing a confidence interval, spread, or standard deviation.

**kwargs

Keyword arguments passed to the aggregation function

Returns#

Returns the collapsed element or HoloMap of collapsed elements

dframe(dimensions=None, multi_index=False)[source]#

Convert dimension values to DataFrame.

Returns a pandas dataframe of columns along each dimension, either completely flat or indexed by key dimensions.

Parameters#

dimensions

Dimensions to return as columns

multi_index

Convert key dimensions to (multi-)index

Returns#

DataFrame of columns corresponding to each dimension

property group#

Group inherited from items

property label#

Label inherited from items

property type#

The type of elements stored in the mapping.

class holoviews.core.overlay.ViewableElement(data, kdims=None, vdims=None, **params)[source]#

Bases: Dimensioned

A ViewableElement is a dimensioned datastructure that may be associated with a corresponding atomic visualization. An atomic visualization will display the data on a single set of axes (i.e. excludes multiple subplots that are displayed at once). The only new parameter introduced by ViewableElement is the title associated with the object for display.

Parameter Definitions

Parameters inherited from:

group = String(constant=True, default='ViewableElement', label='Group')

A string describing the data wrapped by the object.

class holoviews.core.overlay.ViewableTree(items=None, identifier=None, parent=None, **kwargs)[source]#

Bases: AttrTree, Dimensioned

A ViewableTree is an AttrTree with Viewable objects as its leaf nodes. It combines the tree like data structure of a tree while extending it with the deep indexable properties of Dimensioned and LabelledData objects.

Parameter Definitions

Parameters inherited from:

group = String(constant=True, default='ViewableTree', label='Group')

A string describing the data wrapped by the object.

dimension_values(dimension, expanded=True, flat=True)[source]#

Return the values along the requested dimension.

Concatenates values on all nodes with requested dimension.

Parameters#

dimension

The dimension to return values for

expandedbool, optional

Whether to expand values Whether to return the expanded values, behavior depends on the type of data:

  • Columnar

    If false returns unique values

  • Geometry

    If false returns scalar values per geometry

  • Gridded

    If false returns 1D coordinates

flatbool, optional

Whether to flatten array

Returns#

NumPy array of values along the requested dimension

property uniform#

Whether items in tree have uniform dimensions