Clarify some points of confusion in the Allen Visual Behavior notebooks

[slinderman]

@dougollerenshaw: Thanks for the Allen Institute notebooks! Some confusions arose during TA training, and I think some extra text explanations could help address them.

1. The load_Allen_Visual_Behavior_from_pre_processed_file.ipynb notebook seems to use "trial" and "stimulus_presentations_id" interchangeably. If these are the same concept, then perhaps "trial_id" would be more straightforward.
2. The confusion about trials and stimulus presentations was exacerbated by the first figure where it says "trial start" with an arrow. If we understand correctly, that should really say "session start." Is that correct?
3. The preprocessed file seems to only have trials where there was a change or an omission. At least that is what was inferred from the other notebook, which loads from the SDK and filters. Is that correct? If so, it would be good to make a note in the notebook.

[matchings]

@slinderman These points of confusion are totally understandable.

The concept of a trial in the change detection task is somewhat complicated because the stimuli are continuously presented with no discrete signal to the animal that a trial has started. The way the task is coded in the behavior control software does designate a trial start start time, which occurs 2 seconds from the time of the animal's last lick. At the trial start time, a change time is selected from a geometric distribution ranging between 2-8 seconds after the trial start. If the animal licks prior to the change time, the trial restarts (using the same change time for up to 5 trials to prevent guessing from being a viable strategy).

This task design is a bit unconventional but it affords the ability to look at some interesting things, like temporal expectation.

To address your specific points:

1. stimulus_presentations_id refers to each individual stimulus presentation throughout the session, and is the index for the stimulus_presentations table. There are something like 4000 stimulus presentations in each session. A "trial" is a distinct concept, as described above. The trials table, accessible via the SDK, is organized by trials, with trials_id as the index. Each row of that table represents a single trial and has a start time, a change time, and an end time. A trial is composed of multiple stimulus_presentations. There are between 200-400 trials in a typical session, depending on the animals behavior.

2. The figure is actually correct, a "trial_start" occurs some amount of time prior to the change time, as described above.

3. This is also correct, the pre-processed file only contains stimulus presentations where the identity of the stimulus changed or where a stimulus was omitted. It was limited to these conditions in order to be able to concatenate multiple sessions from many mice together without ending up with an intractably large file size. The SDK notebook shows how to access the full dataset, with every stimulus presentation in a given session in the stimulus_presentations attribute, as well as the data organized as trials, in the trials attribute.

@dougollerenshaw is on vacation today, but we will make sure to edit the notebook to clarify the terminology of "stimulus presentation" and "trial". We can also include another schematic for further clarification.

Additional details about the task design can also be found in these two publications (we can also link to these in the notebook):

Experience shapes activity dynamics and stimulus coding of VIP inhibitory cells Characterization of Learning, Motivation, and Visual Perception in Five Transgenic Mouse Lines Expressing GCaMP in Distinct Cell Populations

[slinderman]

Thanks for clarifying these points, @matchings! This all makes sense now, and this description would be a great addition to the notebook. This is now obvious, but you could also mention that the trace associated with each stimulus presentation will capture responses to preceding and following stimulus presentations as well, since the window is [-1.25, +1.5s] in size and the inter-stimulus intervals are only 500ms.