Scripting and COM Automation

Scripting and COM

Analyzing fMRI data using a powerful Graphical User Interface (GUI) allows to easily specify different analysis steps such as motion correction, slice timing correction, spatial and temporal filtering, normalization and statistical routines. For a specific experiment, one usually wants to preprocess and analyze the functional data of all subjects in the same way. For preprocessing, for example, this means that each functional run is processed using the same order of routines with the same parameter settings. In this situation, scripting and automation may come as a great saver of repetitive manual work: A simple loop across subjects’ functional data can be implemented requesting the same analysis steps for each run. In order to let users request processing steps by scripts, BrainVoyager QX exposes an interface providing access to major analysis steps. The scripting environment provided by BV QX (see snapshot below) helps in writing scripts quickly and efficiently.

Scripting and COM - 2

The scripting environment is useful for writing and launching cross-platform scripts directly from within BV QX. It might be, however, desirable to launch BV QX and to run scripts from outside the program. Such a scenario would, for example, allow to have a “master script” starting several computers each working on part of the data. For a large group study, each computer could analyze the data of a subset of subjects. BrainVoyager QX 1.9 will allow this scenario on Windows by running as a “COM server” (see below). For Linux and Mac OS X, platform-specific approaches with similar capabilities are scheduled to be integrated in a later release.

The provided COM (Component Object Model) interface allows to access the functionality of BrainVoyager QX from any “COM-aware” program or scripting engine. You may use a number of scripting languages such as Visual Basic Script (VBS), JavaScript and Perl to remotely control BrainVoyager QX. VBS scripts will run directly on Windows without the need to install additional software (for more details, see here). The figure below shows a VBS script running outside of BrainVoyager QX. The most essential command of the script is the one in the first line, “CreateObject”, which, when executed, launches BrainVoyagerQX.

Scripting and COM - 3

All subsequent commands are identical to the commands used in scripts within BrainVoyager QX. In fact, I expose the same set of commands to the internal scripting engine (based on Qt Script for Applications) as for the COM commands.

Since Matlab is also COM-aware, you may also use this high-level programming language to remotely control BrainVoyager QX. This might be particularly useful for power users who want to mix custom analysis routines with the processing and display capabilities of BV QX. The snapshot on top of this blog entry shows the Command window of Matlab with a line of code launching BrainVoyager QX. The “actxserver” command is the way how Matlab uses COM to access other COM-aware servers. In the VBS script shown in the snapshot above, the corresponding command is “CreateObject”. Both commands need the name of the COM server as input, which is “BrainVoyagerQX.BrainVoyagerQXInterface” in the case of BV QX. After having access to BV QX (in form of the “BrainVoyagerQX” handle), all commands provided at the general application level can be called including commands to open existing documents or to create new documents from raw data. As soon as a document has been opened or created, additional document-level commands are available as partially shown in the Matlab snapshot below. The list of available commands is obtained by pressing the “Tab” key after entering the document handle, here “DocVMR”, and the dot.

Scripting and COM - 4

Since the commands are the same for internal and external scripting, you can use the scripting documentation created by Hester Breman (email: breman at brainvoyager dot com) to learn about all available scripting commands. Hester also created a nice Scripting Getting Started Guide, which will be available on our web site and also distributed with the BrainVoyager QX 1.9 release. On behalf of Brain Innovation, Jens Schwarzbach has also created a nice guide for Matlab-based BV scripting. While this guide has been originally written for the outdated BrainVoyager 2000 software, an updated QX version should be available in the near future.