visbrain.objects.SourceObj¶

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.

Parameters:

Parameters:	name : string Name of the source object. xyz : array_like Array of positions of shape (n_sources, 2) or (n_sources, 3). data : array_like \| None Array of weights of shape (n_sources,). color : array_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. alpha : float \| 1. Transparency level. symbol : string \| ‘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_max : float \| 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_color : string/list/array_like \| ‘black’ Edge color of source’s markers. edge_width : float \| 0. Edge width source’s markers. system : {‘mni’, ‘tal’} Specify if the coodinates are in the MNI space (‘mni’) or Talairach (‘tal’). mask : array_like \| None Array of boolean values to specify masked sources. For example, if data are p-values, mask could be non-significant sources. mask_color : array_like/tuple/string \| ‘gray’ Color to use for masked sources. mask_radius : float \| None Radius size of masked sources. text : list \| None Text to attach to each source. For example, text could be the name of each source. text_size : float \| 2. Text size attached to sources. text_color : array_like/string/tuple \| ‘white’ Text color attached to sources. text_bold : bool \| False Specify if the text attached to sources should be bold. text_translate : tuple \| (0., 2., 0.) Translate the text along the (x, y, z) axis. visible : bool/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. transform : VisPy.visuals.transforms \| None VisPy transformation to set to the parent node. parent : VisPy.parent \| None Markers object parent. verbose : string Verbosity level. _z : float \| 10. In case of (n_sources, 2) use _z to specify the elevation. kw : dict \| {} Optional arguments are used to control the colorbar (See `ColorbarObj`).

name : string: Name of the source object.
xyz : array_like: Array of positions of shape (n_sources, 2) or (n_sources, 3).
data : array_like | None: Array of weights of shape (n_sources,).
color : array_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.
alpha : float | 1.: Transparency level.
symbol : string | ‘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_max : float | 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_color : string/list/array_like | ‘black’: Edge color of source’s markers.
edge_width : float | 0.: Edge width source’s markers.
system : {‘mni’, ‘tal’}: Specify if the coodinates are in the MNI space (‘mni’) or Talairach (‘tal’).
mask : array_like | None: Array of boolean values to specify masked sources. For example, if data are p-values, mask could be non-significant sources.
mask_color : array_like/tuple/string | ‘gray’: Color to use for masked sources.
mask_radius : float | None: Radius size of masked sources.
text : list | None: Text to attach to each source. For example, text could be the name of each source.
text_size : float | 2.: Text size attached to sources.
text_color : array_like/string/tuple | ‘white’: Text color attached to sources.
text_bold : bool | False: Specify if the text attached to sources should be bold.
text_translate : tuple | (0., 2., 0.): Translate the text along the (x, y, z) axis.
visible : bool/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.
transform : VisPy.visuals.transforms | None: VisPy transformation to set to the parent node.
parent : VisPy.parent | None: Markers object parent.
verbose : string: Verbosity level.
_z : float | 10.: In case of (n_sources, 2) use _z to specify the elevation.
kw : dict | {}: Optional arguments are used to control the colorbar (See ColorbarObj).

Notes

List of supported shortcuts :

s : save the figure

<delete> : reset camera

Examples

>>> 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)

Methods

`__init__`(name, xyz[, data, color, alpha, …])	Init.
`analyse_sources`([roi_obj, replace_bad, …])	Analyse sources using Region of interest (ROI).
`animate`([step, interval, iterations])	Animate the object.
`color_sources`([analysis, color_by, data, …])	Custom color sources methods.
`copy`()	Get a copy of the object.
`describe_tree`()	Tree description.
`fit_to_vertices`(v)	Move sources to the closest vertex.
`preview`([bgcolor, axis, xyz, show, obj, …])	Previsualize the result.
`project_sources`(b_obj[, project, radius, …])	Project source’s activity or repartition onto the brain object.
`record_animation`(name[, n_pic, bgcolor])	Record an animated object and save as a *.gif file.
`render`()	Render the canvas.
`screenshot`(saveas[, print_size, dpi, unit, …])	Take a screeshot of the scene.
`set_shortcuts_to_canvas`(canvas)	Set shortcuts to a VisbrainCanvas.
`set_visible_sources`([select, v, distance])	Select sources that are either inside or outside the mesh.
`to_dict`()	Return a dictionary of all colorbar args.
`to_kwargs`([addisminmax])	Return a dictionary for input arguments.
`update`()	Update the source object.
`update_from_dict`(kwargs)	Update attributes from a dictionary.

alpha¶: Get the alpha value.

