PyBpodGUI

PyBpodGUI is a multi-threaded GUI utility to run neuroscience experiments with the Bpod system by Sanworks. The GUI is written in Python using PyQt5 and connectivity to the Bpod system is made possible thanks to the PyBpod API by the Champalimaud Foundation. The PyBpod API is based on the Bpod system's MATLAB API by Josh Sanders of Sanworks.

How to Install

1. Download and install Anaconda or Miniconda from the conda website.
2. Open Anaconda Prompt or Anaconda Powershell Prompt (they can be found in a new Start Menu folder called Anaconda3).
3. Create a conda environment named pybpodenv and install Python v3.6 with:

   conda create -n pybpodenv python=3.6
   

4. Activate the newly created conda environment with:

   conda activate pybpodenv
   

5. (Optional) Install Git if not already installed on the local system.

   conda install -c conda-forge git
   

6. Navigate to a desired directory in which the repositories will be cloned (e.g. create a new folder called pybpod):

   mkdir pybpod
   cd pybpod
   

7. Clone the PyBpod API repository into a new folder called pybpod-api with:

   git clone https://github.com/olfa-lab/pybpod-api.git pybpod-api
   

8. Navigate into the new folder and install the PyBpod API in developer mode with (note the period at the end):

   cd pybpod-api
   pip install -e .
   

9. Navigate out of the pybpod-api folder and clone the PyBpodGUI (this) repository into a new folder called PyBpodGUI with:

   cd ..
   git clone https://github.com/olfa-lab/PyBpodGUI.git PyBpodGUI
   

10. Navigate into the new folder and install the following required packages with:

    cd PyBpodGUI
    pip install pyqt5-tools pyqtgraph matplotlib tables
    

How to Use

Launching the Application

In the PyBpodGUI folder, launch the GUI with:

python app.py

Main Window Overview

1. On the top of the window there is a menu bar for several tasks and actions.

2. On the left-hand side there is the Experiment Setup dock widget with the parameters to be set before performing an experiment.

3. On the right-hand side there is the MDI area which contains several sub-windows. They can be moved, resized, or closed, and can be re-opened from the View menu in the top menu bar.

4. The Current Trial Info sub-window contains several fields that update every trial to show useful information.

5. The Streaming Plot sub-window contains an animated scope-like plotter to show digital input events (like snout pokes or licks) on each behavior port on the Bpod and analog input signals (like a sniff signal) sampled by an Analog Input Module or the built-in ADC on the Bpod r2 Plus. It also highlights the start and end of the response window and indicates the response result by color. There are several parameters on the left of the plot to adjust properties of the animation and axis.

6. The Bpod Control sub-window contains several parameters to specify the behavior port number of the left and right input sensors and valves, the duration to open the left and right valves, and buttons to open and close the valves manually.

7. The Results Plot sub-window contains a line plot of the total percentage of trials which the mouse licked left correctly for each flow rate in order to produce a sigmoid curve for odor intensity experiments. There are buttons that combine or separate the lines of the plot based on the odor vials. For odor identity experiments, the plot becomes a two-dimensional matrix that maps each pair of odors as a greyscale pixel on an image where the brightness represents the percentage of trials for which the mouse licked correctly for that odor pair. The Results Plot is dependent on the Experiment Type parameter in the Experiment Setup dock widget on the left-hand side.

8. The Flow Usage Plot sub-window contains a line plot of the number of trials that each flow rate was used. There are buttons that combine or separate the lines of the plot based on the odor vials.

Running a Session

1. Connect the Bpod to the PC with the USB cable and connect all the sensors, valves, or modules to their appropriate ports on the Bpod. If using the Analog Input Module, connect it to the PC with the USB cable as well.

2. In the Experiment Setup dock widget, select the application mode from the Application Mode combo box. The two options are:

   1. Standard -- used when performing a single session for the specified number of trials
   2. Automatic (RFID) -- used for autonomous 24/7 operation of RFID tagged mice where a session begins automatically when a mouse enters the behavioral space and continues until the mouse leaves

   Select Standard for this tutorial.

3. Enter the Bpod's COM port in the Bpod Port spin box. The COM port can be found in Device Manager, which can be opened by searching for Device Manager in the Start Menu. If using the Bpod r2 Plus, click the spin box down arrow until Auto-detect appears, or enter 0 as the value. This will instruct the PC to scan the available COM ports to identify the Bpod r2 Plus because it creates three separate COM ports: a primary port for the main connection, a secondary port for an auxiliary application, and a third port for streaming analog input data to the PC.

