holoviews.core.dimension module#

Provides Dimension objects for tracking the properties of a value, axis or map dimension. Also supplies the Dimensioned abstract baseclass for classes that accept Dimension values.

class holoviews.core.dimension.Dimension(spec, **params)[source]#

Bases: Parameterized

Dimension objects are used to specify some important general features that may be associated with a collection of values.

For instance, a Dimension may specify that a set of numeric values actually correspond to ‘Height’ (dimension name), in units of meters, with a descriptive label ‘Height of adult males’.

All dimensions object have a name that identifies them and a label containing a suitable description. If the label is not explicitly specified it matches the name.

These two parameters define the core identity of the dimension object and must match if two dimension objects are to be considered equivalent. All other parameters are considered optional metadata and are not used when testing for equality.

Unlike all the other parameters, these core parameters can be used to construct a Dimension object from a tuple. This format is sufficient to define an identical Dimension:

Dimension(‘a’, label=’Dimension A’) == Dimension((‘a’, ‘Dimension A’))

Everything else about a dimension is considered to reflect non-semantic preferences. Examples include the default value (which may be used in a visualization to set an initial slider position), how the value is to rendered as text (which may be used to specify the printed floating point precision) or a suitable range of values to consider for a particular analysis.

Units#

Full unit support with automated conversions are on the HoloViews roadmap. Once rich unit objects are supported, the unit (or more specifically the type of unit) will be part of the core dimension specification used to establish equality.

Until this feature is implemented, there are two auxiliary parameters that hold some partial information about the unit: the name of the unit and whether or not it is cyclic. The name of the unit is used as part of the pretty-printed representation and knowing whether it is cyclic is important for certain operations.

Parameter Definitions

label = String(allow_None=True, label='Label')

Unrestricted label used to describe the dimension. A label should succinctly describe the dimension and may contain any characters, including Unicode and LaTeX expression.

cyclic = Boolean(default=False, label='Cyclic')

Whether the range of this feature is cyclic such that the maximum allowed value (defined by the range parameter) is continuous with the minimum allowed value.

default = Parameter(allow_None=True, label='Default')

Default value of the Dimension which may be useful for widget or other situations that require an initial or default value.

nodata = Integer(allow_None=True, inclusive_bounds=(True, True), label='Nodata')

Optional missing-data value for integer data. If non-None, data with this value will be replaced with NaN.

range = Tuple(default=(None, None), label='Range', length=2)

Specifies the minimum and maximum allowed values for a Dimension. None is used to represent an unlimited bound.

soft_range = Tuple(default=(None, None), label='Soft range', length=2)

Specifies a minimum and maximum reference value, which may be overridden by the data.

step = Number(allow_None=True, inclusive_bounds=(True, True), label='Step')

Optional floating point step specifying how frequently the underlying space should be sampled. May be used to define a discrete sampling over the range.

type = Parameter(allow_None=True, label='Type')

Optional type associated with the Dimension values. The type may be an inbuilt constructor (such as int, str, float) or a custom class object.

unit = String(allow_None=True, label='Unit')

Optional unit string associated with the Dimension. For instance, the string ‘m’ may be used represent units of meters and ‘s’ to represent units of seconds.

value_format = Callable(allow_None=True, label='Value format')

Formatting function applied to each value before display.

values = List(bounds=(0, None), default=[], label='Values')

Optional specification of the allowed value set for the dimension that may also be used to retain a categorical ordering.

clone(spec=None, **overrides)[source]#

Clones the Dimension with new parameters

Derive a new Dimension that inherits existing parameters except for the supplied, explicit overrides

Parameters#

spectuple, optional

Dimension tuple specification

**overrides: Dimension parameter overrides

Returns#

Cloned Dimension object

property pprint_label#

The pretty-printed label string for the Dimension

pprint_value(value, print_unit=False)[source]#

Applies the applicable formatter to the value.

Parameters#

value

Dimension value to format

Returns#

Formatted dimension value

pprint_value_string(value)[source]#

Pretty print the dimension value and unit with title_format

Parameters#

value

Dimension value to format

Returns#

Formatted dimension value string with unit

property spec#

“Returns the Dimensions tuple specification