analyse_sources(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.

Parameters:

Parameters:	roi_obj : string/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_bad : bool \| True Replace bad values (True) or not (False). bad_patterns : list \| [-1, ‘undefined’, ‘None’] Bad patterns to replace if replace_bad is True. replace_with : string \| ‘Not found’ Replace bad patterns with this string. keep_only : list \| None List of string patterns to keep only sources that match.
Returns:	df : pandas.DataFrames A Pandas DataFrame or a list of DataFrames if roi_obj is a list.

roi_obj : string/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_bad : bool | True: Replace bad values (True) or not (False).
bad_patterns : list | [-1, ‘undefined’, ‘None’]: Bad patterns to replace if replace_bad is True.
replace_with : string | ‘Not found’: Replace bad patterns with this string.
keep_only : list | None: List of string patterns to keep only sources that match.

Returns:

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

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

Animate the object.

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

Parameters:	step : float \| 1. Rotation step. interval : float \| ‘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. iterations : int \| -1 Number of iterations. Can be -1 for infinite.

cmap¶: Get the cmap value.

color¶: Get the color value.

color_sources(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)

Parameters:

Parameters:	data : array_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. analysis : pandas.DataFrames \| None ROI analysis runned using the analyse_sources method. color_by : string \| 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_color : dict \| 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_others : array_like/tuple/string \| ‘black’ Specify how to color sources that are not found using the roi_to_color dictionary. hide_others : bool \| False Show or hide sources that are not found using the roi_to_color dictionary.

data : array_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.
analysis : pandas.DataFrames | None: ROI analysis runned using the analyse_sources method.
color_by : string | 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_color : dict | 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_others : array_like/tuple/string | ‘black’: Specify how to color sources that are not found using the roi_to_color dictionary.
hide_others : bool | False: Show or hide sources that are not found using the roi_to_color dictionary.

copy()[source]¶: Get a copy of the object.

data¶: Get the data value.

data_folder¶: Get the data_folder value.

edge_color¶: Get the edge_color value.

edge_width¶: Get the edge_width value.

fit_to_vertices(v)[source][source]¶

Move sources to the closest vertex.

Parameters:	v : array_like The vertices of shape (nv, 3) or (nv, 3, 3) if index faced.

hide¶: Get the hide value.

is_masked¶: Get the is_masked value.

mask¶: Get the mask value.

mask_color¶: Get the mask_color value.

name¶: Get the name value.

parent¶: Get the parent value.

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

Previsualize the result.

Parameters:

Parameters:	bgcolor : array_like/string/tuple \| ‘black’ Background color for the preview. axis : bool \| False Add x and y axis with ticks. xyz : bool \| False Add an (x, y, z) axis to the scene. obj : VisbrainObj \| None Pass a Visbrain object if you want to use the camera of an other object. size : tuple \| (1200, 800) Default size of the window. mpl : bool \| False Use Matplotlib to display the object. This result in a non interactive figure. kwargs : dict \| {} Optional arguments are passed to the VisbrainCanvas class.

bgcolor : array_like/string/tuple | ‘black’: Background color for the preview.
axis : bool | False: Add x and y axis with ticks.
xyz : bool | False: Add an (x, y, z) axis to the scene.
obj : VisbrainObj | None: Pass a Visbrain object if you want to use the camera of an other object.
size : tuple | (1200, 800): Default size of the window.
mpl : bool | False: Use Matplotlib to display the object. This result in a non interactive figure.
kwargs : dict | {}: Optional arguments are passed to the VisbrainCanvas class.

project_sources(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.

Parameters:

Parameters:	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’). radius : float The radius under which activity is projected on vertices. contribute: bool \| False Specify if sources contribute on both hemisphere. cmap : string \| ‘viridis’ The colormap to use. clim : tuple \| None The colorbar limits. If None, (data.min(), data.max()) will be used instead. vmin : float \| None Minimum threshold. vmax : float \| None Maximum threshold. under : string/tuple/array_like \| ‘gray’ The color to use for values under vmin. over : string/tuple/array_like \| ‘red’ The color to use for values over vmax. mask_color : string/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_overlay : int \| 0 The overlay number used for the projection.

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’).
radius : float: The radius under which activity is projected on vertices.
contribute: bool | False: Specify if sources contribute on both hemisphere.
cmap : string | ‘viridis’: The colormap to use.
clim : tuple | None: The colorbar limits. If None, (data.min(), data.max()) will be used instead.
vmin : float | None: Minimum threshold.
vmax : float | None: Maximum threshold.
under : string/tuple/array_like | ‘gray’: The color to use for values under vmin.
over : string/tuple/array_like | ‘red’: The color to use for values over vmax.
mask_color : string/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_overlay : int | 0: The overlay number used for the projection.

radius_max¶: Get the radius_max value.

radius_min¶: Get the radius_min value.

record_animation(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

Parameters:	name : string Name of the gif file (e.g ‘myfile.gif’) n_pic : int \| 10 Number of pictures to use to render the gif. bgcolor : string, tuple, list \| None Background color.

render()[source]¶

Render the canvas.

Returns:	img : array_like Array of shape (n_rows, n_columns, 4) where 4 describes the RGBA components.

screenshot(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.

Parameters:

Parameters:	saveas : str The name of the file to be saved. This file must contains a extension like .png, .tiff, .jpg… 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. obj : VisbrainObj \| None Pass a Visbrain object if you want to use the camera of an other object for the sceen rendering. kwargs : dict \| {} Optional arguments are passed to the VisbrainCanvas class.

saveas : str: The name of the file to be saved. This file must contains a extension like .png, .tiff, .jpg…
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.
obj : VisbrainObj | None: Pass a Visbrain object if you want to use the camera of an other object for the sceen rendering.
kwargs : dict | {}: Optional arguments are passed to the VisbrainCanvas class.

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

Select sources that are either inside or outside the mesh.

Parameters:

Parameters:	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. v : array_like \| None The vertices of shape (nv, 3) or (nv, 3, 3) if index faced. distance : float \| 5. Distance between the source and the surface.

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.
v : array_like | None: The vertices of shape (nv, 3) or (nv, 3, 3) if index faced.
distance : float | 5.: Distance between the source and the surface.