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