diff --git a/examples/user_guide/03-Applying_Customizations.ipynb b/examples/user_guide/03-Applying_Customizations.ipynb index c955c7e86d..cbc1f3b5e7 100644 --- a/examples/user_guide/03-Applying_Customizations.ipynb +++ b/examples/user_guide/03-Applying_Customizations.ipynb @@ -724,8 +724,7 @@ "\n", "##### ``norm`` options:\n", "\n", - "``norm`` options are a special type of plot option that are applied orthogonally to the above two types, to control normalization. Normalization refers to adjusting the properties of one plot relative to those of another. For instance, two images normalized together would appear with relative brightness levels, with the brightest image using the full range black to white, while the other image is scaled proportionally. Two images normalized independently would both cover the full range from black to white. Similarly, two axis ranges normalized together will expand to fit the largest range of either axis, while those normalized separately would cover different ranges. For listing available options, see the output of ``hv.help``.\n", - "\n", + "``norm`` options are a special type of plot option that are applied orthogonally to the above two types, to control normalization. Normalization refers to adjusting the properties of one plot relative to those of another. For instance, two images normalized together would appear with relative brightness levels, with the brightest image using the full range black to white, while the other image is scaled proportionally. Two images normalized independently would both cover the full range from black to white. Similarly, two axis ranges normalized together are effectively linked and will expand to fit the largest range of either axis, while those normalized separately would cover different ranges. For listing available options, see the output of ``hv.help``.\n", "\n", "You can preserve the semantic distinction between these types of option in an augmented form of the [Literal syntax](#Literal-syntax) as follows:" ] diff --git a/examples/user_guide/05-Dimensioned_Containers.ipynb b/examples/user_guide/05-Dimensioned_Containers.ipynb index 661fc8c5f3..7514e92d70 100644 --- a/examples/user_guide/05-Dimensioned_Containers.ipynb +++ b/examples/user_guide/05-Dimensioned_Containers.ipynb @@ -22,8 +22,11 @@ "source": [ "import numpy as np\n", "import holoviews as hv\n", + "\n", "from holoviews import opts\n", - "hv.notebook_extension('bokeh')\n", + "\n", + "hv.extension('bokeh')\n", + "\n", "opts.defaults(opts.Curve(line_width=1))" ] }, @@ -247,7 +250,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Since this simply represents a multi-dimensional parameter space we can collapse this datastructure into a single table containing columns for each of the dimensions we have declared:" + "Since this simply represents a multi-dimensional parameter space we can collapse this datastructure into a single `Dataset` containing columns for each of the dimensions we have declared:" ] }, { @@ -256,10 +259,17 @@ "metadata": {}, "outputs": [], "source": [ - "ds = hv.Dataset(grid.table())\n", + "ds = grid.collapse()\n", "ds.data.head()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A ``Dataset`` is an element type which does not itself have a visual representation and may contain any type of data supported by HoloViews interfaces." + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -330,6 +340,15 @@ "source": [ "As you can see the 'New dimension' was added at position zero." ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Onwards\n", + "\n", + "As we have seen Dimensioned containers make it easy to explore multi-dimensional datasets by mapping the dimensions onto visual layers (`NdOverlay`), 2D grid axes (`GridSpace`), widgets (`HoloMap`) or an arbitrary layout (`NdLayout`). In the [next section](06-Dimensioned_Containers.ipynb) we will discover how to construct composite objects of heterogeneous data." + ] } ], "metadata": { diff --git a/examples/user_guide/06-Building_Composite_Objects.ipynb b/examples/user_guide/06-Building_Composite_Objects.ipynb index 794683fe4b..da341b0d98 100644 --- a/examples/user_guide/06-Building_Composite_Objects.ipynb +++ b/examples/user_guide/06-Building_Composite_Objects.ipynb @@ -86,22 +86,6 @@ "layout" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The structure of this object can be seen using ``print()``:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "print(layout)" - ] - }, { "cell_type": "markdown", "metadata": {}, @@ -302,7 +286,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "At this point, we have reached the end of the HoloViews objects; below this object is only the raw data as a Numpy array:" + "At this point, we have reached the end of the HoloViews objects; below this object is only the raw data stored in one of the supported formats (e.g. NumPy arrays or Pandas DataFrames):" ] }, { @@ -398,8 +382,7 @@ "metadata": {}, "outputs": [], "source": [ - "layout.Parameters.Sines.select(Amplitude=0.5,Power=1.0, \n", - " Frequency=1.0).Phases.Sines.select(Phase=0.0)" + "layout.Parameters.Sines.select(Amplitude=0.5,Power=1.0, Frequency=1.0, Phase=0.0).Phases.Sines" ] }, { @@ -415,9 +398,9 @@ "source": [ "As you can see, HoloViews lets you compose objects of heterogenous types, and objects covering many different numerical or other dimensions, laying them out spatially, temporally, or overlaid. The resulting data structures are complex, but they are composed of simple elements with well-defined interactions, making it feasible to express nearly any relationship that will characterize your data. In practice, you will probably not need this many levels, but given this complete example, you should be able to construct an appropriate hierarchy for whatever type of data that you want to represent or visualize. \n", "\n", - "As emphasized above, it is not possible to combine these objects in other orderings. Of course, any ``Element`` can be substituted for any other, which doesn't change the structure. But you cannot e.g. display an ``Overlay`` or ``HoloMap`` of ``Layout`` objects. Confusingly, the objects may *act* as if you have these arrangements. For instance, a ``Layout`` of ``HoloMap`` objects will be animated, like ``HoloMap`` objects, but only because of the extra dimension(s) provided by the enclosed ``HoloMap`` objects, not because the ``Layout`` itself has data along those dimensions. Similarly, you cannot have a ``Layout`` of ``Layout`` objects, even though it looks like you can. E.g. the ``+`` operator on two ``Layout`` objects will not create a ``Layout`` of ``Layout`` objects; it just creates a new ``Layout`` object containing the data from both of the other objects. Similarly for the ``Overlay`` of ``Overlay`` objects using ``*``; only a single combined ``Overlay`` is returned.\n", + "As emphasized above, it is not recommended to combine these objects in other orderings. Of course, any ``Element`` can be substituted for any other, which doesn't change the structure. But you should not e.g. display an ``Overlay`` of ``Layout`` objects. The display system will generally attempt to figure out the correct arrangement and warn you to call the `.collate` method to reorganize the objects in the recommended format.\n", "\n", - "If you are confused about how all of this works in practice, you can use the examples in the [Dimensioned Containers](./05-Dimensioned_Containers.ipynb) user guide." + "Another important thing to observe is that ``Layout`` and ``Overlay`` types may not be nested, e.g. using the ``+`` operator on two `Layout` objects will not create a nested `Layout` instead combining the contents of the two objects. The same applies to the ``*`` operator and combining of `Overlay` objects. " ] } ], diff --git a/holoviews/core/ndmapping.py b/holoviews/core/ndmapping.py index 3c7831574d..094eb53667 100644 --- a/holoviews/core/ndmapping.py +++ b/holoviews/core/ndmapping.py @@ -853,6 +853,54 @@ def clone(self, data=None, shared_data=True, new_type=None, link=True, if k not in pos_args}) + def collapse(self, dimensions=None, function=None, spreadfn=None, **kwargs): + """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. + + Args: + 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 + """ + from .data import concat + if not dimensions: + dimensions = self.kdims + if not isinstance(dimensions, list): dimensions = [dimensions] + if self.ndims > 1 and len(dimensions) != self.ndims: + groups = self.groupby([dim for dim in self.kdims + if dim not in dimensions]) + + elif all(d in self.kdims for d in dimensions): + groups = UniformNdMapping([(0, self)], ['tmp']) + else: + raise KeyError("Supplied dimensions not found.") + + collapsed = groups.clone(shared_data=False) + for key, group in groups.items(): + if hasattr(group.values()[-1], 'interface'): + group_data = concat(group) + if function: + agg = group_data.aggregate(group.last.kdims, function, spreadfn, **kwargs) + group_data = group.type(agg) + else: + group_data = [el.data for el in group] + args = (group_data, function, group.last.kdims) + data = group.type.collapse_data(*args, **kwargs) + group_data = group.last.clone(data) + collapsed[key] = group_data + return collapsed if self.ndims-len(dimensions) else collapsed.last + + def dframe(self, dimensions=None, multi_index=False): """Convert dimension values to DataFrame. diff --git a/holoviews/core/spaces.py b/holoviews/core/spaces.py index 93dd8521b1..2e08b18f36 100644 --- a/holoviews/core/spaces.py +++ b/holoviews/core/spaces.py @@ -349,53 +349,6 @@ def collate(self, merge_type=None, drop=[], drop_constant=False): drop_constant=drop_constant)() - def collapse(self, dimensions=None, function=None, spreadfn=None, **kwargs): - """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. - - Args: - 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 - """ - from .data import concat - if not dimensions: - dimensions = self.kdims - if not isinstance(dimensions, list): dimensions = [dimensions] - if self.ndims > 1 and len(dimensions) != self.ndims: - groups = self.groupby([dim for dim in self.kdims - if dim not in dimensions]) - elif all(d in self.kdims for d in dimensions): - groups = HoloMap([(0, self)]) - else: - raise KeyError("Supplied dimensions not found.") - - collapsed = groups.clone(shared_data=False) - for key, group in groups.items(): - if hasattr(group.last, 'interface'): - group_data = concat(group) - if function: - agg = group_data.aggregate(group.last.kdims, function, spreadfn, **kwargs) - group_data = group.type(agg) - else: - group_data = [el.data for el in group] - args = (group_data, function, group.last.kdims) - data = group.type.collapse_data(*args, **kwargs) - group_data = group.last.clone(data) - collapsed[key] = group_data - return collapsed if self.ndims-len(dimensions) else collapsed.last - - def sample(self, samples=[], bounds=None, **sample_values): """Samples element values at supplied coordinates. @@ -931,11 +884,6 @@ def __init__(self, callback, initial_items=None, streams=None, **params): elif not isinstance(callback, Callable): callback = Callable(callback) - if 'sampled' in params: - self.param.warning('DynamicMap sampled parameter is deprecated ' - 'and no longer needs to be specified.') - del params['sampled'] - valid, invalid = Stream._process_streams(streams) if invalid: msg = ('The supplied streams list contains objects that '