class visbrain.objects.SourceObj(name, xyz, data=None, color='red', alpha=1.0, symbol='disc', radius_min=5.0, radius_max=10.0, edge_width=0.0, edge_color='black', system='mni', mask=None, mask_color='gray', mask_radius=5.0, text=None, text_size=2.0, text_color='white', text_bold=False, text_translate=(0.0, 2.0, 0.0), visible=True, transform=None, parent=None, verbose=None, _z=-10.0, **kw)[source][source]

Create a source object.


Name of the source object.


Array of positions of shape (n_sources, 2) or (n_sources, 3).

dataarray_like | None

Array of weights of shape (n_sources,).

colorarray_like/string/tuple | ‘red’

Marker’s color. Use a string (i.e ‘green’) to use the same color across markers or a list of colors of length n_sources to use different colors for markers.

alphafloat | 1.

Transparency level.

symbolstring | ‘disc’

Symbol to use for sources. Allowed style strings are: disc, arrow, ring, clobber, square, diamond, vbar, hbar, cross, tailed_arrow, x, triangle_up, triangle_down, and star.

radius_min / radius_maxfloat | 5. / 10.

Define the minimum and maximum source’s possible radius. By default if all sources have the same value, the radius will be radius_min.

edge_colorstring/list/array_like | ‘black’

Edge color of source’s markers.

edge_widthfloat | 0.

Edge width source’s markers.

system{‘mni’, ‘tal’}

Specify if the coodinates are in the MNI space (‘mni’) or Talairach (‘tal’).

maskarray_like | None

Array of boolean values to specify masked sources. For example, if data are p-values, mask could be non-significant sources.

mask_colorarray_like/tuple/string | ‘gray’

Color to use for masked sources.

mask_radiusfloat | None

Radius size of masked sources.

textlist | None

Text to attach to each source. For example, text could be the name of each source.

text_sizefloat | 2.

Text size attached to sources.

text_colorarray_like/string/tuple | ‘white’

Text color attached to sources.

text_boldbool | False

Specify if the text attached to sources should be bold.

text_translatetuple | (0., 2., 0.)

Translate the text along the (x, y, z) axis.

visiblebool/array_like | True

Specify which source’s have to be displayed. If visible is True, all sources are displayed, False all sources are hiden. Alternatively, use an array of shape (n_sources,) to select which sources to display.

transformVisPy.visuals.transforms | None

VisPy transformation to set to the parent node.

parentVisPy.parent | None

Markers object parent.


Verbosity level.

_zfloat | 10.

In case of (n_sources, 2) use _z to specify the elevation.

kwdict | {}

Optional arguments are used to control the colorbar (See ColorbarObj).


List of supported shortcuts :

  • s : save the figure

  • <delete> : reset camera


>>> import numpy as np
>>> from visbrain.objects import SourceObj
>>> n_sources = 100
>>> pos = np.random.uniform(-10, 10, (n_sources, 3))
>>> color = ['orange'] * 50 + ['red'] * 50
>>> data = np.random.rand(n_sources)
>>> text = ['s' + str(k) for k in range(n_sources)]
>>> s = SourceObj('test', pos, color=color, data=data, radius_min=10.,
>>>               radius_max=20., edge_color='black', edge_width=1.,
>>>               text=text, text_size=10.)
>>> s.preview(axis=True)


__init__(self, name, xyz[, data, color, …])


analyse_sources(self[, roi_obj, …])

Analyse sources using Region of interest (ROI).

animate(self[, step, interval, iterations])

Animate the object.

color_sources(self[, analysis, color_by, …])

Custom color sources methods.


Get a copy of the object.


Tree description.

fit_to_vertices(self, v)

Move sources to the closest vertex.

preview(self[, bgcolor, axis, xyz, show, …])

Previsualize the result.

project_sources(self, b_obj[, project, …])

Project source’s activity or repartition onto the brain object.

record_animation(self, name[, n_pic, bgcolor])

