feat(occurrence-stats): drop ORDER threshold; add coarsest_rank query param

Replaces hardcoded `lca >= TaxonRank.ORDER` agreement gate with two layers:

- Always returned: `agreed_any_rank_*` — exact matches plus any non-null LCA
  at a real rank (UNKNOWN excluded). The upstream filter (e.g. a Lepidoptera
  include list) is what bounds the meaningful scope, not a hardcoded
  threshold in this function.
- Optional `?agreement_coarsest_rank=FAMILY`: when supplied, response also
  includes `agreed_coarser_rank_*` (exact + LCAs at or below the threshold).
  The applied rank is echoed in `agreement_coarsest_rank`; null when absent.

Also addresses CodeRabbit feedback on the existing branch:
- Dedupe base queryset before counting (joins from default-filter chain can
  inflate Occurrence rows).
- Bound `*_pct` FloatFields to [0.0, 1.0] in the serializer.

Param validation: invalid rank → 400; UNKNOWN rejected as not meaningful.
Tests cover any-rank fallback, threshold filtering, invalid + UNKNOWN
rejection, and threshold echo.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

ami/main/api/serializers.py

@@ -1754,31 +1754,70 @@ class TopIdentifiersResponseSerializer(serializers.Serializer):
 class ModelAgreementSerializer(serializers.Serializer):
     """Verified / agreement rates over the filtered Occurrence set.
 
-    `agreed_exact_count` is a subset of `agreed_under_order_count` by
-    construction — an exact match implies an LCA at SPECIES, which is
-    deeper than ORDER. `*_pct` percentages are 0.0..1.0 (not 0..100).
+    `agreed_exact_count` is a subset of `agreed_any_rank_count` by
+    construction — an exact match implies the LCA is the taxon itself.
+    `*_pct` percentages are 0.0..1.0 (not 0..100).
 
     Denominator note: `agreed_*_pct` divide by `verified_with_prediction_count`
     (verified occurrences that *also* have a machine prediction), NOT by
     `verified_count`. A verified occurrence with no machine prediction can't
     agree or disagree — including it in the denominator would drag the rate
     down without representing actual model disagreement. `no_prediction_count`
     is surfaced so the consumer can see how many such occurrences exist.
+
+    Optional rank threshold: when the caller passes
+    `?agreement_coarsest_rank=FAMILY`, the response also includes
+    `agreed_coarser_rank_*` counting only LCAs at that rank or deeper. The
+    threshold rank is echoed in `agreement_coarsest_rank`. When the param is
+    absent, the coarser-rank fields are null and `agreement_coarsest_rank`
+    is null.
     """
 
     project_id = serializers.IntegerField()
     total_occurrences = serializers.IntegerField()
     verified_count = serializers.IntegerField(help_text="Occurrences with at least one non-withdrawn identification.")
-    verified_pct = serializers.FloatField(help_text="verified_count / total_occurrences")
+    verified_pct = serializers.FloatField(
+        min_value=0.0,
+        max_value=1.0,
+        help_text="verified_count / total_occurrences",
+    )
     verified_with_prediction_count = serializers.IntegerField(
         help_text="Verified occurrences that also have a machine prediction (denominator for agreed_*_pct)."
     )
     no_prediction_count = serializers.IntegerField(
         help_text="Verified occurrences with no machine prediction (excluded from agreement denominator)."
     )
     agreed_exact_count = serializers.IntegerField()
