Brainview API¶

Brainview high-level API functions.

brainview.brain_morphometry_view(fig, vert_coords, faces, morphometry_data, **kwargs)¶

Create a surface from the mesh and morphometry data.

Create an mlab surface from the vert_coords, faces and morphometry_data. Additional keyword arguments will be passed on to the call to the mlab.triangular_mesh function.

Parameters:	fig (figure handle) – The figure the surface should be added to vert_coords (2D numpy array of shape (n_verts, 3)) – An array of vertex corrdinates. Each vertex position is identified by an x, y, and z coordinate. faces (2D numpy array of shape (n_faces, 3)) – An array of 3-faces, i.e., each face has to consists of 3 vertices. The 3 vertices are indices into the vert_coords array. morphometry_data (1D numpy array of shape (n_verts, )) – Assigns a scalar value to each vertex. kwargs (extra keyword arguments) – Will be passed on to the call to the mlab.triangular_mesh function from Mayavi.
Returns:	surface – The resulting surface. It gets added to the current scene by default and potentially triggers actions in there (like camera re-orientation), use kwargs to change that behaviour.
Return type:	mayavi.modules.surface.Surface

Examples

Load cortical thickness data for a subject and visualize it:

>>> import brainload as bl; import brainview as bv; import os
>>> subjects_dir = os.getenv('SUBJECTS_DIR')   # or whatever
>>> subject = 'subject1'
>>> vert_coords, faces, morphometry_data, morphometry_meta_data = bl.subject(subject, subjects_dir=subjects_dir, measure='thickness')      # load mesh and morphometry data
>>> fig = mlab.figure('Some title', bgcolor=(1, 1, 1), size=(800, 600))                                     # create figure and scene
>>> surface = bv.brain_morphometry_view(fig, vert_coords, faces, vertex_labels, morphometry_data)        # create an mlab mesh and add it to the scene
>>> bv.show()                                                                                               # open figure in interactive window

This will get you a view of the morphometry data on the brain mesh of the subject.

brainview.brain_label_view(fig, vert_coords, faces, verts_in_label)¶

View the vertices which are part of a label.

View the vertices which are part of a label. A label is a nothing but a set of vertices.

Parameters:	fig (figure handle) – The figure the surface should be added to vert_coords (2D numpy array of shape (n_verts, 3)) – An array of vertex corrdinates. Each vertex position is identified by an x, y, and z coordinate. faces (2D numpy array of shape (n_faces, 3)) – An array of 3-faces, i.e., each face has to consists of 3 vertices. The 3 vertices are indices into the vert_coords array. verts_in_label (ndarray, shape (m_vertices,)) – An array containing the indices of all vertices which are part of the label. All other vertices are assumed not to be part of the label.
Returns:	surface – The resulting surface. It gets added to the current scene by default and potentially triggers actions in there (like camera re-orientation), use kwargs to change that behaviour.
Return type:	mayavi.modules.surface.Surface

Examples

Load a label file using brainload and visualize it on the surface mesh of a subject:

>>> import brainload as bl; import brainview as bv; import os
>>> subjects_dir = os.getenv('SUBJECTS_DIR')   # or whatever
>>> subject = 'subject1'
>>> vert_coords, faces, morphometry_data, morphometry_meta_data = bl.subject(subject, subjects_dir=subjects_dir, load_morphometry_data=False)      # load mesh
>>> verts_in_label, label_meta_data = bl.label(subject, subjects_dir, 'Medial_wall', meta_data=morphometry_meta_data)                               # load label
>>> fig = mlab.figure('Some title', bgcolor=(1, 1, 1), size=(800, 600))             # create figure and scene
>>> surface = bv.brain_label_view(fig, vert_coords, faces, verts_in_label)          # create an mlab mesh and add it to the scene
>>> bv.show()                                                                       # open figure in interactive window

This will get you a view of the labels on the brain mesh of the subject.

brainview.brain_atlas_view(fig, vert_coords, faces, vertex_labels, label_colors, label_names)¶

View the vertices which are part of an annotation using the annotation colors.

View the vertices which are part of an annotation, usually a brain atlas. An atlas consists of several sets of vertices, each of which is assigned a color and a label. This version uses the color list.

Parameters:	fig (figure handle) – The figure the surface should be added to vert_coords (2D numpy array of shape (n_verts, 3)) – An array of vertex corrdinates. Each vertex position is identified by an x, y, and z coordinate. faces (2D numpy array of shape (n_faces, 3)) – An array of 3-faces, i.e., each face has to consists of 3 vertices. The 3 vertices are indices into the vert_coords array. vertex_labels (ndarray, shape (n_vertices,)) – An array containing the index (for each vertex) into the label_colors and label_names datastructures to retrieve the color and name. If some vertex has no annotation, -1 must be set for it.False.) label_colors (ndarray, shape (n_labels, 4)) – RGBT + label id colortable array. The first 4 values encode the label color: RGB is red, green, blue as usual, from 0 to 255 per value. T is the transparency, which is defined as 255 - alpha. If the array has more than 4 entries, all others are ignored. label_names (list of strings) – The names of the labels. The length of the list is n_labels.
Returns:	surface – The resulting surface. It gets added to the current scene by default and potentially triggers actions in there (like camera re-orientation), use kwargs to change that behaviour.
Return type:	mayavi.modules.surface.Surface

Examples

Load an annotation file using brainload and visualize it on the surface mesh of a subject. In this case, we are loading the cortical parcellation based on the Desikan atlas:

