refactor: only allow wrapped NonSurgeryInjections in Procedures.subject_procedures (#1802)

* refactor: only allow Injections in Procedures.subject_procedures when wrapped with an InjectionProcedure

* chore: add ethics_review_id/protocol_id

* fix: only allow Injection, BrainInjection requires a full CS from Surgery

* update docs [skip actions]

* refactor: NonSurgicalInjection

* update docs

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: dbirman

docs/source/components/injection_procedures.md

@@ -12,7 +12,7 @@ Description of an injection procedure
 | `targeted_structure` | Optional[[MouseAnatomyModel](../aind_data_schema_models/external.md#mouseanatomymodel)] | Injection target (Use InjectionTargets) |
 | `relative_position` | Optional[List[[AnatomicalRelative](../aind_data_schema_models/coordinates.md#anatomicalrelative)]] | Relative position  |
 | `dynamics` | List[[InjectionDynamics](#injectiondynamics)] | Injection dynamics (List of injection events, one per location/depth) |
-| `protocol_id` | `Optional[str]` | Protocol ID (DOI for protocols.io) |
+| <del>`protocol_id`</del> | `Optional[str]` | **[DEPRECATED]** Use protocol_id in Surgery or NonSurgicalInjection instead. Protocol ID (DOI for protocols.io) |
 
 
 ### InjectionDynamics

docs/source/components/subject_procedures.md

@@ -16,6 +16,20 @@ Description of a non-surgical procedure performed on a subject
 | `notes` | `Optional[str]` | Notes  |
 
 
+### NonSurgicalInjection
+
+Injection procedure performed outside of surgery,
+which may include one or more injections at different locations/depths
+
+| Field | Type | Title (Description) |
+|-------|------|-------------|
+| `start_date` | `datetime.date` | Start date  |
+| `ethics_review_id` | `str` | Ethics review ID  |
+| `protocol_id` | `Optional[str]` | Protocol ID (DOI for protocols.io) |
+| `injections` | List[[Injection](injection_procedures.md#injection)] | Injections  |
+| `notes` | `Optional[str]` | Notes  |
+
+
 ### Surgery
 
 Description of subject procedures performed at one time

docs/source/components/surgery_procedures.md

@@ -26,7 +26,7 @@ Description of an injection procedure into a brain
 | `injection_materials` | List[[ViralMaterial](injection_procedures.md#viralmaterial) or [NonViralMaterial](injection_procedures.md#nonviralmaterial)] | Injection material  |
 | `relative_position` | Optional[List[[AnatomicalRelative](../aind_data_schema_models/coordinates.md#anatomicalrelative)]] | Relative position  |
 | `dynamics` | List[[InjectionDynamics](injection_procedures.md#injectiondynamics)] | Injection dynamics (List of injection events, one per location/depth) |
-| `protocol_id` | `Optional[str]` | Protocol ID (DOI for protocols.io) |
+| <del>`protocol_id`</del> | `Optional[str]` | **[DEPRECATED]** Use protocol_id in Surgery or NonSurgicalInjection instead. Protocol ID (DOI for protocols.io) |
 
 
 ### CatheterImplant

docs/source/procedures.md

@@ -27,7 +27,7 @@ Description of all procedures performed on a subject, including surgeries, injec
 | Field | Type | Title (Description) |
 |-------|------|-------------|
 | `subject_id` | `str` | Subject ID (Unique identifier for the subject of data acquisition) |
-| `subject_procedures` | List[[Surgery](components/subject_procedures.md#surgery) or [Injection](components/injection_procedures.md#injection) or [TrainingProtocol](components/subject_procedures.md#trainingprotocol) or [WaterRestriction](components/subject_procedures.md#waterrestriction) or [GenericSubjectProcedure](components/subject_procedures.md#genericsubjectprocedure)] | Subject Procedures (Procedures performed on a live subject) |
+| `subject_procedures` | List[[Surgery](components/subject_procedures.md#surgery) or [Injection](components/injection_procedures.md#injection) or [NonSurgicalInjection](components/subject_procedures.md#nonsurgicalinjection) or [TrainingProtocol](components/subject_procedures.md#trainingprotocol) or [WaterRestriction](components/subject_procedures.md#waterrestriction) or [GenericSubjectProcedure](components/subject_procedures.md#genericsubjectprocedure)] | Subject Procedures (Procedures performed on a live subject) |
 | `specimen_procedures` | List[[SpecimenProcedure](components/specimen_procedures.md#specimenprocedure)] | Specimen Procedures (Procedures performed on tissue extracted after perfusion) |
 | `coordinate_system` | Optional[[CoordinateSystem](components/coordinates.md#coordinatesystem)] | Coordinate System (Origin and axis definitions for determining the configured position of devices implanted during procedures. Required when coordinates are provided within the Procedures) |
 | `notes` | `Optional[str]` | Notes  |

src/aind_data_schema/components/injection_procedures.py

@@ -116,4 +116,9 @@ class Injection(DataModel):
     dynamics: List[InjectionDynamics] = Field(
         ..., title="Injection dynamics", description="List of injection events, one per location/depth"
     )
-    protocol_id: Optional[str] = Field(default=None, title="Protocol ID", description="DOI for protocols.io")
+    protocol_id: Optional[str] = Field(
+        default=None,
+        title="Protocol ID",
+        description="DOI for protocols.io",
+        deprecated="Use protocol_id in Surgery or NonSurgicalInjection instead",
+    )

src/aind_data_schema/components/subject_procedures.py

@@ -39,6 +39,18 @@ class GenericSubjectProcedure(DataModel):
     notes: Optional[str] = Field(default=None, title="Notes")
 
 
+class NonSurgicalInjection(DataModel):
+    """Injection procedure performed outside of surgery,
+    which may include one or more injections at different locations/depths
+    """
+
+    start_date: date = Field(..., title="Start date")
+    ethics_review_id: str = Field(..., title="Ethics review ID")
+    protocol_id: Optional[str] = Field(default=None, title="Protocol ID", description="DOI for protocols.io")
+    injections: List[Injection] = Field(..., title="Injections", min_length=1)
+    notes: Optional[str] = Field(default=None, title="Notes")
+
+
 class TrainingProtocol(DataModel):
     """Description of an animal training protocol"""
 

src/aind_data_schema/core/procedures.py

@@ -1,5 +1,6 @@
 """schema for various Procedures"""
 
+import warnings
 from typing import List, Literal, Optional
 
 from pydantic import Field, SkipValidation, model_validator
@@ -13,6 +14,7 @@
     Surgery,
     TrainingProtocol,
     WaterRestriction,
+    NonSurgicalInjection,
 )
 from aind_data_schema.utils.merge import merge_coordinate_systems, merge_notes
 from aind_data_schema.utils.validators import subject_specimen_id_compatibility
@@ -31,7 +33,7 @@ class Procedures(DataCoreModel):
         title="Subject ID",
     )
     subject_procedures: DiscriminatedList[
-        Surgery | Injection | TrainingProtocol | WaterRestriction | GenericSubjectProcedure
+        Surgery | Injection | NonSurgicalInjection | TrainingProtocol | WaterRestriction | GenericSubjectProcedure
     ] = Field(default=[], title="Subject Procedures", description="Procedures performed on a live subject")
     specimen_procedures: List[SpecimenProcedure] = Field(
         default=[], title="Specimen Procedures", description="Procedures performed on tissue extracted after perfusion"
@@ -72,6 +74,22 @@ def get_device_names(self) -> List[str]:
 
         return list(device_names)
 
+    @model_validator(mode="after")
+    def reject_injections(self):
+        """Raise a warning for injections since they should now be wrapped
+        in a Surgery or NonSurgicalInjection procedure
+        """
+
+        for procedure in self.subject_procedures:
+            if isinstance(procedure, Injection):
+                warnings.warn(
+                    "Injection procedures should be wrapped in a Surgery or NonSurgicalInjection procedure.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        return self
+
     @model_validator(mode="after")
     def validate_subject_specimen_ids(self):
         """Validate that the subject_id and specimen_id match"""

tests/test_procedures.py

@@ -53,6 +53,29 @@ def test_required_field_validation_check(self):
         p = Procedures(subject_id="12345")
         self.assertEqual("12345", p.subject_id)
 
+    @patch("aind_data_schema_models.mouse_anatomy.get_emapa_id")
+    def test_unwrapped_injection_warns(self, mock_get_emapa_id):
+        """Unwrapped Injection in subject_procedures should emit a UserWarning"""
+        mock_get_emapa_id.return_value = "123456"
+        with self.assertWarns(UserWarning):
+            Procedures(
+                subject_id="12345",
+                subject_procedures=[
+                    Injection(
+                        injection_materials=[NonViralMaterial(name="saline", source=Organization.OTHER)],
+                        dynamics=[
+                            InjectionDynamics(
+                                volume=1,
+                                volume_unit=VolumeUnit.UL,
+                                duration=1,
+                                duration_unit=TimeUnit.S,
+                                profile=InjectionProfile.BOLUS,
+                            )
+                        ],
+                    )
+                ],
+            )
+
     @patch("aind_data_schema_models.mouse_anatomy.get_emapa_id")
     def test_injection_material_check(self, mock_get_emapa_id):
         """Check for validation error when injection_materials is empty"""