-    agreed_exact_pct = serializers.FloatField(help_text="agreed_exact_count / verified_with_prediction_count")
-    agreed_under_order_count = serializers.IntegerField()
-    agreed_under_order_pct = serializers.FloatField(
-        help_text="agreed_under_order_count / verified_with_prediction_count"
+    agreed_exact_pct = serializers.FloatField(
+        min_value=0.0,
+        max_value=1.0,
+        help_text="agreed_exact_count / verified_with_prediction_count",
+    )
+    agreed_any_rank_count = serializers.IntegerField(
+        help_text="Exact matches plus disagreements whose LCA is at any real rank (UNKNOWN excluded)."
+    )
+    agreed_any_rank_pct = serializers.FloatField(
+        min_value=0.0,
+        max_value=1.0,
+        help_text="agreed_any_rank_count / verified_with_prediction_count",
+    )
+    agreement_coarsest_rank = serializers.CharField(
+        allow_null=True,
+        required=False,
+        help_text="Threshold rank from ?agreement_coarsest_rank query param. Null when the param is absent.",
+    )
+    agreed_coarser_rank_count = serializers.IntegerField(
+        allow_null=True,
+        required=False,
+        help_text=(
+            "Exact matches plus disagreements whose LCA is at `agreement_coarsest_rank` or deeper. "
+            "Null when no threshold was supplied."
+        ),
+    )
+    agreed_coarser_rank_pct = serializers.FloatField(
+        min_value=0.0,
+        max_value=1.0,
+        allow_null=True,
+        required=False,
+        help_text="agreed_coarser_rank_count / verified_with_prediction_count. Null when no threshold supplied.",
     )

ami/main/api/views.py

@@ -56,6 +56,7 @@
     Tag,
     TaxaList,
     Taxon,
+    TaxonRank,
     User,
     update_detection_counts,
 )
@@ -1390,15 +1391,34 @@ def model_agreement(self, request):
         Accepts every query param the `/occurrences/` list endpoint accepts.
         Reuses `apply_default_filters` so `apply_defaults=false` bypasses
         project default taxa lists + score thresholds.
+
+        Optional ?agreement_coarsest_rank=<RANK> adds `agreed_coarser_rank_*`
+        counts — LCAs at the given rank or deeper. Valid values: any
+        TaxonRank name (FAMILY, GENUS, etc.); invalid → 400.
         """
         project = self.get_active_project()
         assert project is not None  # require_project=True guarantees this
         if not Project.objects.visible_for_user(request.user).filter(pk=project.pk).exists():
             raise NotFound("Project not found.")
 
+        coarsest_rank_param = request.query_params.get("agreement_coarsest_rank")
+        coarsest_rank = None
+        if coarsest_rank_param:
+            try:
+                coarsest_rank = TaxonRank[coarsest_rank_param.upper()]
+            except KeyError:
+                valid = ", ".join(r.name for r in TaxonRank if r.name != "UNKNOWN")
+                raise api_exceptions.ValidationError(
+                    {"agreement_coarsest_rank": f"Invalid rank '{coarsest_rank_param}'. Must be one of: {valid}."}
+                )
+            if coarsest_rank == TaxonRank.UNKNOWN:
+                raise api_exceptions.ValidationError(
+                    {"agreement_coarsest_rank": "UNKNOWN is not a valid threshold rank."}
+                )
+
         base_qs = Occurrence.objects.filter(project=project).valid().apply_default_filters(project, request)
         filtered_qs = self.filter_queryset(base_qs)
-        payload = model_agreement_for_project(filtered_qs)
+        payload = model_agreement_for_project(filtered_qs, coarsest_rank=coarsest_rank)
         payload["project_id"] = project.pk
         return Response(ModelAgreementSerializer(payload, context={"request": request}).data)
 

ami/main/models_future/occurrence.py

@@ -163,7 +163,10 @@ def detection_image_urls_from_prefetch(occurrence: Occurrence, limit: int | None
     return [get_media_url(det.path) for det in detections]
 
 
-def model_agreement_for_project(queryset: QuerySet[Occurrence]) -> dict:
+def model_agreement_for_project(
+    queryset: QuerySet[Occurrence],
+    coarsest_rank: TaxonRank | None = None,
+) -> dict:
     """Verified / agreement stats over a pre-filtered Occurrence queryset.
 
     The queryset MUST already be filtered to the project + user-supplied
@@ -174,9 +177,16 @@ def model_agreement_for_project(queryset: QuerySet[Occurrence]) -> dict:
 
     "Verified" means the occurrence has at least one non-withdrawn
     Identification. "Model prediction" means the Classification chosen by
