Implementation of new Annotator API

examples/Basics.ipynb

@@ -16,16 +16,6 @@
     "from holonote.annotate import Annotator"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "042914f0-cb8d-427d-b1e1-3a2056bc392e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "hv.opts.defaults(hv.opts.Rectangles(apply_ranges=False))"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "2c4a4b17-173b-43c2-ab20-251c459029fe",
@@ -97,7 +87,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.overlay()  # If you have a database file generated by a previous commit, your annotations will now be displayed"
+    "annotator * speed_curve  # If you have a database file generated by a previous commit, your annotations will now be displayed"
    ]
   },
   {
@@ -151,7 +141,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.set_range(np.datetime64('2022-06-06'), np.datetime64('2022-06-08'))\n",
+    "annotator.set_regions(TIME=(np.datetime64('2022-06-06'), np.datetime64('2022-06-08')))\n",
     "annotator.add_annotation(description='A programmatically defined annotation')"
    ]
   },
@@ -291,7 +281,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.set_range(np.datetime64('2022-06-15'), np.datetime64('2022-06-18'))\n",
+    "annotator.set_regions(TIME=(np.datetime64('2022-06-15'), np.datetime64('2022-06-18')))\n",
     "annotator.add_annotation(description='An annotation description we will update...')"
    ]
   },
@@ -359,7 +349,7 @@
    "source": [
     "input_uuid = 'deadcafe'\n",
     "description = f'Annotation with set UUID {input_uuid!r}'\n",
-    "annotator.set_range(np.datetime64('2022-06-10'), np.datetime64('2022-06-13'))\n",
+    "annotator.set_regions(TIME=(np.datetime64('2022-06-10'), np.datetime64('2022-06-13')))\n",
     "annotator.add_annotation(description=description, uuid=input_uuid)\n",
     "description"
    ]
@@ -422,9 +412,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "starts = [np.datetime64('2022-06-%.2d' % d) for d in  range(6,15, 4)]\n",
-    "ends = [np.datetime64('2022-06-%.2d' % (d+2)) for d in  range(6,15, 4)]\n",
-    "descriptions = ['Annotation %d' % d for d in range(3)]\n",
+    "starts = pd.date_range(\"2022-06-06\", freq=\"3D\", periods=3)\n",
+    "ends = starts + pd.Timedelta(\"2D\")\n",
+    "descriptions = [\"Annotation 0\", \"Annotation 1\", \"Annotation 2\"]\n",
     "data = pd.DataFrame({'start':starts, 'end':ends, 'description':descriptions})\n",
     "data"
    ]