4. Enter the Analog Input Module's COM port in the Analog Input Module Port spin box if it will be used. If not, click the spin box down arrow until Do Not Use appears, or enter 0 as the value.

5. Specify an olfactometer configuration file by going to the top menu bar and clicking on Olfactometer > Select config file. A file explorer dialog window will appear. Browse for the desired olfactometer configuration file to use for the current session. An olfactometer configuration file is needed if an olfactometer will be used during the session to instruct the PC how to operate the olfactometer. If the olfactometer will not be used, uncheck the Enable Olfactometer check box. Once the olfactometer configuration file is selected, its path will appear in the Olfa Config File line edit box.

   Note that the olfactometer configuration file must be a JSON file. There is a folder in this repository's root location called olfactometry_config_files that the file explorer dialog window browses by default. Refer to the olfactometer configuration file that is included in this repository for the JSON structure. This folder can be used to hold all olfactometer configuration files and is where the built-in editor saves new files to. It is recommended to use the built-in editor to modify or create new olfactometer configuration files. Instructions can be found below.

6. Specify a protocol file by going to the top menu bar and clicking on File > Open Protocol. A file explorer dialog window will appear. Browse for the desired protocol file to use for the current session. A protocol file is needed to instruct the Bpod how to build the state machine. Once the protocol file is selected, its path will appear in the Protocol File line edit box.

   Note that the protocol file must be a JSON file. There is a folder in this repository's root location called protocol_files that the file explorer dialog windows browses by default. Refer to the protocol files that are included in this repository for the JSON structure. This folder can be used to hold all protocol files and is where the built-in editor saves new files to. It is recommended to use the built-in editor to modify or create new protocol files. Instructions can be found below.

7. Select the experiment type in the Experiment Type combo box. This instructs the PC on how to generate the olfactometer stimulus/stimuli for each trial which will determine the correct response (left or right). It also instructs the PC on how to display results. The three options are:

   1. None -- for experiments that do not need to generate a new stimulus/stimuli each trial, such as with lick training
   2. Intensity -- for experiments where odor intensity determines the correct response (depending on MFC flowrate value)
   3. Identity -- for experiments where odor equality determines the correct response (depending on odor name)

8. Enter a value in the Shuffle Multiplier spin box. This value is used when parsing the olfactometer configuration file to determine how many times to copy and extend the lists of vial numbers and flowrates before shuffling them. The greater the value, the more random the vials and flowrates will be presented. For example, if the Shuffle Multiplier is set to 3 and the olfactometer configuration file contains four vials resulting in the vial numbers list ['5', '6', '7', '8'], the list will be copied and extended 3 times resulting in

   ['5', '6', '7', '8', '5', '6', '7', '8', '5', '6', '7', '8']
   

   and then shuffled

   ['6', '7', '5', '6', '5', '5', '6', '8', '7', '7', '8', '8']
   

   which will then be iterated through with each trial. Once the iteration through the entire list is complete, it will be re-shuffled and the iteration resets from the beginning. This processes of copying and extending and then shuffling also applies to the list of flowrates obtained when parsing the olfactometer configuration file. Note that increasing the Shuffle Multiplier also increases the probability of consecutive repetitions.

   Set the Shuffle Multiplier value to 1 to avoid consecutive repetitions. This will not copy and extend the lists of vial numbers and flowrates but instead will only shuffle and iterate through them and re-shuffle when iteration is complete to start from the beginning.

   Set the Shuffle Multiplier value to 0 to prevent shuffling, or click the spin box down arrow until Do Not Shuffle appears. This will neither copy and extend the lists of vial numbers and flowrates nor shuffle them, but instead will only iterate through them with each trial in the order they are written in the olfactometer configuration file and repeat from the beginning when iteration completes.

9. Enter the number of trials to run during the session in the Number of Trials spin box.

10. Enter the number of consecutive "No Response" trials after which the PC should abort the session in the Abort when no response for spin box. To disable aborting, click the spin box down arrow until Never appears or enter 0 as the value.

11. Enter the number of consecutive "No Response" trials after which the Bpod should automatically open the water valves to "re-motivate" the mouse in the Auto water when no response for spin box. The left and right water valves will open for one second. To disable automatic watering, click the spin box down arrow until Never appears or enter 0 as the value.