-    BEST_MACHINE_PREDICTION_ORDER. "Under-order" agreement means the user's
-    taxon and the model's prediction share an ancestor at rank >= ORDER
-    (inclusive of ORDER itself).
+    BEST_MACHINE_PREDICTION_ORDER. "Any-rank" agreement means the user's
+    taxon and the model's prediction share an ancestor at any real rank
+    (UNKNOWN excluded) — exact matches included. The upstream filter (e.g.
+    a Lepidoptera include list) is what bounds the meaningful scope, not
+    a hardcoded rank threshold in this function.
+
+    When ``coarsest_rank`` is supplied, additionally compute "coarser-rank"
+    agreement: the LCA must be at ``coarsest_rank`` or deeper (e.g. passing
+    FAMILY only counts LCAs at FAMILY, GENUS, or SPECIES). Exact matches
+    always count regardless of rank.
 
     Performance: the heavy work — correlated subqueries over Identification
     and Classification — is scoped to the verified set, which is typically
@@ -198,6 +208,10 @@ def model_agreement_for_project(queryset: QuerySet[Occurrence]) -> dict:
 
     from ami.main.models import BEST_IDENTIFICATION_ORDER, Identification, Taxon
 
+    # Default filters can join Identification (verified_by_me) and Taxon
+    # parents_json (taxa_list_id) which inflates row count if not deduped.
+    # Dedupe up front so total + verified counts share one canonical set.
+    queryset = queryset.distinct()
     total = queryset.count()
 
     best_user_ident = Identification.objects.filter(occurrence=OuterRef("pk"), withdrawn=False).order_by(
@@ -244,32 +258,43 @@ def model_agreement_for_project(queryset: QuerySet[Occurrence]) -> dict:
             ]
             taxa_by_id[t.pk] = (t.pk, t.rank, parents)
 
-    under_order_disagreement_count = 0
+    any_rank_disagreement_count = 0
+    coarser_rank_disagreement_count = 0
     for (u_id, m_id), count in pair_counts.items():
         u = taxa_by_id.get(u_id)
         m = taxa_by_id.get(m_id)
         if not u or not m:
             continue
         lca = lca_rank_between(u, m)
-        if lca is not None and lca >= TaxonRank.ORDER:
-            under_order_disagreement_count += count
+        if lca is None:
+            continue
+        any_rank_disagreement_count += count
+        if coarsest_rank is not None and lca >= coarsest_rank:
+            coarser_rank_disagreement_count += count
 
-    agreed_under_order = agreed_exact + under_order_disagreement_count
+    agreed_any_rank = agreed_exact + any_rank_disagreement_count
+    agreed_coarser_rank = agreed_exact + coarser_rank_disagreement_count
 
     def _pct(num: int, denom: int) -> float:
         return round(num / denom, 4) if denom else 0.0
 
