Refactor project

Author: MalloryWittwer

README.md

@@ -3,56 +3,58 @@
 
 [demo.webm](https://github.com/user-attachments/assets/d44aa86c-7976-4240-91bd-ca194762d038)
 
-This is an extended version of Napari's built-in [features table widget](https://napari.org/0.6.3/gallery/features_table_widget.html), with extra options to:
+This plugin is similar to Napari's built-in [features table widget](https://napari.org/0.6.3/gallery/features_table_widget.html), but optimized for usage with **2D and 3D `Labels` layers**. It offers extra options to:
 
-- Sort table values
-- Display a subset of table columns
-- Colorize `Labels` based on feature values
+- Sort table values.
+- Hide or show table columns.
+- Colorize `Labels` based on feature values, with different color maps.
+- Connect your own callback functions to customize what happens when users click on a table row.
+- Connect your own featurizer functions that run automatically when the data in the `Labels` changes and update the displayed table.
 
-The table is essentially a graphical view of the `features` attribute of a layer.
-
-The table is optimized for usage with **2D and 3D `Labels` layers**. It can probably be used to display features from other layer types as well, but this hasn't been tested.
+The content of the table is a graphical view of the `features` attribute of a `Labels` layer.
 
 ## Displaying the table
 
 Open the table from `Plugins > Features Table` in Napari.
 
 The table displays features from the **currently selected layer** in the layers list. It will automatically update when the layer selection changes. If multiple layers are selected, only features from the first selected layer will be displayed.
 
-## Computing custom features
+## Connecting featurizer functions
 
 By default, the table displays a `label` column for the selected `Labels` layer, along with any pre-existing features that can be matched with the `label` column (they should be in Pandas DataFrame format with at least a 'label' column).
 
-It is possible to **compute features automatically** when a new Labels layer is selected, based on a provided featurizer function. Featurizer functions will receive as input the labels layer data as a Numpy array, and should return a Pandas DataFrame with at least a `label` column, along with any other feature columns.
+You can customize the behaviour of the plugin to **update features automatically** when a new Labels layer is selected, or when its data changes, based on a featurizer function that you provide. Featurizer functions will receive as input the labels layer data as a Numpy array, and should return a Pandas DataFrame with at least a `label` column, along with any other feature columns.
 
-For example, the following code extends the behaviour of the table to compute and display the `area` (or volume) of a labels layer:
+For example, the following code extends the behaviour of the table to display the `area` (or volume) of objects:
 
 ```python
+import napari
 import pandas as pd
 from skimage.measure import regionprops_table
+from napari_label_focus import ConfigurableFeaturesTableWidget
 
+# Write an "area" featurizer
 def area_featurizer(labels: np.ndarray) -> pd.DataFrame:
     return pd.DataFrame(regionprops_table(labels, properties=["label", "area"]))
 
 if __name__ == "__main__":
-    import napari
-    from napari_label_focus import ConfigurableFeaturesTableWidget
     viewer = napari.Viewer()
-    widget = ConfigurableFeaturesTableWidget(viewer, featurizers=[area_featurizer])
+    widget = ConfigurableFeaturesTableWidget(viewer, featurizer_functs=[area_featurizer])
     viewer.window.add_dock_widget(widget)
     napari.run()
 ```
 
-If more than one featurizer is provided, featurizers will be run one by one and the results from each will be merged into a single features DataFrame.
+If more than one featurizer function is provided, these functions will be run one by one and the results will be merged into a single features DataFrame.
 
 ## Controlling what clicking on a table row does
 
 By default, clicking on a table row selects the corresponding label in the `Labels` layer. This behaviour can be extended by adding callback functions to the *table_click_callbacks* parameter of the table widget. The callback functions receive a selection context object with references to the viewer, selected layer, selected table row, and the table itself.
 
-The following example illustrates how this works:
+For example:
 
 ```python
-from napari_label_focus._context import SelectionContext
+import napari
+from napari_label_focus import ConfigurableFeaturesTableWidget, SelectionContext
 
 def print_selection_context(ctx: SelectionContext):
     print(f"Napari viewer: {ctx.viewer}")
@@ -61,8 +63,6 @@ def print_selection_context(ctx: SelectionContext):
     print(f"Features table: {ctx.features_table}")
 
 if __name__ == "__main__":
-    import napari
-    from napari_label_focus import ConfigurableFeaturesTableWidget
     viewer = napari.Viewer()
     widget = ConfigurableFeaturesTableWidget(viewer, table_click_callbacks=[print_selection_context])
     viewer.window.add_dock_widget(widget)

src/napari_label_focus/__init__.py

@@ -1,3 +1,4 @@
 from ._widget import ConfigurableFeaturesTableWidget
+from ._context import SelectionContext
 
-__all__ = ("ConfigurableFeaturesTableWidget",)
+__all__ = ("ConfigurableFeaturesTableWidget", "SelectionContext")

src/napari_label_focus/_featurizer.py

@@ -0,0 +1,142 @@
+from typing import Callable, List, Optional
+
+import napari.layers
+import numpy as np
+import pandas as pd
+import skimage.measure
+from napari.utils.notifications import show_warning
+
+from napari_label_focus._utils import sanitize_layer_features
+
+
+def default_featurizer(labels: np.ndarray) -> pd.DataFrame:
+    return pd.DataFrame(skimage.measure.regionprops_table(labels, properties=["label"]))
+
+
+class Featurizer:
+    def __init__(
+        self,
+        featurizer_functs: Optional[List[Callable[[np.ndarray], pd.DataFrame]]] = None,
+    ) -> None:
+        self.featurizer_functs: List = [default_featurizer]
+        if isinstance(featurizer_functs, List):
+            self.featurizer_functs.extend(featurizer_functs)
+
+    def recompute_features(
+        self, labels_layer: napari.layers.Layer
+    ) -> Optional[pd.DataFrame]:
+        """
+        Performs checks to sanitize a labels layer and its data, then runs featurizer functions and updates layer features.
+        """
+        if not isinstance(labels_layer, napari.layers.Labels):
+            return
+
+        # Sanitize labels layer data
+        labels = labels_layer.data
+
+        if not isinstance(labels, np.ndarray):
+            show_warning("Labels data should be a Numpy array")
+            return
+
+        # Sanitize labels layer features
+        features_df = sanitize_layer_features(labels_layer)
+
+        # Compute the "default featurizer"
+        merged_df = default_featurizer(labels)
+
+        # Merge it with existing features
+        if "label" in features_df.columns:
+            merged_df = self._merge_incoming_df(features_df, merged_df)
+
+        # Compute extra feature dataframes and merge them into the layer features
+        for featurizer_func in self.featurizer_functs:
+            df_incoming = featurizer_func(labels)
+
+            if "label" not in df_incoming.columns:
+                show_warning(
+                    "Featurizer should output a dataframe with a 'label' column"
+                )
+                continue
+
+            merged_df = self._merge_incoming_df(df_incoming, merged_df)
+
+        # Update the layer features
+        labels_layer.features = merged_df
+
+    def _merge_incoming_df(
+        self, df_incoming: pd.DataFrame, df_existing: pd.DataFrame
+    ) -> pd.DataFrame:
+        # Shared columns that are not "label"
+        shared_cols = df_incoming.columns.intersection(df_existing.columns).difference(
+            ["label"]
+        )
+
+        # Left merge to keep only label rows present in the incoming features
+        df_merged = df_incoming.merge(
+            df_existing, on="label", how="left", suffixes=("_incoming", "_existing")
+        )
+
+        # Overwrite existing values with incoming values
+        for col in shared_cols:
+            df_merged[col] = df_merged[f"{col}_incoming"]
+
+        # Drop all suffixed columns
+        cols_to_drop = [f"{col}_incoming" for col in shared_cols] + [
+            f"{col}_existing" for col in shared_cols
+        ]
+        df_merged = df_merged.drop(columns=cols_to_drop)
+
+        return df_merged
+
+
+class FeaturizerWidget:
+    def __init__(
+        self,
+        napari_viewer: napari.Viewer,
+        featurizer_functs: Optional[List[Callable[[np.ndarray], pd.DataFrame]]] = None,
+    ):
+        self.viewer = napari_viewer
+
+        self.featurizer_functs = Featurizer(featurizer_functs=featurizer_functs)
+
+        # Keep track of the selected layer
+        self.selected_layer = None
+        
+        # Keep track of layers selected at least once to avoid recomputing their features on layer change
+        self.seen_layers = []
+
+        # Layer events
+        self.viewer.layers.selection.events.changed.connect(self._selection_changed)
+        self.viewer.layers.events.inserted.connect(
+            lambda e: self._selection_changed(None)
+        )
+        self._selection_changed(None)
+
+    def _selection_changed(self, event=None):
+        if event is None:
+            layer = self.viewer.layers.selection.active
+        else:
+            layer = event.source.active
+
+        if not isinstance(layer, napari.layers.Layer):
+            return
+
+        # Connect the "paint" and "data change" events to recomputing features
+        if isinstance(self.selected_layer, napari.layers.Labels):
+            self.selected_layer.events.paint.disconnect(self._recompute)
+            self.selected_layer.events.data.disconnect(self._recompute)
+
+        if isinstance(layer, napari.layers.Labels):
+            layer.events.data.connect(self._recompute)
+            layer.events.paint.connect(self._recompute)
+
+        self.selected_layer = layer
+
+        # Only compute features on selection change when the layer is seen for the first time
+        if layer not in self.seen_layers:
+            self.featurizer_functs.recompute_features(layer)
+
+    def _recompute(self, event):
+        layer = event.sources[0]
+
+        self.featurizer_functs.recompute_features(layer)

src/napari_label_focus/_featurizers.py

@@ -0,0 +1,75 @@
+from collections import defaultdict
+import napari.layers
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from napari.utils import DirectLabelColormap
+from napari.utils.notifications import show_warning
+
+
+def sanitize_layer_features(layer: napari.layers.Layer) -> pd.DataFrame:
+    """Converts existing layer features to a Pandas DataFrame (empty if features are non-existent, or incompatible with the plugin)."""
+    if not hasattr(layer, "features"):
+        return pd.DataFrame()
+    else:
+        features = getattr(layer, "features")
+        if isinstance(features, pd.DataFrame):
+            return features
+        else:
+            show_warning(
+                f"Layer `{layer.name}` contains features that aren't a pandas DataFrame (not displayable in the features table widget)."
+            )
+            return pd.DataFrame()
+
+
+def color_labels_layer_by_values(
+    layer: napari.layers.Labels,
+    features_df: pd.DataFrame,
+    color_by: str,
+    colormap: str = "inferno",
+):
+    """Colorize a napari Labels layer based on the values of a column in a features dataframe."""
+    # Drop the NaNs
+    features_df_filtered = features_df.dropna(axis=0)
+    if len(features_df_filtered) == 0:
+        return
+
+    # Check that the `label` column is present
+    if "label" not in features_df_filtered.columns:
+        raise ValueError("Features dataframe does not have a `label` column.")
+    label_values = features_df_filtered["label"].values
+
+    # Check the values to plot from the dataframe
+    numeric_cols = features_df_filtered.select_dtypes(include=[np.number]).columns
+    if color_by not in numeric_cols:
+        raise ValueError(
+            f"Column {color_by} is either not present or non-numeric (cannot be plotted)."
+        )
+
+    plot_vals = features_df_filtered[color_by].values
+    if not isinstance(plot_vals, np.ndarray):
+        raise ValueError(
+            f"Values in column {color_by} are not a NumPy array (cannot be plotted)"
+        )
+
+    # Rescale values to [0-1] for colormapping
+    min_vals = np.min(plot_vals)
+    max_vals = np.max(plot_vals)
+    val_range = max_vals - min_vals
+    if val_range > 0:
+        relative_vals = (plot_vals - min_vals) / val_range
+    else:
+        relative_vals = (plot_vals - min_vals) + 1
+
+    # Plot in `inferno` colour
+    cmap = plt.get_cmap(colormap)
+    rgba = cmap(relative_vals)
+
+    color_dict = defaultdict(lambda: np.zeros(4))
+    for lab, color in zip(label_values, rgba):
+        color_dict[lab] = color
+
+    layer.events.selected_label.block()
+    layer.colormap = DirectLabelColormap(color_dict=color_dict)
+    layer.events.selected_label.unblock()
+    layer.refresh()