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', text=None, text_size=3.0, text_color='black', 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:
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.0/10.0

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.

text : list | None

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

text_size : float | 3.

Text size attached to sources.

text_color : array_like/string/tuple | ‘black’

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).
color_sources([analysis, color_by, data, …]) Custom color sources methods.
describe_tree() Tree description.
fit_to_vertices(v) Move sources to the closest vertex.
preview([bgcolor, axis, xyz, show, obj, size]) Previsualize the result.
project_sources(b_obj[, project, radius, …]) Project source’s activity or repartition onto the brain object.
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:
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.

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

Get the data 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), **kwargs)[source]

Previsualize the result.

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.

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)[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’).

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.

radius_max

Get the radius_max value.

radius_min

Get the radius_min value.

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

symbol

Get the symbol value.

text

Get the text value.

text_color

Get the text_color value.

text_size

Get the text_size value.

text_translate

Get the text_translate value.

transform

Get the transform value.

visible

Get the visible value.

visible_and_not_masked

Get the visible_and_not_masked value.

visible_obj

Get the visible_obj value.

xyz

Get the visible xyz value.