add temporal alignment with notes

src/constantinople_lab_to_nwb/schierek_embargo_2024/schierek_embargo_2024_notes.md

@@ -129,6 +129,37 @@ column_descriptions = dict(
 )
 ```
 
+### Temporal alignment
+
+1. Align trial-base relative timestamps to Raw Bpod trial start time:
+For each trial sum all relative timestamps to the respective trial start time
+
+2. Align TTL signals to Raw Bpod trial times:
+Compute the time shift from global center port timestamps (`global_center_port_times`) to the aligned center port timestamps.
+The aligned center port times can be accessed from the processed behavior data using the `"Cled"` field.
+
+```python
+from ndx_structured_behavior.utils import loadmat
+
+bpod_data = loadmat("path/to/bpod_session.mat")["SessionData"] # should contain "SessionData" named struct
+S_struct_data = loadmat("path/to/processed_behavior.mat")["S"] # should contain "S" named struct
+
+bpod_trial_start_times = bpod_data['TrialStartTimestamp']
+num_trials = len(bpod_trial_start_times)
+global_center_port_times = []
+for i in range(num_trials):
+  center_port_relative_start_time = bpod_data["RawEvents"]["Trial"][i]["States"]["NoseInCenter"][0]
+  bpod_global_start_times = bpod_trial_start_times[i] + center_port_relative_start_time
+  global_center_port_times.append(bpod_global_start_times)
+
+# "Cled" field contains the aligned onset and offset times for each trial [2 x ntrials]
+center_port_aligned_onset_times = [center_port_times[0] for center_port_times in S_struct_data["Cled"]]
+time_shift = global_center_port_times[0] - center_port_aligned_onset_times[0]
+```
+
+We are using this computed time shift to shift the ephys timestamps.
+
+
 ### Mapping to NWB
 
 The following UML diagram shows the mapping of source data to NWB.

src/constantinople_lab_to_nwb/schierek_embargo_2024/schierek_embargo_2024_nwbconverter.py

@@ -141,3 +141,29 @@ def get_metadata(self):
         )
 
         return metadata
+
+    def temporally_align_data_interfaces(self):
+        processed_behavior_interface = self.data_interface_objects["ProcessedBehavior"]
+        center_port_aligned_times = processed_behavior_interface._get_aligned_center_port_times()
+
+        raw_behavior_interface = self.data_interface_objects["RawBehavior"]
+        bpod_struct = raw_behavior_interface._bpod_struct
+        bpod_first_trial_start_time = bpod_struct["TrialStartTimestamp"][0]
+        bpod_first_trial_relative_center_port_time = bpod_struct["RawEvents"]["Trial"][0]["States"]["NoseInCenter"][0]
+        bpod_first_trial_global_time = bpod_first_trial_start_time + bpod_first_trial_relative_center_port_time
+        # TODO: time shift was negative so I used abs here, is this correct?
+        time_shift = abs(bpod_first_trial_global_time - center_port_aligned_times[0])
+
+        recording_interface_names = [
+            interface_name for interface_name in self.data_interface_objects if "Recording" in interface_name
+        ]
+        for recording_interface_name in recording_interface_names:
+            recording_interface = self.data_interface_objects[recording_interface_name]
+            recording_interface.set_aligned_starting_time(aligned_starting_time=time_shift)
+
+        sorting_interface_names = [
+            interface_name for interface_name in self.data_interface_objects if "Sorting" in interface_name
+        ]
+        for sorting_interface_name in sorting_interface_names:
+            sorting_interface = self.data_interface_objects[sorting_interface_name]
+            sorting_interface.register_recording(self.data_interface_objects[recording_interface_names[0]])