Detection label plot

docs/source/aplose.rst

@@ -38,7 +38,9 @@ The :class:`osekit.core.detection.Detection` class inherits from the :class:`ose
 Plotting a detection
 ^^^^^^^^^^^^^^^^^^^^
 
-Detection boxes can be plotted on spectrograms thanks to the :method:`osekit.core.detection.Detection.to_rectangle` method:
+Detection boxes can be plotted on spectrograms thanks to the :meth:`osekit.core.detection.Detection.plot` method.
+
+First, let's plot a spectrogram, and keep track of the ``Axes`` in which the spectrogram is plot (returned by the :meth:`osekit.core.spectro_data.SpectroData.plot` method):
 
 .. code-block:: python
 
@@ -49,16 +51,69 @@ Detection boxes can be plotted on spectrograms thanks to the :method:`osekit.cor
     sd = SpectroData(...)
     detection = Detection(...)
 
-    fig, axs = plt.subplots()
+    # Plot the spectrogram and keep the Axes in which the plot is made
+    ax = sd.plot(ax=ax)
+
+
+Now, we can plot the detection directly in the ``ax`` Axes.
+The detection is plotted as a `matplotlib Rectangle <https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Rectangle.html>`_.
+Keyword arguments can be passed to the rectangle constructor thanks to the ``detection_rect_kwargs`` parameter:
+
+.. code-block:: python
+
+    detection.plot(
+        ax=ax,
+        detection_rect_kwargs={ # Keyword arguments passed to the Rectangle constructor
+            "color": "#fde725",
+            "linewidth": 7,
+        },
+    )
+
+    # Show the spectrogram with the detection plotted on top of it
+    plt.show()
+
+.. image::
+    _static/detections/detection_unlabelled.png
+    :align: center
+
+Detection labels (:class:`osekit.core.detection.Label`) can be added to the detection rectangle thanks to the ``plot_label`` parameter.
 
-    # Plot the spectrogram
-    sd.plot(ax=ax)
+Labels consist in a background `matplotlib Rectangle <https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Rectangle.html>`_ and a foreground
+`matplotlib Text <https://matplotlib.org/stable/api/text_api.html#matplotlib.text.Text>`_.
 
-    # Get a rectangle from the detection
-    rectangle = detection.to_rectangle(fill = False)
+Keyword arguments can be passed to the background rectangle thanks to the ``background_kwargs`` parameter and to the foreground text thanks to the
+``text_kwargs`` parameter:
+
+.. code-block:: python
 
-    # Draw the detection
-    ax.add_patch(rectangle)
+    detection.plot(
+        ax=ax,
+        detection_rect_kwargs={ # Keyword arguments passed to the detection Rectangle constructor
+            "color": "#fde725",
+            "linewidth": 7,
+        },
+        plot_label=True,
+        label_kwargs={
+            "anchor": "bottom_left",
+            "inner_text": True,
+            "text_kwargs": { # Keyword arguments passed to the label Text
+                "color": "#440154",
+                "size": "x-large"
+            },
+            "background_kwargs": {}, # Keyword arguments passed to the label background rectangle
+        },
+    )
 
-    # Show the spectrogram
     plt.show()
+
+.. image::
+    _static/detections/detection_labelled.png
+    :align: center
+
+The label position (relative to the detection rectangle) can be set thanks to the ``anchor`` and ``inner_text`` parameters.
+
+The following figure displays all 8 possible combinations. In the notation ``x_y_z``, ``x_y`` represents the anchor (``T_R`` stands for ``"top_right"``) and ``z`` represents the ``inner_text`` parameter (``I`` for ``True`` (inner), ``O`` for ``False`` (outer)).
+
+.. image::
+    _static/detections/label_anchors.png
+   :align: center

docs/source/detection.rst

@@ -6,6 +6,9 @@ Detection
 .. autoclass:: osekit.core.detection.Detection
    :members:
 
+.. autoclass:: osekit.core.detection.Label
+   :members:
+
 .. autoclass:: osekit.core.detection.FrequencyBounds
    :members:
 

docs/source/example_aplose_result.ipynb

