Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

User guide 01 and 02 fixups #1690

Merged
merged 6 commits into from Jul 7, 2017
Merged

User guide 01 and 02 fixups #1690

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fda945b
First pass through 01 and 02; work in progress.
ceball Jul 6, 2017
f26e4ad
Minor fixups.
ceball Jul 6, 2017
2779d31
Remove extraneous metadata changes.
ceball Jul 6, 2017
1e146f8
More minor fixes.
ceball Jul 6, 2017
d3299be
More minor fixups.
ceball Jul 6, 2017
9fd177b
Fixed mistaken description of Dimension name.
ceball Jul 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 21 additions & 17 deletions examples/user_guide/01-Annotating_Data.ipynb
View file
Open in desktop
Expand Up @@ -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."
]
},
{
Expand All @@ -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:"
]
Expand All @@ -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':"
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -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",
"<br>\n",
"<dl class=\"dl-horizontal\">\n",
" <dt>``name``</dt><dd>(core) A concise name for the dimension that should be useable as a Python keyword</dd>\n",
" <dt>``name``</dt><dd>(core) A concise name for the dimension that should be useable as a keyword argument</dd>\n",
" <dt>``label`` <dd>(core) A longer description of the dimension (can contain unicode)</dd>\n",
" <dt>``range`` <dd>The minumum and maximum allowable values for the dimension.</dd>\n",
" <dt>``soft_range`` <dd>Suggested minumum and maximum values, used to specify a useful portion of the range.</dd>\n",
Expand All @@ -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``:"
]
},
{
Expand All @@ -131,22 +133,23 @@
"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"
]
},
{
"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."
]
},
{
Expand All @@ -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:"
]
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -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."
]
}
],
Expand Down