Record an animated object and save as a *.gif file.


Render the canvas.

screenshot(self, saveas[, print_size, dpi, …])

Take a screeshot of the scene.

set_shortcuts_to_canvas(self, canvas)

Set shortcuts to a VisbrainCanvas.

set_visible_sources(self[, select, v, distance])

Select sources that are either inside or outside the mesh.


Return a dictionary of all colorbar args.

to_kwargs(self[, addisminmax])

Return a dictionary for input arguments.


Update the source object.

update_from_dict(self, kwargs)

Update attributes from a dictionary.

property alpha

Get the alpha value.

analyse_sources(self, roi_obj='talairach', replace_bad=True, bad_patterns=[-1, 'undefined', 'None'], distance=None, replace_with='Not found', keep_only=None)[source][source]

Analyse sources using Region of interest (ROI).

This method can be used to identify in which structure is located a source.

roi_objstring/list | ‘talairach’

The ROI object to use. Use either ‘talairach’, ‘brodmann’ or ‘aal’ to use a predefined ROI template. Otherwise, use a RoiObj object or a list of RoiObj.

replace_badbool | True

Replace bad values (True) or not (False).

bad_patternslist | [-1, ‘undefined’, ‘None’]

Bad patterns to replace if replace_bad is True.

replace_withstring | ‘Not found’

Replace bad patterns with this string.

keep_onlylist | None

List of string patterns to keep only sources that match.


A Pandas DataFrame or a list of DataFrames if roi_obj is a list.

animate(self, step=1.0, interval='auto', iterations=-1)[source]

Animate the object.

Note that this method can only be used with 3D objects.

stepfloat | 1.

Rotation step.

intervalfloat | ‘auto’

Time between events in seconds. The default is ‘auto’, which attempts to find the interval that matches the refresh rate of the current monitor. Currently this is simply 1/60.

iterationsint | -1

Number of iterations. Can be -1 for infinite.

property cmap

Get the cmap value.

property color

Get the color value.

color_sources(self, analysis=None, color_by=None, data=None, roi_to_color=None, color_others='black', hide_others=False, cmap='viridis', clim=None, vmin=None, vmax=None, under='gray', over='red')[source][source]

Custom color sources methods.

This method can be used to color sources :

  • According to a data vector. In that case, source’s colors are inferred using colormap inputs (i.e cmap, vmin, vmax, clim, under and over)

  • According to ROI analysis (using the analysis and color_by input parameters)

dataarray_like | None

A vector of data with the same length as the number os sources. The color is inferred from this data vector and can be controlled using the cmap, clim, vmin, vmax, under and over parameters.

analysispandas.DataFrames | None

ROI analysis runned using the analyse_sources method.

color_bystring | None

A column name of the analysis DataFrames. This columns is then used to identify the color to set to each source inside ROI.

roi_to_colordict | None

Define custom colors to ROI. For example use {‘BA4’: ‘red’, ‘BA32’: ‘blue’} to define custom colors. If roi_to_color is None, random colors will be used instead.

color_othersarray_like/tuple/string | ‘black’

Specify how to color sources that are not found using the roi_to_color dictionary.

hide_othersbool | False

Show or hide sources that are not found using the roi_to_color dictionary.


Get a copy of the object.

property data

Get the data value.

property data_folder

Get the data_folder value.

property edge_color

Get the edge_color value.

property edge_width

Get the edge_width value.

fit_to_vertices(self, v)[source][source]

Move sources to the closest vertex.


The vertices of shape (nv, 3) or (nv, 3, 3) if index faced.

property hide

Get the hide value.

property is_masked

Get the is_masked value.

property mask

Get the mask value.

property mask_color

Get the mask_color value.

property name

Get the name value.

property parent

Get the parent value.

preview(self, bgcolor='black', axis=False, xyz=False, show=True, obj=None, size=(1200, 800), mpl=False, **kwargs)[source]