@@ -2,13 +2,15 @@
  "cells": [
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "initial_id",
    "metadata": {
     "collapsed": true,
     "tags": [
      "remove-cell"
     ]
    },
+   "outputs": [],
    "source": [
     "# Executing this cell will:\n",
     "\n",
@@ -21,9 +23,7 @@
     "from osekit import setup_logging\n",
     "\n",
     "setup_logging()  # Overwrites the default logger to"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -36,8 +36,9 @@
    ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
+   "id": "90049102bdc38599",
+   "metadata": {},
    "source": [
     "# Creating the Public Project\n",
     "\n",
@@ -46,22 +47,24 @@
     "First, we will build a project and run a transform that would be uploaded and annotated on APLOSE (see the [Public API documentation](https://project-osmose.github.io/OSEkit/publicapi_usage.html) for more info).\n",
     "\n",
     "The `_static/detections/aplose_results.csv` file used in this notebook simulates the results of this annotation campaign."
-   ],
-   "id": "90049102bdc38599"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
+   "id": "e2d5321198880205",
+   "metadata": {},
    "source": [
     "## Build the Project\n",
     "\n",
     "First, we have to build the project from the raw audio files:"
-   ],
-   "id": "e2d5321198880205"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
+   "execution_count": null,
+   "id": "3ab3cb447c59a857",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "from pathlib import Path\n",
     "from osekit.public.project import Project\n",
@@ -78,24 +81,24 @@
     ")\n",
     "\n",
     "project.build()"
-   ],
-   "id": "3ab3cb447c59a857",
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
+   "id": "2f5510c9c396ee2f",
+   "metadata": {},
    "source": [
     "## Declare & Run the Transform\n",
     "\n",
     "Then we **declare** and **run** a `Transform` which would export the spectrograms to be annotated:"
-   ],
-   "id": "2f5510c9c396ee2f"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
+   "execution_count": null,
+   "id": "d993991e8c23a2c0",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "from osekit.public.transform import Transform, OutputType\n",
     "from osekit.utils.audio import Normalization\n",
@@ -120,10 +123,7 @@
     "ads.remove_empty_data(threshold=0.99)\n",
     "\n",
     "project.run(transform=transform, audio_dataset=ads)"
-   ],
-   "id": "d993991e8c23a2c0",
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -133,16 +133,16 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "1948b260fcaf03ab",
    "metadata": {},
+   "outputs": [],
    "source": [
     "from pathlib import Path\n",
     "from osekit.core.detection import Detection\n",
     "\n",
     "detections = Detection.from_csv(csv=Path(r\"_static/detections/aplose_results.csv\"))"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -171,8 +171,10 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "45892d179652235b",
    "metadata": {},
+   "outputs": [],
    "source": [
     "def does_satisfy_constraints(detection: Detection) -> bool:\n",
     "    # Keeping only odontocete whistles\n",
@@ -196,9 +198,7 @@
     "filtered_detections = [\n",
     "    detection for detection in detections if does_satisfy_constraints(detection)\n",
     "]"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -212,8 +212,10 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "237d399b7de6ffd5",
    "metadata": {},
+   "outputs": [],
    "source": [
     "# Recover the transform output (SpectroDataset)\n",
     "sds = project.get_output(output_name=\"example_transform\")\n",
@@ -224,9 +226,7 @@
     "    for sd in sds.data\n",
     "    if any(detection.overlaps(sd) for detection in filtered_detections)\n",
     "]"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -240,8 +240,10 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "d0d242240e791509",
    "metadata": {},
+   "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
@@ -261,25 +263,36 @@
     "            continue\n",
     "\n",
     "        # Detections are plotted as matplotlib Rectangles\n",
-    "        rectangle = detection.to_rectangle(fill=False)\n",
-    "        ax.add_patch(rectangle)\n",
+    "        detection.plot(\n",
+    "            ax=ax,\n",
+    "            plot_label=True,  # We can plot the label along with the detection rectangle\n",
+    "            detection_rect_kwargs={  # kwargs passed to the detection matplotlib Rectangle\n",
+    "                \"color\": \"#fde725\"\n",
+    "            },\n",
+    "            label_kwargs={  # kwargs passed to the Label osekit object\n",
+    "                \"anchor\": \"bottom_left\",\n",
+    "                \"inner_text\": False,\n",
+    "                \"background_kwargs\": {},  # kwargs passed to the label background matplotlib Rectangle\n",
+    "                \"text_kwargs\": {\n",
+    "                    \"color\": \"#440154\"\n",
+    "                },  # kwargs passed to the label matplotlib Text\n",
+    "            },\n",
+    "        )\n",
     "\n",
     "# Let's take a look at the output figure\n",
     "plt.show()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "449dc442b4a5df75",
    "metadata": {},
+   "outputs": [],
    "source": [
     "# Reset the project to get all files back to place.\n",
     "project.reset()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   }
  ],
  "metadata": {