Add ability to unflip individual signs in get_corrected_centroid_guesses() helper.

Author: patcon

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Add `print_selected_statements()` presenter for inspecting `PolisClusteringResult`.
 - Add `print_consensus_statements()` presenter for inspecting `PolisClusteringResult`.
 - Allow `pick_max` and `confidence` interval args to be set in `polis.run_clustering()`.
+- Allow `get_corrected_centroid_guesses()` to unflip each axis if correction not needed.
 
 ### Chores
 

docs/notebooks/polis-implementation-demo.ipynb

@@ -132,7 +132,7 @@
         "# We can run this from scratch, but kmeans is non-deterministic and might find slightly different clusters\n",
         "# or even different k-values (number of groups) if the silhouette scores it finds are better.\n",
         "# To show how to reproduce Polis results, we'll set init guess coordinates that we know polis platform got:\n",
-        "init_cluster_center_guesses = get_corrected_centroid_guesses(math_data, skip_correction=False)\n",
+        "init_cluster_center_guesses = get_corrected_centroid_guesses(math_data)\n",
         "print(f\"{init_cluster_center_guesses=}\")"
       ],
       "metadata": {

docs/notebooks/polis-implementation-results-docs.ipynb

@@ -172,7 +172,7 @@
         "# Prepare some optional data to kickstart\n",
         "\n",
         "# KMeans is only reproducible when it starts with previous cluster center guesses.\n",
-        "INIT_CLUSTER_CENTER_GUESSES = get_corrected_centroid_guesses(loader.math_data, skip_correction=False)\n",
+        "INIT_CLUSTER_CENTER_GUESSES = get_corrected_centroid_guesses(loader.math_data)\n",
         "\n",
         "# Polis has some edge-cases logic that keeps arbitrary [early] participants in\n",
         "# the clustering algorithm for reasons that are hard to reproduce, so we\n",

reddwarf/utils/polismath.py

@@ -156,15 +156,16 @@ def create_bidirectional_id_maps(base_clusters):
 def get_corrected_centroid_guesses(
     polis_math_data: dict,
     source: Literal["group-clusters", "base-clusters"] = "group-clusters",
-    skip_correction: bool = False,
+    flip_x: bool = True,
+    flip_y: bool = True,
 ):
     """
     A helper to extract and correct centroid guesses from polismath data.
 
     This is helpful to seed new rounds of KMeans locally.
 
     NOTE: It seems that there's an inversion somewhere in the polis codebase, and so
-    we need to invert their coordinates in relation to ours.
+    we usually (but not always) need to invert their coordinates in relation to ours.
 
     Given the consistency of this intervention, it's likely not a PCA artifact,
     and instead relates to using inverting the sign of agree/disagree in
@@ -177,7 +178,8 @@ def get_corrected_centroid_guesses(
     Arguments:
         polis_math_data (dict): The polismath data from the Polis API
         source (str): Where to extract centroid data from. One of "group-clusters" or "base-clusters".
-        skip_correction (bool): Whether to skip correction (helpful for debugging)
+        flip_x (bool): Whether to correctively flip X sign (usually helpful)
+        flip_y (bool): Whether to correctively flip Y sign (usually helpful)
 
     Returns:
         centroids: A list of centroid [x,y] coord guesses
@@ -197,8 +199,11 @@ def get_corrected_centroid_guesses(
         # Defensive fallback in case `source` comes from dynamic or untyped input
         raise ValueError(f"Unknown source '{source}'. Must be 'group-clusters' or 'base-clusters'.")
 
-    if skip_correction:
-        return extracted_centroids
-    else:
-        corrected_centroids = [[-xy[0], -xy[1]] for xy in extracted_centroids]
-        return corrected_centroids
+    corrected_centroids = [
+        [
+            -xy[0] if flip_x else xy[0],
+            -xy[1] if flip_y else xy[1],
+        ] for xy in extracted_centroids
+    ]
+
+    return corrected_centroids

tests/utils/test_polismath.py

@@ -2,6 +2,7 @@
 from reddwarf.utils import polismath
 from tests.fixtures import polis_convo_data
 from reddwarf.utils import matrix as MatrixUtils
+from reddwarf.utils.polismath import get_corrected_centroid_guesses
 from reddwarf.data_loader import Loader
 
 # TODO: Figure out if in-conv is always equivalent. If so, remove this test.
@@ -45,6 +46,43 @@ def test_user_vote_count_sanity_check(polis_convo_data):
 
     assert expected_user_vote_counts == actual_user_vote_counts.to_dict()
 
-@pytest.mark.skip
-def test_get_corrected_centroid_guesses():
-    raise NotImplementedError
+@pytest.fixture
+def mock_math_data():
+    return {
+        "group-clusters": [
+            {"center": [1.0, 2.0]},
+            {"center": [-3.0, 4.0]}
+        ],
+        "base-clusters": {
+            "x": [5.0, -6.0],
+            "y": [7.0, -8.0]
+        }
+    }
+
+def test_get_corrected_centroid_guesses_default_flip(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data)
+    assert result == [[-1.0, -2.0], [3.0, -4.0]]
+
+def test_get_corrected_centroid_guesses_unflip_x(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data, flip_x=False)
+    assert result == [[1.0, -2.0], [-3.0, -4.0]]
+
+def test_get_corrected_centroid_guesses_unflip_y(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data, flip_y=False)
+    assert result == [[-1.0, 2.0], [3.0, 4.0]]
+
+def test_get_corrected_centroid_guesses_group_unflip_both(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data, source="group-clusters", flip_x=False, flip_y=False)
+    assert result == [[1.0, 2.0], [-3.0, 4.0]]
+
+def test_get_corrected_centroid_guesses_base_clusters_unflip_x(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data, source="base-clusters", flip_x=False)
+    assert result == [[5.0, -7.0], [-6.0, 8.0]]
+
+def test_get_corrected_centroid_guesses_base_clusters_unflip_y(mock_math_data):
+    result = get_corrected_centroid_guesses(mock_math_data, source="base-clusters", flip_y=False)
+    assert result == [[-5.0, 7.0], [6.0, -8.0]]
+
+def test_get_corrected_centroid_guesses_unknown_source(mock_math_data):
+    with pytest.raises(ValueError, match="Unknown source 'invalid-source'"):
+        get_corrected_centroid_guesses(mock_math_data, source="invalid-source")