Ultrasession in opensesame

The recommended way to acquire ultrasound data in the Phonology Lab is via an Opensesame experiment. You can use Opensesame to display a series of prompts to a subject and use inline scripts to run and control the data acquisition utilities ultracomm and ultrasession.py. A simple experiment proceeds like this:

1. Set configuration variables related to data acquisition. These are the imaging parameters and the location to store results.
2. Initialize the ultrasound acquisition system.
3. Loop over a list of stimuli which are used to prompt the subject.
   1. Display a preparatory prompt to the subject.
   2. Start data acquisition and wait until the ultrasound system confirms that it is imaging.
   3. Display a speaking prompt to the subject during data acquisition. This prompt can be shown for a defined duration, or it can be displayed until the subject presses a key.
   4. Send a signal to stop data acquisition.
   5. Repeat the loop.

Sample experiment

A sample experiment that contains the steps listed in the previous section is available in the ultracomm repository on github. See the test experiment provided in the latest release.

The sample experiment relates to the listed steps as follows:

• The ultrasound_arguments inline script defines variables related to data acquisition, and you need to edit some variable definitions. The most important variables to change are myparams, which points to your imaging parameters file, and datadir, which is the parent directory for your timestamped acquisitions. In the Phonology Lab the data directory should be somewhere on the U: drive. Set do_log to True if you want ultracomm to produce a detailed log of its activity.

• The init_ultrasound inline script initializes the Ultrasonix system. You should not need to make any changes to this script.

• The stimuli loop object contains a list of prompts to display to the subject. The prompts are provided in the stimulus variable, and to keep things simple you should give your prompt variable the same name.

• The display_word_prep object shows the preparatory prompt to the subject. Customize this display for your own needs.

• The run_ultrasession inline script starts ultrasession.py and waits until the ultrasound system has confirmed it is imaging. You should not need to change this script unless you did not call your prompt variable stimulus.

• The display_word_while_acquiring object displays the acquisition prompt to the subject. Customize this display for your own needs. It can end after a duration of your choosing, or on a keypress.

• The stop_acquisition inline script terminates ultrasession.py. You should not need to change this script.

Troubleshooting

• Early versions of ultracomm and ultrasession.py had issues with occasional hangs when run in an Opensesame experiment. These problems are believed to have been resolved as of the Summer 2015 0.2.1-alpha release of ultracomm when used with an up-to-date ultrasession.py and following the inline scripts used in the sample experiment. Nevertheless, it is good form to check for instances of sox and ultracomm that continue to run after your experiment has concluded, as they may continue to write data to disk until they are terminated. To do this press Ctrl-Alt-Delete and open the Task Manager. Check the Processes tab for instances of rec.exe (an alias for sox.exe) and ultracomm.exe and use the End Process button to terminate these programs if they are present.

• A known issue is that the Ultrasonix system sometimes starts imaging but never sends data to the acquisition computer. This situation occurs in about 1% of acquisitions and results in empty .bpr and .bpr.idx.txt files.

• There is an issue with ultracomm occasionally terminating with an access violation error. This error occurs at program end, after acquisition has completed and data files are closed. It is believed to be the result of a bug in the Ulterius library supplied by Ultrasonix and used by ultracomm. The error occurs at program end and doesn't seem to result in bad or missed data, but it can result in a Windows error dialog box popping up, which can interfere with the flow of a series of acquisitions in an experiment. The --av-hack option is used to set the program's error reporting so that access violations do not result in popup messages:

 ultracomm --params /path/to/params.cfg --output /path/to/output.bpr --av-hack

You can use the same parameter when calling ultracomm via ultrasession.py:

 python C:\Anaconda\Scripts\ultrasession.py --params \path\to\params.cfg --datadir \path\to\output\dir --av-hack

• The Windows Error Reporting service has also been turned off on the data acquisition computer to help prevent popup error messages.

• ultracomm and ultrasession.py can generate lots of text sent to STDOUT and STDERR, especially in verbose mode. As a result it is safer to use communicate() from the Python subprocess module rather than wait() when calling ultrasession.py or ultracomm because wait() can hang the calling script if either of these buffers fills up. See Python's subprocess documentation for more information.