Merge pull request #420 from BiAPoL/add-context-menu-to-plotter-for-layer-export

Add option to plotter for copying selected objects to a new layer

Author: jo-mueller

docs/usage/imgs/categorical_features.png

@@ -38,3 +38,9 @@ In combination with the dimensionality reduction and clustering algorithms, this
 The drawing of the plotted data is triggered whenever the data in the `layer.features` attribute has been updated. This gives trise to a few cool use cases of the clusters plotter. One of them is the simple generation of feature maps directly on top of an existing layer:
 
 ![Feature map generation](./imgs/features_immediacy1.gif)
+
+## Copy selected objects to new layers
+
+In case you ever found yourself in the situation that you wanted to process or inspect an individual object from a layer separately from all the other objects without tedious image processing to pick out *just the right object*, you can now do this in the clusters plotter. Simply draw a selection in the canvas (using the `MANUAL_CLUSTER_ID`) as hue column or select any other categorical feature. Then use the cluster selector on the top of the canvas to select the object class you'd want to export and click the `Add current class as new layer button`!
+
+![Add selected objects to new layer](./imgs/copy_export_objects_function.gif)

docs/usage/imgs/copy_export_objects_function.gif

@@ -22,16 +22,17 @@ The core functionality of the plugin is available to you directly upon opening i
 5. Canvas: Features will be visualized here
 6. What feature to plot on the x-axis and y-axis, respectively. The `Hue` dropdown controls the coloring of the data on the canvas, categorical features are highlighted in orange.
 7. Reset button: Resets all drawn clusters
+8. Copy button: Copies the currently selected objects according to selector **3** to a new layer. All respective features will be copied over to the new layer accordingly.
 
 ![Advanced settings](./imgs/plotter_overview3_annotated.png)
 
 Under the `Advanced Options` tab, you have access to some more customization options for the visualization:
 
-8. Change the colormap for the chosen overlay color. If a layer is colored by a non-categorical feature, this determines the colormap for the depiction. Only enabled if a non-categorical feature is selected in the `Hue` dropdown.
-9. Apply a log-scale to the chosen feature
-10. Switch plot type between `SCATTER` and `HISTOGRAM2D`
-11. Colorap for 2D histogram (only enabled if `HISTOGRAM2D` is selected in 10.)
-12. Change the size of the bins (only enabled if `HISTOGRAM2D` is selected in 10.)
+9. Change the colormap for the chosen overlay color. If a layer is colored by a non-categorical feature, this determines the colormap for the depiction. Only enabled if a non-categorical feature is selected in the `Hue` dropdown.
+10. Apply a log-scale to the chosen feature
+11. Switch plot type between `SCATTER` and `HISTOGRAM2D`
+12. Colorap for 2D histogram (only enabled if `HISTOGRAM2D` is selected in 10.)
+13. Change the size of the bins (only enabled if `HISTOGRAM2D` is selected in 10.)
 
 ## Visualizing layer features
 
@@ -69,3 +70,27 @@ There are two things to keep in mind here:
 So far, the `Hue` selector was always set to `MANUAL_CLUSTER_ID`, which is by design a *categorical* column. However, the napari-clusters-plotter supports visualizing any feature as the `Hue` parameter. If this is done, the points are colored according to the selected feature and each point's color will be project on the respective object in the napari viewport. In essence, this creates feature maps for each feature you select:
 
 ![Selecting features as hue](./imgs/selecting_features1.gif)