12. Enter the upper bound for the Inter-Trial Interval (ITI) range in the Maximum ITI spin box. The ITI is the duration in between the end of a trial and the start of the next trial in seconds (and there is actually one additional second used by the PC always). The PC randomly selects an ITI with each trial from the given range. To disable random selection and set a fixed ITI to use every trial, enter the same ITI value for the upper and lower bounds, i.e. the Maximum ITI and Minimum ITI spin boxes.

13. Enter the lower bound for the Inter-Trial Interval (ITI) range in the Minimum ITI spin box. The ITI is the duration in between the end of a trial and the start of the next trial in seconds (and there is actually one additional second used by the PC always). The PC randomly selects an ITI with each trial from the given range. To disable random selection and set a fixed ITI to use every trial, enter the same ITI value for the lower and upper bounds, i.e. the Minimum ITI and Maximum ITI spin boxes.

14. Enter a mouse identifier in the Mouse ID line edit box. This identifier is used when saving the session data file.

15. Enter a rig identifier in the Rig ID line edit box. This identifier is used when saving the session data file.

16. Click the Connect Devices push button to connect to the Bpod and, if applicable, the Analog Input Module. It may take a few seconds for the PC to auto-detect the Bpod r2 Plus. Once connected, the Connect Devices push button will say Connected and become greyed-out and disabled, while the Disconnect Devices and Start push buttons will become enabled (not greyed-out). The push buttons in the Bpod Control subwindow will also become enabled.

17. In the Bpod Control subwindow, select the port numbers (on the Bpod) and valve open durations for the left and right sensors and water valves, and the port number for the final valve. Flush out the air from the left and right water lines if necessary by clicking on the Flush Left Water and Flush Right Water push buttons. This will open a small dialog window with a progress bar until the operation completes. The operation opens and closes the respective water valve 100 times, where the open and close durations are each equal to the durations given in the Left Water Valve Duration and Right Water Valve Duration spin boxes, in milliseconds.

18. Click the Start push button to start the session. The Current Trial Info subwindow should become populated and the Streaming Plot subwindow should animate the input signals (e.g. sniff signal, lick detections). After the first trial completes, the Results Plot subwindow should update, as well as the Flow Usage Plot if applicable.

Creating a New Protocol

A protocol file defines the state machine that will be sent to the Bpod to instruct it on what to do. The state machine can be thought of being like a flowchart that checks for different conditions but the "flow" of operation takes only one path from start to end. A state contains four attributes: a name, a timer duration, another state to transition to after a condition is met, and an optional output action. The protocol file is saved in the JSON file format for easy readability and gets parsed when running a session. It can be written with a text editor by following the required structure as can be found in one of the example protocol files, or it can be created by the GUI's built-in protocol editor. To use the built-in protocol editor:

1. Connect a Bpod to the PC first and enter its COM port (or select Auto-detect if it is a Bpod r2 Plus) in the Experiment Setup dock widget on the left side of the main window. This is so that the PC can read all the available input and output channels from the Bpod and display them in the built-in protocol editor. Click the Connect Devices push button.

2. From the top menu bar, click File > New Protocol. The protocol editor will open in a new window. Note that if a protocol file was already selected before launching the protocol editor, the protocol editor will read the selected protocol file and display the states and contents in the diagram area.

3. It may be helpful to draw the state machine as a flowchart before creating it in the protocol editor. Beginning with the first state, enter the state name in the State Name combo box. The combo box is editable and will hold the state names used for previous states for convenience.

4. Enter the state timer value in the State Timer combo box. The combo box is editable and will hold keywords that the PC will use as variables for when the state timer value changes every trial. Those keywords are:

   • rewardDuration -- used for the "reward" state to reward the mouse with water after responding correctly in a trial. It is a variable whose value represents the duration of the reward state, which is just the duration to keep the water valve open and is set by the Left Water Valve Duration and Right Water Valve Duration spin boxes from the Bpod Control subwindow. This variable is needed because the left and right water valve durations may not be equal, and because the correct response changes every trial so this variable is updated at the start of every trial depending on the correct response.

   • itiDuration -- used for the ITI state at the end of every trial. It is a variable whose value represents the ITI duration and is set by the range of the Min ITI and Max ITI spin boxes in the Experiment Setup dock widget. This variable is needed for when the ITI duration changes every trial and is updated at the start of every trial.

   Use the keywords for the applicable states. Otherwise, enter a numeric value for the desired state timer or enter 0 for infinite duration. Note that the state timer will only take effect (i.e. transition to the next state after the elapsed duration) if the "Tup" condition is used in the state's change conditions, as explained below.

