Merge pull request #4 from catalystneuro/add_extra_metadata

Add acquisition signal description

src/fox_lab_to_nwb/behavior.py

@@ -33,7 +33,7 @@ def add_to_nwbfile(
             "LWingBeatAmp",
             "RWingBeatAmp",
             "WingBeatFreq",
-            "LHutchen",
+            "LHutchen",  # hütchens means little hat and is the shape of the signal on the sensor
             "RHutchen",
             "PTrigger",
         ]
@@ -44,7 +44,7 @@ def add_to_nwbfile(
         wing_beat_frequency = daq_struct["data"][:, 5]
 
         unit = "tbd"
-        description = "tbd"
+        description = "Recorded by the WingBeat Analyzer, an LED directly overhead a photodiode that detects changes in light (i.e., changes in how much the fly’s wing is occluding the LED)"
         left_wing_beat_amplitude_time_series = TimeSeries(
             name="LeftWingBeatAmplitudeTimeSeries",
             data=left_wing_beat_amplitude,
@@ -53,7 +53,7 @@ def add_to_nwbfile(
             description=description,
         )
 
-        description = "tbd"
+        description = "Recorded by the WingBeat Analyzer, an LED directly overhead a photodiode that detects changes in light (i.e., changes in how much the fly’s wing is occluding the LED)"
         right_wing_beat_amplitude_time_series = TimeSeries(
             name="RightWingBeatAmplitudeTimeSeries",
             data=right_wing_beat_amplitude,
@@ -62,42 +62,60 @@ def add_to_nwbfile(
             description=description,
         )
 
-        description = "tbd"
-        unit = "Hz"  # TODO: Figure this out, the values in the plot are around 3 but should be higher for flies
+        description = "Recorded by the WingBeat Analyzer "
+        unit = "Hz"  # a normal Drosophila will flap between 180 and 220 Hz
         wing_beat_frequency_time_series = TimeSeries(
             name="WingBeatFrequencyTimeSeries",
             data=wing_beat_frequency,
             unit=unit,
             timestamps=timestamps,
+            conversion=0.1,
             description=description,
         )
 
         nwbfile.add_acquisition(left_wing_beat_amplitude_time_series)
         nwbfile.add_acquisition(right_wing_beat_amplitude_time_series)
         nwbfile.add_acquisition(wing_beat_frequency_time_series)
 
-        # TODO: Ask Ben if this nesting makes sense? probably not
-        # time_series = [left_wing_beat_amplitude_time_series, right_wing_beat_amplitude_time_series, wing_beat_frequency_time_series]
-        # behavioral_time_series_container = BehavioralTimeSeries(name="BehavioralTimeSeries", time_series=time_series)
-        # nwbfile.add_acquisition(behavioral_time_series_container)
 
-        # Not clear what are those signals, haltere?
+
+        # Hutchen is the shape of the signal on the sensor, means little hats
         lhutchen = daq_struct["data"][:, 6]
         rhutchen = daq_struct["data"][:, 7]
 
-        unit = "tbd"
-        description = "tbd"
-        lhutchen_time_series = TimeSeries(
-            name="LHutchenTimeSeries", data=lhutchen, unit=unit, timestamps=timestamps, description=description
+        unit = "arbitrary units or z-score"
+        lhutchen_description = (
+            "Voltage recording of the shadow of the fly’s left wingbeat. "
+            "Low voltages indicate the wing is fully extended forward (minimal light occlusion), "
+            "and high voltages indicate the wing is fully back (maximal light occlusion). "
+            "Voltage values depend on the fly’s positioning over the photodiode."
         )
 
-        description = "tbd"
-        rhutchen_time_series = TimeSeries(
-            name="RHutchenTimeSeries", data=rhutchen, unit=unit, timestamps=timestamps, description=description
+        rhutchen_description = (
+            "Voltage recording of the shadow of the fly’s right wingbeat. "
+            "Low voltages indicate the wing is fully extended forward (minimal light occlusion), "
+            "and high voltages indicate the wing is fully back (maximal light occlusion). "
+            "Voltage values depend on the fly’s positioning over the photodiode."
         )
 
-        nwbfile.add_acquisition(lhutchen_time_series)
-        nwbfile.add_acquisition(rhutchen_time_series)
+        # Updated object names and definitions
+        left_wing_voltage_series = TimeSeries(
+            name="LeftWingVoltageTimeSeries",
+            data=lhutchen,
+            unit=unit,
+            timestamps=timestamps,
+            description=lhutchen_description
+        )
+
+        right_wing_voltage_series = TimeSeries(
+            name="RightWingVoltageTimeSeries",
+            data=rhutchen,
+            unit=unit,
+            timestamps=timestamps,
+            description=rhutchen_description
+        )
+        nwbfile.add_acquisition(left_wing_voltage_series)
+        nwbfile.add_acquisition(right_wing_voltage_series)
 
     def extract_synchronization_signals_info(self):
 
@@ -107,7 +125,7 @@ def extract_synchronization_signals_info(self):
 
         daq_sampling_rate = daq_struct["fs"]
 
-        cam_sync = daq_struct["data"][:, 0]
+        cam_sync = daq_struct["data"][:, 0]  # This is a defunct channel and not used according to authors
         cam_trigger = daq_struct["data"][:, 1]
         opto_trigger = daq_struct["data"][:, 2]
         ptrigger = daq_struct["data"][:, 8]
@@ -121,4 +139,3 @@ def extract_synchronization_signals_info(self):
         }
 
         return return_dict
-

src/fox_lab_to_nwb/conversion_notes.md

@@ -94,6 +94,7 @@ Not yet available
 
 # Files on data shared 
 
+## DAQ
 ### Tshx18D07_240124_115923_f3_r1.fly2
 This is supposed to be a struct with DAQ data and the wingbeat analysis. Can't open it with matlab online unless extension is changed to .mat
 
@@ -111,6 +112,62 @@ This is supposed to be a struct with DAQ data and the wingbeat analysis. Can't o
 
 These can't be extracted with pyton from matlab because they are strings. Are they always the same order?
 
+This explains how the data of the data of the DAQ can be interpreted:
+
+https://reiserlab.github.io/Modular-LED-Display/Generation%202/Arenas/docs/g2_user-guide.html#optical-wingbeat-analyzer
+
+
+A description of the DAQs fields given by the authors:
+
+**CamSync**
+- Defunct channel, not currently used
+
+**CamTrigger**
+- Trigger for Fastec IL5 high-speed cameras (pointed at the head, sampling at 2000 FPS)
+- Single trigger is split via BNC connector to reach both cameras simultaneously, then a copy of the signal is recorded by DAQ
+
+**OptoTrigger**
+- Trigger for optogenetic light
+- 625nm red wavelength, collimated light (ThorLabs)
+- Trace is recorded as voltage output to the optogenetic light. Higher voltage translates to higher light intensity (a variable within the experiment)
+- Power Driver (receives BNC input from DAQ): [ThorLabs Power Driver](https://www.thorlabs.com/newgrouppage9.cfm?objectgroup_id=2616)
+
+**LWingBeatAmp**
+- Recorded by the WingBeat Analyzer, an LED directly overhead a photodiode that detects changes in light (i.e., changes in how much the fly’s wing is occluding the LED)
+- Left wing only
+- Sampling at 10 kHz
+
+**RWingBeatAmp**
+- See above, but for the right wing
+- Sampling at 10 kHz
+
+**WingBeatFreq**
+- Recorded by the WingBeat Analyzer
+- Units in 1/10th Hz (a normal Drosophila will flap between 180 and 220 Hz)
+- Sampling at 10 kHz
+
+**LHutchen**
+- Voltage recording of the shadow of the fly’s wingbeat
+  - Low voltages correspond to when the fly’s wing is fully extended forward (minimal light from the overhead LED)
+  - High voltages correspond to when the fly’s wing is fully back (maximal light from the overhead LED, no occlusion by the wing)
+- Listed in arbitrary units or z-score when published, as the voltage will depend on how centered/far forward the fly is over the photodiode
+- Specific sensor for the left wing
+- Sampling at 10 kHz
+
+**RHutchen**
+- Voltage recording of the shadow of the fly’s wingbeat
+  - Low voltages correspond to when the fly’s wing is fully extended forward (minimal light from the overhead LED)
+  - High voltages correspond to when the fly’s wing is fully back (maximal light from the overhead LED, no occlusion by the wing)
+- Listed in arbitrary units or z-score when published, as the voltage will depend on how centered/far forward the fly is over the photodiode
+- Specific sensor for the right wing
+- Sampling at 10 kHz
+
+**PTrigger**
+- Trigger for Photron Fastcam Mini AX100 (pointed at the haltere, sampling at 10,000 FPS)
+- Single trigger is split via BNC connector to reach both cameras simultaneously, then a copy of the signal is recorded by DAQ
+
+Note that the triggers fire when the buffer of the camera should be emptied and therefore point out the end of the video camera signal. The DAQ is on for longer.
+
 ## Cameras 
 
 ### Fastec