ScanImage 2019 : Set Up of ScanImage-Wavesurfer Intercommunication

Created by Lawrence Niu on May 07, 2019

Terminology

  • In Wavesurfer, a "trial" is a single acquire for a (usually) fixed duration.

  • In Wavesurfer, an "experiment" is a series of trials, acquired one after the other (possibly with gaps between).

Step-by-step guide

By following these steps, WaveSurfer will be allowed to send commands to ScanImage to coordinate trial and experiment acquisition with ScanImage.

  1. Start MATLAB and run ScanImage.
  2. Load a .usr and .cfg file in ScanImage or save the current settings to a .usr and .cfg (This sets up a usr/cfg file path for SI, which is currently required for ScanImage-WaveSurfer communication).
  3. If the .usr/.cfg files haven't set up ScanImage for external triggering for interacting with WaveSurfer, follow these steps:
    1. Go to the "Settings" menu on ScanImage.
    2. Select the "Triggers" menu entry.
    3. Choose the desired Terminal and Edge type for "Acquisition Start". If WaveSurfer is using internal triggering only, connect ScanImage to WaveSurfer's internal trial-trigger terminal, for most cases this should be "PFI12" on the corresponding board
    4. On the "Main Controls" window, select the "EXT" button to turn on external triggering.
  4. Start a new instance of MATLAB and run WaveSurfer. At the moment, Wavesurfer should be installed in a different directory.
  5. Go to the "Settings" menu on ScanImage and click on the entry "Yoke to Wavesurfer". A check mark should become visible next to the menu entry.
  6. Go to the "Settings" menu on WaveSurfer and click on the entry "Yoke to ScanImage". A check mark should become visible next to the menu entry.

You should now be in "Yoked" mode. In this mode you have the following coordinated options:

  • Clicking "Play" or "Record" on Wavesurfer will also start acquisition in SI if SI is in an idle state.  This will cause SI and Wavesurfer to start their trials at the exact same time, due to external triggering on ScanImage's side.  Additional clicks of "Play" or "Record" in Wavesurfer will again start acquisition in SI if SI is in an idle state, with no need for the user to do anything in SI.  Trials started in this way will have the same trial index in SI and Wavesurfer.
  • Wavesurfer opening/saving a Protocol (.cfg) / User (.usr) file causes the opening/saving of a "parallel" .cfg/.usr file in ScanImage.  A "parallel" .cfg/.usr file is a .cfg/.usr file with the same name as the Wavesurfer file, but in a different directory. At the moment, yoking requires the user have one directory with wavesurfer .cfg/.usr files, e.g., "C:/prep/wavesurfer", and another parallel one with ScanImage .cfg/.usr files, e.g., C:/prep/scanimage.

To turn off "yoked"-mode, simply click on the aforementioned entries "Yoke to Wavesurfer" and "Yoke to ScanImage" in ScanImage and WaveSurfer, respectively. The check mark next to the menu entries should no longer be visible.

IMPORTANT

Icon

It is currently required for the user to set up appropriate Wavesurfer trial durations in order to prevent WaveSurfer from sending a new-trial trigger to ScanImage before ScanImage's current Acquisition is done.

Debugging Mode

Icon

Correct operation of ScanImage-Wavesurfer intercommunication assumes that an external trigger has been set. If external triggering has not been enabled, then ScanImage will use a software trigger to start acquisition. This mode exists solely for debugging purposes and should not be used for data acquisition

Different computers

Icon

ScanImage-Wavesurfer intercommunication assumes that both applications are being run on the same computer. However, if ScanImage and Wavesurfer are on different computers but share a network folder, it is possible for them to interact if one simply overrides Matlab's tempdir function on each computer with the following:

function res = tempdir()

  res = "INSERT_NETWORK_FOLDER_NAME";

end