5. Add the state change conditions by selecting an event from the State Change Event combo box and then enter the name of the state to transition to when the event occurs in the State Change Name combo box, or select one of the reserved names. The reserved names are used as variables by the PC for transitions that change every trial and for indicating response results. They are:

   • WaitForResponse -- used for the state that checks for the response after presenting the stimulus and transitions to the response state (e.g. reward, punish, etc.) depending on the event occurrence. The PC uses this state to indicate the start of the response window, which is animated in the Streaming Plot subwindow.

   • leftAction -- used as a variable by the PC and gets replaced by the name of the response state depending on the correct response of the trial. It is used in conjunction with the "WaitForResponse" state as the name of the transition state in the state change conditions. For example, if the correct response for a trial is left, then the PC will replace "leftAction" with "Correct" and "rightAction" with "Wrong" before sending the state machine to the Bpod. The opposite applies if the correct response for a trial is right.

   • rightAction -- used as a variable by the PC and gets replaced by the name of the response state depending on the correct response of the trial. It is used in conjunction with the "WaitForResponse" state as the name of the transition state in the state change conditions. For example, if the correct response for a trial is right, then the PC will replace "rightAction" with "Correct" and "leftAction" with "Wrong" before sending the state machine to the Bpod. The opposite applies if the correct response for a trial is left.

   • Correct -- used to indicate when the mouse responds correctly, and signals to the Streaming Plot to end the response window animation and change its color to green.

   • Wrong -- used to indicate when the mouse responds incorrectly, and signals to the Streaming Plot to end the response window animation and change its color to red.

   • NoResponse -- used to indicate when the mouse does not respond within the response window, and signals to the Streaming Plot to end the response window animation.

   • NoSniff -- used to indicate when the sniff sensor does not detect a threshold crossing and can be used as a cutoff for ending the trial instead of waiting forever for the sniff.

   • ITI -- used to indicate the ITI state in conjunction with the "itiDuration" variable.

   • exit -- used to signal the Bpod to exit the state machine, which signals the end of a trial.

   After selecting the state change event and entering the associated state change name, click the Add state change condition push button. The state change condition will be listed in the State Change Conditions list widget box. Continue adding all of the desired state change conditions for the current state. If an error was made, click on the Clear all entries push button to remove all the added state change conditions for the current state and start over.

6. Add an output action for the current state by selecting an output channel from the Output Channel Name combo box. Then select the output value from the Output Channel Value combo box. Then click on the Add output action push button. The output action will be listed in the Output Actions list widget box. Continue adding all of the desired output actions for the current state. If an error was made, click on the Clear all entries push button to remove all the added output actions for the current state and start over. Note that an output action is not required.

7. After verifying all parameters, click the Add State push button on the bottom. The state will appear as a graphic item in the flowchart diagram area and will show the defined parameters. If an error was made, click on the Remove State push button on the bottom to remove the last state added.

8. Repeat the process for defining and adding the next state(s), which will be in the state change conditions of the previous state.

9. When all states have been added, click the Save As button to save the protocol as a new file. The Save button is used to save an existing file. The Save As New Protocol File explorer window will appear. Select the location to save the file to, which is in the protocol_files folder in the root of this repository by default. Name the file and click the Save button to close the windows.

Creating a New Olfactometer Configuration

An olfactometer configuration file defines the settings and contents of the olfactometer, such as the MFC parameters, odor vials to use, and their flowrates. The file is JSON format for easy readability. The PC chooses the odor and flowrate for each trial based on the vials and flowrates information contained in this file. An olfactometer configuration file must only define the settings and odor vials that will be used when it is loaded during a session. To create or edit an olfactometer configuration file using the GUI's built-in editor:

1. From the top menu bar, click on Olfactometer > Configure settings. The editor window will appear.

   

2. Enter the olfactometer's COM port in the the COM Port line edit box.

3. Select the interface in the Interface combo box. Currently, the only interface is teensy.

4. Enter the serial number for Cassette 1 in the Cassette 1 SN line edit box.

5. Enter the serial number for Cassette 2 in the Cassette 2 SN line edit box.

6. Enter the master serial number in the Master SN line edit box.

7. Enter the slave index number in the Slave Index line edit box.

8. Select the MFC type of MFC 0 and MFC 1 from the respective MFC Type combo box.

9. Select the MFC address of MFC 0 and MFC 1 from the respective Address combo box.

