BrainVoyager v22.4

Installing and Enabling Python

Since BrainVoyager 22 Python plays an important function: Besides being the primary interpreted language (next to JavaScript) to enable users to writie analysis scripts as well as to program new functionality, Python is also necessary for executing the code cells in BrainVoyager notebooks. Furthermore, Python is used in the background to run the high-resolution deep neural network (DNN) based cortex segmentation tool. The trained 'Tiramisu' DNN has been implemented using Google's TensorFlow machine learning platform, whiich is also accessed using its Python interface.

BrainVoyager is based on a standard (CPython) Python runtime environment as it is available directly from Python's home page Python.org or from distributions that focus on data science such as Anaconda. To enhance flexibility, Python support is now enabled via an isolated plugin, which is only launched when needed the first time. With this approach BrainVoyager lets you chose any (compatible) Python environment on your disk after starting BrainVoyager. The selected Python version and its location on disk is then stored permanently in BV's global settings but you can switch to another Python on disk at any moment in time (but before Python is used the first time in a session since switching to a new Python is blocked until the program is restarted). Since version 22.2, BrainVoyager supports multiple Python versions (only Python 3.6 was supported in earlier releases). The latest version, BrainVoyager 22.4, supports Python 3.8 and 3.10. While downloading Python from Python.org is one possible way to get a supported Python version, it is recommended to use the data science oriented distribution 'Anaconda' (actually Miniconda, see below) since it provides powerful means to setup environments for multiple Python versions in an elegant way. Using environments allows, for example, to use specific sets of modules potentially with different Python versions next to each other. This makes it possible to install a Python environment for BrainVoyager without affecting any other (system) Python installation that may require different (versions of) Python modules. Of course one can add to the BrainVoyager environment all other (neuroimaging) modules that one wants to use in addition to BrainVoyager's Python programming interface.

While one could go with Anaconda coming with hundreds of modules, we recommend Miniconda since it starts with a minimal Python implementation to which one can just add the needed packages for a specific purpose. Miniconda plays also nice with already installed Python versions: You do not need to uninstall other Python installations or packages in order to use conda, which is the package and environment manager of Miniconda. Even if you already have a system Python or another Python installation (e.g. from Python.org), you do not need to uninstall, remove, or change any of them before using conda. Another advantage to use a miniconda environment is that you can provide a specific name (see below) that is auto-detected by BrainVoyager.

Python Installation Using Miniconda

Here are the recommended steps to setup Python using Miniconda:

1. Install Miniconda

If not yet installed, download the latest 3.x (not 2.7) version from the Miniconda page. Make sure that you download the 64-bit version for your operating system:

2. Create a Python Environment for BV

Note that the installed Python version may be newer (likely 3.9 or higher) than the versions (3.6, 3.8) currently supported by BrainVoyager. This is no problem since miniconda allows us to create environments using different versions of Python than in the base environment. Now open a Terminal window (macOS, Linux) or open the 'Anaconda Prompt (Miniconda3)' Prompt from the Windows Start menu and type the following from the active base environment:

1: > conda update conda

This command is executed just to ensure that the package manager 'conda' is up-to-data. Now we create an environment containing Python 3.8 (and/or 3.6) as well as basic data science libraries required by BrainVoyager:

2: > conda create -n env_bv_py38 python=3.8 numpy scipy matplotlib

Note that the name of the created environment is env_bv_py38 (a Python 3.8 environment for use with BrainVoyager) that will be automatically detected when enabling Python in BrainVoyager (see below). At this point the installed Python 3.8 environment can be already used from BrainVoyager. To also prepare Python to run the DNN Segmentation tool, one needs to also install TensorFlow.

3. Add TensorFlow to Enable DNN Segmentator

Note that the conda command above to create a Python 3.8 environment did not request specific package versions for numpy, scipy and matplotlib as in earlier descriptions. The reason is that this avoids the risk of package conflicts and for BrainVoyager the latest available versions of these packages should work fine. For TensorFlow only, specific versions were requested in previous versions of this document:

( > conda create -n env_bv_py38 python=3.8 numpy=1.20 scipy=1.4 matplotlib=3.3 )

This way to create the environment is, however, no longer recommended because the specific package versions might no longer be available (without conflicts) in the conda repositories. Furthermore, recent versions of TensorFlow (2.2 or higher) resolve potential conflicts automatically.

To install TensorFlow (TF) into our created Python environment, we first need to activate it:

3: > conda activate env_bv_py38

With the activated environment, commands like 'python' or 'pip' will use the correct (3.8) version. We will use the standard Python package installerpipto install TensorFlow (the first line just ensures that 'pip' is up-to-date):

4: > python -m pip install --upgrade pip

5: > python -m pip install tensorflow

You may also specify a specific version of Tensorflow, e.g. to install the (tested) version 2.2, you would write tensorflow==2.2. The last package to add in the environment is nibabel, which is used to read and write NIfTI files from Python:

6: > python -m pip install nibabel

