Validate feature: setting baseline models (#266)

add new set model as baseline functions to client, remove add_criteria in favor of add_eval_function, bump version number and changelog

Author: sasha-scale

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to the [Nucleus Python Client](https://github.com/scaleapi/n
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.3](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.8.3) - 2022-03-29
+
+### Added
+- new Validate functionality to intialize scenario tests without a threshold, and to set test thresholds based on a baseline model.
 ## [0.8.2](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.8.2) - 2022-03-18
 
 ### Added

cli/tests.py

@@ -109,7 +109,7 @@ def build_scenario_test_info_tree(client, scenario_test, tree):
         slice_branch.add(f"name: '{slice_info['name']}'")
         slice_branch.add(f"len: {len(slc.items)}")
         slice_branch.add(f"url: {slice_url}")
-        criteria = scenario_test.get_criteria()
+        criteria = scenario_test.get_eval_functions()
         criteria_branch = tree.add(":crossed_flags: Criteria")
         for criterion in criteria:
             pretty_criterion = format_criterion(

nucleus/validate/client.py

@@ -4,13 +4,13 @@
 from nucleus.job import AsyncJob
 
 from .constants import SCENARIO_TEST_ID_KEY
-from .data_transfer_objects.eval_function import (
-    EvaluationCriterion,
-    GetEvalFunctions,
-)
+from .data_transfer_objects.eval_function import GetEvalFunctions
 from .data_transfer_objects.scenario_test import CreateScenarioTestRequest
 from .errors import CreateScenarioTestError
-from .eval_functions.available_eval_functions import AvailableEvalFunctions
+from .eval_functions.available_eval_functions import (
+    AvailableEvalFunctions,
+    EvalFunction,
+)
 from .scenario_test import ScenarioTest
 
 SUCCESS_KEY = "success"
@@ -51,7 +51,7 @@ def create_scenario_test(
         self,
         name: str,
         slice_id: str,
-        evaluation_criteria: List[EvaluationCriterion],
+        evaluation_functions: List[EvalFunction],
     ) -> ScenarioTest:
         """Creates a new Scenario Test from an existing Nucleus :class:`Slice`:. ::
 
@@ -61,28 +61,30 @@ def create_scenario_test(
             scenario_test = client.validate.create_scenario_test(
                 name="sample_scenario_test",
                 slice_id="YOUR_SLICE_ID",
-                evaluation_criteria=[client.validate.eval_functions.bbox_iou() > 0.5]
+                evaluation_functions=[client.validate.eval_functions.bbox_iou()]
             )
 
         Args:
             name: unique name of test
             slice_id: id of (pre-defined) slice of items to evaluate test on.
-            evaluation_criteria: :class:`EvaluationCriterion` defines a pass/fail criteria for the test. Created with a
-                comparison with an eval functions. See :class:`eval_functions`.
+            evaluation_functions: :class:`EvalFunctionEntry` defines an evaluation metric for the test.
+            Created with an element from the list of available eval functions. See :class:`eval_functions`.
 
         Returns:
             Created ScenarioTest object.
         """
-        if not evaluation_criteria:
+        if not evaluation_functions:
             raise CreateScenarioTestError(
-                "Must pass an evaluation_criteria to the scenario test! I.e. "
-                "evaluation_criteria = [client.validate.eval_functions.bbox_iou() > 0.5]"
+                "Must pass an evaluation_function to the scenario test! I.e. "
+                "evaluation_functions=[client.validate.eval_functions.bbox_iou()]"
             )
         response = self.connection.post(
             CreateScenarioTestRequest(
                 name=name,
                 slice_id=slice_id,
-                evaluation_criteria=evaluation_criteria,
+                evaluation_functions=[
+                    ef.to_entry() for ef in evaluation_functions  # type:ignore
+                ],
             ).dict(),
             "validate/scenario_test",
         )

nucleus/validate/constants.py

@@ -9,6 +9,7 @@
 THRESHOLD_KEY = "threshold"
 SCENARIO_TEST_ID_KEY = "scenario_test_id"
 SCENARIO_TEST_NAME_KEY = "scenario_test_name"
+SCENARIO_TEST_METRICS_KEY = "scenario_test_metrics"
 
 
 class ThresholdComparison(str, Enum):

nucleus/validate/data_transfer_objects/scenario_test.py

@@ -4,13 +4,13 @@
 
 from nucleus.pydantic_base import ImmutableModel
 
-from .eval_function import EvaluationCriterion
+from .eval_function import EvalFunctionEntry
 
 
 class CreateScenarioTestRequest(ImmutableModel):
     name: str
     slice_id: str
-    evaluation_criteria: List[EvaluationCriterion]
+    evaluation_functions: List[EvalFunctionEntry]
 
     @validator("slice_id")
     def startswith_slice_indicator(cls, v):  # pylint: disable=no-self-argument

nucleus/validate/data_transfer_objects/scenario_test_metric.py

@@ -1,12 +1,8 @@
 from nucleus.pydantic_base import ImmutableModel
 
-from ..constants import ThresholdComparison
 
-
-class AddScenarioTestMetric(ImmutableModel):
+class AddScenarioTestFunction(ImmutableModel):
     """Data transfer object to add a scenario test."""
 
     scenario_test_name: str
     eval_function_id: str
-    threshold: float
-    threshold_comparison: ThresholdComparison

nucleus/validate/eval_functions/base_eval_function.py

@@ -58,3 +58,6 @@ def _op_to_test_metric(self, comparison: ThresholdComparison, value):
             threshold_comparison=comparison,
             threshold=value,
         )
+
+    def to_entry(self):
+        return self.eval_func_entry

nucleus/validate/scenario_test.py

@@ -5,14 +5,22 @@
 and have confidence that they’re always shipping the best model.
 """
 from dataclasses import dataclass, field
-from typing import List
+from typing import List, Optional
 
 from ..connection import Connection
 from ..constants import NAME_KEY, SLICE_ID_KEY
 from ..dataset_item import DatasetItem
-from .data_transfer_objects.eval_function import EvaluationCriterion
+from .constants import (
+    EVAL_FUNCTION_ID_KEY,
+    SCENARIO_TEST_ID_KEY,
+    SCENARIO_TEST_METRICS_KEY,
+    THRESHOLD_COMPARISON_KEY,
+    THRESHOLD_KEY,
+    ThresholdComparison,
+)
 from .data_transfer_objects.scenario_test_evaluations import GetEvalHistory
-from .data_transfer_objects.scenario_test_metric import AddScenarioTestMetric
+from .data_transfer_objects.scenario_test_metric import AddScenarioTestFunction
+from .eval_functions.available_eval_functions import EvalFunction
 from .scenario_test_evaluation import ScenarioTestEvaluation
 from .scenario_test_metric import ScenarioTestMetric
 
@@ -36,6 +44,7 @@ class ScenarioTest:
     connection: Connection = field(repr=False)
     name: str = field(init=False)
     slice_id: str = field(init=False)
+    baseline_model_id: Optional[str] = None
 
     def __post_init__(self):
         # TODO(gunnar): Remove this pattern. It's too slow. We should get all the info required in one call
@@ -45,10 +54,10 @@ def __post_init__(self):
         self.name = response[NAME_KEY]
         self.slice_id = response[SLICE_ID_KEY]
 
-    def add_criterion(
-        self, evaluation_criterion: EvaluationCriterion
+    def add_eval_function(
+        self, eval_function: EvalFunction
     ) -> ScenarioTestMetric:
-        """Creates and adds a new criteria to the :class:`ScenarioTest`. ::
+        """Creates and adds a new evaluation metric to the :class:`ScenarioTest`. ::
 
             import nucleus
             client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
@@ -58,49 +67,52 @@ def add_criterion(
 
             e = client.validate.eval_functions
             # Assuming a user would like to add all available public evaluation functions as criteria
-            scenario_test.add_criterion(
-                e.bbox_iou() > 0.5
+            scenario_test.add_eval_function(
+                e.bbox_iou
             )
-            scenario_test.add_criterion(
-                e.bbox_map() > 0.85
+            scenario_test.add_eval_function(
+                e.bbox_map
             )
-            scenario_test.add_criterion(
-                e.bbox_precision() > 0.7
+            scenario_test.add_eval_function(
+                e.bbox_precision
             )
-            scenario_test.add_criterion(
-                e.bbox_recall() > 0.6
+            scenario_test.add_eval_function(
+                e.bbox_recall
             )
 
         Args:
-            evaluation_criterion: :class:`EvaluationCriterion` created by comparison with an :class:`EvalFunction`
+            eval_function: :class:`EvalFunction`
 
         Returns:
             The created ScenarioTestMetric object.
         """
         response = self.connection.post(
-            AddScenarioTestMetric(
+            AddScenarioTestFunction(
                 scenario_test_name=self.name,
-                eval_function_id=evaluation_criterion.eval_function_id,
-                threshold=evaluation_criterion.threshold,
-                threshold_comparison=evaluation_criterion.threshold_comparison,
+                eval_function_id=eval_function.id,
             ).dict(),
-            "validate/scenario_test_metric",
+            "validate/scenario_test_eval_function",
         )
+        print(response)
         return ScenarioTestMetric(
-            scenario_test_id=response["scenario_test_id"],
-            eval_function_id=response["eval_function_id"],
-            threshold=evaluation_criterion.threshold,
-            threshold_comparison=evaluation_criterion.threshold_comparison,
+            scenario_test_id=response[SCENARIO_TEST_ID_KEY],
+            eval_function_id=response[EVAL_FUNCTION_ID_KEY],
+            threshold=response.get(THRESHOLD_KEY, None),
+            threshold_comparison=response.get(
+                THRESHOLD_COMPARISON_KEY,
+                ThresholdComparison.GREATER_THAN_EQUAL_TO,
+            ),
+            connection=self.connection,
         )
 
-    def get_criteria(self) -> List[ScenarioTestMetric]:
+    def get_eval_functions(self) -> List[ScenarioTestMetric]:
         """Retrieves all criteria of the :class:`ScenarioTest`. ::
 
             import nucleus
             client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
             scenario_test = client.validate.scenario_tests[0]
 
-            scenario_test.get_criteria()
+            scenario_test.get_eval_functions()
 
         Returns:
             A list of ScenarioTestMetric objects.
@@ -109,8 +121,8 @@ def get_criteria(self) -> List[ScenarioTestMetric]:
             f"validate/scenario_test/{self.id}/metrics",
         )
         return [
-            ScenarioTestMetric(**metric)
-            for metric in response["scenario_test_metrics"]
+            ScenarioTestMetric(**metric, connection=self.connection)
+            for metric in response[SCENARIO_TEST_METRICS_KEY]
         ]
 
     def get_eval_history(self) -> List[ScenarioTestEvaluation]:
@@ -141,3 +153,24 @@ def get_items(self) -> List[DatasetItem]:
         return [
             DatasetItem.from_json(item) for item in response[DATASET_ITEMS_KEY]
         ]
+
+    def set_baseline_model(self, model_id: str):
+        """Set's a new baseline model for the ScenarioTest.  In order to be eligible to be a baseline,
+        this scenario test must have been evaluated using that model.  The baseline model's performance
+        is used as the threshold for all metrics against which other models are compared.
+
+            import nucleus
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            scenario_test = client.validate.scenario_tests[0]
+
+            scenario_test.set_baseline_model('my_baseline_model_id')
+
+        Returns:
+            A list of :class:`ScenarioTestEvaluation` objects.
+        """
+        response = self.connection.post(
+            {},
+            f"validate/scenario_test/{self.id}/set_baseline_model/{model_id}",
+        )
+        self.baseline_model_id = response.get("baseline_model_id")
+        return self.baseline_model_id

nucleus/validate/scenario_test_metric.py

@@ -1,14 +1,33 @@
-from nucleus.pydantic_base import ImmutableModel
+from dataclasses import dataclass, field
+from typing import Dict, Optional
 
+from ..connection import Connection
 from .constants import ThresholdComparison
 
 
-class ScenarioTestMetric(ImmutableModel):
+@dataclass
+class ScenarioTestMetric:
     """A Scenario Test Metric is an evaluation function combined with a comparator and associated with a Scenario Test.
     Scenario Test Metrics serve as the basis when evaluating a Model on a Scenario Test.
     """
 
     scenario_test_id: str
     eval_function_id: str
-    threshold: float
-    threshold_comparison: ThresholdComparison
+    threshold: Optional[float]
+    connection: Connection
+    eval_func_arguments: Optional[Dict] = field(default_factory=dict)
+    threshold_comparison: ThresholdComparison = (
+        ThresholdComparison.GREATER_THAN_EQUAL_TO
+    )
+
+    def set_threshold(self, threshold: Optional[float] = None) -> None:
+        """Sets the threshold of the metric to the new value passed in as a parameters.
+        Attributes:
+            threshold (str): The ID of the scenario test.
+        """
+        payload = {"threshold": threshold}
+        response = self.connection.post(
+            payload,
+            f"validate/metric/set_threshold/{self.scenario_test_id}/{self.eval_function_id}",
+        )
+        self.threshold = response.get("threshold")

pyproject.toml

@@ -21,7 +21,7 @@ exclude = '''
 
 [tool.poetry]
 name = "scale-nucleus"
-version = "0.8.2"
+version = "0.8.3"
 description = "The official Python client library for Nucleus, the Data Platform for AI"
 license =  "MIT"
 authors = ["Scale AI Nucleus Team <nucleusapi@scaleapi.com>"]