Returns#

tuple : Dimension tuple specification

class holoviews.core.dimension.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.dimension.LabelledData(data, id=None, plot_id=None, **params)[source]#

Bases: Parameterized

LabelledData is a mix-in class designed to introduce the group and label parameters (and corresponding methods) to any class containing data. This class assumes that the core data contents will be held in the attribute called ‘data’.

Used together, group and label are designed to allow a simple and flexible means of addressing data. For instance, if you are collecting the heights of people in different demographics, you could specify the values of your objects as ‘Height’ and then use the label to specify the (sub)population.

In this scheme, one object may have the parameters set to [group=’Height’, label=’Children’] and another may use [group=’Height’, label=’Adults’].

Note#

Another level of specification is implicit in the type (i.e class) of the LabelledData object. A full specification of a LabelledData object is therefore given by the tuple (<type>, <group>, label>). This additional level of specification is used in the traverse method.

Any strings can be used for the group and label, but it can be convenient to use a capitalized string of alphanumeric characters, in which case the keys used for matching in the matches and traverse method will correspond exactly to {type}.{group}.{label}. Otherwise the strings provided will be sanitized to be valid capitalized Python identifiers, which works fine but can sometimes be confusing.

Parameter Definitions

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

A string describing the type of data contained by the object. By default this will typically mirror the class name.

label = String(constant=True, default='', label='Label')

Optional label describing the data, typically reflecting where or how it was measured. The label should allow a specific measurement or dataset to be referenced for a given group.

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

map(map_fn, specs=None, clone=True)[source]#

Map a function to all objects matching the specs

Recursively replaces elements using a map function when the specs apply, by default applies to all objects, e.g. to apply the function to all contained Curve objects:

dmap.map(fn, hv.Curve)

Parameters#

map_fn : Function to apply to each object specs : List of specs to match

List of types, functions or type[.group][.label] specs to select objects to return, by default applies to all objects.

clone

Whether to clone the object or transform inplace

Returns#

Returns the object after the map_fn has been applied

matches(spec)[source]#

Whether the spec applies to this object.

Parameters#

specA function, spec or type to check for a match
  • A ‘type[[.group].label]’ string which is compared

    against the type, group and label of this object

  • A function which is given the object and returns

    a boolean.

  • An object type matched using isinstance.

Returns#

bool

Whether the spec matched this object.

relabel(label=None, group=None, depth=0)[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

traverse(fn=None, specs=None, full_breadth=True)[source]#

Traverses object returning matching items Traverses the set of children of the object, collecting the all objects matching the defined specs. Each object can be processed with the supplied function.

Parameters#

fnfunction, optional

Function applied to matched objects

specsList of specs to match

Specs must be types, functions or type[.group][.label] specs to select objects to return, by default applies to all objects.

full_breadthWhether to traverse all objects

Whether to traverse the full set of objects on each container or only the first.

Returns#

list

List of objects that matched

class holoviews.core.dimension.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.dimension.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

holoviews.core.dimension.asdim(dimension)[source]#

Convert the input to a Dimension.

Parameters#

dimension : tuple, dict or string type to convert to Dimension

Returns#

A Dimension object constructed from the dimension spec. No copy is performed if the input is already a Dimension.

holoviews.core.dimension.dimension_name(dimension)[source]#

Return the Dimension.name for a dimension-like object.

Parameters#

dimension : Dimension or dimension string, tuple or dict

Returns#

The name of the Dimension or what would be the name if the input as converted to a Dimension.

holoviews.core.dimension.param_aliases(d)[source]#

Called from __setstate__ in LabelledData in order to load old pickles with outdated parameter names.

Warning#

We want to keep pickle hacking to a minimum!

holoviews.core.dimension.process_dimensions(kdims, vdims)[source]#

Converts kdims and vdims to Dimension objects.

Parameters#

kdimsList or single key dimension(s) specified as strings,

tuples dicts or Dimension objects.

vdimsList or single value dimension(s) specified as strings,

tuples dicts or Dimension objects.

Returns#

Dictionary containing kdims and vdims converted to Dimension objects

{‘kdims’: [Dimension(‘x’)], ‘vdims’: [Dimension(‘y’)]