>>> import brainload as bl; import brainview as bv; import os
>>> subjects_dir = os.getenv('SUBJECTS_DIR')   # or whatever
>>> subject = 'subject1'
>>> vert_coords, faces, morphometry_data, morphometry_meta_data = bl.subject(subject, subjects_dir=subjects_dir, load_morphometry_data=False)      # load mesh
>>> vertex_labels, label_colors, label_names, atlas_meta_data = bl.annot(subject, subjects_dir, 'aparc')                 # load annotation
>>> fig = mlab.figure('Some title', bgcolor=(1, 1, 1), size=(800, 600))                                     # create figure and scene
>>> surface = bv.brain_atlas_view(fig, vert_coords, faces, vertex_labels, label_colors, label_names)     # create an mlab mesh and add it to the scene
>>> bv.show()                                                                                               # open figure in interactive window

This will get you a view of the annotation on the brain mesh of the subject.

brainview.show()¶

Display the currently active Mayavi scene in an interactive window.

Render and display the currently active mayavi scene in an interactive window. This requires a GUI and a working setup of matplotlib with proper backend configuration on the machine. Currently does nothing but to call mlab.show().

Examples

>>> ...
>>> fig = mlab.figure('Some title', bgcolor=(1, 1, 1), size=(800, 600))     # create a figure
>>> surface = bv.brain_label_view(fig, vert_coords, faces, verts_in_label)  # add something to the current scene, optional
>>> bv.show()

brainview.get_config()¶

Retrieve the brainload configuration.

Tries to load the configuration from the default config file location. If that file does not exist, uses internal defaults.

Returns:

config (SafeConfigParser) – A config parser that contains Brainview configuration information. If the file ~/.brainloadrc exists, the config gets loaded from that file. The file is expected to be in INI format. Otherwise, internal defaults settings are used. See get_default_config for available settings.
config_file_used (string or None) – The path to the config file that was loaded, or None if the internal config was used.

Examples

Print the setting width from the section figure in the settings:

>>> import brainview as bv
>>> cfg, config_file_used = bv.get_config()
>>> print cfg.getint('figure', 'width')
800

brainview.get_default_config_filename()¶

Return the path to the Brainview default config file.

Return the path to the Brainview default config file. The file must be in INI format.

Returns:	The path to the Brainview default config file. This does not imply that the file exists.
Return type:	string

Examples

>>> import brainview as bv
>>> print bv.get_default_config_filename()
/home/me/.brainloadrc

brainview.cfg_getboolean(section, option, default_value, config=None)¶

Retrieve a Boolean value from the configuration or use the default.

Retrieve a Boolean value from the configuration. If the config does not contain the value, use the default_value passed on a parameter instead.

Parameters:	section (string) – The section in the config that contains the requested option. option (string) – The requested option name. Its value in the configuration will be returned (if available). default_value (string) – The value to return if the configuration does not contain the requested data. config (configparser, optional.) – If given, the config is searched for the value. If omitted, this function will get the config itself, which may include loading it from disk. If you have already loaded the configuration, it is faster to pass it to prevent a useless reload.
Returns:	The option value. If the configuration contained the option in the requested section, the value is from the configuration. Otherwise, the parameter default_value is used.
Return type:	boolean

brainview.cfg_getint(section, option, default_value, config=None)¶

Retrieve an int value from the configuration or use the default.

Retrieve an int value from the configuration. If the config does not contain the value, use the default_value passed on a parameter instead.

Parameters:	section (string) – The section in the config that contains the requested option. option (string) – The requested option name. Its value in the configuration will be returned (if available). default_value (string) – The value to return if the configuration does not contain the requested data. config (configparser, optional.) – If given, the config is searched for the value. If omitted, this function will get the config itself, which may include loading it from disk. If you have already loaded the configuration, it is faster to pass it to prevent a useless reload.
Returns:	The option value. If the configuration contained the option in the requested section, the value is from the configuration. Otherwise, the parameter default_value is used.
Return type:	int

brainview.cfg_get(section, option, default_value, config=None)¶

Retrieve a string value from the configuration or use the default.

Retrieve a string value from the configuration. If the config does not contain the value, use the default_value passed on a parameter instead.

Parameters:	section (string) – The section in the config that contains the requested option. option (string) – The requested option name. Its value in the configuration will be returned (if available). default_value (string) – The value to return if the configuration does not contain the requested data. config (configparser, optional.) – If given, the config is searched for the value. If omitted, this function will get the config itself, which may include loading it from disk. If you have already loaded the configuration, it is faster to pass it to prevent a useless reload.
Returns:	The option value. If the configuration contained the option in the requested section, the value is from the configuration. Otherwise, the parameter default_value is used.
Return type:	string

brainview.cfg_getfloat(section, option, default_value, config=None)¶

Retrieve a float value from the configuration or use the default.

Retrieve a float value from the configuration. If the config does not contain the value, use the default_value passed on a parameter instead.

Parameters:	section (string) – The section in the config that contains the requested option. option (string) – The requested option name. Its value in the configuration will be returned (if available). default_value (string) – The value to return if the configuration does not contain the requested data. config (configparser, optional.) – If given, the config is searched for the value. If omitted, this function will get the config itself, which may include loading it from disk. If you have already loaded the configuration, it is faster to pass it to prevent a useless reload.
Returns:	The option value. If the configuration contained the option in the requested section, the value is from the configuration. Otherwise, the parameter default_value is used.
Return type:	float

brainview.export_mesh_to_file(filename, vertex_coords, faces, morphometry_data=None, colormap_name='viridis', colormap_adjust_alpha_to=-1)¶