10. Select the Arduino port number of MFC 0 and MFC 1 from the respective Arduino Port Num combo box.

11. Enter the MFC capacity of MFC 0 and MFC 1 in the respective Capacity spin box.

12. Select the MFC gas type of MFC 0 and MFC 1 from the respective Gas combo box.

13. Enter the details of each odor vial in the Vials section. Ensure that the vial number matches the physical position in the olfactometer. Only enter details of odor vials that will be used in the olfactometer during the session with which this olfactometer configuration file will be loaded. Unused positions in the olfactometer must be left blank and zeroed in the file.

    • Odor vials cannot have the same name in the Odor name line edit box. To use more than one odor vial containing the same odor name, differentiate between them by appending the vial number to the name.

    • Multiple flowrates can be listed for each odor vial by separating them with commas. They do not need to be sorted, but keep in mind that if shuffling is disabled, the PC will iterate through them in the oder they are listed. Vials can each have different flowrates listed and of different lengths. The flowrate represents the value for MFC 1 and can range from 1 to the capacity of MFC 1.

14. Enter the details of the dilutor if applicable.

15. Click the Save pushbutton to save to the existing file, or the Save As pushbutton to create a new file. A file explorer dialog window will appear. Enter a name for the file and click Save to finish.

Configuring Bpod Flex Channels

The Bpod r2 Plus features four Flex Channels that can each be configured independently as digital input, digital output, analog input, or analog output. The Flex Channels must be configured before running a session. To configure the Flex Channels:

1. From the top menu bar, click on Bpod > Configure Flex Channels. The configuration window will appear.

2. Select the desired channel type of each flex channel from the Channel Type combo box of the respective channel column.

3. Enter the threshold voltage that will trigger an event upon crossing in the Threshold 1 double spin box of the respective channel column.

4. (Optional) Enter a second threshold voltage that will trigger another separate event upon crossing in the Threshold 2 double spin box of the respective channel column.

5. Select the crossing polarity of the first threshold from the Polarity 1 combo box of the respective channel column. This defines the slope direction of the first threshold crossing.

6. (Optional) Select a crossing polarity of the second threshold from the Polarity 2 combo box of the respective channel column. This defines the slope direction of the second threshold crossing.

7. Select the threshold activation mode from the Activation Mode combo box of the respective channel column. The options are:

   • Manual -- thresholds inactivate when crossed and must be re-enabled by the state machine.

   • Automatic -- the two thresholds inactivate, but activate each other (so crossing 1 disables 1 and activates 2, while crossing 2 disables 2 and activates 1). This mode can be used to generate a pair of events for each sniff.

8. Enter the sampling period to use for all analog input channels in the Sampling Period spin box.

9. Click the OK button to finish. The Bpod flex channels will be changed to the new settings.

Configuring Analog Input Module Settings

If using the separate Analog Input Module with the Bpod, the settings must be configured before running a session. To configure the Analog Input Module Settings:

1. From the top menu bar, click on AnalogInputModule > Configure settings. The configuration window will appear.

2. Enter the number of channels on the Analog Input Module that will be used in the Num Of Active Channels spin box.

3. Enter the sampling rate to use for all channels in the Sampling Rate (Hz) spin box.

4. Select the input voltage range from the Input Voltage Range combo box of the respective channel column.

5. Enter the threshold voltage that will trigger an event upon crossing in the Threshold Voltage double spin box of the respective channel column.

6. Enter the reset voltage to be crossed before triggering an event again for the threshold voltage crossing in the Reset Voltage double spin box of the respective channel column.

7. Enable or disable event reporting to the state machine using the Enable SM Event Reporting check box of the respective channel column. This must be enabled in order for the Analog Input Module to send a signal to the Bpod of the threshold crossing event.

8. Enable or disable analog data streaming to the PC using the Enable USB Streaming check box of the respective channel column. This must be enabled to view the analog data in the Streaming Plot subwindow and to save the analog data to the .h5 file created with every session.

9. Enable or disable analog data streaming to another module connected to the Analog Input Module using the Enable Module Streaming check box of the respective channel column.

10. Click the OK button to finish. The Analog Input Module's settings will be updated to the new settings.

Viewing Saved Data

Results of every session are saved in an HDF5 file (.h5 extension) in the results/ folder within location where the repository was cloned to on the local system. It is automatically created when running a session for the first time. The results files can be viewed with the HDF5View application. Data is saved using PyTables and is organized in tables, and similar tables are organized in groups.