This document briefly describes the various software tools developed for the Generation 4 Modular LED Display system. Full documentation is available at https://reiserlab.github.io/Modular-LED-Display/. The G4 Display Tools require the Hardware and Software to be working correctly. It is compatible with matlab versions R2019b and newer, but has not been tested on earlier versions.
These tools can be used to generate visual stimuli, run experiments, and analyze the acquired results. Some of the software tools described later in this document do not require a physical LED arena set up and attached to the computer in order to be used; for example, the Pattern Generator scripts can be used to generate and visualize patterns without any G4 hardware attached, and the Data Analysis scripts only require the TDMS log files generated during an experiment in order to analyze and plot data. Other tools, such as PControl and the Protocol Designer scripts, will only be fully functional when connected to a G4 Display system.
This set of scripts and GUIs can be used to design patterns (primarily for displaying pattern, rather than pictures of objects) on the G4 display. Patterns are generated using the G4_Pattern_Generator_gui.m script based on input parameters that describe the desired pattern. These scripts output two types of pattern files: The first type is a .mat file which contains the created pattern matrix and all the pattern parameters so that it can be easily read back into MATLAB. The second type is a .pat file containing a binary vector of the pattern that can be quickly accessed by the Display Controller. Only the .pat file is necessary to be displayed on a G4 arena, though the .mat file is needed to be easily loaded back into MATLAB for viewing, debugging, or for creating experiments with the G4 Protocol Designer.
This set of scripts and GUIs allow for the design and creation of analog output functions and position functions, to be used in conjunction with displaying patterns on a G4 display. Position functions control what frame of the selected pattern is displayed for every refresh cycle (when the display system is operating in position function mode), operating at a rate of either 500 or 1000 Hz (1-bit or 4-bit patterns, respectively). Analog output functions control the voltage of the analog output channels of the G4 system (accessed easily with the optional breakout box) in a way that is synchronized to the display refresh cycle, operating at 1000 Hz regardless of the pattern refresh rate. Similar to G4 Pattern Generator, functions are created using the G4_Function_Generator.m script based on input parameters that describe the desired function. These scripts output two types of files: The first type is a .mat file which contains the created function array and all the function parameters so that it can be easily read back into MATLAB. The second type is either a .afn (for analog output functions) or .pfn (for position functions) file containing a binary vector of the function that can be quickly accessed by the Display Controller.
Developed by Jinyang Liu, PControl_G4 allows for communication between the G4 display system and MATLAB by establishing a TCP connection between the two. A controller can be opened by created an instance of the class PanelsController. Commands for displaying patterns and using functions in various modes can be sent using the controller, provided that an experiment folder has been created and specified. Experiment folders can be made by manually selecting pre-made pattern and function files using the design_exp GUI. Running PControl_G4 automatically connects to the G4 display and opens a window where an experiment folder can be specified and various commands can be sent, including commands for displaying the patterns included in the experiment folder. Finally, examples of custom-written patterns and functions are also included in this set of scripts.
Developed by Lisa (Taylor) Ferguson, these scripts and GUIs allow for designing, visualizing, and running experimental protocols using patterns and functions that have already been created. An experimental structure can be created and visualized using the G4_Experiment_Designer GUI, where pre-made pattern and function files can be selected and organized. Experimental protocols can be validated within the GUI and saved as .g4p files. The G4_Experiment_Conductor GUI can run experimental protocols and display information on the current experiment progress in real-time. See the documentation on the G4 Protocol Designer for more details on how to use these scripts.
The “G4 Experiment Conductor GUI” can run experimental protocols and display information on the current experiment progress in real-time.
These scripts – using many of the functions described in the previous tools – demonstrate an entirely script-based solution for creating patterns, functions, and experiment folders, as well as creating and running experiments with the G4 system.
These scripts can be used to read data logged and acquired by the G4 display system into MATLAB. Each experiment (marked by start log and stop log commands) outputs a folder of log files in .TDMS format, which can be read and converted into a MATLAB struct using the G4_TDMS_folder2struct function. These log files contain data and timestamps corresponding to the frames displayed during that experiment as well as the commands received over TCP. Any active analog output and analog input channels are also logged by both voltage and corresponding timestamp. Additional scripts are included for further processing, analyzing, and plotting data from two example categories of experiments – a tethered fly walking on an air-suspended ball, and a tethered flying fly monitored with a wingbeat analyzer. An example of a full data analysis pipeline is shown in the test_G4_Data_Analysis.m script.
This software uses a couple work arounds for bugs found in matlab that mathworks has not yet addressed. The function findjobj, written by Yair Altman, allows us to reset the position of a table's scroll bar after updating the table, instead of letting the scroll bar jump to the top of the table. The function fixfocus, written by Jorg Woehl, corrects a bug in which the file window opened when the user tries to browse for a file opens behind the GUI figure and not in front of it.
Yair Altman (2024). findjobj - find java handles of Matlab graphic objects (https://www.mathworks.com/matlabcentral/fileexchange/14317-findjobj-find-java-handles-of-matlab-graphic-objects), MATLAB Central File Exchange. Retrieved June 4, 2024.
Jorg Woehl (2024). fixfocus (https://github.com/JorgWoehl/fixfocus/releases/tag/v1.2), GitHub. Retrieved June 4, 2024.