1.3.1. Main Brain class inputs

class visbrain.Brain(bgcolor='black', verbose=None, **kwargs)[source][source]

Visualization of brain-data on a standard MNI brain.

By default the Brain module display a standard MNI brain. Then, this brain can interact with several objects :

  • Brain (brain_obj)
  • Sources (source_obj)
  • Connectivity (connect_obj)
  • Time-series (time_series_obj)
  • Pictures (picture_obj)
  • Vectors (vector_obj)
  • Volume (vol_obj)
  • Cross-sections (cross_sec_obj)
  • Region Of Interest (roi_obj)

Alternatively, if an other brain template is needed, a brain object (BrainObj) can also be used (see brain_obj).

Parameters:

brain_obj : BrainObj | None

A brain object.

vol_obj : VolumeObj | None

A volume object.

cross_sec_obj : CrossSecObj | None

A cross-sections object.

roi_obj : RoiObj | None

A Region Of Interest (ROI) object.

source_obj : SourceObj | None

An object (or list of objects) of type source (SourceObj).

connect_obj : ConnectObj | None

An object (or list of objects) of type connectivity (ConnectObj).

time_series_obj : TimeSeries3DObj | None

An object (or list of objects) of type time-series (TimeSeries3DObj).

picture_obj : Picture3DObj | None

An object (or list of objects) of type pictures (Picture3DObj).

vector_obj : VectorObj | None

An object (or list of objects) of type vector (VectorObj).

project_radius : float | 10.

The projection radius to use.

project_type : {‘activity’, ‘repartition’}

Define the projection type. Use ‘activity’ to project the source’s activity or ‘repartition’ to get the number of contributing sources per vertex.

project_contribute : bool | False

Specify if source’s can contribute to both hemisphere during projection (True) or if it can only be projected on the hemisphere the source belong.

project_mask_color : string/tuple/array_like | ‘orange’

The color to assign to vertex for masked sources.

project_cmap : string | ‘viridis’

The colormap to use for the source projection.

project_clim : tuple | (0., 1.)

Colorbar limits of the projection.

project_vmin : float | None

Minimum threshold for the projection colorbar.

project_under : string/tuple/array_like | ‘gray’

Color to use for values under project_vmin.

project_vmax : float | None

Maximum threshold for the projection colorbar.

project_over : string/tuple/array_like | ‘red’

Color to use for values over project_vmax.

bgcolor : string/tuple | ‘black’

Background color of the GUI.

Methods

show() Display the graphical user interface.
rotate([fixed, custom]) Rotate the scene elements using a predefined or a custom rotation.
background_color([color]) Set the background color of the main canvas and the colorbar.
screenshot(saveas[, canvas, print_size, …]) Take a screeshot of the selected canvas.
load_config(config) Load a configuration file.
save_config(config) Save a configuration file.
brain_control([template, hemisphere, …]) Control the type of brain to use.
brain_list() Get the list of available mesh brain templates.
add_mesh(name, vertices, faces, **kwargs) Add a mesh to the scene.
sources_control(name[, data, color, symbol, …]) Set data to sources and control source’s properties.
sources_display([name, select]) Select sources to display.
sources_fit_to_vertices([name, fit_to]) Force sources coordinates to fit to a selected object.
sources_to_convex_hull(xyz) Convert a set of sources into a convex hull.
cortical_projection([radius, project_on, …]) Project sources activity.
cortical_repartition([radius, project_on, …]) Project the number of contributing sources per vertex.
time_series_control(name[, color, …]) Control time-series settings.
pictures_control(name[, width, height, …]) Control pictures settings.
connect_control(name[, color_by, dynamic, …]) Update connectivity object.
cbar_control(name, **kwargs) Control the colorbar of a specific object.
cbar_select(name[, visible]) Select and display a colorbar.
cbar_list() Get the list of objects for which the colorbar can be controlled.
cbar_export([filename, export_only, get_dict]) Export colorbars in a text file or in a dictionary.
cbar_autoscale(name) Autoscale the colorbar to the best limits.

1.3.2. GUI functions and settings

Set of functions for an interactive control of the graphical user interface elements.

1.3.2.1. Show graphical interface

Brain.show()[source]

Display the graphical user interface.

1.3.2.2. Rotation

Brain.rotate(fixed='top', custom=None)[source]

Rotate the scene elements using a predefined or a custom rotation.

The rotation is applied on every objects on the scene.

Parameters:

fixed : str | ‘top’

Use a fixed rotation :

  • Top view : ‘top’ or ‘axial_0’
  • Bottom view : ‘bottom’ or ‘axial_1’
  • Left : ‘left’ or ‘sagittal_0’
  • Right : ‘right’ or ‘sagittal_1’
  • Front : ‘front’ or ‘coronal_0’
  • Back : ‘back’ or ‘coronal_1’