@@ -434,7 +424,7 @@
    "id": "fc931d2b-285a-4fa3-944d-f17c39196344",
    "metadata": {},
    "source": [
-    "To load this data, we *first* need to define the data in the annotation fields (for this annotator this is the `description` field):"
+    "To load this data, we use `define_annotations` and pass in the columns from the DataFrame. "
    ]
   },
   {
@@ -444,40 +434,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.define_fields(data[['description']])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "c2683667-6abb-4b97-955f-9192f78ce3f2",
-   "metadata": {},
-   "source": [
-    "Now we can define the starts and ends of our annotation regions as follows:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "3ba550f2-3695-4999-b66d-ce70e087f09d",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "annotator.define_ranges(data['start'], data['end'])"
+    "annotator.define_annotations(data, TIME=(\"start\", \"end\"), description=\"description\")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "9710c385-7ff6-43f7-ac41-aee2aa990670",
    "metadata": {},
    "source": [
-    "The `DataFrame`/`Series` index (here the default pandas index) is what links our ranges to their corresponding field entries.\n",
-    "\n",
-    "Note the following rules:\n",
-    "\n",
-    "1. The index values supplied to the `define_` region methods must first be defined by `define_fields`.\n",
-    "2. Before we can call the `.commit` method, every index supplied to `define_fields` must have been given at least one region.\n",
-    "\n",
-    "As with `add_annotation`, the annotator automatically create uuid primary key values and the original index is ignored:"
+    "If a column name matches with a name of region or a field it will be used this means the `description=\"description` in the above line is not needed. "
    ]
   },
   {
@@ -495,8 +460,6 @@
    "id": "245eff10-f59e-4b00-b933-68aafdd38499",
    "metadata": {},
    "source": [
-    "This can be overridden by supplying `preserve_index=True` to the `define_fields` method as now described.\n",
-    "\n",
     "### Preserving the index"
    ]
   },
@@ -505,7 +468,7 @@
    "id": "fda1a724-11e9-40e4-ae72-d2922c240fd0",
    "metadata": {},
    "source": [
-    "Sometimes the annotations you are loading have meaningful primary keys defined elsewhere (e.g. some other pre-existing database) that need to be preserved. This is possible by supplying `preserve_index=True` to the `define_fields` method.\n",
+    "Sometimes the annotations you are loading have meaningful primary keys defined elsewhere (e.g. some other pre-existing database) that need to be preserved. This is possible by supplying `index=True` in the `define_annotations` method.\n",
     "\n",
     "*Note: The user bears the same responsibilities for using appropriate index values as described in the  ***Caveats when picking your own primary keys*** section!*\n"
    ]
@@ -530,7 +493,7 @@
    "id": "4053d426-770d-4309-b8c4-582b76f11d3e",
    "metadata": {},
    "source": [
-    "To preserve the index call, the `define_fields` must be called with `preserve_index=True`:"
+    "To preserve the index call, the `define_annotations` must be called with `index=True`:"
    ]
   },
   {
@@ -540,25 +503,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.define_fields(indexed_data[['description']], preserve_index=True)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "1ee25eee-df47-440d-b5bc-cc7bfade3f9f",
-   "metadata": {},
-   "source": [
-    "Now we can call `define_ranges` as before:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "b555fff9-9e8b-48ed-878c-b39a49714a97",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "annotator.define_ranges(indexed_data['start'], indexed_data['end'])"
+    "annotator.define_annotations(indexed_data, TIME=(\"start\", \"end\"), description=\"description\", index=True)"
    ]
   },
   {
@@ -586,7 +531,7 @@
    "id": "57962a14-32be-4239-9ad3-f9eee5d18158",
    "metadata": {},
    "source": [
-    "## Selecting and highlighting annotations\n",
+    "## 🚧 Selecting and highlighting annotations\n",
     "\n",
     "Earlier we styled the indicators with `color='red', alpha=0.2`. To highlight a select a specific indicator, we can create a dimension expression to assign selected and non-selected indicators different values. Here we have a highlighter that uses a value of `0.6` for selected indicators and `0.1` for non-selected indicators. We can then apply these values to the `alpha` option:"
    ]
@@ -687,7 +632,7 @@
    "id": "16134a64-1347-4ebe-909a-716f55c520ac",
    "metadata": {},
    "source": [
-    "## Using `.overlay`\n",
+    "## 🚧 Using `.overlay`\n",
     "\n",
     "The `.overlay` method is a shortcut to building the following overlay:\n",
     "\n",

examples/Basics_2D.ipynb

@@ -66,7 +66,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator = Annotator(image, fields=['description'], region_types=['Range'])"
+    "annotator = Annotator(image, fields=['description'])"
    ]
   },
   {
@@ -92,7 +92,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.overlay()"
+    "annotator * image"
    ]
   },
   {
@@ -102,13 +102,7 @@
    "source": [
     "The default output of `.overlay` is designed to be useful by default. Options on controlling the displayed layers and their styles can be found in the **Using `.overlay` section**.\n",
     "\n",
-    "**Note** The tools made available by the region editor is appropriate to the dimensionality of the element (here, a single key dimension on the x-axis).\n",
-    "\n",
-    "Also note that if we had used the key dimension type specification in the constructor instead of the element, the following would be equivalent:\n",
-    "\n",
-    "```python\n",
-    "annotator.overlay(element=speed_curve)\n",
-    "```"
+    "**Note** The tools made available by the region editor is appropriate to the dimensionality of the element (here, a single key dimension on the x-axis)."
    ]
   },
   {
@@ -154,7 +148,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.set_range(-0.25,0.25,-0.25,0.25)\n",
+    "annotator.set_regions(A=(-0.25,0.25),B=(-0.25,0.25))\n",
     "annotator.add_annotation(description='A programmatically defined annotation')"
    ]
   },
@@ -284,7 +278,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.set_range(-0.35,-0.15,-0.35,-0.25)\n",
+    "annotator.set_regions(A=(-0.35,-0.15), B=(-0.35,-0.25))\n",
     "annotator.add_annotation(description='An annotation description we will update...')"
    ]
   },
@@ -352,7 +346,7 @@
    "source": [
     "input_uuid = 'deadcafe'\n",
     "description = f'Annotation with set UUID {input_uuid!r}'\n",
-    "annotator.set_range(0.35,0.15,0.35,0.25)\n",
+    "annotator.set_regions(A=(-0.35,-0.15), B=(-0.35,-0.25))\n",
     "annotator.add_annotation(description=description, uuid=input_uuid)\n",
     "description"
    ]
@@ -417,7 +411,7 @@
    "source": [
     "startx, endx = [-0.1,-0.2,-0.3], [0.1,0.2,0.3]\n",
     "starty, endy = [-0.2,-0.3,-0.4], [0.2,0.3,0.4]\n",
-    "descriptions = ['Annotation %d' % d for d in range(3)]\n",
+    "descriptions = [\"Annotation 0\", \"Annotation 1\", \"Annotation 2\"]\n",
     "data = pd.DataFrame({'startx':startx, 'endx':endx, 'starty':starty, 'endy':endy, 'description':descriptions})\n",
     "data"
    ]
