Ultrasession.py

ultrasession.py is a Python script that acquires ultrasound data via the ultracomm utility while simultaneously acquiring an audio signal and the ultrasound synchronization signal. In addition it creates timestamped acquisition directories and logs various acquisition parameters so that they are available for postprocessing.

The favored method of calling ultrasession.py in the Phonology Lab is by including it in an Opensesame experiment.

Usage

ultrasession.py requires a parameter file that it passes to ultracomm. It also requires you to specify an output data directory:

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

Since ultracomm is a Windows-only utility ultrasession.py must run under Windows. The path to ultrasession.py shown here is its standard location on the Phonology Lab's ultrasound acquisition workstation.

For a full listing of options, use:

 python C:\Anaconda\Scripts\ultrasession.py --help

Output files

Each time ultrasession.py runs it creates a timestamped subdirectory in the directory identified by --datadir. This subdirectory contains:

1. a *.bpr file that contains the ultrasound image data. (The * indicates a timestamp.)

1. a *.bpr.idx.txt file that contains a list of frame indexes corresponding to the frames of data in the .bpr file. This list of indexes is important for detecting dropped frames in the .bpr data. At high acquisition rates some images will be missed.

1. a two-channel *.bpr.wav file containing audio data captured from a microphone in the first channel and the ultrasound synchronization signal in the second channel.

1. a copy of the imaging parameter file specified by --params

1. if the --stim or --stims option is used, a file named stim.txt that contains the stimulus item used for the acquisition.

1. if the --log-versions option is used, a file named versions.txt that contains information related to the version of ultracomm used in the acquisition.

The first two items are created by ultracomm directly, and the remaining files are added by ultrasession.py. The last two optional files are created if you use ultrasession.py in an Opensesame experiment in the recommended way.