Prevent duplicate renamed metaclusters in Pixie remapping

src/ark/phenotyping/cell_meta_clustering.py

@@ -192,20 +192,21 @@ def apply_cell_meta_cluster_remapping(base_dir, cell_som_input_data, cell_remapp
     )
 
     # create the mapping from cell SOM to cell meta cluster
-    # TODO: generating cell_remapped_dict and cell_renamed_meta_dict should be returned
+    # TODO: generated cell_remapped_dict and cell_renamed_meta_dict should be returned
     # to prevent repeat computation in summary file generation functions
     cell_remapped_dict = dict(
         cell_remapped_data[
             ['cell_som_cluster', 'cell_meta_cluster']
         ].values
     )
 
+    # ensure no duplicated renamed meta clusters make it in
+    cluster_helpers.verify_unique_meta_clusters(cell_remapped_data, meta_cluster_type="cell")
+
     # create the mapping from cell meta cluster to cell renamed meta cluster
-    cell_renamed_meta_dict = dict(
-        cell_remapped_data[
-            ['cell_meta_cluster', 'cell_meta_cluster_rename']
-        ].drop_duplicates().values
-    )
+    cell_renamed_meta_dict = dict(cell_remapped_data[
+        ['cell_meta_cluster', 'cell_meta_cluster_rename']
+    ].drop_duplicates().values)
 
     # load the cell consensus data in
     print("Using re-mapping scheme to re-label cell meta clusters")

src/ark/phenotyping/cluster_helpers.py

@@ -4,7 +4,7 @@
 import warnings
 from abc import ABC, abstractmethod
 from itertools import combinations
-from typing import List, Protocol, runtime_checkable
+from typing import List, Literal, Protocol, runtime_checkable
 
 import feather
 import numpy as np
@@ -16,6 +16,39 @@
 from alpineer.misc_utils import verify_in_list
 
 
+def verify_unique_meta_clusters(pixie_remapped_data: pd.DataFrame,
+                                meta_cluster_type: Literal["pixel", "cell"]):
+    """Verifies that a mapping contains a unique renamed meta cluster for every base meta cluster
+
+    Args:
+        pixie_remapped_data (pandas.DataFrame):
+            Must have `{pixel/cell}_meta_cluster` and `{pixel/cell}_meta_cluster_rename` columns
+        meta_cluster_type (Literal["pixel", "cell"]):
+            Whether pixel or cell meta clusters are being validated
+
+    Raises:
+        ValueError:
+            If there are duplicate `{pixel/cell}_meta_cluster_rename` entries for multiple
+            `{pixel/cell}_meta_cluster` values
+    """
+    verify_in_list(
+        specified_meta_cluster=meta_cluster_type,
+        acceptable_meta_clusters=["pixel", "cell"]
+    )
+
+    meta_pairs = pixie_remapped_data[
+        [f"{meta_cluster_type}_meta_cluster", f"{meta_cluster_type}_meta_cluster_rename"]
+    ].drop_duplicates()
+    meta_dups = meta_pairs[
+        meta_pairs.duplicated(f"{meta_cluster_type}_meta_cluster_rename", keep=False)
+    ][f"{meta_cluster_type}_meta_cluster_rename"].unique().tolist()
+    if len(meta_dups) > 0:
+        raise ValueError(
+            f"Duplicate renamed {meta_cluster_type} meta cluster values found: %s, "
+            "please re-run remapping GUI to resolve naming conflicts" % str(meta_dups)
+        )
+
+
 class PixieSOMCluster(ABC):
     @abstractmethod
     def __init__(self, weights_path: pathlib.Path, columns: List[str], num_passes: int = 1,

src/ark/phenotyping/pixel_meta_clustering.py

@@ -371,12 +371,13 @@ def apply_pixel_meta_cluster_remapping(fovs, channels, base_dir,
         ].values
     )
 
+    # ensure no duplicated renamed meta clusters make it in
+    cluster_helpers.verify_unique_meta_clusters(pixel_remapped_data, meta_cluster_type="pixel")
+
     # create the mapping from pixel meta cluster to renamed pixel meta cluster
-    pixel_renamed_meta_dict = dict(
-        pixel_remapped_data[
-            ['pixel_meta_cluster', 'pixel_meta_cluster_rename']
-        ].drop_duplicates().values
-    )
+    pixel_renamed_meta_dict = dict(pixel_remapped_data[
+        ['pixel_meta_cluster', 'pixel_meta_cluster_rename']
+    ].drop_duplicates().values)
 
     # define the partial function to iterate over
     fov_data_func = partial(

start_docker.sh

@@ -44,7 +44,7 @@ fi
 # find lowest open port available
 PORT=8888
 
-until [[ $(docker container ls | grep 0.0.0.0:$PORT | wc -l) -eq 0 ]]
+until [[ $(netstat -an | grep LISTEN | grep $PORT | wc -l) -eq 0 ]]
   do
     ((PORT=$PORT+1))
 done

templates/2_Pixie_Cluster_Pixels.ipynb

@@ -1,7 +1,6 @@
 {
  "cells": [
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -44,7 +43,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -69,7 +67,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -94,7 +91,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {
     "tags": []
@@ -104,7 +100,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -137,7 +132,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -162,15 +156,13 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Define multiprocessing parameters"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -195,7 +187,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {
     "tags": []
@@ -205,7 +196,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -230,7 +220,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -264,7 +253,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -297,7 +285,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -333,7 +320,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -362,7 +348,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -407,23 +392,20 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## 3: Pixel clustering"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### 3.1: Train pixel SOM"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -454,7 +436,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -487,15 +468,13 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### 3.2: Assign pixel SOM clusters"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -539,15 +518,13 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### 3.3: Run pixel consensus clustering"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -562,7 +539,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -609,23 +585,20 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## 4: Visualize results"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### 4.1: Interactive adjustments to relabel pixel meta clusters"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -648,7 +621,7 @@
     "### Other features and notes\n",
     "- You will likely need to zoom out to see the entire visualization. To toggle Zoom, use Ctrl -/Ctrl + on Windows or ⌘ +/⌘ - on Mac.\n",
     "- The bars at the top show the number of pixels in each SOM cluster.\n",
-    "- The text box at the bottom right allows you to rename a particular meta cluster. This can be useful as remapping may cause inconsistent numbering.\n",
+    "- The text box at the bottom right allows you to rename a particular meta cluster. This can be useful as remapping may cause inconsistent numbering. **You cannot use the same name for different meta clusters; doing so will cause the next step to fail.**\n",
     "- Adjust the z-score limit using the slider on the bottom left to adjust your dynamic range.\n",
     "- When meta clusters are combined or a meta cluster is renamed, the change is immediately saved to `pixel_meta_cluster_remap_name`.\n",
     "- You won't be able to advance in the notebook until you've clicked `New metacluster` or renamed a meta cluster at least once. If you don't want to make changes, just click `New metacluster` to trigger a save before continuing."
@@ -677,7 +650,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -718,7 +690,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -742,7 +713,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -802,7 +772,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -866,15 +835,13 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## 5: Save parameters for use in cell clustering"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -918,7 +885,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -966,7 +932,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.16"
+   "version": "3.8.15"
   },
   "toc-autonumbering": false,
   "toc-showcode": true,