Add standard deviation to grants review recap for vote divergence (#4532)

Author: estyxx

backend/reviews/admin.py

@@ -13,6 +13,7 @@
     OuterRef,
     Prefetch,
     Q,
+    StdDev,
     Subquery,
     Sum,
 )
@@ -426,6 +427,10 @@ def _review_grants_recap_view(self, request, review_session):
                     F("total_score") / F("vote_count"),
                     output_field=FloatField(),
                 ),
+                std_dev=StdDev(
+                    "userreview__score__numeric_value",
+                    filter=Q(userreview__review_session_id=review_session_id),
+                ),
                 has_sent_a_proposal=Exists(
                     Submission.objects.non_cancelled().filter(
                         speaker_id=OuterRef("user_id"),

backend/reviews/templates/grants-recap.html

@@ -181,6 +181,74 @@
   tr:nth-of-type(odd) {
     background-color: var(--body-bg);
   }
+
+  /* Tooltip */
+  .tooltip {
+    position: relative;
+    display: inline-block;
+  }
+
+  .tooltip .tooltiptext {
+    visibility: hidden;
+    opacity: 0;
+    width: 220px;
+    background-color: #333;
+    color: #fff;
+    text-align: left;
+    text-transform: none;
+    padding: 8px 10px;
+    border-radius: 6px;
+    position: absolute;
+    z-index: 1;
+    top: 125%;
+    left: 50%;
+    margin-left: -110px;
+    font-size: 12px;
+    font-weight: normal;
+    line-height: 1.4;
+    transition: opacity 0.2s ease-in-out 0.5s, visibility 0.2s ease-in-out 0.5s;
+  }
+
+  .tooltip .tooltiptext::after {
+    content: "";
+    position: absolute;
+    bottom: 100%;
+    left: 50%;
+    margin-left: -5px;
+    border-width: 5px;
+    border-style: solid;
+    border-color: transparent transparent #333 transparent;
+  }
+
+  .tooltip:hover .tooltiptext {
+    visibility: visible;
+    opacity: 1;
+  }
+
+  /* Sortable columns */
+  .sortable {
+    cursor: pointer;
+    user-select: none;
+  }
+
+  .sortable:hover {
+    text-decoration: underline;
+  }
+
+  /* Center-align columns */
+  .results-table th:nth-child(1), /* number column */
+  .results-table th:nth-child(3), /* score column */
+  .results-table th:nth-child(4), /* std dev column */
+  .results-table th:nth-child(6), /* current status column */
+  .results-table th:nth-child(7), /* pending status column */
+  .results-table td:nth-child(1), /* number column */
+  .results-table td:nth-child(3), /* score column */
+  .results-table td:nth-child(4), /* std dev column */
+  .results-table td:nth-child(6), /* current status column */
+  .results-table td:nth-child(7) /* pending status column */
+  {
+    text-align: center;
+  }
 </style>
 <script type="application/javascript">
   const grantsById = {};
@@ -372,6 +440,84 @@
       {% endfor %}
 
   };
+
+  // Sorting functionality
+  const sortTable = (sortBy, direction) => {
+      const tbody = document.querySelector('#result_list tbody');
+      const rows = Array.from(tbody.querySelectorAll('tr.grant-item'));
+
+      rows.sort((a, b) => {
+          let aVal, bVal;
+
+          if (sortBy === 'score') {
+              aVal = parseFloat(a.dataset.score);
+              bVal = parseFloat(b.dataset.score);
+          } else if (sortBy === 'std_dev') {
+              aVal = parseFloat(a.dataset.stdDev);
+              bVal = parseFloat(b.dataset.stdDev);
+          }
+
+          // Handle null/NaN values - push them to the end
+          if (isNaN(aVal)) aVal = direction === 'desc' ? -Infinity : Infinity;
+          if (isNaN(bVal)) bVal = direction === 'desc' ? -Infinity : Infinity;
+
+          if (direction === 'desc') {
+              return bVal - aVal;
+          } else {
+              return aVal - bVal;
+          }
+      });
+
+      // Re-append rows in sorted order and update row numbers
+      rows.forEach((row, index) => {
+          row.querySelector('td:first-child').textContent = index + 1;
+          tbody.appendChild(row);
+      });
+  };
+
+  const initSorting = () => {
+      document.querySelectorAll('.sortable').forEach(header => {
+          header.addEventListener('click', (e) => {
+              e.stopPropagation();
+              const sortBy = header.dataset.sort;
+              let currentDir = header.dataset.sortDir;
+
+              // Toggle direction
+              let newDir;
+              if (currentDir === 'desc') {
+                  newDir = 'asc';
+              } else {
+                  newDir = 'desc';
+              }
+
+              // Update all sortable headers
+              document.querySelectorAll('.sortable').forEach(h => {
+                  h.dataset.sortDir = '';
+                  // Remove arrow from text, keeping tooltip if present
+                  const tooltipSpan = h.querySelector('.tooltiptext');
+                  if (tooltipSpan) {
+                      h.childNodes[0].textContent = h.childNodes[0].textContent.replace(/ [▲▼]/, '');
+                  } else {
+                      h.textContent = h.textContent.replace(/ [▲▼]/, '');
+                  }
+              });
+
+              // Set new direction and arrow
+              header.dataset.sortDir = newDir;
+              const arrow = newDir === 'desc' ? ' ▼' : ' ▲';
+              const tooltipSpan = header.querySelector('.tooltiptext');
+              if (tooltipSpan) {
+                  header.childNodes[0].textContent = header.childNodes[0].textContent.trim() + arrow;
+              } else {
+                  header.textContent = header.textContent.trim() + arrow;
+              }
+
+              sortTable(sortBy, newDir);
+          });
+      });
+  };
+
+  window.addEventListener('load', initSorting);
 </script>
 <ul class="object-tools">
   <li>
@@ -428,7 +574,15 @@ <h3>
                 </th>
                 <th scope="col">
                   <div class="text">
-                    <a>Score</a>
+                    <span class="sortable" data-sort="score" data-sort-dir="desc">Score ▼</span>
+                  </div>
+                  <div class="clear"></div>
+                </th>
+                <th scope="col">
+                  <div class="text">
+                    <span class="tooltip sortable" data-sort="std_dev" data-sort-dir="">Std Dev
+                      <span class="tooltiptext">Standard Deviation: measures reviewer disagreement. High value = controversial (needs discussion), Low value = consensus.</span>
+                    </span>
                   </div>
                   <div class="clear"></div>
                 </th>
@@ -481,6 +635,8 @@ <h3>
                 id="grant-{{ item.id }}"
                 data-type="{{ item.type }}"
                 data-num-of-votes="{{ item.userreview_set.count }}"
+                data-score="{{ item.score|default_if_none:'-999' }}"
+                data-std-dev="{{ item.std_dev|default_if_none:'-1' }}"
               >
                 <td>{{ forloop.counter }}</td>
                 <td class="results-item">
@@ -573,6 +729,7 @@ <h3>
                   </ul>
                 </td>
                 <td>{{ item.score }}</td>
+                <td>{{ item.std_dev|floatformat:2 }}</td>
                 <td class="votes-list">
                   <ul>
                     {% for reviewer in item.userreview_set.all %}

backend/reviews/tests/test_admin.py

@@ -191,6 +191,124 @@ def test_grants_review_scores(rf, scores, avg):
     assert grant_to_check.score == avg
 
 
+@pytest.mark.parametrize(
+    "scores, expected_std_dev",
+    [
+        # Multiple different scores: mean=0.6, std_dev ≈ 1.744
+        (
+            [
+                {"user": 0, "score": 2},
+                {"user": 1, "score": 2},
+                {"user": 2, "score": 2},
+                {"user": 3, "score": -1},
+                {"user": 4, "score": -2},
+            ],
+            1.744,
+        ),
+        # All same scores: std_dev = 0
+        (
+            [
+                {"user": 0, "score": -2},
+                {"user": 1, "score": -2},
+                {"user": 2, "score": -2},
+                {"user": 3, "score": -2},
+                {"user": 4, "score": -2},
+            ],
+            0.0,
+        ),
+        # Single score: std_dev = 0
+        (
+            [
+                {"user": 0, "score": 1},
+            ],
+            0.0,
+        ),
+        # No scores: std_dev = None
+        ([], None),
+        # Two different scores (1 and -1): mean=0, std_dev = sqrt(((1-0)^2 + (-1-0)^2) / 2) = 1.0
+        (
+            [
+                {"user": 0, "score": 1},
+                {"user": 1, "score": -1},
+            ],
+            1.0,
+        ),
+        # Three scores with same value: std_dev = 0
+        (
+            [
+                {"user": 0, "score": 1},
+                {"user": 1, "score": 1},
+                {"user": 2, "score": 1},
+            ],
+            0.0,
+        ),
+        # Mixed scores showing consensus with outlier: 3x score=1, 1x score=-2
+        # mean = (1+1+1-2)/4 = 0.25
+        # std_dev = sqrt(((1-0.25)^2 + (1-0.25)^2 + (1-0.25)^2 + (-2-0.25)^2) / 4)
+        #         = sqrt((0.5625 + 0.5625 + 0.5625 + 5.0625) / 4) = sqrt(1.6875) ≈ 1.299
+        (
+            [
+                {"user": 0, "score": 1},
+                {"user": 1, "score": 1},
+                {"user": 2, "score": 1},
+                {"user": 3, "score": -2},
+            ],
+            1.299,
+        ),
+    ],
+)
+def test_grants_review_std_dev(rf, scores, expected_std_dev):
+    conference = ConferenceFactory()
+    review_session = ReviewSessionFactory(
+        conference=conference,
+        session_type=ReviewSession.SessionType.GRANTS,
+        status=ReviewSession.Status.COMPLETED,
+    )
+
+    users = UserFactory.create_batch(10, is_staff=True, is_superuser=True)
+    all_scores = {
+        -2: AvailableScoreOptionFactory(
+            review_session=review_session, numeric_value=-2, label="Rejected"
+        ),
+        -1: AvailableScoreOptionFactory(
+            review_session=review_session, numeric_value=-1, label="Not convinced"
+        ),
+        0: AvailableScoreOptionFactory(
+            review_session=review_session, numeric_value=0, label="Maybe"
+        ),
+        1: AvailableScoreOptionFactory(
+            review_session=review_session, numeric_value=1, label="Yes"
+        ),
+        2: AvailableScoreOptionFactory(
+            review_session=review_session, numeric_value=2, label="Absolutely"
+        ),
+    }
+
+    grant = GrantFactory(conference=conference)
+    for score in scores:
+        UserReviewFactory(
+            review_session=review_session,
+            grant=grant,
+            user=users[score["user"]],
+            score=all_scores[score["score"]],
+        )
+
+    request = rf.get("/")
+    request.user = users[5]
+
+    admin = ReviewSessionAdmin(ReviewSession, AdminSite())
+    response = admin._review_grants_recap_view(request, review_session)
+    context_data = response.context_data
+    items = context_data["items"]
+    grant_to_check = next(item for item in items if item.id == grant.id)
+
+    assert grant_to_check.id == grant.id
+    if expected_std_dev is None:
+        assert grant_to_check.std_dev is None
+    else:
+        assert grant_to_check.std_dev == pytest.approx(expected_std_dev, abs=0.01)
+
+
 def test_review_start_view_when_no_items_are_left(rf, mocker):
     mock_messages = mocker.patch("reviews.admin.messages")