+
+
+## Adding objects to new layer
+(widget:plotter:add_objects_to_layer)=
+
+If you want to copy selected objects to a new layer, you can use the `Add current class to new layer` button in the Plotter Widget. To use it, make sure you have a *categorical feature* selected in the `Hue` dropdown selector (i.e., `MANUAL_CLUSTER_ID`, which is generated upon drawing a selection). However, resulting cluster ids from a clustering operation (see [Clustering Widget](widget:clustering)) can also be used here. Generally, categorical features are highlighted in orange in the `Hue` dropdown selector:
+
+![Categorical features in hue selector](./imgs//categorical_features.png)
+
+Then, select the cluster id you want to copy to a new layer in the `Selected cluster index` selector (see above):
+
+![Selecting cluster id](./imgs/selecting_cluster_id.png)
+
+Finally, click the `Add current class as new layer` button.
+
+![Adding objects to a new layer](./imgs/copy_export_objects_function.gif)
+
+```{note}
+It is possible to export all *unselected objects* to a new layer, too. To do so, simply select zero as the `Selected cluster index`. This will copy all objects that are not part of any selection to a new layer.
+```
+
+```{note}
+Selecting a cluster id that is not present in the `Hue` column will result in nothing happening.
+```

docs/usage/imgs/plotter_overview1.png

@@ -0,0 +1,233 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "e28ea1eb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import napari\n",
+    "from napari.layers import Points\n",
+    "import numpy as np\n",
+    "from napari_clusters_plotter._new_plotter_widget import _export_cluster_to_layer, PlotterWidget"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "c8eef9bc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "viewer = napari.Viewer(ndisplay=3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "57b5ae7a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def create_multi_point_layer(n_samples: int = 100):\n",
+    "    import pandas as pd\n",
+    "\n",
+    "    loc = 5\n",
+    "    n_timeframes = 5\n",
+    "    frame = np.arange(n_timeframes).repeat(n_samples // n_timeframes)\n",
+    "    # make some random points with random  features\n",
+    "    points = np.random.random((n_samples, 4))\n",
+    "    points2 = np.random.random((n_samples - 1, 4))\n",
+    "\n",
+    "    points[:, 0] = frame\n",
+    "    points2[:, 0] = frame[:-1]\n",
+    "\n",
+    "    features = pd.DataFrame(\n",
+    "        {\n",
+    "            \"frame\": frame,\n",
+    "            \"feature1\": np.random.normal(size=n_samples, loc=loc),\n",
+    "            \"feature2\": np.random.normal(size=n_samples, loc=loc),\n",
+    "            \"feature3\": np.random.normal(size=n_samples, loc=loc),\n",
+    "            \"feature4\": np.random.normal(size=n_samples, loc=loc),\n",
+    "        }\n",
+    "    )\n",
+    "\n",
+    "    features2 = pd.DataFrame(\n",
+    "        {\n",
+    "            \"frame\": frame[:-1],\n",
+    "            \"feature2\": np.random.normal(size=n_samples - 1, loc=-loc),\n",
+    "            \"feature3\": np.random.normal(size=n_samples - 1, loc=-loc),\n",
+    "            \"feature4\": np.random.normal(size=n_samples - 1, loc=-loc),\n",
+    "        }\n",
+    "    )\n",
+    "\n",
+    "    layer = Points(\n",
+    "        points, features=features, size=0.1, blending=\"translucent_no_depth\"\n",
+    "    )\n",
+    "    layer2 = Points(\n",
+    "        points2,\n",
+    "        features=features2,\n",
+    "        size=0.1,\n",
+    "        translate=(0, 0, 2),\n",
+    "        blending=\"translucent_no_depth\",\n",
+    "    )\n",
+    "\n",
+    "    return layer, layer2\n",
+    "\n",
+    "\n",
+    "def create_multi_tracks_layer(n_samples: int = 100):\n",
+    "    from napari.layers import Tracks\n",
+    "\n",
+    "    points1, points2 = create_multi_point_layer(n_samples=n_samples)\n",
+    "\n",
+    "    tracks1 = points1.data.copy()\n",
+    "    tracks2 = points2.data.copy()\n",
+    "\n",
+    "    # insert empty track id column\n",
+    "    tracks1 = np.insert(tracks1, 0, 0, axis=1)\n",
+    "    tracks2 = np.insert(tracks2, 0, 0, axis=1)\n",
+    "\n",
+    "    for t in range(int(points1.data[:, 0].max() + 1)):\n",
+    "        # set the track id for each point\n",
+    "        tracks1[tracks1[:, 1] == t, 0] = np.arange(\n",
+    "            len(tracks1[tracks1[:, 1] == t]), dtype=int\n",
+    "        )\n",
+    "\n",
+    "    for t in range(int(points2.data[:, 0].max() + 1)):\n",
+    "        # set the track id for each point\n",
+    "        tracks2[tracks2[:, 1] == t, 0] = np.arange(\n",
+    "            len(tracks2[tracks2[:, 1] == t]), dtype=int\n",
+    "        )\n",
+    "\n",
+    "    tracks1 = Tracks(tracks1, features=points1.features, name=\"tracks1\")\n",
+    "    tracks2 = Tracks(\n",
+    "        tracks2, features=points2.features, name=\"tracks2\", translate=(0, 0, 2)\n",
+    "    )\n",
+    "\n",
+    "    return tracks1, tracks2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "73f9b34c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "layer1, layer2 = create_multi_tracks_layer()\n",
+    "viewer.add_layer(layer1)\n",
+    "viewer.add_layer(layer2)\n",
+    "viewer.layers.select_all()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "1909214b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "c:\\Users\\Johan\\mambaforge\\envs\\clusters-plotter\\Lib\\site-packages\\biaplotter\\colormap.py:34: UserWarning: Categorical colormap detected. Setting categorical=True. If the colormap is continuous, set categorical=False explicitly.\n",
+      "  warnings.warn(\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "<napari._qt.widgets.qt_viewer_dock_widget.QtViewerDockWidget at 0x1b685722dd0>"
+      ]
+     },
+     "execution_count": 15,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "n_layers = len(viewer.layers)\n",
+    "\n",
+    "widget = PlotterWidget(viewer)\n",
+    "viewer.window.add_dock_widget(widget, area=\"right\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c74f2128",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for layer in viewer.layers:\n",
+    "    if type(layer) in widget.input_layer_types:\n",
+    "        features = layer.features\n",
+    "        features['MANUAL_CLUSTER_ID'] = np.random.randint(low=0, high=2, size=len(features))\n",
+    "        layer.features = features\n",
+    "\n",
+    "widget.plot_needs_update.emit()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d2d5fd4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "widget._on_export_clusters()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "7dda611d",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(100, 5)"
+      ]
+     },
+     "execution_count": 20,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "viewer.layers[0].data.shape"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8751cb4a",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "clusters-plotter",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/usage/imgs/plotter_overview1_annotated.png

@@ -39,7 +39,7 @@ def _get_features(self):
             _features = layer.features[self.common_columns].copy()
 
             # Add layer name as a categorical column
-            _features["layer"] = layer.name
+            _features["layer"] = layer.unique_id
             _features["layer"] = _features["layer"].astype("category")
             features = pd.concat([features, _features], axis=0)