diff --git a/examples/user_guide/01-Annotating_Data.ipynb b/examples/user_guide/01-Annotating_Data.ipynb index 6c6b631258..2ed23d5d48 100644 --- a/examples/user_guide/01-Annotating_Data.ipynb +++ b/examples/user_guide/01-Annotating_Data.ipynb @@ -22,7 +22,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "One of the fundamental concepts in HoloViews introduced in the 'Getting Started' guide [Introduction](../getting_started/1-Introduction.ipynb) is that of annotating data with key, semantic metadata. This user guide documents the two main types annotation (1) dimensions used to specify the abstract space in which the data resides (2) the element group/label system used to organize and select data." + "One of the fundamental concepts in HoloViews introduced in the [Getting Started guide](../getting_started/1-Introduction.ipynb) is that of annotating data with key, semantic metadata. This user guide documents the two main types of annotation:\n", + " 1. dimensions, used to specify the abstract space in which the data resides;\n", + " 2. the element group/label system, used to organize and select data." ] }, { @@ -31,7 +33,7 @@ "source": [ "## Specifying dimensionality\n", "\n", - "Simple datastructure such as dataframes, arrays, lists or dictionaries cannot be given a suitable visual representation without some associated semantic context. Fundamentally, HoloViews lets you specify this context by first selecting a suitable element type from the [gallery] and by then specifying the corresponding *dimensions*.\n", + "Simple data structures such as dataframes, arrays, lists, or dictionaries cannot be given a suitable visual representation without some associated semantic context. Fundamentally, HoloViews lets you specify this context by first selecting a suitable element type (see the [Reference Gallery](TODO)), and then specifying the corresponding *dimensions*.\n", "\n", "Here is a very simple example, showing a ``Curve`` element:" ] @@ -52,9 +54,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "All elements (except a small number of annotation elements) have two types of dimensions: *key dimensions* (``kdims``) and *value dimensions* (``vdims``). The *key dimensions* are the dimensions you can index *by* to get the values corresponding to the *value* dimensions. You can learn more about indexing data in the [Indexing and Selecting Data](./09-Indexing_and_Selecting_Data.ipynb) user guide.\n", + "All elements (except a small number of annotation elements) have two types of dimensions: *key dimensions* (``kdims``) and *value dimensions* (``vdims``). The *key dimensions* are the dimensions you can index *by* to get the values corresponding to the *value* dimensions. You can learn more about indexing data in the later [Indexing and Selecting Data](./09-Indexing_and_Selecting_Data.ipynb) user guide.\n", "\n", - "Different elements have different numbers of required key dimensions and value dimensions. For instance, a ``Curve`` always has one key dimension and a value dimension. As we did not explicitly specify anything regarding dimensions when declaring the curve above, the ``kdims`` and ``vidms`` use their default names 'x' and 'y':" + "Different elements have different numbers of required key dimensions and value dimensions. For instance, a ``Curve`` always has one key dimension and one value dimension. As we did not explicitly specify anything regarding dimensions when declaring the curve above, the ``kdims`` and ``vidms`` use their default names 'x' and 'y':" ] }, { @@ -96,7 +98,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can see our strings have been 'promoted' to dimension objects describing the space in which our trajectory data resides: the ``kdims`` and ``vdims`` *always* contain instances of the ``Dimension`` class which will be described in a later section. Note that naming our dimensions has given the corresponding visual representation appropriate axis labels." + "We can see our strings have been 'promoted' to dimension objects describing the space in which our trajectory data resides: the ``kdims`` and ``vdims`` *always* contain instances of the ``Dimension`` class, described in the following section. Note that naming our dimensions has given the corresponding visual representation appropriate axis labels." ] }, { @@ -105,12 +107,12 @@ "source": [ "### Dimension parameters\n", "\n", - "``Dimension`` objects have a number of parameters used to describe the space in which the data resides. Only two of these are considered *core* parameters that identify the identity of the dimension object, the rest consist of auxilliary metadata. Here are the descriptions of the most important ones:\n", + "``Dimension`` objects have a number of parameters used to describe the space in which the data resides. Only two of these are considered *core* parameters that identify the dimension object; the rest are auxilliary metadata. Here are the descriptions of the most important ones:\n", "\n", "\n", "
\n", "
\n", - "
``name``
(core) A concise name for the dimension that should be useable as a Python keyword
\n", + "
``name``
(core) A concise name for the dimension that should be useable as a keyword argument
\n", "
``label``
(core) A longer description of the dimension (can contain unicode)
\n", "
``range``
The minumum and maximum allowable values for the dimension.
\n", "
``soft_range``
Suggested minumum and maximum values, used to specify a useful portion of the range.
\n", @@ -122,7 +124,7 @@ "\n", "For the full list of parameters, you can call ``hv.help(hv.Dimension)``.\n", "\n", - "Note that you can also use a ``(name, label)`` tuple instead of just a string name if you want to specify both ``name`` and ``label`` without building an explicit ``Dimension`` object which can also be used in the ``kdims`` and ``vdims``:" + "Instead of just a string name, you can use a ``(name, label)`` tuple if you want to specify both ``name`` and ``label`` without building an explicit ``Dimension`` for ``kdims`` and ``vdims``:" ] }, { @@ -131,14 +133,15 @@ "metadata": {}, "outputs": [], "source": [ - "distance = hv.Dimension('distance', label='Horizontal distance', unit='m')\n", - "height = hv.Dimension(('height','Height above sea-level'), unit='m')\n", - "\n", "wo_unit = hv.Curve((xs, ys), \n", " kdims=[('distance','Horizontal distance')], \n", " vdims=[('height','Height above sea-level')])\n", + "\n", + "distance = hv.Dimension('distance', label='Horizontal distance', unit='m')\n", + "height = hv.Dimension(('height','Height above sea-level'), unit='m')\n", "with_unit = hv.Curve((xs, ys), kdims=[distance], vdims=[height])\n", "\n", + "# (using + to compose elements is described in the next guide)\n", "wo_unit + with_unit" ] }, @@ -146,7 +149,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Note that we after supplying the longer labels, you still use the short name to specify the dimension as keyword arguments. For instance,try using ``with_unit.select(distance=(5,8))`` in the cell above." + "Note that after supplying the longer labels, you still use the short name to specify the dimension as keyword arguments. For instance,try using ``with_unit.select(distance=(5,8))`` in the cell above." ] }, { @@ -160,7 +163,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Declaring dimension objects with appropriate parameters can be verbose if you only want a set a few specific parameters. You can often avoid declaring explicit dimension objects using the ``redim`` method which returns a *clone* of the element: the same data, wrapped in a new instance of the same element type with the new dimension settings.\n", + "Declaring dimension objects with appropriate parameters can be verbose if you only want to set a few specific parameters. You can often avoid declaring explicit dimension objects using the ``redim`` method, which returns a *clone* of the element: the same data, wrapped in a new instance of the same element type with the new dimension settings.\n", "\n", "Let's use ``redim`` to swap out the 'height' dimension for the 'altitude' dimension:" ] @@ -195,7 +198,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "This pattern can be used to set any of the parameters listed above (unit, range, values etc) by specifying the dimension name and the new value for the parameter." + "This pattern can be used to set any of the parameters listed above (unit, range, values, etc) by specifying the dimension name and the new value for the parameter." ] }, { @@ -214,16 +217,17 @@ "outputs": [], "source": [ "low_ys = [25-(0.5*el)**2 for el in xs]\n", - "hv.Curve((xs, low_ys), group='Trajectory', label='Shallow')" + "hv.Curve((xs, low_ys), group='Trajectory', label='Shallow') + \\\n", + "hv.Curve((xs, ys), group='Trajectory', label='Medium')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "As shown above, ``group`` and ``label`` have been used generate a sensible title. The ``group`` is expected to specify what the element corresponds to as the level of its type whereas the ``label`` is used to specify a particular element in a group.\n", + "As shown above, ``group`` and ``label`` have been used generate sensible titles. The ``group`` is expected to specify what the element corresponds to at the level of its type, while the ``label`` is used to specify a particular element in a group.\n", "\n", - "The ``group`` and ``label`` system is used for indexing as we will see in the following [Composing_Elements](./02-Composing_Elements.ipynb) guide as well as for [Customizing Plots](./03-Customizing_Plots.ipynb)." + "The ``group`` and ``label`` system also allows [Customizing Plots](./03-Customizing_Plots.ipynb), and it is used for indexing, as we will see in the following [Composing_Elements](./02-Composing_Elements.ipynb) guide." ] } ], diff --git a/examples/user_guide/02-Composing_Elements.ipynb b/examples/user_guide/02-Composing_Elements.ipynb index 6a109a7b32..bbe55135e6 100644 --- a/examples/user_guide/02-Composing_Elements.ipynb +++ b/examples/user_guide/02-Composing_Elements.ipynb @@ -22,14 +22,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "HoloViews supports two primary composition operators that apply to (nearly) all visual HoloViews objects in order to create heterogeous collections: ``+`` to generate [``Layout``](../reference/containers/bokeh/Layout.ipynb) objects and ``*`` to create [``Overlay``](../reference/containers/bokeh/Overlay.ipynb) objects.\n", + "HoloViews supports two primary composition operators that apply to nearly all visual HoloViews objects and create heterogeous collections: ``+`` to generate [``Layout``](../reference/containers/bokeh/Layout.ipynb) objects and ``*`` to create [``Overlay``](../reference/containers/bokeh/Overlay.ipynb) objects.\n", "\n", "* **Layout:** A collection of HoloViews objects to be grouped and displayed side-by-side \n", - "* **Overlay:** A collection of HoloViews objects to be displayed simultanously, overlaid in the same space.\n", + "* **Overlay:** A collection of HoloViews objects to be displayed simultaneously, overlaid in the same space.\n", "\n", - "These containers are unliked the *dimensioned* containers where you cannot mix types and each item has an associated keys. Examples of dimension containers include [``HoloMap``](../reference/containers/bokeh/HoloMap.ipynb) , [``GridSpace``](../reference/containers/bokeh/GridSpace.ipynb) and [``NdLayout``](../reference/containers/bokeh/NdLayout.ipynb).\n", + "The Layout and Overlay containers allow you to mix types, and a contained item is not associated with a key. In contrast, [Dimensioned containers](./04-Dimensioned_Containers.ipynb) such as [``HoloMap``](../reference/containers/bokeh/HoloMap.ipynb) , [``GridSpace``](../reference/containers/bokeh/GridSpace.ipynb) and [``NdLayout``](../reference/containers/bokeh/NdLayout.ipynb), do not allow mixed types, and each item has an associated key.\n", "\n", - "As you can compose an mix of HoloViews elements into layouts and overlays, these types of container are very common which is why they have dedicated operators. This user guide describes how you can build and organize your data using these two types of composition.\n", + "As you can compose a mix of HoloViews elements into layouts and overlays, these types of container are very common, which is why they have dedicated composition operators. This user guide describes how you can build and organize your data using these two types of composition.\n", "\n", "To show how layouts and overlays work with heterogeneous types, we will use these two elements throughout this notebook:" ] @@ -56,9 +56,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "A ``Layout`` cannot contain ``NdLayouts`` but can otherwise contain *any* other HoloViews object; see [Building Composite Objects](05-Building_Composite_Objects.ipynb) for more details on how to compose containers. \n", + "A ``Layout`` can contain any HoloViews object except ``NdLayout``. [Building Composite Objects](05-Building_Composite_Objects.ipynb) contains more details on how to compose containers.\n", "\n", - "You can build a ``Layout`` between any two HoloViews objects (which can have different types) using the ``+`` operator:" + "You can build a ``Layout`` from two HoloViews objects (which can have different types) using the ``+`` operator:" ] }, { @@ -74,7 +74,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this example, we have a ``Layout`` composed of a ``Curve`` element and a ``Scatter`` element. The one restriction on what you can put in a ``Layout`` is that you cannot combine an [``NdLayout``](./NdLayout.ipynb) with a regular ``Layout``." + "In this example, we have a ``Layout`` composed of a ``Curve`` element and a ``Scatter`` element. " ] }, { @@ -88,7 +88,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "You can build Layout's of any size by passing a list of objects to the ``Layout`` constructor as shown below:" + "You can build Layouts of any size by passing a list of objects to the ``Layout`` constructor:" ] }, { @@ -121,9 +121,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "``Layout`` and ``Overlay`` are fundamentally tree-structures holding arbitrary heterogenous HoloViews objects and are quite different from the dictionary-like dimensioned containers.\n", + "``Layout`` and ``Overlay`` are fundamentally tree structures holding arbitrary heterogenous HoloViews objects, and are quite different from the dictionary-like dimensioned containers (which will be described in a later guide).\n", "\n", - "As mentioned in [Annotating Data](01-Annotating_Data.ipynb), HoloViews objects have string ``group`` and ``label`` parameters, which allows a two-level attribute access on ``Layout`` objects. First let us see how to index the the above example where the ``group`` and ``label`` parameters were left unspecified:" + "As mentioned previously in [Annotating Data](01-Annotating_Data.ipynb), HoloViews objects have string ``group`` and ``label`` parameters, which allows a two-level attribute access on ``Layout`` objects. First let us see how to index the the above example where the ``group`` and ``label`` parameters were left unspecified:" ] }, { @@ -132,16 +132,26 @@ "metadata": {}, "outputs": [], "source": [ - "layout.Curve.I + layout.Scatter.II" + "layout2 = layout.Curve.I + layout.Scatter.II\n", + "layout2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Here we create a second layout by indexing two elements from our earlier ``layout`` object and using ``+`` between them. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a roman numeral (I,II,III etc).\n", + "Here we create a second layout by indexing two elements from our earlier ``layout`` object and using ``+`` between them. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a roman numeral (I,II,III, etc). \n", "\n", - "As no group and label was specified, our new ``layout`` will once again have ``Curve.I`` for the curve but as there is only one scatter element, it will have ``Scatter.II`` to index the scatter." + "As group and label were not specified, our new ``Layout`` will once again have ``Curve.I`` for the curve, but as there is only one scatter element, it will have ``Scatter.I`` to index the scatter:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "layout2.Scatter.I" ] }, { @@ -155,7 +165,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now let's return to the first simple layout example, although this time we will set a group and label; see the [Annotating Data](../../../user_guide/01-Annotating_Data.ipynb) for more information:" + "Now let's return to the first simple layout example, this time setting a group and label as introduced in the [Annotating Data](../../../user_guide/01-Annotating_Data.ipynb) guide:" ] }, { @@ -175,8 +185,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can now see how group and label affect access, in addition to being used for setting the titles shown above and for allowing plot customization (see \n", - "[Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information):" + "We can now see how group and label affect access in addition to being used for setting the titles:" ] }, { @@ -192,7 +201,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We have used the semantic group and label names to access the elements and build a new re-ordered layout." + "We have used the semantic group and label names to access the elements and build a new re-ordered layout.\n", + "\n", + "Group and label also allow plot customization; see \n", + "[Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information." ] }, { @@ -206,9 +218,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "A ``Overlay`` cannot contain any other container type other than ``NdOverlay`` but can contain any HoloViews elements; see [Building Composite Objects](05-Building_Composite_Objects.ipynb) for more details on how to compose containers.\n", + "An ``Overlay`` can contain any HoloViews elements, but the only container type it can contain is ``NdOverlay``. [Building Composite Objects](05-Building_Composite_Objects.ipynb) provides more detail on how to compose containers.\n", "\n", - "Other than being composed with ``*`` and displaying elements together in the same space, ``Overlay`` shared many of the same concepts as layout. The rest of this section will show the overlay equivalents of the manipulations shown above for layout. First composition with ``*`` instead of ``+``:" + "Other than being composed with ``*`` and displaying elements together in the same space, ``Overlay`` shares many of the same concepts as layout. The rest of this section will show the overlay equivalents of the manipulations shown above for layout. \n", + "\n", + "First, composition with ``*`` instead of ``+``:" ] }, { @@ -231,7 +245,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "As ``Overlay`` can be built explicitly from a list, just like a ``Layout``:" + "An ``Overlay`` can be built explicitly from a list, just like a ``Layout``:" ] }, { @@ -250,21 +264,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Note that one concept that applied to ``Overlay`` but not ``Layouts`` is that of *color cycles* which you can learn about in [Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb)." + "Note: one concept that applies to ``Overlay`` but not ``Layout`` is that of *color cycles*, which you can learn about in [Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### A ``Overlay`` has two-level attribute access" + "### ``Overlay`` has two-level attribute access" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Like ``Layout``, ``Overlay`` is fundamentally a tree-structures that holds arbitrary heterogenous HoloViews, unlike the dimensioned containers. ``Overlay`` obejcts also make use of the ``group`` and ``label`` parameters, introduced in [Annotating Data](01-Annotating_Data.ipynb) for two-level attribute access.\n", + "Like ``Layout``, ``Overlay`` is fundamentally a tree structure holding arbitrary heterogenous HoloViews objects, unlike the dimensioned containers. ``Overlay`` objects also make use of the ``group`` and ``label`` parameters, introduced in [Annotating Data](01-Annotating_Data.ipynb), for two-level attribute access.\n", "\n", "Once again, let us see how to index the above example where the ``group`` and ``label`` parameters were left unspecified:" ] @@ -282,24 +296,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", - "Here we create a second overlay by indexing two elements from our earlier ``overlay`` object and using ``*`` between them. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a roman numeral (I,II,III etc).\n", - "\n", - "As no group and label was specified, our new ``Overlay`` will once again have ``Curve.I`` for the curve but as there is only one scatter element, it will have ``Scatter.II`` to index the scatter." + "Here we create a second overlay by indexing two elements from our earlier ``overlay`` object and using ``*`` between them. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a roman numeral (I,II,III etc)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Using ``group`` and ``label`` with ``Overlay`" + "### Using ``group`` and ``label`` with ``Overlay``" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Now let's return to the first simple overlay example, although this time we will set a ``group`` and ``label``; see the [Annotating Data](../../../user_guide/01-Annotating_Data.ipynb) for more information:" + "Now let's return to the first simple overlay example, this time setting ``group`` and ``label`` as introduced in the [Annotating Data](../../../user_guide/01-Annotating_Data.ipynb) guide:" ] }, { @@ -309,7 +320,7 @@ "outputs": [], "source": [ "high_freq = hv.Curve((xvals, [np.sin(2*x) for x in xvals]), group='Sinusoid', label='High Frequency')\n", - "labelled = low_freq * high_freq * scatter\n", + "labelled = low_freq * high_freq * linpoints\n", "labelled" ] }, @@ -317,10 +328,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Once again, this examples follows the corresponding ``Layout`` example although this time we added a high-frequency curve to demonstrate how the ``group`` and ``label`` is now used to generate the legend (as opposed to the title as it was for ``Layout``.\n", + "Once again, this example follows the corresponding ``Layout`` example, although this time we added a high-frequency curve to demonstrate how ``group`` and ``label`` are now used to generate the legend (as opposed to the title, as it was for ``Layout``).\n", "\n", - "The following example shows how ``group`` and ``label`` affect access, in addition to being used for setting the titles shown above and for allowing plot customization (see \n", - "[Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information):" + "The following example shows how ``group`` and ``label`` affect access:" ] }, { @@ -339,6 +349,14 @@ "This new re-ordered ``Overlay`` switches the z-ordering as well as the legend color of the two sinusoidal curves." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Group and label also allow plot customization; see \n", + "[Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information." + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -360,6 +378,13 @@ "\n", "In a code cell and you should see the first levels of indexing (``Curve`` and ``Scatter``) conveniently listed at the top. If this is not the case, you may need to enable improved tab-completion as described in [Configuring HoloViews](../../../user_guide/Configuring_HoloViews.ipynb)." ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Having seen how to compose elements, the next section shows how to [customize your plots](../../../user_guide/03-Customizing_Plots.ipynb)." + ] } ], "metadata": {