Bassoon

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

Requirements

Critical

• Windows (10+) or Linux (Bassoon has not been validated on macOS, iOS, Android, or Linux distributions other than Ubuntu).

Recommended

• A modern graphics card. While Bassoon will run on a CPU, optimal performance during experiments is achieved only with a GPU.
• >1 monitor. Typically, it is helpful to play stimuli on one monitor and to show informational text about stimuli on a second.

Optional

• A USB to TTL serial cable can be used to output precise timing data from the computer running Bassoon to another device. This is typically used to align stimuli to data collected in another program or on another machine (e.g., for electrophysiology or behavioral experiments).
• Meshmapper can be used to create morph files that Bassoon uses to project stimuli onto spherical displays instead of planar monitors.

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).

Common Problems

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

• Package Versions: pip installing psychopy should give you the most up to date version with no dependency conflicts. If you run into errors installing or using the manually installed packages (tk and pyserial) try explicitly installing the following versions:
  • pip install tk==8
  • pip install pyserial==3.5
• Python Version: pip install psychopy may not work with python version 3.12+. If you get an error message that includes something similar to AttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'? when trying to install psychopy, try checking the python version. Type conda python --version into the terminal (make sure the Bassoon environment is activated). If you see 3.12, try downgrading python by typing conda install python=3.11. Then try reinstalling psychopy using pip install psychopy.
• Dukpy Error: Some users have encountered a problem installing the Dukpy package when running pip install psychopy. Typically the error reads something like ERROR: Visual C++ 14.0 is required. Get it with "Microsoft Visual C++ Build Tools". The solution is to download and install Visual Studio from Microsoft, making sure to select the C++ packages during the installation process. Sometimes a link to dowload the software is also reported with the error message, which works equally well. Once you've installed Visual Studio, try rerunning pip install psychopy.
• macOS Fatal Python Error: Bassoon can be successfully installed on Apple Mac following the same steps described above. However, when trying to launch the GUI by running the main.py file, several users have encountered a fatal python error. This seems to be an inherent problem with how Macs use Tkinter, and a quick google search reveals it's a common problem across many applications. There is no known solution to this issue yet; thus, it may not be possible to run the Bassoon GUI on Mac. However, experiments can still be created programmatically, and all of Bassoon's core functionality still works.

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

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. 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:
   • backgroundColor: The color of the background of the monitor, behind/under the presented stimulus. Like all parameters that modify a color property, this value is given as a list of floats corresponding to RGB values. A value of -1.0 corresponds to 0 (dark/black) and a value of 1.0 corresponds to 255 (bright/white).
   • interStimulusInterval: The time between epochs, given in seconds
   • preTime: The time at the beginning of a stimulus before the stimulus is made dynamic. For the Flash stimulus, this is a period of time in which the background is visible, but the flash has not started. For an oscillating grating stimulus, the grating is visible during this time, but it hasn't started oscillating yet. Given in seconds.
   • protocolName: The name of the protocol that you are playing. This defaults to the corresponding file name in Bassoon, and changing this is usually not recommended.
   • randomSeed: A random float value between 0 and 1 that is used for pseudorandom computations in some stimuli. For instance, in a stimulus that presents a random sequence of images, the random seed can be used to calculate the sequence to show the images. By using the same random seed twice, you can exactly repeat the same pseudorandom sequence.
   • stimTime: During this time, the stimulus becomes dynamic. For the flash, it's the amount of time that the screen lights up. For the oscillating grating, it's the amount of time that the grating oscillates. Given in seconds.
   • stimulusReps: Number of repetitions of the stimulus. For some stimuli, this number is multiplied by another parameter (such as a list of directions for a moving bar) to determine the total number of epochs. For the flash, the number of epochs is equal to the number of stimulusReps. Given as an integer.
   • suffix: A string value that you can add on to the name of your stimulus in order to differentiate its display name from other similar ones. For instance, you might add "_long" to the flash, which will update its name in the protocol list to "Flash_long". It's always recommended to start suffix strings with the underscore character "_" in order to distinguish them from the protocolName.
   • tagList: A list of strings that you can use to add tags to a stimulus for analysis. Add any tags you want.
   • tailTime: The same as the preTime, but it happens after the stimTime instead of before.
   • userInitiated: A boolean value that is set to True only if the user wants to manually press a keyboard button to specifically start the stimulus during the experiment. This value can also be set for all stimuli at once in the experiment settings.
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.
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).
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:

