Bassoon

Bassoon Logo

Develop, organize, and deploy vision science experiments.

Bassoon is no-code visual graphics software to easily create, manage, and execute custom visual stimuli for vision science experiments. Bassoon is python based, and is built on the popular Psychopy API.

Maintained by the Dunn Lab at UCSF.

Documentation

Table of Contents

Requirements

Critical
Recommended
Optional

Installation

Bassoon relies on Python 3 and the Psychopy libraries. Follow these steps to install Bassoon on your computer:

  1. Download Bassoon: Download a zipped Bassoon folder here. You can also download or clone directly from the Github repository. Once downloaded, extract the files into a directory on your local computer (if you'd like to receive updates to your local copy as they're published to github, cloning is highly recommended over downloading. If you're new to git and using Windows, checkout github desktop to manage your packages).
  2. Download Python 3, Create an Environment, and Install Psychopy: There are two options for downloading python if you do not already have it.
    1. Create a conda environment (recommended): Download anaconda or miniconda. Launch the terminal (on windows, you must use "Anaconda Prompt") and create a new conda environment called "Bassoon" by typing conda create -n Bassoon python=3.10. Once the environment is created, activate it using conda activate Bassoon and install psychopy by entering pip install psychopy (note that there used to be a conda distribution for Psychopy, but it is no longer up to date). If you run into trouble, look through the Psychopy documentation.
    2. Install python/psychopy outside of conda: If you would prefer to install python/psychopy in a different way, you may. Regular Venvs should work along with pip installs. Be sure to use python 3 and to pay close attention to the psychopy documentation.
  3. Install Additional Dependencies: Other packages that are needed are tkinter and pyserial. Install them into your conda or virtual environment by running pip install tk and pip install pyserial. Make sure that your conda or virtual environment is activated before pip installing (typically, this is indicated by the name of the environment being listed in parentheses in your terminal/anaconda prompt. For instnace, (base) C:\Users\mrsco> indicates that the base environment is active).
  4. Install an IDE for Python: This step is not strictly required, but highly recommended. It will allow you to make changes to Bassoon, including adding or modifying stimuli on your local device, debugging errors, and making contributions to the Github repository. If you installed Psychopy via conda, make sure the environment is activated (conda activate Bassoon) and then enter conda install spyder into the terminal (or conda prompt). Once installed, you can type spyder into the terminal, and it should launch an IDE from which you can view, test, and run Bassoon. If you prefer an IDE other than spyder, a popular option is VS Code (you can follow these instructions on how to connect VS code to python, especially if you are not using a conda environment).
You should now be ready to run Bassoon. Locate the file called main.py, which is located in /Bassoon/src/. Either open this file in your IDE and press run, or run it directly from your terminal (on Windows: python /path/to/main.py). If the Bassoon window launches then you're ready to go! If you encounter an error (either here or at any further step) make sure you have the neccessary dependencies installed.

Common Problems

This section contains a list of known errors that users have encountered while trying to install Bassoon.

General Advice for Python Beginners: If you're new to programming, one of the most tempting things to do when you encounter a new or unknown error is to give up and ask for help. However, a closely kept secret is that even for experienced programmers, almost every error is a new error! I strongly encourage you to try to debug errors and problems yourself (at least for a bit). It's by far the best way to learn and build confidence. The biggest tips I can provide are to read the error messages and terminal outputs, look through the code (especially if an error message points you to a particular line), experiment, and USE GOOGLE! There's a 99% chance that the solution is documented somewhere online - Stack Overflow, Reddit, and even ChatGPT are great starting points. If you really can't figure something out, then ask for help - but don't be surprised if the "expert" you turn to just as quickly goes to Google to find the answer.

General Use

This section describes how to create custom experiments using Bassoon's no-code GUI. For a detailed explanation of how Bassoon operates behind the scenes, including descriptions on how to create new protocol classes, see Nuts And Bolts.

To launch Bassoon run the main.py file. Enter python /path/to/main.py in your terminal, where /path/to/ is replaced by the path on your local machine to the directory that houses Bassoon's main.py file (you can also cd to the directory and then just enter python main.py).

The following window will open Bassoon Main Window With Labeled Buttons

The general work flow is to create (or load) an "experiment sketch" and then run it. The experiment sketch consists of a list (in order) of all the stimuli that you will run, customizations that you have made to each of them, and the settings that you would like to use for the experiment. Once you've built an experiment sketch, you can run it and save it. You can also load previously built experiment sketches directly into Bassoon, which can then be run immediately.

The red numbers in the image above label the basic buttons to use in Bassoon. Broadly, you will add stimuli to your experiment sketch, customize their parameters, customize the experiment settings, and then run the experiment. Below is specific information on each button:

  1. Protocol Drop Down Menu: Click this to see all available stimuli that you can add to your experiment. Select one to add.
  2. Protocol Index Box: Enter the index number where you would like to add your selected protocol. 1 corresponds to the first protocol that will be played in the experiment sketch.
  3. Add Stimulus Button: Press this button to add the stimulus you selected at the index number listed in the Protocol Index Box.
  4. Protocol List: After pressing the Add Stimulus button, your new stimulus should be displayed in the white area. The order of stimuli listed here corresponds to the order in which they will play. There are several features available via the "Quick Actions" menu (number 10) to modify this list rapidly.
  5. Edit Stimulus Parameters: Bassoon allows you to easily customize the parameters of each stimuli in the experiment sketch. Select any of the stimuli in the protocol list, either by single clicking on their name and then pressing edit button (5b), or by double clicking on their name. This should open a new window, which shows all of the customizable parameters for the stimulus. Parameters for the flash stimulus You can change the values of each parameter using the text boxes next to their name in the new window. The information in brackets < > on the right side tell you the data type that you must enter (these correspond to python classes). For lists, you'll see two entries, one that says 'list' and a second that specifies the data type of each list element, such as 'float'. You can click the information buttons next to each parameter to print out a description of what they do to the console. Once you've customized the stimulus by changing all necessary parameters, click the Apply Changes button. You should receive a report in your python console indicating that the properties were successfully updated. After pressing Apply, the Estimated Time value will also update, indicating the amount of time that the stimulus is expected to take. Once you are finished customizing the parameters, you may exit the edit window. Note that for lists, you must use the correct syntax, including square brackets on either end and commas between entries. If you enter the wrong data type, your changes may be rejected, and this will be reflected in the python console.

    While most stimuli share some parameters in common, each one also contains its own unique parameters. If the information icons do not provide enough information, the best way to get familiar with what each parameter does is through experimentation. You can also look at the source code files (see Nuts and Bolts). A few common stimulus paramaters are described here:
  6. Remove Button: Select a stimulus and then press this button to delete it from the experiment sketch.
  7. Save Button: You can save an experiment sketch at any time using this button. When a stimulus runs, new parameters are generated so it's always important to save after running (and Bassoon will automatically prompt you to do this by openning a save dialogue at the end of each experiment). However, you can also save an experiment before running it (including while you're in the process of designing it). This allows you to build an experiment ahead of time, save it, and then reload the experiment into Bassoon when you're ready to run it. Similarly, you can rerun previous experiments that you've performed. The button appears red when the current experiment is not saved and green when it is saved.
  8. Load Experiment Menu: Select this button to load a previous experiment. You will be taken to a dialogue box to select a previosuly saved experiment. Once loaded, that experiment sketch will automatically populate your Bassoon window. You can run it immediately, or make additional customizations. Note, that when loading experiments, you will load in the same randomSeed parameters as previously used, meaning that pseudorandom stimulus sequences will be identical unless this value is changed.
  9. Options Menu: Allows you to customize specific parameters for your experiment. See below for a walkthrough of some of these features. Of primary importance, you must set up a monitor using the Psychopy monitor API or monitor center in order for stimuli to appear at the correct size during experiments.Experiment Options Window
  10. Quick Actions Menu: Use this window to quickly perform different tasks. You can reorder stimuli, make a copy of a stimulus you have already customized, or manually turn ON and OFF a TTL output (if you have one).Quick Actions Menu
  11. Run Experiment Button: Press this button once you have fully customized your experiment. It will launch the stimuli in a new window on the screen you specified in the Options Menu (#9). The stimuli will play in the order that they appeared in the protocol list box. The main Bassoon window will disappear from view while stimuli are playing, but Bassoon will continue to send you real time updates about the experiment through the python console, so look for messages. You may skip a stimulus at any time by pressing the 'q' key. You may also pause a stimulus by pressing the 'p' key. If you have selected to use an information window, additional information about the stimulus will appear there. Once the stimulus is done playing, you will automatically be requested to save the experiment. It is a good idea to do so, even if it has been previously saved, because there are new parameters that are created when the experiment runs. These include many paramters about the structure and timing of stimuli that can be critical for analysis.
  12. Quit Menu Option: Once you have finished running your experiment and saved everything, you may exit Bassoon by pressing the quit button.

When Bassoon saves experiments, it creates one file with the extension .EXPERIMENT, and another that is in JSON format. The former is a pickled python file that can be easily loaded into python for analysis. The latter contains all of the same data, but is visualizable and more easily used with other programming languages such as MATLAB or R. All of the parameters from each protocol that you added to the experiment are available through either file.

Nuts and Bolts

Experiments, Protocols, and Epochs

Bassoon's goal is to present a temporally precise sequence of customized stimuli to the user. It does this by organizing stimuli into three levels of abstraction. From lowest to highest level:

Experiments and protocols are created and manipulated through the Bassoon GUI. This is to make it as easy as possible to create, customize, and execute experiments. However, you can also access them programmatically, outside of the GUI:

from psychopy import core, visual, data, event, monitors
from experiments.experiment import experiment
from protocols.protocol import protocol

# You must import each protocol that you want to use. Here I import just the flash stimulus as an example.
from protocols.Flash import Flash

# Load an experiment
exp = experiment()

# Load the flash stimulus
stim = Flash()

# Edit an attribute of the flash
stim.stimTime=5 #in seconds

# Add the stimulus to the experiment (put it in the "bag")
exp.addProtocol(stim)

# Change an attribute of the experiment
exp.useInformationMonitor=True

# Run the experiment
exp.activate()

main.py

The main.py file is the outter-most layer of Bassoon. It is used to launch the GUI, contains all of the code for every button and action, and can be thought of as the orchestrator of all Bassoon functionality. Tkinter is used for the graphical interface. The best way to understand how the GUI works is to look through the code and experiment with it. There are plenty of example snippets that can be used as a reference to implement your own buttons and functionality.

For most users, it will not be necessary to make any changes to the GUI. The only section of the main.py file that requires regular attention is the import statements at the top of the script. If you create a new stimulus (which can easily be done by making a new .py file in the Bassoon/src/protocols folder, copying the structure of a previously existing protocol file, and making adjustments for your new stimulus as needed), you will have to add a corresponding import statement to the top of main.py. This takes the form of from protocols.myprotocol import myprotocol (replacing myprotocol with whatever you named your new protocol).

Use and Contributions

Bassoon is intended for noncommercial use only. If you would like to use this software for commercial research, please send us a message to inquire about a license.

If you use Bassoon for published science, please include a citation.

Contributions to the Github repository are welcomed. Suggestions or questions can also be directed to Scott Harris.