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

namestring: Name of the source object.
xyzarray_like: 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.
verbosestring: 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).

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__`(self, name, xyz[, data, color, …])	Init.
`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.
`copy`(self)	Get a copy of the object.
`describe_tree`(self)	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`(self)	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.
`to_dict`(self)	Return a dictionary of all colorbar args.
`to_kwargs`(self[, addisminmax])	Return a dictionary for input arguments.
`update`(self)	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.

Parameters

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.

Returns

dfpandas.DataFrames: 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.

Parameters

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)

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.

copy(self)[source]¶: 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.

Parameters

varray_like: 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.

Parameters

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.

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’).
radiusfloat: 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

Parameters

namestring: 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(self)[source]¶

Render the canvas.

Returns

imgarray_like: 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.

Parameters

saveasstr: 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.

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