Support for default category taxonomy (#164)

* Made taxonomy names optional

* Added tests for default taxonomy

* bug fixes

* Fixed doc string in annotation.py

* New version number

Author: cmpajot

nucleus/annotation.py

@@ -515,25 +515,25 @@ class CategoryAnnotation(Annotation):
 
         category = CategoryAnnotation(
             label="dress",
-            taxonomy_name="clothing_type",
             reference_id="image_1",
+            taxonomy_name="clothing_type",
             metadata={"dress_color": "navy"}
         )
 
     Parameters:
         label (str): The label for this annotation.
-        taxonomy_name (str): The name of the taxonomy this annotation conforms to.
-          See :meth:`Dataset.add_taxonomy`.
         reference_id (str): User-defined ID of the image to which to apply this annotation.
+        taxonomy_name (Optional[str]): The name of the taxonomy this annotation conforms to.
+          See :meth:`Dataset.add_taxonomy`.
         metadata (Optional[Dict]): Arbitrary key/value dictionary of info to attach to this annotation.
           Strings, floats and ints are supported best by querying and insights
           features within Nucleus. For more details see our `metadata guide
           <https://nucleus.scale.com/docs/upload-metadata>`_.
     """
 
     label: str
-    taxonomy_name: str
     reference_id: str
+    taxonomy_name: Optional[str] = None
     metadata: Optional[Dict] = None
 
     def __post_init__(self):
@@ -543,29 +543,31 @@ def __post_init__(self):
     def from_json(cls, payload: dict):
         return cls(
             label=payload[LABEL_KEY],
-            taxonomy_name=payload[TAXONOMY_NAME_KEY],
             reference_id=payload[REFERENCE_ID_KEY],
+            taxonomy_name=payload.get(TAXONOMY_NAME_KEY, None),
             metadata=payload.get(METADATA_KEY, {}),
         )
 
     def to_payload(self) -> dict:
-        return {
+        payload = {
             LABEL_KEY: self.label,
-            TAXONOMY_NAME_KEY: self.taxonomy_name,
             TYPE_KEY: CATEGORY_TYPE,
             GEOMETRY_KEY: {},
             REFERENCE_ID_KEY: self.reference_id,
             METADATA_KEY: self.metadata,
         }
+        if self.taxonomy_name is not None:
+            payload[TAXONOMY_NAME_KEY] = self.taxonomy_name
+        return payload
 
 
 @dataclass
 class MultiCategoryAnnotation(Annotation):
     """This class is not yet supported: MultiCategory annotation support coming soon!"""
 
     labels: List[str]
-    taxonomy_name: str
     reference_id: str
+    taxonomy_name: Optional[str] = None
     metadata: Optional[Dict] = None
 
     def __post_init__(self):
@@ -575,20 +577,22 @@ def __post_init__(self):
     def from_json(cls, payload: dict):
         return cls(
             labels=payload[LABELS_KEY],
-            taxonomy_name=payload[TAXONOMY_NAME_KEY],
             reference_id=payload[REFERENCE_ID_KEY],
+            taxonomy_name=payload.get(TAXONOMY_NAME_KEY, None),
             metadata=payload.get(METADATA_KEY, {}),
         )
 
     def to_payload(self) -> dict:
-        return {
+        payload = {
             LABELS_KEY: self.labels,
-            TAXONOMY_NAME_KEY: self.taxonomy_name,
             TYPE_KEY: MULTICATEGORY_TYPE,
             GEOMETRY_KEY: {},
             REFERENCE_ID_KEY: self.reference_id,
             METADATA_KEY: self.metadata,
         }
+        if self.taxonomy_name is not None:
+            payload[TAXONOMY_NAME_KEY] = self.taxonomy_name
+        return payload
 
 
 def is_local_path(path: str) -> bool:

nucleus/prediction.py

@@ -348,9 +348,9 @@ class CategoryPrediction(CategoryAnnotation):
 
     Parameters:
         label: The label for this annotation (e.g. car, pedestrian, bicycle).
+        reference_id: The reference ID of the image you wish to apply this annotation to.
         taxonomy_name: The name of the taxonomy this annotation conforms to.
           See :meth:`Dataset.add_taxonomy`.
-        reference_id: The reference ID of the image you wish to apply this annotation to.
         confidence: 0-1 indicating the confidence of the prediction.
         class_pdf: An optional complete class probability distribution on this
             prediction. Each value should be between 0 and 1 (inclusive), and sum up to
@@ -365,8 +365,8 @@ class CategoryPrediction(CategoryAnnotation):
     def __init__(
         self,
         label: str,
-        taxonomy_name: str,
         reference_id: str,
+        taxonomy_name: Optional[str] = None,
         confidence: Optional[float] = None,
         metadata: Optional[Dict] = None,
         class_pdf: Optional[Dict] = None,

tests/helpers.py

@@ -168,6 +168,14 @@ def reference_id_from_url(url):
     for i in range(len(TEST_IMG_URLS))
 ]
 
+TEST_DEFAULT_CATEGORY_ANNOTATIONS = [
+    {
+        "label": f"[Pytest] Category Label ${i}",
+        "reference_id": reference_id_from_url(TEST_IMG_URLS[i]),
+    }
+    for i in range(len(TEST_IMG_URLS))
+]
+
 TEST_MULTICATEGORY_ANNOTATIONS = [
     {
         "labels": [
@@ -180,6 +188,17 @@ def reference_id_from_url(url):
     for i in range(len(TEST_IMG_URLS))
 ]
 
+TEST_DEFAULT_MULTICATEGORY_ANNOTATIONS = [
+    {
+        "labels": [
+            f"[Pytest] MultiCategory Label ${i}",
+            f"[Pytest] MultiCategory Label ${i+1}",
+        ],
+        "reference_id": reference_id_from_url(TEST_IMG_URLS[i]),
+    }
+    for i in range(len(TEST_IMG_URLS))
+]
+
 TEST_MASK_URL = "https://raw.githubusercontent.com/scaleapi/nucleus-python-client/master/tests/testdata/000000000285.png"
 
 TEST_SEGMENTATION_ANNOTATIONS = [
@@ -253,6 +272,20 @@ def reference_id_from_url(url):
     for i in range(len(TEST_CATEGORY_ANNOTATIONS))
 ]
 
+TEST_DEFAULT_CATEGORY_PREDICTIONS = [
+    {
+        **TEST_DEFAULT_CATEGORY_ANNOTATIONS[i],
+        "confidence": 0.10 * i,
+        "class_pdf": TEST_CATEGORY_MODEL_PDF,
+    }
+    if i != 0
+    else {
+        **TEST_DEFAULT_CATEGORY_ANNOTATIONS[i],
+        "confidence": 0.10 * i,
+    }
+    for i in range(len(TEST_DEFAULT_CATEGORY_ANNOTATIONS))
+]
+
 TEST_INDEX_EMBEDDINGS_FILE = "https://raw.githubusercontent.com/scaleapi/nucleus-python-client/master/tests/testdata/pytest_embeddings_payload.json"
 
 
@@ -310,18 +343,20 @@ def assert_category_annotation_matches_dict(
     annotation_instance, annotation_dict
 ):
     assert annotation_instance.label == annotation_dict["label"]
-    assert (
-        annotation_instance.taxonomy_name == annotation_dict["taxonomy_name"]
-    )
+    if annotation_instance.taxonomy_name:
+        assert annotation_instance.taxonomy_name == annotation_dict.get(
+            "taxonomy_name", None
+        )
 
 
 def assert_multicategory_annotation_matches_dict(
     annotation_instance, annotation_dict
 ):
     assert set(annotation_instance.labels) == set(annotation_dict["labels"])
-    assert (
-        annotation_instance.taxonomy_name == annotation_dict["taxonomy_name"]
-    )
+    if annotation_instance.taxonomy_name:
+        assert annotation_instance.taxonomy_name == annotation_dict.get(
+            "taxonomy_name", None
+        )
 
 
 def assert_segmentation_annotation_matches_dict(