First steps user guide: BV file formats in nibabel

Installation

Important note: As of now (August 2016) the pull request is not yet merged in to the main repository of nibabel. Therefore, we need to install from a nibabel fork of Thomas Emmerling. As soon as a new version of nibabel is released that includes the new features, this manual installation procedure is not needed anymore and nibabel can be installed through the usual package repositories (pip, etc.; see also http://nipy.org/nibabel/installation.html).

Prerequisites

• git
• Python environment (preferably Anaconda)

1. From the command line, clone the repository (change the directory accordingly):

   git clone https://github.com/thomastweets/nibabel.git ~/git/nibabel
   

2. Install the local clone with pip as a development package:

   pip install -e ~/git/nibabel
   

Basic usage

You can easily explore the functionality of nibabel from the (iPython) REPL. Please see also the nibabel documentation. As a general principle all header information is stored in an ordered dictionary that can be altered in an image (header) object (see below for an example). Some sanity checks are performed on load and save, however, the user needs to know about valid values for header fields in order to keep compatibility with BrainVoyager.

Whenever possible, an affine transformation to real-world space (RAS+; i.e. rightward-anterior-superior orientation with axes running from negative to positive in these directions; see also this) is computed and available as the affine property of objects. In some file formats this is only possible as an estimation (e.g. VTC files) but maintains compatibility with other file formats available in nibabel.

To save memory resources nibabel is capable of on-the-fly disk access via the dataobj property. See here and below for an example.

This implementation as of now (August 2016) only supports VTC, VMP, MSK, and VMR files in their respective current versions.

Examples

• Reading a VMR file:

>>> import nibabel as nb
>>> vmr = nb.load('~/git/nibabel/nibabel/tests/data/test.vmr')
>>> print vmr
<class 'nibabel.brainvoyager.bv_vmr.BvVmrImage'>
data shape (5, 4, 3)
affine:
[[-1.  0.  0.  0.]
 [ 0.  0. -1. -1.]
 [ 0. -1.  0.  1.]
 [ 0.  0.  0.  1.]]
metadata:
<nibabel.brainvoyager.bv_vmr.BvVmrHeader object at 0x10a6a5ed0>

• Changing the header of a VMP file and saving the file:

>>> import nibabel as nb
>>> vmp = nb.load('~/git/nibabel/nibabel/tests/data/test.vmp')
>>> print vmp.header._hdr_dict['vtc_filename']
'test.vtc'
>>> vmp.header._hdr_dict['vtc_filename'] = 'test2.vtc'
>>> print vmp.header._hdr_dict['vtc_filename']
'test2.vtc'
>>> vmp.to_filename('~/test.vmp')
>>> # or alternatively
>>> nb.save(vmp, '~/test.vmp')

• Accessing data from a VTC file:

>>> import nibabel as nb
>>> vtc = nb.load('~/git/nibabel/nibabel/tests/data/test.vtc')
>>> vtc_data = vtc.get_data()
>>> print vtc_data
[[[[  1.81556824e+02   1.56530869e+02   9.43887100e+01   1.59228455e+02
      1.75129471e+02]
   [  1.34450317e+02   1.40765467e+01   2.48943806e+01   8.50732346e+01
      1.56533157e+02]
   [  1.17829308e+02   9.44271851e+01   6.75769424e+00   3.60147057e+01
      1.86363937e+02]
   ...,

>>> # nibabel is also capable of on-the-fly data access (not loading the whole file at once):
>>> print vtc.dataobj[0,0,0,:]
[ 181.55682373  156.53086853   94.38871002  159.22845459  175.12947083]

• Creating a new MSK file:

>>> import nibabel as nb
>>> import numpy as np
>>> msk_data = np.zeros((10,10,10))
>>> # we need to convert the numpy array to the correct datatype for MSK files
>>> msk = nb.brainvoyager.BvMskImage(msk_data.astype(np.dtype('uint8')), None)
>>> print msk.shape
(10, 10, 10)
>>> # the header was filled with standard values that fit the shape of the data
>>> print msk.header._hdr_dict
OrderedDict([('resolution', 3),
             ('x_start', 57),
             ('x_end', 87),
             ('y_start', 52),
             ('y_end', 82),
             ('z_start', 59),
             ('z_end', 89)])
>>> msk.to_filename('~/test.msk')