feat: add support for calibration objects (#1471)

* feat: add support for phantoms

Phantom implemented as a Device

* refactor: phantom has a description and optional list of component devices

* refactor: Phantom -> Calibration object

* feat: new validator for calibration tag

* tests: adding coverage

* chore: lint

* tests: repair tests that were broken by a merge

* chore: lint

* tests: coverage for new validator

* fix: code got removed at some point

Author: dbirman

examples/data_description.py

@@ -11,7 +11,7 @@
 
 d = DataDescription(
     modalities=[Modality.ECEPHYS, Modality.BEHAVIOR_VIDEOS],
-    subject_id="12345",
+    subject_id="123456",
     creation_time=datetime(2022, 2, 21, 16, 30, 1, tzinfo=timezone.utc),
     institution=Organization.AIND,
     investigators=[Person(name="Daniel Birman", registry_identifier="0000-0003-3748-6289")],  # Include ORCID IDs

src/aind_data_schema/components/subjects.py

@@ -12,6 +12,7 @@
 from pydantic_core.core_schema import ValidationInfo
 
 from aind_data_schema.base import DataModel
+from aind_data_schema.components.devices import Device
 from aind_data_schema.utils.validators import TimeValidation
 
 
@@ -140,3 +141,15 @@ class HumanSubject(DataModel):
         description="Where the subject was acquired from.",
         title="Source",
     )
+
+
+class CalibrationObject(DataModel):
+    """Description of a calibration object"""
+
+    empty: bool = Field(
+        default=False, title="Empty", description="Set to true if the calibration was performed with no object."
+    )
+    description: str = Field(..., title="Description")
+    objects: Optional[list[Device]] = Field(
+        default=None, title="Objects", description="For calibration objects that are built up from one or more devices."
+    )

src/aind_data_schema/core/metadata.py

@@ -20,6 +20,7 @@
 
 from aind_data_schema.base import DataCoreModel
 from aind_data_schema.components.identifiers import DatabaseIdentifiers
+from aind_data_schema.components.subjects import CalibrationObject
 from aind_data_schema.core.acquisition import Acquisition
 from aind_data_schema.core.data_description import DataDescription
 from aind_data_schema.core.instrument import Instrument
@@ -242,6 +243,29 @@ def validate_acquisition_connections(self):
 
         return self
 
+    @model_validator(mode="after")
+    def validate_calibration_object_tags(self):
+        """Validator to ensure 'calibration' tag is present when subject is a CalibrationObject"""
+
+        if (
+            self.subject
+            and self.subject.subject_details
+            and isinstance(self.subject.subject_details, CalibrationObject)
+            and self.data_description
+        ):
+            if self.data_description.tags is None:
+                # Initialize tags list if it doesn't exist
+                self.data_description.tags = []
+
+            if "calibration" not in self.data_description.tags:
+                warnings.warn(
+                    "Subject is a CalibrationObject but 'calibration' tag is missing from data_description.tags. "
+                    "Adding 'calibration' tag automatically."
+                )
+                self.data_description.tags.append("calibration")
+
+        return self
+
     @model_validator(mode="after")
     def validate_training_protocol_references(self):
         """Validate that training_protocol_name in StimulusEpoch matches a TrainingProtocol in procedures"""

src/aind_data_schema/core/subject.py

@@ -5,7 +5,7 @@
 from pydantic import Field, SkipValidation
 
 from aind_data_schema.base import DataCoreModel, Discriminated
-from aind_data_schema.components.subjects import HumanSubject, MouseSubject
+from aind_data_schema.components.subjects import HumanSubject, MouseSubject, CalibrationObject
 
 
 class Subject(DataCoreModel):
@@ -20,6 +20,8 @@ class Subject(DataCoreModel):
         title="Subject ID",
     )
 
-    subject_details: Discriminated[MouseSubject | HumanSubject] = Field(..., title="Subject Details")
+    subject_details: Discriminated[MouseSubject | HumanSubject | CalibrationObject] = Field(
+        ..., title="Subject Details"
+    )
 
     notes: Optional[str] = Field(default=None, title="Notes")

tests/test_metadata.py

@@ -13,7 +13,7 @@
 from aind_data_schema.components.coordinates import CoordinateSystemLibrary
 from aind_data_schema.components.devices import EphysAssembly, EphysProbe, Laser, Manipulator
 from aind_data_schema.components.identifiers import Code, Database, Person
-from aind_data_schema.components.subjects import BreedingInfo, Housing, MouseSubject, Sex, Species
+from aind_data_schema.components.subjects import BreedingInfo, Housing, MouseSubject, Sex, Species, CalibrationObject
 from aind_data_schema.components.surgery_procedures import BrainInjection
 from aind_data_schema.core.acquisition import Acquisition, AcquisitionSubjectDetails, DataStream
 from aind_data_schema.core.data_description import DataDescription, Funding
@@ -29,6 +29,9 @@
 from aind_data_schema.components.subject_procedures import TrainingProtocol
 from aind_data_schema.core.acquisition import StimulusEpoch
 
+from examples.data_description import d as data_description
+
+
 EXAMPLES_DIR = Path(__file__).parents[1] / "examples"
 EPHYS_INST_JSON = EXAMPLES_DIR / "ephys_instrument.json"
 EPHYS_SESSION_JSON = EXAMPLES_DIR / "ephys_acquisition.json"
@@ -786,6 +789,36 @@ def test_validate_time_constraints_processing(self):
         self.assertIn("must be after", str(context.exception))
         self.assertIn("start_date_time", str(context.exception))
 
+    def test_validate_calibration_object_tags(self):
+        """Tests that calibration tag warning is issued when subject is CalibrationObject but tag is missing"""
+
+        # Create a subject with CalibrationObject
+        calibration_subject = Subject(
+            subject_id="calibration_object_001",
+            subject_details=CalibrationObject(
+                description="Test calibration object",
+            ),
+        )
+
+        # Use the existing data_description from class setup (which doesn't have 'calibration' tag)
+
+        # This should trigger a warning since subject is CalibrationObject but no 'calibration' tag
+        with self.assertWarns(UserWarning) as w:
+            metadata = Metadata(
+                name="Test Metadata",
+                location="Test Location",
+                subject=calibration_subject,
+                data_description=data_description,
+            )
+
+        warning_messages = [str(warning.message) for warning in w.warnings]
+        self.assertIn(
+            "Subject is a CalibrationObject but 'calibration' tag is missing from data_description.tags. "
+            "Adding 'calibration' tag automatically.",
+            warning_messages,
+        )
+        self.assertIsNotNone(metadata)
+
 
 if __name__ == "__main__":
     unittest.main()