custom : tuple | None

Custom rotation. This parameter must be a tuple of two floats respectively describing the (azimuth, elevation).

Examples

>>> # Define a Brain instance :
>>> vb = Brain()
>>> # Predefined rotation :
>>> vb.rotate(fixed='sagittal_1')
>>> # Custom rotation :
>>> vb.rotate(custom=(90.0, 0.0))
>>> # Show the GUI :
>>> vb.show()

1.3.2.3. Background color

Brain.background_color(color=(0.1, 0.1, 0.1))[source]

Set the background color of the main canvas and the colorbar.

The main canvas is defined as the canvas where all objects are displayed. The colorbar has it own canvas and the background set will be the same as the one of the main canvas.

Parameters:

color : tuple/string | (.1, .1, .1)

The color to use for the background color of the main canvas. The color can either be a tuple of integers (R, G, B), a matplotlib color (string) or a hexadecimal color (string).

Examples

>>> # Define a Brain instance :
>>> vb = Brain()
>>> # Set the background color (using a RGB tuple) :
>>> vb.background_color(color=(1., 1., 1.))
>>> # Set the background color (using matplotlib format) :
>>> vb.background_color(color='white')
>>> # Set the background color (using hexadecimal format) :
>>> vb.background_color(color='#ffffff')
>>> # Show the GUI :
>>> vb.show()

1.3.2.4. Screenshot

Brain.screenshot(saveas, canvas='main', print_size=None, dpi=300.0, unit='centimeter', factor=None, region=None, autocrop=False, bgcolor=None, transparent=False)[source]

Take a screeshot of the selected canvas.

By default, the rendered canvas will have the size of your screen. The screenshot() method provides two ways to increase to exported image resolution :

  • Using print_size, unit and dpi inputs : specify the size of the image at a specific dpi level. For example, you might want to have an (10cm, 15cm) image at 300 dpi.
  • Using the factor input : multiply the default image size by this factor. For example, if you have a (1920, 1080) monitor and if factor is 2, the exported image should have a shape of (3840, 2160) pixels.
Parameters:

saveas : str

The name of the file to be saved. This file must contains a extension like .png, .tiff, .jpg…

canvas : {‘main’, ‘colorbar’, ‘cross-sections’}

The name of the canvas to render. Use ‘main’ to select the main canvas where the brain is displayed. Use ‘colorbar’ to render the colorbar or ‘cross-sections’ to render the cross-sections panel (in splitted view).

print_size : tuple | None

The desired print size. This argument should be used in association with the dpi and unit inputs. print_size describe should be a tuple of two floats describing (width, height) of the exported image for a specific dpi level. The final image might not have the exact desired size but will try instead to find a compromize regarding to the proportion of width/height of the original image.

dpi : float | 300.

Dots per inch for printing the image.

unit : {‘centimeter’, ‘millimeter’, ‘pixel’, ‘inch’}

Unit of the printed size.

factor : float | None

If you don’t want to use the print_size input, factor simply multiply the resolution of your screen.

region : tuple | None

Select a specific region. Must be a tuple of four integers each one describing (x_start, y_start, width, height).

autocrop : bool | False

Automaticaly crop the figure in order to have the smallest space between the brain and the border of the picture.

bgcolor : array_like/string | None

The background color of the image.

transparent : bool | False

Specify if the exported figure have to contains a transparent background.

Examples

>>> # Define a Brain instance :
>>> vb = Brain()
>>> # Export the main brain as a (10cm, 20cm) image at 300 dpi:
>>> vb.screenshot('main.png', canvas='brain', print_size=(10, 20))

1.3.3. Load and save GUI configuration

1.3.3.1. Load an existing configuration

Brain.load_config(config)[source]

Load a configuration file.

Parameters:

config : string

File name of the configuration file.

1.3.3.2. Save the current configuration

Brain.save_config(config)[source]

Save a configuration file.

Parameters:

config : string

File name of the configuration file.

1.3.4. Brain methods

Set of functions for an interactive control of the main brain object. Use the methods below to define which brain template or hemisphere to display, the transparency level…

1.3.4.1. Control the brain

Brain.brain_control(template=None, hemisphere=None, translucent=None, alpha=None, visible=True)[source]

Control the type of brain to use.

Use this method to switch between several brain templates. Then, you can to display selected hemisphere (left or right).

Parameters:

template : string | None

Template to use for the MNI brain. Use either ‘B1’, ‘B2’ or ‘B3’.

visible : bool | True

Show (True) or hide (False) the MNI brain.

hemisphere : {‘both’, ‘left’, ‘ritgh’}

Define if you want to see only ‘left’ or ‘right’ hemisphere. Otherwise use ‘both’.

