Usage of 'control' and 'control_description' Parameters in TwoPhotonSeries

[shnakazawa]

Hello NWB community,

I'd like to discuss the usage of "control" and "control_description" parameters in TwoPhotonSeries.

In our experiment, we perform time-series imaging with two-photon microscopy and give stimulations at specific timepoints.
I would like to make it clear at which timepoints the stimulations are given.
I'm considering using the "control" parameter as a list of values, where '0' represents timepoints before stimulation, '1' represents timepoints after stimulation A, and '2' represents timepoints after stimulation B (e.g., control=[0,0,1,1,2,2]).
Additionally, "control_description" will be used to provide descriptions for each value in the control parameter (e.g., control_description=['before stimulation', 'after stimulation A', 'after stimulation B']).
I want to ensure our data is well-annotated, but I'm unsure if this approach to using "control" and "control_description" is appropriate.

The image data is in a 4-dimensional format (time, z, x, y). I'm considering using the TimeSeries Module to store the detailed information of the stimulations.

If you have insights, suggestions, or recommendations, I would greatly appreciate your input. Thank you in advance for your feedback, and I look forward to hearing from the community.

[CodyCBakerPhD]

@oruebel @bendichter Anyone remember the intended use for this field?

FYI @alessandratrapani, something we may want to remove or really clarify in ndx-microscopy

[rly]

"control" and "control_description" are datasets of any TimeSeries, including TwoPhotonSeries. These are carryovers from NWB 1.0 and as far as I am aware, no tools in the NWB 2.0 ecosystem make use of them, and few if any NWB 2.0 datasets use them.

It is OK to use "control" and "control_description" in the way that you describe. That is what they were designed for. However, I would suggest also encoding those stimulation times in a second way that I think is more commonly used -- TimeIntervals. (@CodyCBakerPhD @bendichter please correct me if I am wrong from your experience working with many datasets)

You can use the TimeIntervals type to encode the start times and stop times of each stimulation period. You can optionally use the timeseries column of the TimeIntervals table to encode the start indices and counts of an associated TimeSeries like your TwoPhotonSeries. This column takes a compound dtype with form (idx_start: int, count: int, timeseries: TimeSeries).

For example, if one of your stimulation periods starts at 1.1 seconds, stops at 1.5 seconds, and starts at index 110 and goes for 40 frames in your TwoPhotonSeries, then the value of one row would be:
start_time = 1.1, stop_time = 1.5, timeseries = (110, 40, my_two_photon_series_object).

This timeseries column makes it easy for users to index into the TwoPhotonSeries to get the stimulation periods without having to search for control == 1. You could do the same for the before stim and after stim periods. You could also not cache those indices and have you / others combine the start/stop times with the TwoPhotonSeries timestamps to determine which frames were before, during, and after stimulation.

[shnakazawa]

Thank you for your informative response and the suggestion to use TimeIntervals for encoding stimulation times. While your suggestion makes sense for cases where imaging and stimulation occur on the same time scale, I want to make sure I understand correctly, especially considering the time scale differences in our experiment.

For example, imaging is conducted every 5 minutes over a total of 1 hour, while stimulation occurs for a few milliseconds between the 3rd and 4th imaging sessions. Given this time scale difference, is there a recommended approach for organizing this within the NWB file?

Your guidance and expertise are greatly appreciated, and I want to ensure that our NWB file is structured in line with best practices.

Thank you so much for your time and assistance!

[rly]

I am a bit confused. How long are your imaging sessions? Is imaging continuous for an entire hour, or are there gaps of no imaging during that hour? Does stimulation occurs only once during an experimental session? What is your imaging frame rate?

Because the stimulation duration is much shorter than the time of acquiring a single imaging frame, if you store the pre/during/post-stimulation times in the control field of TwoPhotonSeries, others trying to interpret your data might think that the stimulation duration was as long as the time between two imaging frames, i.e., it started when at timestamp X and stopped at the next timestamp Y. Storing the stimulation start time and stop time in the TimeIntervals object allows you to specify those times to their full precision. If I understand your experimental setup correctly, I would advise against using the control field.

[shnakazawa]

Thank you for your response and your questions regarding our experimental setup.

How long are your imaging sessions? Is imaging continuous for an entire hour, or are there gaps of no imaging during that hour?

What is your imaging frame rate?

The imaging sessions are not continuous but consist of 1-minute sessions with 4-minute gaps in between.
Each imaging session includes XYZ imaging, and the frame rate for a single XY plane is approximately 1 Hz.

Does stimulation occurs only once during an experimental session?

Yes. Stimulation occurs only once during an experimental session.

Our typical imaging sequence is like this:
1-min imaging -> 4-min gap -> 1-min imaging -> 4-min gap -> millisecond stimulus -> 1-min imaging -> 4-min gap -> ...

There is no "during stimulation" condition in our imaging due to the absence of continuous acquisition during the stimulation event.
This setup raises questions about aligning the time frames encoded in TwoPhotonSeries with the timing of the stimulus.

Thank you for your time and expertise.