Previsualize the result.

bgcolorarray_like/string/tuple | ‘black’

Background color for the preview.

axisbool | False

Add x and y axis with ticks.

xyzbool | False

Add an (x, y, z) axis to the scene.

objVisbrainObj | None

Pass a Visbrain object if you want to use the camera of an other object.

sizetuple | (1200, 800)

Default size of the window.

mplbool | False

Use Matplotlib to display the object. This result in a non interactive figure.

kwargsdict | {}

Optional arguments are passed to the VisbrainCanvas class.

project_sources(self, b_obj, project='modulation', radius=10.0, contribute=False, cmap='viridis', clim=None, vmin=None, under='black', vmax=None, over='red', mask_color=None, to_overlay=0)[source][source]

Project source’s activity or repartition onto the brain object.

b_obj{BrainObj, RoiObj}

The object on which to project sources.

project{‘modulation’, ‘repartition’}

Project either the source’s data (‘modulation’) or get the number of contributing sources per vertex (‘repartition’).


The radius under which activity is projected on vertices.

contribute: bool | False

Specify if sources contribute on both hemisphere.

cmapstring | ‘viridis’

The colormap to use.

climtuple | None

The colorbar limits. If None, (data.min(), data.max()) will be used instead.

vminfloat | None

Minimum threshold.

vmaxfloat | None

Maximum threshold.

understring/tuple/array_like | ‘gray’

The color to use for values under vmin.

overstring/tuple/array_like | ‘red’

The color to use for values over vmax.

mask_colorstring/tuple/array_like | ‘gray’

The color to use for the projection of masked sources. If None, the color of the masked sources is going to be used.

to_overlayint | 0

The overlay number used for the projection.

property radius_max

Get the radius_max value.

property radius_min

Get the radius_min value.

record_animation(self, name, n_pic=10, bgcolor=None)[source]

Record an animated object and save as a *.gif file.

Note that this method :

  • Can only be used with 3D objects.

  • Requires the python package imageio


Name of the gif file (e.g ‘myfile.gif’)

n_picint | 10

Number of pictures to use to render the gif.

bgcolorstring, tuple, list | None

Background color.


Render the canvas.


Array of shape (n_rows, n_columns, 4) where 4 describes the RGBA components.

screenshot(self, saveas, print_size=None, dpi=300.0, unit='centimeter', factor=None, region=None, autocrop=False, bgcolor=None, transparent=False, obj=None, line_width=1.0, **kwargs)[source]

Take a screeshot of the scene.

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.


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

print_sizetuple | 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.

dpifloat | 300.

Dots per inch for printing the image.

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

Unit of the printed size.

factorfloat | None

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

regiontuple | None

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

autocropbool | False

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

bgcolorarray_like/string | None

The background color of the image.

transparentbool | False

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

objVisbrainObj | None

Pass a Visbrain object if you want to use the camera of an other object for the sceen rendering.

kwargsdict | {}

Optional arguments are passed to the VisbrainCanvas class.

set_visible_sources(self, select='all', v=None, distance=5.0)[source][source]

Select sources that are either inside or outside the mesh.

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

Custom source selection. Use ‘inside’ or ‘outside’ to select sources respectively inside or outside the volume. Use ‘close’ to select sources that are closed to the surface (see the distance parameter below). Finally, use ‘all’ (or True), ‘none’ (or None, False) to show or hide all of the sources.

varray_like | None

The vertices of shape (nv, 3) or (nv, 3, 3) if index faced.

distancefloat | 5.

Distance between the source and the surface.

property symbol

Get the symbol value.

property text

Get the text value.

property text_color

Get the text_color value.

property text_size

Get the text_size value.

property text_translate

Get the text_translate value.

property transform

Get the transform value.

property visible

Get the visible value.

property visible_and_not_masked

Get the visible_and_not_masked value.

property visible_obj

Get the visible_obj value.

property xyz

Get the visible xyz value.