translucent : bool | None

Set the brain translucent (True) or opaque (False).

alpha : float | None

Transparency level.

visible : bool | True

Display or hide the brain.

See also

brain_list
Get the list of available mesh brain templates.

Examples

>>> # Define a Brain instance :
>>> vb = Brain()
>>> # Display the right hemisphere of 'B3' template :
>>> vb.brain_control(template='B3', hemisphere='right')
>>> # Show the GUI :
>>> vb.show()

1.3.4.2. List of available templates

Brain.brain_list()[source]

Get the list of available mesh brain templates.

Returns:

meshes : list

List of available mesh brain templates.

Examples

>>> # Define a Brain instance :
>>> vb = Brain()
>>> print(vb.brain_list())

1.3.4.3. Add mesh to the scene

Brain.add_mesh(name, vertices, faces, **kwargs)[source]

Add a mesh to the scene.

Parameters:

name : string

Name of the object to add.

vertices : array_like

Vertices of the mesh.

faces : array_like

Faces of the mesh.

kargs : dict | {}

Supplementar arguments pass to the BrainMesh class.

1.3.5. Sources methods

Set of functions for an interactive control of sources object. Use the methods below to pass some data to sources, to control the transparency level, to run the cortical projection / repartition…

1.3.5.1. Control sources

Brain.sources_control(name, data=None, color=None, symbol=None, radius_min=None, radius_max=None, edge_color=None, edge_width=None, alpha=None, mask=None, mask_color=None, visible=True)[source]

Set data to sources and control source’s properties.

See the definition of SourceObj for the description of input parameters.

See also

sources_display
Select sources to display.

1.3.5.2. Select sources

Brain.sources_display(name=None, select='all')[source]

Select sources to display.

Parameters:

name : string | None

Name of the source object to control. If None, the selection is applied to all sources.

select : {‘all’, ‘none’, ‘left’, ‘right’, ‘inside’, ‘outside’}

The select parameter can be ‘all’, ‘none’, ‘left’, ‘right’, ‘inside’ or ‘outside’.

See also

sources_control
Set data to sources and control source’s properties.

1.3.5.3. Fit to an object

Brain.sources_fit_to_vertices(name=None, fit_to='brain')[source]

Force sources coordinates to fit to a selected object.

Parameters:

name : string | None

If name is None, all sources across objects are going to be used.

fit_to : {‘brain’, ‘roi’}

The object name to fit. Use ‘brain’ or ‘roi’.

1.3.5.4. Convert into convex hull

Brain.sources_to_convex_hull(xyz)[source]

Convert a set of sources into a convex hull.

Parameters:

xyz : array_like

Array of sources coordinates of shape (N, 3)

Returns:

faces : array_like

A set of faces than can be then passed to the add_mesh method.

See also

add_mesh
add a mesh to the scene

1.3.5.5. Cortical projection

Brain.cortical_projection(radius=10.0, project_on='brain', contribute=False, mask_color='orange', **kwargs)[source]

Project sources activity.

This method can be used to project the sources activity either onto the brain or on region of interest.

Parameters:

radius : float | 10.

Projection radius.

project_on : {‘brain’, ‘roi’}

Define on which object to project the sources activity. Choose either ‘brain’ for projecting the sources activity onto the brain or ‘roi’ to project on region of interest (if defined).

contribute : bool | False

Specify if sources contribute on both hemisphere.

mask_color : string/tuple/array_like | ‘orange’

The color to assign to vertex for masked sources.

kwargs : dict

Further arguments are be passed to the cbar_control method.

See also

cortical_repartition
project number of contributing sources.
roi_control
add a region of interest.
sources_colormap
Change the colormap properties.

1.3.5.6. Cortical repartition

Brain.cortical_repartition(radius=10.0, project_on='brain', contribute=False, mask_color='orange', **kwargs)[source]

Project the number of contributing sources per vertex.

Parameters:

radius : float | 10.

Projection radius.

project_on : {‘brain’, ‘roi’}

Define on which object to project the sources activity. Chose either ‘brain’ for projecting the sources activity onto the brain or ‘roi’ to project on region of interest (if defined).

contribute : bool | False

Specify if sources contribute on both hemisphere.

mask_color : string/tuple/array_like | ‘orange’

The color to assign to vertex for masked sources.

kwargs : dict

Further arguments are be passed to the cbar_control method

1.3.6. Time-series methods

1.3.6.1. Time-series control

Brain.time_series_control(name, color=None, line_width=None, amplitude=None, width=None, translate=None, visible=True)[source]

Control time-series settings.

Parameters:

name : string

Name of the time-series object to control.

color : string/list/tuple/array_like | None

Color of the time-series.

amplitude : float | None