While this completes the necessary steps for BrainVoyager, you can move on to test whether everything works as expected, i.e. whether the created environment uses Python 3.8. To launch Python from the activated 'envbvpy38' environment, type 'python' (plus 'Return' key) in the Terminal. You should get a message that you are running a Python 3.8.x version and then a standard Python prompt '>>>' ready to receive your Python commands. To exit the Python interpreter type 'exit()' followed by 'Return'. Note that you can leave the 'env-bv_py38' environment by entering 'conda deactivate' which will bring you back to the base environment. While you can use the created environment from a Terminal, this is not required for BrainVoyager, which accesses it without the need of issuing activation commands.

Note that with older versions of TensorFlow, GPU support was not automatically installed. When using newer versions (e.g. 2.10), GPU support is automatically installed if the appropriate GPU drivers are installed on the system. For details consult the official TensorFlow documentation. A useful blog post to install TensorFlow 2.6 with GPU support on Windows can be found here.

Python 3.6

The installed TensorFlow version (2.2) requires Python 3.8 or higher. For Python 3.6, TF 2.0 should be installed. As noted ebove, a Tensorflow version has requirements for specific versions of the previously installed standard data science packages (mainly numpy and scipy) as well as for the h5py package. TensorFlow 2.2 (and newer) now automatically 'downgrades' some packages during installation to make them compatible to the requested Tensorflow version. In BV 22.0, the installation of Tensorflow 2.0 was described (in a Python 3.6 environment), which did not adjust the version of the 'h5py' package to a compatible version (as TF 2.2 does) and the following command was necessary in case that a more recent version(e.g. 3.1) was installed:

( > python -m pip install h5py==2.10.0 )

In case you get Python errors when running the DNN segmentation routine, check the version of the modules scipy and h5py. If problems persist, please contact Brain Innovation for support.

Selecting a Python Version in BrainVoyager

After starting BrainVoyager, click the Select Python item in the Python menu.

SelectPython

This will open the Select Python On Disk dialog:

SelectPyDlg

The section Auto-detected Python locations lists all Python versions that are compatible with the current BrainVoyager version (e.g. Python 3.8 and 3.10 for BrainVoyager 22.4) and that are found on disk using a heuristic search in standard locations, including Miniconda environments, the Python.org Python and the version installed by the operating system on Linux. After a standard setup as described above, you should find here the env_bv_py38 Miniconda environment created above as well as other environments you might have created. In the example snapshot of the dialog above, three Python 3.6 installations were detected (two in Miniconda environments and a Python.org installation), as well as the Python 3.8 version in the environment created above (env_bv_py38).

The Python version currently selected (if any) is shown in the Location of selected Python field with the the version in the Version field and the folder on disk in the Folder field. To select another Python environment / installation, simply select one in the list of auto-detected Python versions and then click the Select From List button. The newly selected Python version will then replace the previously selected Pythin in the Version and Folder text fields in the Location of selected Python section. To accept the newly selected version, click the dialog's OK button.

In case the Miniconda Python 3.8 env_bv_py38 environment has been created as described above, BrainVoyager 22.4 will select this version as default on first launch. If you have a Python 3.8 / 3.10 on disk that was not detected automatically, you can also use the Select On Disk button to specify any other compatible version by selecting its main folder on disk. Before clicking on Select On Disk, the version you want to specify on disk needs to be selected in the Python version selection box (default selection is Python 3.8). Note that the program ensures that you select a valid Python installation / environment by restricting the file selection to the core Python library in the respective Python folder. After selecting the desired version in the appearing Open File dialog, the version and folder of the selected Python in the respective entries of the Location of selected Python section.

When clicking the OK button of the Select Python on Disk dialog. the chosen Python versiony will be permanently kept so you only need to go back to this dialog in case you want to switch to another Python version. When running a Python script or when executing a code cell in a BrainVoyager notebook, the selected Python version will automatically be launched on first use and will then be available throughout a BrainVoyager session. You can also test whether the selected Python version can be initialized successfully by clicking the Initialize Python item in the Python menu.

Recommended test. To test whether BrainVoyager uses the specified Python, you can open and run the 'Test Python' notebook that is available in the Notebooks menu (the notebook can also be opened from its location, which is in 'Documents/BrainVoyager/Notebooks' folder after BrainVoyager installation).

Note. Make sure that the Pyton version you select contains the minimal set of modules as described above. If, for example, the 'numpy' and 'matplotlib' librarires are not installed, the Python cells in BrainVoyager notebooks will print an error message since these libraries are assumed to be present for provided default functionality (e.g. embedding of matplotlib images). When using the DNN Segmentator, TensorFlow must be properly installed, otherwise an error message will be printed in the Python Console panel.

Note. After a Python version has been selected and initialized (and used), you can no longer switch to another Python version in the current BrainVoyager session. If you clcik on the Select Pyton item in the Python menu, the program will show a message that Python is already in use and can not be changed. If you want to use another Python version, you must first close BrainVoyager and relaunch it. You can then open again the Select Python On Disk dialog as long as Python has not been used in a script or notebook.


Copyright © 2022 Rainer Goebel. All rights reserved.