Output files

Outputs & NWB files

During and at the end of the behavioural session, the software outputs several files that are then used to create NWB files.

Here, all saved variables are explained with their current/intended usage by downstream code such as NWB_converter.

Note: this code does not generate NWB files directly.

Output files

• Session information: session_config.json: text file created at session start and containing the GUI parameters selected at before session start, saving session-wide parameters, etc.
• Trial information: results.csv: trial-based file, appended after each trial during the session. This file contains trial-by-trial parameters, etc.
• Continuous behavioural data, events and epochs: log_continuous.bin: binary file containing 5000Hz sampled analog data acquired during the entire session. The number of channels should be that of the Log_S session object.

Output files content

Session information

The session_config.json file contains session-wide parameters, i.e. parameters valid for the entire session. The goal of this file is to keep a record of the state of the GUI and which parameters were used during the session, in order to describe the type of the experimental session but also provide additional/forgotten information that may useful months after the session was recorded e.g. "Did I have video filming during this session?".

• twophoton_session: boolean flag if the session involved two-photon imaging - these flags are combinedto create a session_type in NWB_converter
• threephoton_session: boolean flag if the session involved three-photon imaging
• wf_session: boolean flag if the session involved wide-field imaging
• ephys_session: boolean flag if the session involved electrophysiology
• opto_session: boolean flag if the session involved optogenetics
• chemo_session: boolean flag if the session involved chemogenetics e.g. DREADDS
• pharma_session: boolean flag if the session involved pharamacology e.g. muscimol injections
• date: date of the session (YYYYMMDD format)
• mouse_name: mouse ID e.g. RS001
• false_alarm_punish_flag: boolean if false alarms were punished with timeout
• early_lick_punish_flag: boolean if early licks were punished with timeout
• association_flag: boolean if session had association trials (free rewards at each stimulus)
• camera_flag: boolean if video filming enabled (``NWB_converter` uses this to look for videos)
• dummy_session_flag: boolean flag sessions that were not meant to be analyzed/kept
• context_flag: boolean if context-task enabled for that session
• behaviour_type: type of behaviour, to be selected from a lab-defined list e.g. 'auditory', 'whisker', 'whisker_psy', 'whisker_context'
• min_quiet_window: minimum quiet window duration (in ms)
• max_quiet_window: maximum quiet window duration (in ms)
• response_window: response window duration (in ms)
• artifact_window: duration of artifact window (in ms) - artifact generated by coil activation on piezo sensor
• min_iti: minimum inter-trial interval (in ms)
• max_iti: maximum inter-trial interval (in ms)
• baseline_window: baseline window duration (in ms)
• trial_duration: duration of a single trial (in ms)
• light_flag: boolean if light task stimulus was used in session
• light_duration: duration of light stimulation (in ms)
• light_prestim_delay: pre-stimulus delay for light (in ms)
• light_amp: amplitude of the light stimulation
• light_freq: frequency of light stimulation (in Hz)
• light_duty: duty cycle for light stimulation (percentage)
• light_aud_proba: probability of light stimulus accompanying auditory stimulus
• false_alarm_timeout: timeout duration for false alarms (in ms)
• early_lick_timeout: timeout duration for early licking (in ms)
• aud_stim_duration: duration of auditory stimulus (in ms)
• aud_stim_amp: amplitude of the auditory stimulus - requires calibration
• aud_stim_freq: frequency of the auditory stimulus (in Hz) - sinusoidal wave
• aud_stim_weight: trial proportion weight assigned to auditory stimulus
• wh_stim_duration: duration of whisker stimulus (in ms)
• wh_scaling_factor: scaling factor for whisker stimulation, relating the amplitudes of the second phase relative to the first
• wh_stim_amp_1: amplitude of whisker stimulus 1 - requires calibration
• wh_stim_weight_1: trial proportion weight assigned to whisker stimulus 1 - if only one whisker stimulus is used, this is the total whisker weight
• wh_stim_amp_range: boolean indicates if more than one whisker stimulus is used in the session
• wh_stim_amp_2: amplitude of whisker stimulus 2
• wh_stim_weight_2: trial proportion weight assigned to whisker stimulus 2
• wh_stim_amp_3: amplitude of whisker stimulus 3
• wh_stim_weight_3: trial proportion weight assigned to whisker stimulus 3
• wh_stim_amp_4: amplitude of whisker stimulus 4
• wh_stim_weight_4: trial proportion weight assigned to whisker stimulus 4
• no_stim_weight: trial proportion weight assigned to trials with no stimulation (catch trials)
• context_block_size: size of context block (in trials) before transition
• reward_valve_duration: duration the reward valve is open (in ms) - requires calibration
• reward_delay_flag: boolean if reward delivery is delayed
• reward_delay_time: duration of reward delay (in ms)
• partial_reward_flag: boolean if partial i.e. probabilistics rewards are used - this is implemented for whisker trials only
• reward_proba: probability of that a normally rewarded whisker trial will give a reward
• aud_reward: boolean if auditory trials are rewarded throughout the session
• wh_reward: boolean if whisker trials are rewarded throughout the session
• lick_threshold: lick detection threshold (in arbitrary units) - used by NWB_converter's processing of continuous data for lick detection
• camera_freq: camera frame rate (in Hz)
• camera_start_delay: delay that was added before the camera starts recording (in ms)
• camera_exposure_time: camera exposure time (in ms)
• last_recent_trials: number of most recent trials to analyze - this was just used for online plotting
• PauseRequested: indicator if a pause in the session was requested (no use)
• mouse_weight_before: mouse weight just before the session (in grams)
• mouse_weight_after: mouse weight just after the session (in grams)
• session_time: time of the session start (in HHMMSS format)
• ReportPause: indicator if the session was paused and reported (no use)

Trial inforation

Theresults.csv is a file that contains trial-by-trial parameters. This file is directly used by NWB_converter to make the trial_table where.

• trial_number: number of the current trial - MATLAB indexing starts at 1
• perf: performance measure or outcome of the trial
• • 0: whisker miss
• • 1: auditory miss
• • 2: whisker hit
• • 3: auditory hit
• • 4: correct rejection
• • 5: false alarm
• • 6: early licks/association trials without distinction (use association_flag to isolate association trials)
• trial_time: time duration of the trial (in ms)
• association_flag: boolean if associative trial (free reward after stimulus)
• quiet_window: duration of the quiet window before the onset of this trial (in ms) - if non-zero, quiet window licks delay onset of current trial
• iti: inter-trial interval (in ms) between the previous trial and this trial
• response_window: time window in which a response is expected (in ms)
• artifact_window: window where piezo sensing is ignored because of coil-induced artifact (in ms)
• baseline_window: baseline window before trial onset (in ms) - if non-zero, baseline licks are early licks, aborting the trial
• trial_duration: total duration of the trial (in ms)
• is_stim: indicates whether stimulation (any type) is present in the trial
• is_whisker: indicates if whisker stimulation is used in the trial
• is_auditory: indicates if auditory stimulation is used in the trial
• lick_flag: indicates if the subject licked during the trial response window
• reaction_time: time taken by the subject to react (in ms)
• wh_stim_duration: duration of whisker stimulation (in ms)
• wh_stim_amp: amplitude of whisker stimulation
• wh_scaling_factor: scaling factor for whisker stimulation intensity
• wh_reward: indicates if the whisker stimulus can be rewarded
• is_reward: for probabilistic whisker trials, indicates if a reward is available or not
• aud_stim_duration: duration of the auditory stimulus (in ms)
• aud_stim_amp: amplitude of the auditory stimulus
• aud_stim_freq: frequency of the auditory stimulus (in Hz)
• aud_reward: indicates if the auditory stimulus can be rewarded
• early_lick: indicates if the subject licked early (during baseline window)
• is_light: indicates if light stimulation was used in the trial
• light_amp: amplitude of light stimulation
• light_duration: duration of light stimulation (in ms)
• light_freq: frequency of light stimulation (in Hz)
• light_prestim: pre-stimulus delay for light (in ms)
• context_block: size of the context block associated with the trial

Continuous data logging

The binary file log_continuous.bin contains 5000Hz-sampled analog data acquired during the entire session. The number of channels should be that of the Log_S session object. This number of is important to allow NWB_converter to correct parse the binary data and perform continuous processing: piezo lick detection, TTLs up/down detection, etc.

Note:

• Change the content of this file at your own risk, unless your experiments really require it! 😉
• For electrophysiology, continuous data is alreayd copied using a separate NI cards so this is left as it.

The channel content is written in the defining_session.m file:

• ai0: lick piezo sensor data
• ai1: galvo scanner position for imaging
• ai2: trial start TTL
• ai3: camera 1 strobe out (exposure times)
• ai4: camera 2 strobe out (exposure times)
• ai5: context transition TTL

Integration with NWB files

• These files are then used by NWB_converter (the behaviour converter mostly) to generate NWB files. See the related code to know more.
• It is possible and desired to have NWB files that only contain behavioural data, before preprocessing of neural/video data is finished.
• Important note ⚠️: behavior_control and NWB_converter work hand-in-hand. Therefore any required updates/changes made in the behavior_control and its output files may require corresponding updates in the NWB data creation code, for the entire lab. For this reason, it is important to consider carefully whether any changes are really needed. For this, the best is to discuss with other lab members first! 🙂