Graphical amplitude of the time-series.

width : float | None

Graphical width of th time-series.

line_width : float | None

Line width of the time-series.

translate : tuple | None

Translation along the (x, y, z) axis for the time-series.

1.3.7. Pictures methods

1.3.7.1. Pictures control

Brain.pictures_control(name, width=None, height=None, translate=None, visible=True, **kwargs)[source]

Control pictures settings.

Parameters:

width : float | 7.

Width of each picture.

height : float | 7.

Height of each picture.

translate : tuple | None

Offset along the (x, y, z) axis for the pictures.

kwargs : dict | {}

Further arguments can be used to control the colorbar (clim, cmap, vmin, under, vmax, over).

1.3.8. Connectivity methods

Set of functions for an interactive control of connectivity object. Use the methods below to pass some data to connectivity, to control the transparency level…

1.3.8.1. Control Connectivity

Brain.connect_control(name, color_by=None, dynamic=None, alpha=None, line_width=None, visible=True, **kwargs)[source]

Update connectivity object.

Parameters:

name : string

Name of the connectivity object to control.

colorby : string | {‘strength’, ‘count’}

Define how to color connexions. Use ‘strength’ if the color has to be modulate by the connectivity strength. Use ‘count’ if the color depends on the number of connexions per node. Use ‘density’to define colors according to the number of line in a sphere of radius c_dradius.

dynamic : tuple | None

Control the dynamic opacity. For example, if dynamic=(0, 1), strong connections will be more opaque than weak connections.

show : bool | True

Display or hide connectivity.

kwargs : dict | {}

Further arguments can be used to control the colorbar (clim, cmap, vmin, under, vmax, over).

See also

cbar_control
control the colormap of a specific object

1.3.9. Colorbar methods

1.3.9.1. Colorbar control

Brain.cbar_control(name, **kwargs)[source]

Control the colorbar of a specific object.

Optional parameters let to None are going to be ignored.

Parameters:

name : string, {‘Projection’, ‘Connectivity’, ‘Pictures’}

Name of the colorbar object. If you want to control the colorbar of either the cortical projection, use ‘Projection’. And ‘Connectivity’ or ‘Pictures’ if defined.

cmap : string | None

Matplotlib colormap (like ‘viridis’, ‘inferno’…).

clim : tuple/list | None

Colorbar limit. Every values under / over clim will clip.

vmin : float | None

Every values under vmin will have the color defined using the under parameter.

vmax : float | None

Every values over vmin will have the color defined using the over parameter.

under : tuple/string | None

Matplotlib color under vmin.

over : tuple/string | None

Matplotlib color over vmax.

cblabel : string | None

Colorbar label.

cbtxtsz : float | None

Text size of the colorbar label.

cbtxtsh : float | None

Shift for the colorbar label.

txtcolor : string | ‘white’

Text color.

txtsz : float | None

Text size for clim/vmin/vmax text.

txtsh : float | None

Shift for clim/vmin/vmax text.

border : bool | None

Display colorbar borders.

bw : float | None

Border width.

limtxt : bool | None

Display vmin/vmax text.

bgcolor : tuple/string | None

Background color of the colorbar canvas.

ndigits : int | None

Number of digits for the text.

1.3.9.2. Select a colorbar

Brain.cbar_select(name, visible=True)[source]

Select and display a colorbar.

Parameters:

name : string, {‘Projection’, ‘Connectivity’, ‘Pictures’}

Name of the colorbar object. If you want to control the colorbar of either the cortical projection, use ‘Projection’. And ‘Connectivity’ or ‘Pictures’ if defined.

visible : bool | True

Set the colorbar of the object “name” visible.

1.3.9.3. List of available colorbars

Brain.cbar_list()[source]

Get the list of objects for which the colorbar can be controlled.

Returns:

cbobjs : list

List of objects for which the colorbar can be controlled.

1.3.9.4. Export colorbar

Brain.cbar_export(filename=None, export_only=None, get_dict=False)[source]

Export colorbars in a text file or in a dictionary.

Parameters:

filename : string | None

Name of the text file (i.e ‘name.txt’). If None, colorbars are not going to be saved.

export_only : list | None

List of names for exporting the colorbar.

get_dict : bool | False

Get colorbars as a dictionary.

Returns:

dict_all : dict

Dictionary of all colorbars (only if get_dict is True)

1.3.9.5. Auto-scaling

Brain.cbar_autoscale(name)[source]

Autoscale the colorbar to the best limits.

Parameters:

name : string, {‘Projection’, ‘Connectivity’, ‘Pictures’}

Name of the colorbar object. If you want to control the colorbar of either the cortical projection, use ‘Projection’. And ‘Connectivity’ or ‘Pictures’ if defined.