[Feature]: Support for importing trial-level behavioral events (CSV format) in GUIDE

[mcelotto]

What would you like to see added to the NWB GUIDE?

Following up on a conversation started during the May 12–13 Data Conversion Workshop. I’m a computational neuroscientist working in the Mriganka Sur Lab at MIT. Along with other colleagues, I’ve been working to promote the adoption of the NWB format in our lab. We find GUIDE extremely helpful for converting different raw data streams into NWB. However, we’ve encountered some difficulty when trying to import behavioral events using GUIDE. In our workflow, trial-level behavioral data are often stored as CSV files, with each row representing a trial. Columns typically include trial start and end times (aligned to a global zero - by our convention, the start of the first physiological recording stream), stimulus onset/offset time, and other custom, experiment-specific features such as stimulus identity, action taken, reward presence, and reaction time. During the workshop, it it came up that this kind of data - which we believe represents a fairly common and general structure in systems neuroscience - can be added to NWB using the TimeIntervals data type (or possibly the newer Events type). Following up on those discussions, I’d like to ask whether it would be possible to add functionality in GUIDE to support automatic import of such table-structured behavioral data (e.g., CSV) into NWB, alongside other data types. We believe this addition would significantly lower the barrier for less-experienced programmers to include behavioral data in their NWB files. Here's the link to one example trial behavioral info CSV file on google drive, for reference: https://drive.google.com/file/d/18bG60H0JI2wxXvqtCUzjRTSTzHTWqmRI/view?usp=sharing

Thanks for your help! I'm also happy to contribute to the effort if needed. Marco

Do you have any interest in helping implement the feature?

Yes, but I would need guidance.

Code of Conduct

Yes

Did you confirm this feature was not already reported?

Yes

[rly]

Hi Marco @mcelotto thank you for creating the issue ticket!

The team agrees that this would be a very useful feature. In your example, it looks like each row represents a trial. Do you work with any other kinds of tabular behavioral data that you want to add to the NWB file, e.g., events from the DAQ, manual or automated behavioral annotations?

I am trying to understand the scope of the support we should add. We can start with CSV/TSV representing trial data.

In case the google sheet becomes unavailable, here are the first 5 rows in markdown:

start_time	stop_time	stim_onset	stim_offset	tone_freq	tone_intensity	tone_idx	output	reaction_time	correct	trial_type	laser	prev_trial_type
13.7539	19.7539	14.2139	14.7139	nan	35dB	NaN	nan	NaN	early_press	early_press	0
15.8015	21.8015	16.6515	17.1515	12kHz	5dB	5	no_press	NaN	error	miss	0	early_press
22.0301	28.0301	22.6301	23.1301	4kHz	5dB	1	press	0.0683	error	fa	0	miss
27.3982	33.3982	28.1082	28.6082	4kHz	15dB	2	no_press	NaN	correct	cr	0	fa
33.5983	39.5983	34.0183	34.5183	4kHz	25dB	3	press	0.538	error	fa	0	cr

I imagine this support would look something like:

1. GUIDE has a page that allows the user to upload a CSV or TSV with trial data and column names
2. GUIDE extracts the column names and asks for the name corresponding to the start time and stop time
3. For each remaining column name, GUIDE asks the user to provide a description and dtype (e.g., float, string). We may expand this to include optionally a list of possible values, meanings for each value, and a label for invalid (e.g., NA/NaN/nan) values
4. Using that information, columns would be added to the NWB trials table, and all the table data would be added to the NWB trials table.

[mcelotto]

Hi @rly, thanks - the outlined support is exactly how I envisioned the process. Yes, each row in the CSV represents a trial. At the moment, this kind of tabular trial-level behavioral data is what we primarily work with. An interface to import CSV/TSV trial data into the NWB trials table via GUIDE would be an amazing addition. Support for incorporating other types of events (e.g., from the DAQ) would certainly be a plus, but it's less of a priority in the short term - at least for our lab. Thanks again!