BrainVoyager v23.0

BV Notebooks

BrainVoyager notebooks - or BV notebooks for short - support reproducible data analyses. Inspired by Jupyter notebooks, BV notebooks provide rich interactive documents containing code, explanatory text, images, animations and BrainVoyager viewers in a sequence of cells. A main unique feature of BV notebooks is that they not only offer (script) programmers a means to write and document code but they also support non-programmers by converting essential GUI actions automatically into corresponding code. If, for example, the GO button in the FMR Preprocessing dialog is clicked, all selected preprocessing operations are converted into Python code, which is added to the current notebook (if enabled). The auto-generated Python code contains BrainVoyager API (scripting) commands and, thus, serves as documentation of analysis steps that were executed in the user interface; furthermore, the auto-generated Python code can be rerun at a later time to reproduce derived data. The (auto-)written code can be easily enriched with annotated graphics, animations, Markdown text as well as embedded BrainVoyager viewers. The screenshot below shows a snapshot of a section of the 'Introduction.bvnb' notebook illustrating how these rich documents appear inside the BV Notebook main window in BrainVoyager (or in the standalone BV Notebook application, see below). The snapshot illustrates that a notebook is composed of cells containing code, rich text, images, animations (not shown) and interactive BV viewers.

BV viewer cells allow to interactively view brain volumes ('VMR viewer') and meshes ('Mesh viewer') with overlaid maps right inside a notebook. Images can be either generated as output from standard Python code (e.g. using the matplotlib module) or added from BrainVoyager's windows, dialogs and plots creating separate image cells. Images are added automatically if a notebook is set in Log GUI Actions mode (see icon on the right side of the toolbar in the snapshot above) but they can also be added manually by making screenshots of the current document window, opened dialogs or the entire BrainVoyager window using simple keyboard shortcuts. Images and animations embedded in a notebook can be further annotated with text, rectangles, circels and arrows.

In the Notebook settings section of the GUI tab of BrainVoyager's Preferences (or Settings on macOS) dialog, choices can be made about the BV Notebook window (see screenshot above). If the Open at program start option is turned on, the BV Notebook window will appear automatically after starting BrainVoyager; this might be useful if one works with a notebook over multiple interactive BrainVoyager sessions; if one is (temporarily) not using notebooks, this setting can be turned off. The Stays on top option keeps the notebook window on top of other BV windows, which is useful when one primarily uses the notebook to interact with BrainVoyager. If screen space allows, it might be also useful to arrange the notebook window and the main BrainVoyager window side by side (both windows store their position on screen in global settings). The Send snapshot widgets has an effect when auto-writing code from BrainVoyager's user interface: when sending code to the notebook, this option determines whether not only code but also (VMR and mesh) viewers should be embedded in the notebook. Note that sending code to the currently open notebook requires that the Log BV GUI Actions As Code option in the notebook is enabled.

Application Scenarios

Automatic code-generation, manual programming, rich text, graphics and interactive viewers offer a wide range of applications for BV notebooks. While there are no clear boundaries, the following list highlights major application scenarios:

• Documentation of reproducible analysis steps . The main usage scenario of BV notebooks is as a transparent documentation of performed data analysis steps either by self-written code or by auto-generated code. Code sections (cells) are (auto-)written in Python, which has been extended to use major BrrainVoyager functionality with a few lines of code. Individual code cells or the wohle code can be executed to reproduce derived data.
• Advanced data analysis pipelines . Python programmers can modify and add code to create custom analysis pipelines that may use BrainVoyager commands as well as functions from additional (neuroimaging) data analysis Python modules. Larger custom Python classes and functions are best saved in external files and imported in notebooks as modules.
• Rich documents . Since text is written with Markdown formatting, rendered text together with images can be used to produce rich sharable documents even without code. TheIntroduction.bvnbdocument shown in the snapshot above is an example of a notebook that mainly uses Markdown text to explain how to create and use BV notebooks.
• Interactive tutorials . BV notebooks may also contain BrainVoyager viewers that work in the same way as in the main user interface but are embedded directly in the notebook. Together with Markdown text, code and images, this can be used as a powerful tool to produce and consume interactive tutorials, for example, to teach MRI data analysis topics.

To document performed data analysis steps, one would typically create one notebook for a (multi-subject) project. The default directory where BV expects top-level project folders is Documents/BrainVoyager/Projects. The code in a notebook usually contains calls of BrainVoyager routines but can also incorporate calls to any (neuroimaging) Python library. In case that the project's folder structure (for original NIfTI and BV derived data) follows the BIDS standard, powerful workflows can be easily defined in code or by using BV's data analysis manager. Having completed the (preprocessing) code to run for all subjects, sessions and runs, one can easily rerun the notebook when data from additional subjects become available. Note that a project-related notebook with explanatory text and eventually images may serve as the basis for the methods section of a manuscript or as supplementary material.

BV Notebook Application

While BV Notebooks can be operated in a similar way as Jupyter notebooks, there are also differences that will be described in the following topics. Note also that the BV Notebook application is not running in a web browser like Jupyter notebooks but runs as a cross-platform native application either embedded in BrainVoyager or as a standalone software. Both versions provide extensions to a standard (currently 3.6) Python interpreter to execute code cells containing BrainVoyager commands and tools to build custom dialogs. The standalone BV Notebook application is ideal for sharing created documents with (non-)BV users but it is not able to run BrainVoyager functionality. For BV 22.2, it is planned to integrate more BV functionality also in the standalone BV Notebook application.

BV Notebook Documents

Notebook documents contain the inputs and outputs of an interactive Python code session as well as narrative Markdown text that accompanies the code. Rich output generated by running Python code, including images and BV viewers, is embeddeed in the notebook, which makes it a self-contained document. BV notebook documents are files on your local filesystem with a .bvnb extension. The notebooks bundled with BrainVoyager are stored in the [user]/Documents/BrainVoyager/Notebooks folder.

BrainVoyager notebooks consist of a sequence of cells supporting

• executable code inPython code cells
• formatted text inMarkdown cells
• images inImage cells, and
• interactive widgets inBV viewer cells.

Copyright © 2023 Rainer Goebel. All rights reserved.