holoviews.core.ndmapping module#

Supplies MultiDimensionalMapping and NdMapping which are multi-dimensional map types. The former class only allows indexing whereas the latter also enables slicing over multiple dimension ranges.

class holoviews.core.ndmapping.MultiDimensionalMapping(initial_items=None, kdims=None, **params)[source]#

Bases: Dimensioned

An MultiDimensionalMapping is a Dimensioned mapping (like a dictionary or array) that uses fixed-length multidimensional keys. This behaves like a sparse N-dimensional array that does not require a dense sampling over the multidimensional space.

If the underlying value for each (key, value) pair also supports indexing (such as a dictionary, array, or list), fully qualified (deep) indexing may be used from the top level, with the first N dimensions of the index selecting a particular Dimensioned object and the remaining dimensions indexing into that object.

For instance, for a MultiDimensionalMapping with dimensions “Year” and “Month” and underlying values that are 2D floating-point arrays indexed by (r,c), a 2D array may be indexed with x[2000,3] and a single floating-point number may be indexed as x[2000,3,1,9].

In practice, this class is typically only used as an abstract base class, because the NdMapping subclass extends it with a range of useful slicing methods for selecting subsets of the data. Even so, keeping the slicing support separate from the indexing and data storage methods helps make both classes easier to understand.

Parameter Definitions

Parameters inherited from:

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

A string describing the data wrapped by the object.

kdims = List(bounds=(0, None), constant=True, default=[Dimension('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, 0), 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.

sort = Boolean(default=True, label='Sort')

Whether the items should be sorted in the constructor.

add_dimension(dimension, dim_pos, dim_val, vdim=False, **kwargs)[source]#

Adds a dimension and its values to the object

Requires the dimension name or object, the desired position in the key dimensions and a key value scalar or sequence of the same length as the existing keys.

Parameters#

dimension

Dimension or dimension spec to add

dim_posint

Integer index to insert dimension at

dim_valscalar or ndarray

Dimension value(s) to add

vdim

Disabled, this type does not have value dimensions

**kwargs

Keyword arguments passed to the cloned element

Returns#

Cloned object containing the new dimension

clone(data=None, shared_data=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

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

drop_dimension(dimensions)[source]#

Drops dimension(s) from keys

Parameters#

dimensions

Dimension(s) to drop

Returns#

Clone of object with with dropped dimension(s)

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

Standard get semantics for all mapping types

groupby(dimensions, container_type=None, group_type=None, **kwargs)[source]#

Groups object by one or more dimensions

Applies groupby operation over the specified dimensions returning an object of type container_type (expected to be dictionary-like) containing the groups.

Parameters#

dimensions

Dimension(s) to group by

container_type

Type to cast group container to

group_type

Type to cast each group to

dynamic

Whether to return a DynamicMap

**kwargs

Keyword arguments to pass to each group

Returns#

Returns object of supplied container_type containing the groups. If dynamic=True returns a DynamicMap instead.

property info#

Prints information about the Dimensioned object, including the number and type of objects contained within it and information about its dimensions.

items()[source]#

Returns all elements as a list in (key,value) format.

keys()[source]#

Returns the keys of all the elements.

property last#

Returns the item highest data item along the map dimensions.

property last_key#

Returns the last key value.

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

Standard pop semantics for all mapping types

reindex(kdims=None, force=False)[source]#

Reindexes object dropping static or supplied kdims

Creates a new object with a reordered or reduced set of key dimensions. By default drops all non-varying key dimensions.

Reducing the number of key dimensions will discard information from the keys. All data values are accessible in the newly created object as the new labels must be sufficient to address each value uniquely.

Parameters#

kdimsoptional

New list of key dimensions after reindexing

forcebool, optional

Whether to drop non-unique items

Returns#

Reindexed object

update(other)[source]#

Merges other item with this object

Parameters#

other

Object containing items to merge into this object Must be a dictionary or NdMapping type

values()[source]#

Returns the values of all the elements.

class holoviews.core.ndmapping.NdMapping(initial_items=None, kdims=None, **params)[source]#

Bases: MultiDimensionalMapping

NdMapping supports the same indexing semantics as MultiDimensionalMapping but also supports slicing semantics.

Slicing semantics on an NdMapping is dependent on the ordering semantics of the keys. As MultiDimensionalMapping sort the keys, a slice on an NdMapping is effectively a way of filtering out the keys that are outside the slice range.

Parameter Definitions

Parameters inherited from:

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

A string describing the data wrapped by the object.

class holoviews.core.ndmapping.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.ndmapping.item_check(enabled)[source]#

Bases: object

Context manager to allow creating NdMapping types without performing the usual item_checks, providing significant speedups when there are a lot of items. Should only be used when both keys and values are guaranteed to be the right type, as is the case for many internal operations.

class holoviews.core.ndmapping.sorted_context(enabled)[source]#

Bases: object

Context manager to temporarily disable sorting on NdMapping types. Retains the current sort order, which can be useful as an optimization on NdMapping instances where sort=True but the items are already known to have been sorted.