• Epochs: An epoch is a single itteration of a stimulus. For a stimulus that consists of a bar that drifts across the screen for instance, an epoch equates to one pass of the bar across the screen. For a flash stimulus, an epoch contains one flash
• Protocols: A protocol is a type of stimulus. Examples of protocols include the Drifting Bar, Oscillating Grating, and Flash. Protocols typically consist of multiple epochs (unless the user specifies that only a single epoch should be played).
  • Each protocol has a .py file associated with it in Basson/src/protocols. This file defines the stimulus, its parameters, and what happens when it is run. There is a common set of functions that each protocol contains, including __init__(), estimateTime(), and run():
    • __init()__: Initializes the protocol (i.e., is executed when the protocol object is created by Bassoon - specifically, this happens when the user adds the protocol to their experiment sketch using the "Add Stimulus" button in the GUI). Listed at the top of this function are several attributes. Some are common across stimuli, while others are particular to certain stimuli. When a user "customizes" a stimulus, they are modifying these attributes. Any attribute that starts with an underscore "_" charcter, however, is not customizable by the user (e.g., self._angleOffset). These underscore properties are manipulated programmatically by Bassoon.
    • estimateTime(): A function that approximates the total time that the stimulus will take to run, based on key properties. The mechanics of this function are similar across protocols, but vary according to the specifics of how the protocol's run() function is designed.
    • run(): This is where Bassoon calls on the psychopy libraries to build and execute stimuli. The first half of the function typically involves creating the initial state of the stimulus and performing some computations that will be used to dynamically modify the stimulus during the stimTime. The run() function almost always also contains a for-loop, which iterates through each epoch to sequentially present them. In the loop, the psychopy stimulus is repeatedly updated and pushed to the stimulus monitor on every frame. This update step typically involves updating some parameter of the stimulus to make it dynamic across time (e.g., changing the position of a drifting bar stimulus on each frame such that it glides across the screen). For every epoch, nearly all protocols have 4 distinct sections of the for-loop that execute:
      • Interstimulus Interval: The period of time between sequential epochs. Typically, a blank or gray screen is presented during this time
      • Pre Time: This is a static period that occurs immediately before a stimulus starts. It typically consists of a static version of the stimulus presented on the screen (e.g., a stationary grating during the oscillating grating stimulus).
      • Stim Time: The stimulus is dynamic during this time (e.g., an oscillating grating is continuously oscillating).
      • Tail Time: Very similar to the pretime, but occurs after the stim time
      Bassoon runs according strictly to frames, not time. This means that for each of the 4 sections of the for-loop above, there is a specified number of frames that Bassoon must execute (which are typically calculated during the first part of the run() function, before the loop). Thus, stimuli that are computationally/graphically heavy can slow down the execution. If this occurs, it will be documented in several saved parameters that are created during the execution of the stimulus, such as self._stimulusStartLog and self._stimulusEndLog, which save the start and end time of each epoch. Note that these attributes start with the underscore "_" character. As described above, that makes them (and many similar ones like them that are created in the run() and other functions noneditable by the user. They are, however, saved with the stimulus so they can be used for analysis.
  • Each protocol file is also a subclass of the protocol superclass (located in the same directory), which holds an additional set of common functions and parameters that are inherited by all protocols:
    • __init__(): Same as the corresponding function for each individual protocol, but these attributes are inherited across all protocols (i.e., in addition to the attributes that are specified within each protocol's own __init__() function).
    • internalValidation(): Used to check whether the user has entered valid values for editable attributes when an experiment is being created. Several individual protocols also have functions called internalValidation() that overwrites this function when it exists (several protocols do not have their own version of this method, in which case this general version is called). This function returns two values: tf is a bool value that is true only if all validations are passed, otherwise it is false; errorMessage is a list of strings containing messages to report back to the user for each of the validations that are not passed. If tf is true, then errorMessage should be and empty list. See the MovingGratingScotoma.py file for an example of how to write a validation function (and you can validate any and all parameters that you like!).
    • validateColorInput(): An add on to the validation function that will check all color parameters. It does this by looking for attributes of the protocol that have the word "color" in their name and checking each one to make sure that it is a list of 3 rgb values between -1 and 1 (the accepted range for rgb values in psychopy). This is a useful method to add onto any protocol's internalValidation function.
    • printDescription(attributeName): Called when a user presses the information button for a parameter in the edit protocol window. This function prints the description of that parameter to the console. Specifically, the description is defined by the comment in the __init__() function in the protocol's .py file, or in the protocol.py superclass.
    • _get_attribute_descriptions(cls): A helper function that is called by self.printDescription(attributeName), this function traverses the protocol's __init__() function to extract the informational comments next to each attribute. It also caches the results so that the process only needs to be performed once per protocol.
    • getFR(win): Returns the frame rate of the stimulus monitor (win) and calculates the number of frames needed for the pretime, stimtime, and tailtime. This function is usually called near the top of each protocol's run() function. Note, that because this is an inherited function by all protocols, they all must have a pretime, stimtime, and tailtime field (sometimes regardless of if they're used). The MovingGratingScotoma stimulus, for instance, should not have a user editable stim time based on its mechanics. However, it needs an attribute called self.stimTime to avoid raising an exception in this and other functions. To get around this, the stimtime is checked in the internalValidation() function and reassigned to 0 if the user attempts to change it. A notice is also provided to the user through a print statement in the console.
    • getPixPerDeg(stimMonitor): Calculates the number of pixels per visual degree for the stimulus monitor. To do this, the function draws on the attributes of the saved/loaded monitor that the user has indicated that they are using (through the attributes of the experiment object). Before running Bassoon for the first time, you may want to set up (and save!) a new psychopy monitor. This can be done entirely through the psychopy api (outside of Bassoon) and/or in the psychopy GUI through the monitor center. If you have saved your monitor correctly, it should show up as a selectable option in the dropdown menu under "monitors" in Bassoon's "options" menu (accessible through the GUI).
    • showInformationText(stimWin, txt): Pushes a message to the information window if the user has enabled it. This is typically updated for each epoch (i.e., for each iteration of a protocol's run() function.
    • checkQuitOrPause(): Checks for two keystrokes that the user can execute while a stimulus is running: p pauses a stimulus and q quits a stimulus (jumps to the next one in the experiment, or ends the experiment if it's the last one). Both pauses and quits are documented in saved parameters.
    • sendTTL(): This function is used to send timing signals over a TTL port. This is useful if you want to align the stimulus to something outside of Bassoon (e.g., a recording of animal behavior). Enable a port from the options menu in the GUI. Hardware wise, you can simply use a USB-to-TTL serial cable such as this one and the system should recognize it once plugged in. Bassoon sends TTL pulses via the RTS pinout. There are two different TTL writing modes that provide different levels of precision:
      • Pulse: Writes one byte rapidly over the line. Used for high temporal precision experiments (such as electrophysiology recordings), but is more difficult to decode in analysis (though certainly not impossible).
      • Sustained: Holds the RTS pinout at 5V during each epoch and 0V between epochs/stimuli. This level of timing is sufficient for most behavioral experiments where millisecond precision is not critical (including eye tracking experiments).
    To better understand how each stimulus uses TTL pulses to send timing signals, look at the their individual files. The calls to sendTTL() happens inside the for-loop in the run() function.
  • burstTTL(win): Sends a stereptyped burst of TTL pulses when in Pulse mode in order to mark the start of a stimulus. This is only implemented for a few stimuli. This function can be modified to change the signature burst to be anything you like, but currently it sends 20 TTL pulses at frame rate, pauses for 0.2 seconds, and then sends 20 more TTL pulses at frame rate. Note: in some contexts, it can be critical to not send TTL pulses faster than the frame rate because depending on the temporal resolution of your detection system, pulses can be missed.
  • reportTime(displayName): Prints a timing report for each protocol to the console when the user checks the corresponding box in the options menu of the GUI. This can be very helpful to understand whether a stimulus is too computationally/graphically heavy to execute at frame rate. It's recommended that each stimulus is tested and timing reports are printed prior to using them in actual experiments.
  • printProgressBar(iteration, total): Used to print a progress bar to the console when needed. This is typically only used for stimuli that have a lot of upfront computation to perform (usually in the run() function) prior to executing in order to inform the user as to approximately how long it will take to load the stimulus.
• Experiments: Experiments are a custom class in Bassoon that contain a list of all the protocols that the user wants to run. You can think of an experiment as a large bag. As a user creates an experiment, they add protocols (with all of their properties) to the bag. When the experiment is run, those protocols are removed from the experiment bag one by one and executed for the user.
  • Loading Experiments: Only one experiment can be loaded into Bassoon at a time. You can do this either by launching the GUI and adding protocols using the drop down menu, or by loading a previously run experiment using the "load experiment" option in the menu bar. When an experiment is loaded, all of the properties are loaded, as well as the list of protocols it contained, and the properties of those protocols. Thus, you can design an experiment well ahead of running it, save it, and then load it when needed. If you are running the same experiment on several subjects, you can always load the same experiment file!
  • Experiment Properties: Experiment properties hold true across stimuli. Thus, these are things like which monitor to use, whether you would like to use a timing signal, and so forth. Properties can be edited (and saved) through the options menu in the GUI. If you save properties, they will be loaded the next time you launch Bassoon. Most properties are intuitive, but here are a few that deserve some explanation:
  • Monitor: Select which monitor to use for the stimulus. NOTE: A MONITOR IS NOT EQUIVALENT TO A SCREEN. A monitor object in psychopy defines the parameters of the monitor (e.g., size and how far the user is positioned from the screen), and is used to adjust the size of stimuli accordingly. The monitor can theoretically be used on any screen, though it should really only be used with the appropriate one. The dropdown menu in the options menu shows all available monitors that you have saved through psychopy. You will likely want to create and save a new monitor prior to using Bassoon beyond testing. You can do this through the psychopy API or in the psychopy GUI through the monitor center. If you have saved your monitor correctly, it should show up as a selectable option in the dropdown menu under "monitors".
  • Full Screen: Check the box to load the stimulus in full screen mode. WARNING: While full screen mode is typically used for real experiments, be careful when using it during experiment creation and debugging. It can be exceedingly diffuclt to manually exit out of psychopy windows once they are created, so if python or Bassoon crashes while a psychopy window is open in full screen mode, you may be forced to make a hard restart.
  • Screen #: Select the screen number that you would like to present the stimulus on. This is 0-indexed according to how your system orders your screens.
  • Use Information Window?: Check the box to show a second window during the experiment, which typically displays text with information about the current stimulus. It can be helpful to place this information window on a second monitor for only the experimenter to see (not using full screen mode). It's usually not critical to create a psychopy monitor for the information window since subjects are not typically looking at it.
  • Manually Initiate Each Protocol: When checked, the user must press a button before the start of each stimulus in order for it to begin. Selecting this option WILL NOT update stimuli that are already in the experiment list. So, if you switch this value after already having added stimuli to your experiment, be sure to go into each pre-existing stimulus to make sure the "userInitiated" setting is what you want it to be. (Note: this behavior can be leveraged for efficiency, for instance by first adding all stimuli that you don't want to manually initiate, and then checking this option and subsequently adding all stimuli that you do want to manually initiate).
  • Angle Offset: Applies a constant angular offset to all stimuli in the experiment.
  • Write TTL Pulses: Set the TTL timing signals to None, Pulse, or Sustained (see above). When in None, timing signals will not be executed.
  • TTL Port: Select the port name to use to send timing signals. The port typically must be configured as a serial/TTL port (see above).
  • TTL Bookmarks: Sends specific timing signal signatures at the start and stop of stimuli when TTL mode is set to sustained. See the protocol.py file to understand how this is used.
  • Use FBO?: Check this box when you want to use a frame buffer object, which is needed to morph stimuli for projection on curved surfaces.
  • Warp File Location: Enter the path to the warp file when using FBO. If no path is entered, but the Use FBO box is checked, you may encounter an error. Warp files can be generated using meshmapper.
  • Recompile Experiment When Saving: There's almost never a need to check this box outside of development. It overwrites custom properties set for each stimulus when saving. Recompilation is automatically turned off when a user is saving an experiment immediately following a run.
  • Print Timing Reports: Prints timing information to the console after each stimulus. Use this when determining if stimuli that you've created can run at the proper speed.
  The underlying experiment attributes that are manipulated can be found in the experiment.py __init__() function. There are also several other attributes that are not accessible to the user through the options menu.
  • The experiment class has a few methods:
    • __init__(): Establishes the default attributes of the experiment when its first loaded (which happens when Bassoon launches). If the user has previously saved experiment properties, it will load this from a JSON file.
    • addProtocol(newProtocol): This function adds protocols to the experiment as their created. Using the analogy above, this is what runs when you place a new protocol into your experiment bag.
    • establishPort(portInfo): Handles the TTL port that is used to send timing signals. The mechanics are not so important, but just know that the status of the port has to be given special attention in order to avoid memory errors.
    • activate(): This is the function that runs when you run the experiment from the Bassoon GUI. It launches the psychopy windows that the stimuli and information are presented on, sets up some basic parameters, and then loops through each stimulus that has been added to the experiment bag, executing them in order. It also has some safety features for TTL handling, and calls the reportTime() function after each protocol if the user has requested it.

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.