Workflow

This section will go through the entire process of using ReVAS GUI, after starting it up, to analyze retinal videos. A typical ReVAS GUI workflow is illustrated in the figure below.

The process starts with selecting a set of videos (or .mat files) and adding them to the File Selection panel. The next step is to open an existing pipeline or creating one from scratch. The third step is to set global flags. The final step is running the pipeline on selected files in the File Selection panel by simply clicking the Run button, or using Run -> All files menu to run all files.

1. File selection

The first step is to select what type of input file that will be used. Selection depends on which step of the analysis that you will begin with:

• Raw videos have a .avi extension. Use this option for videos that have not been analyzed at all.
• Trimmed videos have a _trim.avi extension. Use this option for videos that have already been trimmed by the Trim Module.
• Stimulus Removed videos have a _nostim.avi extension. Use this option for videos that have already had their stimulus removed by the Remove Stimulus Module.
• Gamma Corrected videos have a _gamscaled.avi extension. Use this option for videos that have already been processed by the Gamma Correction Module.
• Bandpass Filtered videos have a _bandfilt.avi extension. Use this option for videos that have already been through bandpass filtering by the Bandpass Filtering Module.
• Eye Position files have a _position.mat extension. Use this option for loading already extracted eye motion traces for further processing (such as filtering, event detection, etc.)
• In Memory files have a _inmemory.* extension. Use this option to do further processing on previously analyzed videos with inMemory flag on. For instance, if modules A, B, and C were used on a video named demo.avi with this flag set to true, intermediate outputs are not written into separate files. Instead, all processes take place in memory and only the final output is written to a file. That final file will be called demo_a_b_c_inmemory.*. As can be seen, the full file name can be used to reconstruct which modules were used to produce that _inmemory.* file.

Once one of these options is clicked via File menu, the following uipickfiles GUI (by Douglas Schwarz) pops up with proper filters.

Then, select the videos that will be added to the list. To do this, navigate to the folders of interest, select relevant files, and then click Add. You should see the added videos appear on the right window. Click Done to complete the process.

To remove selected videos, highlight the videos you want removed, then click the Remove button. When you are finished with your selection(s), click Done. Your selected videos should appear in the File Selection panel of the main GUI.

2. Pipeline configuration

The second step is to load an existing pipeline or create one from scratch using Pipeline -> New menu. During this process, available modules can be added to the pipeline and their parameters can be adjusted to desired values. The New Pipeline Tool automatically checks the connectivity rules for modules in the pipeline and throws an error dialog if there is any violations.

Note: When a new module is created, its connectivity rules, file extension keyword, default values and validation functions for its parameters must be added to the GetDefaults.m function under utils/ folder.

The connectivity matrix for the available modules as of 5/2020 is given below. Modules given in rows can come before those listed on columns. For instance, the StripAnalysis module can be placed before None (i.e., StripAnalysis can be the final module of the pipeline), 'MakeReference', 'Pix2Deg', and 'Re-reference'. To see which modules can be inserted before a given module, the corresponding column can be read. Following the same example, StripAnalysis can be preceded by None (i.e., it can be the first module of a pipeline), Trim, RemoveStimulus, FindBlinks, ContrastEnhancement (or GammaCorrect), BandpassFilter, and MakeReference modules. Note that connectivity matrix is not symmetrical.

An example pipeline is visualized below.

Clicking Pipeline -> New will cause New Pipeline Tool window to pop up.

Available modules (within corepipeline/ folder) are listed on the left. After selecting a module and pressing -> button, it can be added to the pipeline, shown on the right. The order of modules in the pipeline listbox determines the order of processing. After adding a module to the pipeline, it can be double clicked to open up a new window with the parameters of that specific module. And example window for modifying parameters of a StripAnalysis module is given below.

Once all necessary modules are added in desired order and their parameters are adjusted, click OK to transfer the pipeline to the main GUI.

Here is how the Pipeline panel should look like after this.

If a pipeline is already loaded to the main GUI, the parameters of its modules can be edited directly by double clicking on a module name in the Pipeline panel. Alternatively, Pipeline -> Edit menu can be used to accomplish the same purpose. The latter method also allows user to add/remove modules.

If a give pipeline produces satisfactory results, users can save it to a file by using Pipeline -> Save menu. If there is no filename associated with the current pipeline, this operation acts identical to Save As where a dialog box appears for user to enter a file name and select a destination folder for the pipeline. Once a pipeline is associated with a file path, subsequent Save operations silently overwrite the same pipeline file.

For a full description of what each module does and usage examples, refer to the function headers of individual modules.

3. Global flags

The third step is setting global flags, i.e., high-level settings which might affect all modules (e.g., visualization), or settings that are made available at this stage for convenience and clarity (e.g., parallelization, GPU, etc.).

• Visualize results?
  • yes: first level of visualization for each module (if available)
  • no: no visualization,
  • module: leave visualization level to individual modules (user needs to set this setting for each module individually to desired effect).
• inMemory: enable it if you don't want to save output of each module to a separate file.
• enableGPU: enable it to use CUDA enabled GPU wherever applicable. If there is no supported GPU on a system, this option will not be available.
• enableParallel: enable it to use multiple cores on the computer. Parallelization is done at input level, so this saves time only when you have multiple files to analyze. When enabled it uses the default parallelization profile for your MATLAB.
• saveLog: Enable to save all messages that appear in the log box (and also in command line) to a text file. This file is always located at gui/log.txt.

Note: It is recommended to clear up this file from time to time since it keeps appending messages and currently there is no check for file size. Especially when reporting issues, please delete this file, then repeat the steps to produce the issue, and attach the log file to your issue ticket.

4. Execution

Once everything has been configured to your preferences, press the Run button. This action runs the pipeline for only the selected files under the File Selection panel. To run for all files in that panel, use Run -> All files menu.

Once the process starts, the 'Run' button text changes to Abort and can be used to prematurely stop execution (may not be available while using parallelization). Execution will stop as soon as it is able to, and a message should appear in the message window.

After processing is completed successfully, inspect the log box for error messages. If satisfied, consider saving your pipeline for future use and sharing it with others. If the results are not satisfactory, go back to Step 2 and modify your pipeline (either by re-adjusting parameters of some modules, or adding/removing modules).

Enjoy!