-    return {
+    payload: dict = {
         "total_occurrences": total,
         "verified_count": verified,
         "verified_pct": _pct(verified, total),
         "verified_with_prediction_count": verified_with_pred,
         "no_prediction_count": no_prediction,
         "agreed_exact_count": agreed_exact,
         "agreed_exact_pct": _pct(agreed_exact, verified_with_pred),
-        "agreed_under_order_count": agreed_under_order,
-        "agreed_under_order_pct": _pct(agreed_under_order, verified_with_pred),
+        "agreed_any_rank_count": agreed_any_rank,
+        "agreed_any_rank_pct": _pct(agreed_any_rank, verified_with_pred),
+        "agreement_coarsest_rank": coarsest_rank.name if coarsest_rank is not None else None,
+        "agreed_coarser_rank_count": agreed_coarser_rank if coarsest_rank is not None else None,
+        "agreed_coarser_rank_pct": (
+            _pct(agreed_coarser_rank, verified_with_pred) if coarsest_rank is not None else None
+        ),
     }
+    return payload
 
 
 def top_identifiers_for_project(project: Project) -> QuerySet[User]:

ami/main/tests.py

@@ -4803,8 +4803,9 @@ def test_unknown_rank_excluded_from_lca(self):
 class TestModelAgreementForProject(APITestCase):
     """Aggregation function over a filtered Occurrence queryset.
 
-    Covers the four bucket transitions: unverified, verified+exact-agreed,
-    verified+under-order-agreed, verified+disagreed-above-order.
+    Covers four bucket transitions: unverified, verified+exact-agreed,
+    verified+any-rank-agreed (no threshold), verified+disagreed-no-shared-rank.
+    Optional coarsest_rank threshold cases handled in the viewset tests below.
     """
 
     def setUp(self) -> None:
@@ -4842,7 +4843,11 @@ def test_empty_project_returns_zeros_not_nans(self):
         self.assertEqual(result["verified_count"], 0)
         self.assertEqual(result["verified_pct"], 0.0)
         self.assertEqual(result["agreed_exact_pct"], 0.0)
-        self.assertEqual(result["agreed_under_order_pct"], 0.0)
+        self.assertEqual(result["agreed_any_rank_pct"], 0.0)
+        # No threshold passed → coarser-rank fields null.
+        self.assertIsNone(result["agreement_coarsest_rank"])
+        self.assertIsNone(result["agreed_coarser_rank_count"])
+        self.assertIsNone(result["agreed_coarser_rank_pct"])
 
     def test_buckets_canonical_cases(self):
         from ami.main.models_future.occurrence import model_agreement_for_project
@@ -4851,20 +4856,43 @@ def test_buckets_canonical_cases(self):
         self.assertEqual(len(occurrences), 4)
         # 0: verified, machine == user (exact agreement at SPECIES)
         self._identify(occurrences[0], self.vanessa_atalanta)
-        # 1: verified, sister species (under-order at GENUS)
+        # 1: verified, sister species (LCA at GENUS)
         self._identify(occurrences[1], self.vanessa_cardui)
-        # 2: verified, different family same order (under-order at ORDER)
+        # 2: verified, different family same order (LCA at ORDER)
         self._identify(occurrences[2], self.pieris_brassicae)
         # 3: unverified
 
         result = model_agreement_for_project(Occurrence.objects.filter(project=self.project))
         self.assertEqual(result["total_occurrences"], 4)
         self.assertEqual(result["verified_count"], 3)
         self.assertEqual(result["agreed_exact_count"], 1)
-        self.assertEqual(result["agreed_under_order_count"], 3)
+        self.assertEqual(result["agreed_any_rank_count"], 3)
         self.assertAlmostEqual(result["verified_pct"], 0.75)
         self.assertAlmostEqual(result["agreed_exact_pct"], 1 / 3, places=3)
-        self.assertAlmostEqual(result["agreed_under_order_pct"], 1.0)
+        self.assertAlmostEqual(result["agreed_any_rank_pct"], 1.0)
+
+    def test_coarsest_rank_threshold_filters_shallow_lcas(self):
+        """With coarsest_rank=FAMILY, an ORDER-only LCA pair is excluded."""
+        from ami.main.models import TaxonRank
+        from ami.main.models_future.occurrence import model_agreement_for_project
+
+        occurrences = list(Occurrence.objects.filter(project=self.project).order_by("pk"))
+        # 0: exact (SPECIES) — counts in both
+        self._identify(occurrences[0], self.vanessa_atalanta)
+        # 1: sister species (LCA = GENUS, deeper than FAMILY) — counts in both
+        self._identify(occurrences[1], self.vanessa_cardui)
+        # 2: different family same order (LCA = ORDER, NOT >= FAMILY) — counts in any_rank only
+        self._identify(occurrences[2], self.pieris_brassicae)
+
+        result = model_agreement_for_project(
+            Occurrence.objects.filter(project=self.project),
+            coarsest_rank=TaxonRank.FAMILY,
+        )
+        self.assertEqual(result["agreed_any_rank_count"], 3)
+        self.assertEqual(result["agreement_coarsest_rank"], "FAMILY")
+        # exact + GENUS LCA = 2; ORDER LCA excluded
+        self.assertEqual(result["agreed_coarser_rank_count"], 2)
+        self.assertAlmostEqual(result["agreed_coarser_rank_pct"], 2 / 3, places=3)
 
 
 class TestOccurrenceStatsViewSet(APITestCase):
@@ -4973,7 +5001,11 @@ def test_agreement_empty_returns_zero_pcts(self):
         self.assertEqual(body["verified_count"], 0)
         self.assertEqual(body["verified_pct"], 0.0)
         self.assertEqual(body["agreed_exact_pct"], 0.0)
-        self.assertEqual(body["agreed_under_order_pct"], 0.0)
+        self.assertEqual(body["agreed_any_rank_pct"], 0.0)
+        # No ?agreement_coarsest_rank → threshold + coarser fields null.
+        self.assertIsNone(body["agreement_coarsest_rank"])
+        self.assertIsNone(body["agreed_coarser_rank_count"])
+        self.assertIsNone(body["agreed_coarser_rank_pct"])
 
     def test_agreement_happy_path(self):
         """One verified occurrence; user agrees with the machine prediction → exact match.
@@ -4996,15 +5028,14 @@ def test_agreement_happy_path(self):
         self.assertEqual(body["verified_with_prediction_count"], 1)
         self.assertEqual(body["no_prediction_count"], 0)
         self.assertEqual(body["agreed_exact_count"], 1)
-        self.assertEqual(body["agreed_under_order_count"], 1)
+        self.assertEqual(body["agreed_any_rank_count"], 1)
 
-    def test_agreement_under_order_bucket(self):
-        """Disagreement at species but same genus → counted under-order, not exact.
+    def test_agreement_any_rank_bucket(self):
+        """Disagreement at species but same genus → counted as any-rank agreement, not exact.
 
         Pick the machine prediction's sister species (same parent genus) for the
-        identification. LCA between the two species is GENUS, which is >= ORDER,
-        so the occurrence falls into the under-order bucket without contributing
-        to agreed_exact_count.
+        identification. LCA between the two species is GENUS, so the occurrence
+        falls into the any-rank bucket without contributing to agreed_exact_count.
         """
         occurrence = Occurrence.objects.filter(project=self.project).order_by("pk").first()
         machine_taxon = occurrence.detections.first().classifications.first().taxon
@@ -5024,10 +5055,34 @@ def test_agreement_under_order_bucket(self):
         self.assertEqual(body["verified_count"], 1)
         self.assertEqual(body["verified_with_prediction_count"], 1)
         self.assertEqual(body["agreed_exact_count"], 0)
-        self.assertEqual(body["agreed_under_order_count"], 1)
-        # 0/1 exact, 1/1 under-order
+        self.assertEqual(body["agreed_any_rank_count"], 1)
+        # 0/1 exact, 1/1 any-rank
         self.assertEqual(body["agreed_exact_pct"], 0.0)
-        self.assertEqual(body["agreed_under_order_pct"], 1.0)
+        self.assertEqual(body["agreed_any_rank_pct"], 1.0)
+
+    def test_agreement_coarsest_rank_invalid_returns_400(self):
+        response = self.client.get(
+            f"{self.agreement_url}?project_id={self.project.pk}&agreement_coarsest_rank=GARBAGE"
+        )
+        self.assertEqual(response.status_code, 400)
+        self.assertIn("agreement_coarsest_rank", response.json())
+
+    def test_agreement_coarsest_rank_unknown_rejected(self):
+        """UNKNOWN is a real enum member but not a meaningful threshold."""
+        response = self.client.get(
+            f"{self.agreement_url}?project_id={self.project.pk}&agreement_coarsest_rank=UNKNOWN"
+        )
+        self.assertEqual(response.status_code, 400)
+
+    def test_agreement_coarsest_rank_echoed_in_response(self):
+        response = self.client.get(f"{self.agreement_url}?project_id={self.project.pk}&agreement_coarsest_rank=family")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        # Param is case-insensitive; response echoes enum name (uppercase).
+        self.assertEqual(body["agreement_coarsest_rank"], "FAMILY")
+        # No verified occurrences in this fixture → coarser fields present but zero.
+        self.assertEqual(body["agreed_coarser_rank_count"], 0)
+        self.assertEqual(body["agreed_coarser_rank_pct"], 0.0)
 
     def test_agreement_filter_passthrough(self):
         """`?deployment=` should narrow the set."""