Skip to content

Commit

Permalink
Updated annotator docs (#4173)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jbednar @philippjfr
jbednar authored and philippjfr committed Jan 9, 2020
1 parent 7017524 commit f3fda4f
Showing 1 changed file with 17 additions and 23 deletions.
40 changes: 17 additions & 23 deletions examples/user_guide/Annotators.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,20 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Plots generally convey information _to_ a viewer of the plot, but there are also circumstances where information needs to be collected _from_ the viewer:\n",
"HoloViews-generated plots generally convey information from Python _to_ a viewer of the plot, but there are also circumstances where information needs to be collected _from_ the viewer and made available for processing in Python:\n",
"\n",
"* annotating data with contextual information to aid later interpretation\n",
"* labeling or tagging data for automated machine-learning or other processing pipelines\n",
"* indicating regions of interest, outliers, or other semantic information\n",
"* specifying inputs to a query, command, or simulation\n",
"* testing sensitivity of analyses to adding, changing, or deleting user-selected data points\n",
"\n",
"In such cases, it is important to be able to augment, edit, and annotate datasets. To perform these actions, HoloViews provides an ``annotate`` helper using [Bokeh's drawing tools](https://docs.bokeh.org/en/latest/docs/reference/models/tools.html#bokeh.models.tools.PointDrawTool) to make it easy to edit HoloViews Elements and add additional information using an associated table. The `annotate` helper:\n",
"In such cases, it is important to be able to augment, edit, and annotate datasets and to access those values from Python. To perform these actions, HoloViews provides an ``annotate`` helper using [Bokeh's drawing tools](https://docs.bokeh.org/en/latest/docs/reference/models/tools.html#bokeh.models.tools.PointDrawTool) to make it easy to edit HoloViews Elements and add additional information using an associated table. The `annotate` helper:\n",
"\n",
"* Adds plot tools that allow editing and adding new elements to a plot \n",
"* Adds table(s) to allow editing the element in a tabular format\n",
"* Returns a layout of these two components\n",
"* Makes the edits, annotations, and selections available on a property of the annotate object"
"* Makes the edits, annotations, and selections available on a property of the annotate object so that they can be utilized in Python"
]
},
{
Expand Down Expand Up @@ -83,18 +83,18 @@
"source": [
"Here we have pre-populated the Element with three points. Each of the points has three bits of information that can be edited using the table: the x location, y location, and a \"Label\", which was initialized to dummy values when we called `annotate` and asked that there be a `Label` column. Try clicking on one of the rows and editing the location or the label to anything you like. As long as Python is running and the new location is in the viewport, you should see the dot move when you edit the location, and any labels you entered should be visible in the table.\n",
"\n",
"You can also edit the locations graphically using the [PointDraw tool](../reference/streams/PointDraw.ipynb) in the toolbar:<img src=\"https://bokeh.pydata.org/en/latest/_images/PointDraw.png\">\n",
"You can also edit the locations graphically using the [PointDraw tool](../reference/streams/bokeh/PointDraw.ipynb) in the toolbar:<img src=\"https://bokeh.pydata.org/en/latest/_images/PointDraw.png\">\n",
"\n",
"Once you select that tool, you should be able to click and drag any of the existing points and see the location update in the table. Whether you click on the table or the points, the same object should be selected in each, so that you can see how the graphical and tabular representations relate.\n",
"\n",
"The PointDraw tool allows us to add completely new points; once the tool is selected, just click on the plot above in locations not already containing a point and you can see a new point and a new table row appear ready for editing. You can also delete points by selecting them in the plot then pressing Backspace or Delete (depending on operating system)."
"The PointDraw tool also allows us to add completely new points; once the tool is selected, just click on the plot above in locations not already containing a point and you can see a new point and a new table row appear ready for editing. You can also delete points by selecting them in the plot then pressing Backspace or Delete (depending on operating system)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"All the above editing and interaction could have been done if we had simply called `hv.annotate(points, annotations=['Label'])` directly, but instead we first saved an \"instance\" of the object so that we'd also be able to access the resulting data. So, once we are done collecting data from the user, let's use the saved `annotator` object handle to read out the values (by re-evaluating the following line):"
"All the above editing and interaction could have been done if we had simply called `hv.annotate(points, annotations=['Label'])` directly, but instead we first saved an \"instance\" of the annotator object so that we'd also be able to access the resulting data. So, once we are done collecting data from the user, let's use the saved `annotator` object handle to read out the values (by re-evaluating the following line):"
]
},
{
Expand All @@ -110,7 +110,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"You should see that you can access the current set of user-provided points and their user-provided labels from within Python, ready for any subsequent processing you need to do. \n",
"You should see that you can access the current set of user-provided or user-modified points and their user-provided labels from within Python, ready for any subsequent processing you need to do. \n",
"\n",
"We can also access the currently `selected` points, in case we care only about a subset of the points (which will be empty if no points/rows are selected):"
]
Expand All @@ -128,13 +128,8 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Configuring the Annotator"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Configuring the Annotator\n",
"\n",
"In addition to managing the list of `annotations`, the `annotate` helper exposes a few additional parameters. Remember like most Param-based objects you can get help about `annotate` parameters using the `hv.help` function:"
]
},
Expand All @@ -153,7 +148,7 @@
"source": [
"### Annotation types\n",
"\n",
"You may have noticed that the default Label value above was \"NaN\", which is because the label type was defaulting to a numeric value but did not yet have any numeric values filled in. To specify the annotation-value types explicitly, we can supply a dictionary mapping from column name to the type:"
"The default annotation type is a string, to allow you to put in arbitrary information that you later process in Python. If you want to enforce a more specific type, you can specify the annotation-value types explicitly using a dictionary mapping from column name to the type:"
]
},
{
Expand Down Expand Up @@ -181,9 +176,7 @@
"* ``Polygons``\n",
"* ``Rectangles``\n",
"\n",
"Adding support for new elements, in most cases, requires adding corresponding drawing/edit tools to Bokeh itself. \n",
"\n",
"If you have data of other types, you may still be able to annotate it by casting it to one of the indicated types, collecting the data, then casting it back."
"Adding support for new elements, in most cases, requires adding corresponding drawing/edit tools to Bokeh itself. But if you have data of other types, you may still be able to annotate it by casting it to one of the indicated types, collecting the data, then casting it back."
]
},
{
Expand All @@ -192,7 +185,8 @@
"source": [
"## Annotating Curves\n",
"\n",
"The ``Curve`` annotator uses the PointDraw tool (<img src=\"https://bokeh.pydata.org/en/latest/_images/PointDraw.png\">) to allow dragging the vertices of the Curve. The vertices will appear when the tool is selected or a vertex is selected in the table. Unlike most other annotators the Curve annotator only allows editing the vertices and does not allow adding new ones."
"To allow dragging the vertices of the Curve, the ``Curve`` annotator uses the PointDraw tool in the toolbar: <img src=\"https://bokeh.pydata.org/en/latest/_images/PointDraw.png\">\n",
"The vertices will appear when the tool is selected or a vertex is selected in the table. Unlike most other annotators the Curve annotator only allows editing the vertices and does not allow adding new ones."
]
},
{
Expand Down Expand Up @@ -232,7 +226,7 @@
"\n",
"The `Rectangles` annotator behaves very similarly to the Points annotator. It allows adding any number of annotation columns, using Bokeh's `BoxEdit` tool that allows both drawing and moving boxes. To see how to use the BoxEdit tool, refer to the HoloViews [BoxEdit stream reference](../reference/streams/bokeh/BoxEdit.ipynb), but briefly:\n",
"\n",
"* Select the `BoxEdit` tool (<img src=\"https://bokeh.pydata.org/en/latest/_images/BoxEdit.png\">) in the toolbar\n",
"* Select the `BoxEdit` tool in the toolbar: <img src=\"https://bokeh.pydata.org/en/latest/_images/BoxEdit.png\">\n",
"* Click and drag on an existing Rectangle to move it\n",
"* Double click to start drawing a new Rectangle at one corner, and double click to complete the rectangle at the opposite corner\n",
"* Select a rectangle and press the Backspace or Delete key (depending on OS) to delete it\n",
Expand Down Expand Up @@ -278,13 +272,13 @@
"\n",
"##### Drawing/Selecting Deleting Paths/Polygons\n",
"\n",
"- Select the PolyDraw tool (<img src=\"https://bokeh.pydata.org/en/latest/_images/PolyDraw.png\">) in the toolbar\n",
"- Select the PolyDraw tool in the toolbar: <img src=\"https://bokeh.pydata.org/en/latest/_images/PolyDraw.png\">\n",
"- Double click to start a new object, single click to add each vertex, and double-click to complete it.\n",
"- Delete paths/polygons by selecting and pressing Delete key (OSX) or Backspace key (PC)\n",
"\n",
"##### Editing Paths/Polygons\n",
"\n",
"- Select the PolyEdit tool (<img src=\"https://bokeh.pydata.org/en/latest/_images/PolyEdit.png\">) in the toolbar.\n",
"- Select the PolyEdit tool in the toolbar: <img src=\"https://bokeh.pydata.org/en/latest/_images/PolyEdit.png\">\n",
"- Double click a Path/Polygon to start editing\n",
"- Drag vertices to edit them, delete vertices by selecting them\n",
"\n",
Expand Down Expand Up @@ -367,7 +361,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This object can be included directly in a Panel layout, be used to watch for parameter changes, or updated directly. To see the effect of updating directly, uncomment the line below, execute that cell, and then look at the previous plot of Africa, which should get updated with a large number of random blue dots."
"This object can be included directly in a Panel layout, be used to watch for parameter changes, or updated directly. To see the effect of updating directly, uncomment the line below, execute that cell, and then look at the previous plot of Africa, which should get updated with 10 randomly located blue dots."
]
},
{
Expand Down

0 comments on commit f3fda4f

Please sign in to comment.