BrainVoyager Python Developer Guide 0.9

BrainVoyager Python Developer Guide

BrainVoyager 20 introduced Python as a powerful language for both scripting and plugin development. As an interpreted language, Python allows scripting and fast prototyping in an interactive shell or console. Despite being an interpreted language, extension modules such as NumPy and SciPy turn Python into a high performance language for scientific computing. Combined with the interactive interpreter these features have made the language very popular for scientific programming and prototyping in a similar way as Matlab. "Cython" is a version of standard Python (also called "CPython") that even achieves performance close to C and C++.

This developer guide describes the support for Python provided in BrainVoyager. Python has been integrated with the goal to provide an easy and comprehensive alternative to both the current JavaScript scripting as well as C++ plugin development. The core of the new tools forms an embedded Python interpreter based on the PythonQt project. Since the Python interpreter is enriched with access to the Qt API, it is easy to add cross-platform user interfaces for scripts and plugins in Python. The interpreter also has full access to the BrainVoyager API enabling scripting and batch programming. Since version 22.0, BrainVoyager's Python commands are more pythonic (and independent from the JavaScript bindings used in earlier versions) using small capitals and underscores (e.g. 'my_function') instead of "camel case" ('MyFunction'). Since Python supports powerful modules such as NumPy and SciPy, the embedded Python language can also be used to extend BrainVoyager's computational capabilities. Plugin development is further supported by providing a "bva" module (see "import bva" statement in the screenshot above) to gain direct access to memory blocks of core BrainVoyager data as NumPy arrays.

Since BrainVoyager 22.0 the extended Python interpreter is also at the core of BrainVoyager notebooks powering its Python code cells. The integrated BrainVoyager API is particularly relevant for notebooks since it supports reproducible data analysis by documenting the sequence of performed analysis steps in BrainVoyager no matter whether they were manually coded, automatically programmed or a mix of both possibilities. The embedded Python interpreter is also used to run the TensorFlow based deep neural network brain segmentation tool introduced in BrainVoyager 22.0

Python integration is supported on recent 64-bit macOS, Windows and Linux operating systems. While BrainVoyager 20 used Python 2.7, BrainVoyager 21 and 22 use Python 3.6. Since macOS provides only Python 2.7, Python 3.6 needs to be installed on macOS. Since Windows does not come with any Python version, Python 3.6 needs to be installed in order to run Python based functionality with BrainVoyager 21 and 22. While Linux comes with Python, the version might not be matching 3.6 and installation of version 3.6 is still recommended. Because of its focus on data science, easy installation of modules and environment support, we recommend to use Miniconda for insalling Python. For details of Python installation, consult the "Installation" topic in the "General Information" chapter of the "User's Guide" or check the information at the BrainVoyager download page for the respective operating system.

Since BrainVoyager 22.0, it is recommended to perform scripting and some development directly in the BV Notebook main window that supports type completion and embedded help for BrainVoyager API properties and functions. To invoke the notebook window, the BV Notebook icon in the main toolbar can be used or the Show Notebook Window entry in the Notebooks menu. For developing custom classes or modules, BrainVoyager offers a simple Python IDE (see screenshot of Python Development window above) to load, edit, save and run Python files. To invoke the IDE (as well as the Python console), the Python icon in the main toolbar can be used or the Python Development entry in the Python menu. The provided Python editor supports basic syntax highlighting of Python commands as well as the BrainVoyager-specific API adjusted for the chosen GUI theme (dark mode or operating system default theme); the editor also provides recommended Python behavior, i.e. a "Tab" key press inserts always 4 spaces (instead of a tab character) and pressing "Return" on a text line will automatically insert indent spaces at the next line. The IDE currently lacks support for debugging, which is planned for a future release. While created Python files can be stored at any location, the default folder for Python scripts is located in the "~/Documents/BrainVoyager/Extensions/PythonScripts" folder and the default folder for Python plugins is located in the "~/Documents/BrainVoyager/Extensions/PythonPlugins" folder. Example files will be stored in these folders after installing BrainVoyager and newly stored files will not be removed when uninstalling BrainVoyager prior to installing a newer version. Since both scripts and plugins are coded in the same language, the distinction between scripts and plugins is not really important - a script usually calls existing BrainVoyager routines, for example to implement batch processing of multi-subject data, while a plugin usually implements a new routine using any imported Python module extending the functionality of BrainVoyager. For fast access to loaded BrainVoyager documents (e.g. anatomical VMR datasets, meshes), the "BrainVoyager Array Access" module ("bva") can be used.