feat: adding Manipulation during acquisition (#1607)

* feat: adding Manipulation during acquisition

* docs: build docs for Manipulation

Author: dbirman

docs/base/core/acquisition.md

@@ -27,6 +27,10 @@ For example, in the `"Brain Computer Interface"` project name, good acquisition
 
 You should use the `Code.parameters` field to store your stimulus properties for each [StimulusEpoch](#stimulusepoch). We have pre-existing parameter schemas for a subset of stimuli defined [here](components/stimulus.md) or you can define your own schema.
 
+## Manipulations
+
+Procedures that occur during an acquisition (between the start_time and end_time) should be recorded in the `Acquisition.manipulations` using a [Manipulation](#manipulation). 
+
 ## FAQs
 
 ### When should a DataStream be split in two

docs/source/acquisition.md

@@ -27,6 +27,10 @@ For example, in the `"Brain Computer Interface"` project name, good acquisition
 
 You should use the `Code.parameters` field to store your stimulus properties for each [StimulusEpoch](#stimulusepoch). We have pre-existing parameter schemas for a subset of stimuli defined [here](components/stimulus.md) or you can define your own schema.
 
+## Manipulations
+
+Procedures that occur during an acquisition (between the start_time and end_time) should be recorded in the `Acquisition.manipulations` using a [Manipulation](#manipulation). 
+
 ## FAQs
 
 ### When should a DataStream be split in two
@@ -88,6 +92,7 @@ while the StimulusEpoch represents all stimuli being presented.
 | `maintenance` | List[[Maintenance](components/measurements.md#maintenance)] | Maintenance (List of maintenance on instrument prior to acquisition.) |
 | `data_streams` | List[[DataStream](acquisition.md#datastream)] | Data streams (A data stream is a collection of devices that are acquiring data simultaneously. Each acquisition can include multiple streams. Streams should be split when configurations are changed.) |
 | `stimulus_epochs` | List[[StimulusEpoch](acquisition.md#stimulusepoch)] | Stimulus (A stimulus epoch captures all stimuli being presented during an acquisition. Epochs should be split when the purpose of the stimulus changes.) |
+| `manipulations` | List[[Manipulation](acquisition.md#manipulation)] | Manipulations (Procedures performed during the acquisition.) |
 | `subject_details` | Optional[[AcquisitionSubjectDetails](acquisition.md#acquisitionsubjectdetails)] | Subject details  |
 
 
@@ -102,7 +107,7 @@ Details about the subject during an acquisition
 | `animal_weight_prior` | `Optional[decimal.Decimal]` | Animal weight (g) (Animal weight before procedure) |
 | `animal_weight_post` | `Optional[decimal.Decimal]` | Animal weight (g) (Animal weight after procedure) |
 | `weight_unit` | [MassUnit](aind_data_schema_models/units.md#massunit) | Weight unit  |
-| `anaesthesia` | Optional[[Anaesthetic](components/surgery_procedures.md#anaesthetic)] | Anaesthesia  |
+| `anaesthesia` | Optional[[Anaesthetic](components/surgery_procedures.md#anaesthetic)] | Anaesthesia (Anaesthesia present during entire acquisition, use Manipulation for partial anaesthesia) |
 | `mouse_platform_name` | `str` | Mouse platform  |
 | `reward_consumed_total` | `Optional[decimal.Decimal]` | Total reward consumed (mL)  |
 | `reward_consumed_unit` | Optional[[VolumeUnit](aind_data_schema_models/units.md#volumeunit)] | Reward consumed unit  |
@@ -125,6 +130,19 @@ same time.
 | `connections` | List[[Connection](components/connections.md#connection)] | Connections (Connections are links between devices that are specific to this acquisition (i.e. not already defined in the Instrument)) |
 
 
+### Manipulation
+
+Description of procedures performed during an acquisition.
+
+| Field | Type | Title (Description) |
+|-------|------|-------------|
+| `start_time` | `datetime (timezone-aware)` | Manipulation start time (Must be between the acquisition start and end times) |
+| `end_time` | `datetime (timezone-aware)` | Manipulation end time (Must be between the acquisition start and end times) |
+| `procedures` | Optional[List[[Injection](components/injection_procedures.md#injection) or [BrainInjection](components/surgery_procedures.md#braininjection)]] | Procedures (Procedures performed during the manipulation) |
+| `anaesthesia` | Optional[[Anaesthetic](components/surgery_procedures.md#anaesthetic)] | Anaesthesia  |
+| `notes` | `Optional[str]` | Notes  |
+
+
 ### PerformanceMetrics
 
 Summary of a StimulusEpoch

docs/source/components/devices.md

@@ -529,7 +529,7 @@ Description of a lick spout
 | `spout_diameter` | `decimal.Decimal` | Spout diameter (mm)  |
 | `spout_diameter_unit` | [SizeUnit](../aind_data_schema_models/units.md#sizeunit) | Spout diameter unit  |
 | `solenoid_valve` | [Device](#device) | Solenoid valve  |
-| `lick_sensor` | [Device](#device) | Lick sensor  |
+| `lick_sensor` | [Device](#device) or [HarpDevice](#harpdevice) | Lick sensor  |
 | `lick_sensor_type` | Optional[[LickSensorType](../aind_data_schema_models/devices.md#licksensortype)] | Lick sensor type  |
 | `name` | `str` | Device name  |
 | `serial_number` | `Optional[str]` | Serial number  |

docs/source/components/identifiers.md

@@ -12,7 +12,7 @@ Code or script identifier
 | `name` | `Optional[str]` | Name  |
 | `version` | `Optional[str]` | Code version  |
 | `container` | Optional[[Container](#container)] | Container  |
-| `run_script` | `Optional[pathlib._local.Path]` | Run script (Path to run script) |
+| `run_script` | `Optional[pathlib.Path]` | Run script (Path to run script) |
 | `language` | `Optional[str]` | Programming language (Programming language used) |
 | `language_version` | `Optional[str]` | Programming language version  |
 | `input_data` | Optional[List[[DataAsset](#dataasset) or [CombinedData](#combineddata)]] | Input data (Input data used in the code or script) |

src/aind_data_schema/core/acquisition.py

@@ -37,6 +37,7 @@
 from aind_data_schema.components.surgery_procedures import Anaesthetic
 from aind_data_schema.utils.merge import merge_notes, merge_optional_list, remove_duplicates
 from aind_data_schema.utils.validators import subject_specimen_id_compatibility
+from aind_data_schema.components.subject_procedures import Injection, BrainInjection
 
 # Define the requirements for each modality
 # Define the mapping of modalities to their required device types
@@ -68,7 +69,10 @@ class AcquisitionSubjectDetails(DataModel):
         description="Animal weight after procedure",
     )
     weight_unit: MassUnit = Field(default=MassUnit.G, title="Weight unit")
-    anaesthesia: Optional[Anaesthetic] = Field(default=None, title="Anaesthesia")
+    anaesthesia: Optional[Anaesthetic] = Field(default=None, title="Anaesthesia", description=(
+            "Anaesthesia present during entire acquisition, use Manipulation for partial anaesthesia"
+        )
+    )
     mouse_platform_name: str = Field(..., title="Mouse platform")
     reward_consumed_total: Optional[Decimal] = Field(default=None, title="Total reward consumed (mL)")
     reward_consumed_unit: Optional[VolumeUnit] = Field(default=None, title="Reward consumed unit")
@@ -237,6 +241,22 @@ class StimulusEpoch(DataModel):
     )
 
 
+class Manipulation(DataModel):
+    """Description of procedures performed during an acquisition."""
+
+    start_time: Annotated[AwareDatetimeWithDefault, TimeValidation.BETWEEN] = Field(
+        ..., title="Manipulation start time", description="Must be between the acquisition start and end times"
+    )
+    end_time: Annotated[AwareDatetimeWithDefault, TimeValidation.BETWEEN] = Field(
+        ..., title="Manipulation end time", description="Must be between the acquisition start and end times"
+    )
+    procedures: Optional[DiscriminatedList[Injection | BrainInjection]] = Field(
+        default=None, title="Procedures", description="Procedures performed during the manipulation"
+    )
+    anaesthesia: Optional[Anaesthetic] = Field(default=None, title="Anaesthesia")
+    notes: Optional[str] = Field(default=None, title="Notes")
+
+
 class Acquisition(DataCoreModel):
     """Description of data acquisition metadata including streams, stimuli, and experimental setup.
 
@@ -312,6 +332,9 @@ class Acquisition(DataCoreModel):
             " Epochs should be split when the purpose of the stimulus changes."
         ),
     )
+    manipulations: List[Manipulation] = Field(
+        default=[], title="Manipulations", description="Procedures performed during the acquisition."
+    )
     subject_details: Optional[AcquisitionSubjectDetails] = Field(default=None, title="Subject details")
 
     @model_validator(mode="after")