@@ -427,7 +421,7 @@
    "id": "fc931d2b-285a-4fa3-944d-f17c39196344",
    "metadata": {},
    "source": [
-    "To load this data, we *first* need to define the data in the annotation fields (for this annotator this is the `description` field):"
+    "To load this data, we use `define_annotations` and pass in the columns from the DataFrame. "
    ]
   },
   {
@@ -437,40 +431,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.define_fields(data[['description']])"
+    "annotator.define_annotations(data, A=(\"startx\", \"endx\"), B=(\"starty\", \"endy\"), description=\"description\")"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "c2683667-6abb-4b97-955f-9192f78ce3f2",
+   "id": "949c7dd8",
    "metadata": {},
    "source": [
-    "Now we can define the starts and ends of our annotation regions as follows:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "3ba550f2-3695-4999-b66d-ce70e087f09d",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "annotator.define_ranges(data['startx'], data['endx'], data['starty'], data['endy'])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "9710c385-7ff6-43f7-ac41-aee2aa990670",
-   "metadata": {},
-   "source": [
-    "The `DataFrame`/`Series` index (here the default pandas index) is what links our ranges to their corresponding field entries.\n",
-    "\n",
-    "Note the following rules:\n",
-    "\n",
-    "1. The index values supplied to the `define_` region methods must first be defined by `define_fields`.\n",
-    "2. Before we can call the `.commit` method, every index supplied to `define_fields` must have been given at least one region.\n",
-    "\n",
-    "As with `add_annotation`, the annotator automatically create uuid primary key values and the original index is ignored:"
+    "If a column name matches with a name of region or a field it will be used this means the `description=\"description` in the above line is not needed. "
    ]
   },
   {
@@ -488,8 +457,6 @@
    "id": "245eff10-f59e-4b00-b933-68aafdd38499",
    "metadata": {},
    "source": [
-    "This can be overridden by supplying `preserve_index=True` to the `define_fields` method as now described.\n",
-    "\n",
     "### Preserving the index"
    ]
   },
@@ -498,7 +465,7 @@
    "id": "fda1a724-11e9-40e4-ae72-d2922c240fd0",
    "metadata": {},
    "source": [
-    "Sometimes the annotations you are loading have meaningful primary keys defined elsewhere (e.g. some other pre-existing database) that need to be preserved. This is possible by supplying `preserve_index=True` to the `define_fields` method.\n",
+    "Sometimes the annotations you are loading have meaningful primary keys defined elsewhere (e.g. some other pre-existing database) that need to be preserved. This is possible by supplying `index=True` in the `define_annotations` method.\n",
     "\n",
     "*Note: The user bears the same responsibilities for using appropriate index values as described in the  ***Caveats when picking your own primary keys*** section!*\n"
    ]
@@ -518,23 +485,21 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "3303236f-faf3-4ace-b18d-6e3d81984f3d",
+   "cell_type": "markdown",
+   "id": "dfbaa70c",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "annotator.define_fields(indexed_data[['description']], preserve_index=True)"
+    "To preserve the index call, the `define_annotations` must be called with `index=True`:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "b555fff9-9e8b-48ed-878c-b39a49714a97",
+   "id": "3303236f-faf3-4ace-b18d-6e3d81984f3d",
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotator.define_ranges(indexed_data['startx'], indexed_data['endx'], indexed_data['starty'], indexed_data['endy'])"
+    "annotator.define_annotations(indexed_data, A=(\"startx\", \"endx\"), B=(\"starty\", \"endy\"), description=\"description\", index=True)"
    ]
   },
   {
@@ -562,7 +527,7 @@
    "id": "57962a14-32be-4239-9ad3-f9eee5d18158",
    "metadata": {},
    "source": [
-    "## Selecting and highlighting annotations\n",
+    "## 🚧 Selecting and highlighting annotations\n",
     "\n",
     "Earlier we styled the indicators with `color='red', alpha=0.2`. To highlight a select a specific indicator, we can create a dimension expression to assign selected and non-selected indicators different values. Here we have a highlighter that uses a value of `0.6` for selected indicators and `0.1` for non-selected indicators. We can then apply these values to the `alpha` option:"
    ]
@@ -663,7 +628,7 @@
    "id": "16134a64-1347-4ebe-909a-716f55c520ac",
    "metadata": {},
    "source": [
-    "## Using `.overlay`\n",
+    "## 🚧 Using `.overlay`\n",
     "\n",
     "The `.overlay` method is a shortcut to building the following overlay:\n",
     "\n",