visbrain.objects.RoiObj¶
-
class
visbrain.objects.
RoiObj
(name, vol=None, labels=None, index=None, hdr=None, system='mni', transform=None, parent=None, verbose=None, preload=True, _scale=1.0, **kw)[source][source]¶ Create a Region Of Interest (ROI) object.
Main functionalities
Display a mesh of selected ROIs
Localize sources
Supported ROI
Brodmann Areas
Talairach atlas
Automated Anatomical Labeling (AAL)
MIST, including levels 7, 12, 20, 36, 64, 122 and ROI [R9f28ad89f053-1]
- Parameters
- namestring
Name of the ROI object. If name is ‘brodmann’, ‘aal’ or ‘talairach’ a predefined ROI object is used and vol, index and label are ignored. MIST [R9f28ad89f053-1] is also supported. To specify a resolution use mist_%s with %s in [‘7’, ‘12’, ‘20’, ‘36’, ‘64’, ‘122’, ‘ROI’] (e.g ‘mist_7’, mist_ROI)
- volarray_like | None
ROI volume. Sould be an array with three dimensions.
- labelsarray_like | None
Array of labels. A structured array can be used (i.e label=np.zeros(n_sources, dtype=[(‘brodmann’, int), (‘aal’, object)])).
- indexarray_like | None
Array of index that make the correspondance between the volume values and labels. The length of index must be the same as label.
- hdrarray_like | None
Array of transform source’s coordinates into the volume space. Must be a (4, 4) array.
- system{‘mni’, ‘tal’}
The system of the volume. Can either be MNI (‘mni’) or Talairach (‘tal’).
- transformVisPy.visuals.transforms | None
VisPy transformation to set to the parent node.
- parentVisPy.parent | None
ROI object parent.
- verbosestring
Verbosity level.
- kwdict | {}
Optional arguments are used to control the colorbar (See
ColorbarObj
).
Notes
List of supported shortcuts :
s : save the figure
<delete> : reset camera
References
- R9f28ad89f053-1(1,2)
Urchs, S., Armoza, J., Benhajali, Y., St-Aubin, J., Orban, P., & Bellec, P. (2017). MIST: A multi-resolution parcellation of functional brain networks. MNI Open Research, 1.
Examples
>>> import numpy as np >>> from visbrain.objects import RoiObj >>> r = RoiObj('brodmann') >>> r.select_roi(select=[4, 6, 38], unique_color=True, smooth=7) >>> r.preview(axis=True)
Methods
__init__
(self, name[, vol, labels, index, …])Init.
animate
(self[, step, interval, iterations])Animate the object.
copy
(self)Get a copy of the object.
describe_tree
(self)Tree description.
get_centroids
(self, select)Get the (x, y, z) coordinates of the center of a ROI.
get_labels
(self[, save_to_path])Get the labels associated with the loaded ROI.
list
(self[, file])Get the list of installed volumes.
localize_sources
(self, xyz[, source_name, …])Localize source’s using this ROI object.
pos_to_slice
(self, pos[, axis, hdr])Return the slice from position.
preview
(self[, bgcolor, axis, xyz, show, …])Previsualize the result.
project_sources
(self, s_obj[, project, …])Project source’s activity or repartition onto ROI.
record_animation
(self, name[, n_pic, bgcolor])Record an animated object and save as a *.gif file.
remove
(self)Remove the volume template.
render
(self)Render the canvas.
reset
(self)Reset the RoiObject.
save
(self[, tmpfile])Save the volume template.
screenshot
(self, saveas[, print_size, dpi, …])Take a screeshot of the scene.
select_roi
(self[, select, unique_color, …])Select several Region Of Interest (ROI).
set_data
(self, name[, vol, labels, index, …])Load an roi object.
set_shortcuts_to_canvas
(self, canvas)Set shortcuts to a VisbrainCanvas.
slice_to_pos
(self, sl[, axis, hdr])Return the position from slice in the volume space.
to_dict
(self)Return a dictionary of all colorbar args.
to_kwargs
(self[, addisminmax])Return a dictionary for input arguments.
update
(self)Fonction to run when an update is needed.
update_from_dict
(self, kwargs)Update attributes from a dictionary.
where_is
(self, patterns[, df, union, …])Find a list of string patterns in a DataFrame.
-
property
alpha
¶ Get the alpha value.
-
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
camera
¶ Get the camera value.
-
property
cmap
¶ Get the cmap value.
-
property
color
¶ Get the color value.
-
property
data_folder
¶ Get the data_folder value.
-
property
faces
¶ Get the faces value.
-
get_centroids
(self, select)[source][source]¶ Get the (x, y, z) coordinates of the center of a ROI.
- Parameters
- selectlist
List of indices of ROIs. Must be a list or tuple of integers.
- Returns
- xyzarray_like
Array of shape (n_indiced, 3) which contains the (x, y, z) coordinates of each ROI center.
-
get_labels
(self, save_to_path=None)[source][source]¶ Get the labels associated with the loaded ROI.
- Parameters
- save_to_pathstr | None
Save labels to an excel file.
-
localize_sources
(self, xyz, source_name=None, replace_bad=True, bad_patterns=[-1, 'undefined', 'None'], replace_with='Not found', distance=None)[source][source]¶ Localize source’s using this ROI object.
- Parameters
- xyzarray_like
Array of source’s coordinates of shape (n_sources, 3)
- source_namearray_like/list | None
List of source’s names.
- replace_badbool | True
Replace bad values (True) or not (False).
- bad_patternslist | [None, -1, ‘undefined’, ‘None’]
Bad patterns to replace if replace_bad is True.
- replace_withstring | ‘Not found’
Replace bad patterns with this string.
-
property
mask_color
¶ Get the mask_color value.
-
property
name
¶ Get the name value.
-
property
normals
¶ Get the normals 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, s_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 ROI.
- Parameters
- s_objSourceObj
The source object to project.
- 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.
-
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.
-
select_roi
(self, select=0.5, unique_color=False, roi_to_color=None, smooth=3, translucent=False)[source][source]¶ Select several Region Of Interest (ROI).
- Parameters
- selectint, float, list | .5
Threshold for extracting vertices from isosuface method.
- unique_colorbool | False
Use a random unique color for each ROI.
- roi_to_colordict | None
Color of specific ROI using a dictionary i.e {1: ‘red’, 2: ‘orange’}.
- smoothint | 3
Smoothing level. Must be an odd integer (smooth % 2 = 1).
- translucentbool | False
Set if the mesh should be translucent or opaque.
-
set_data
(self, name, vol=None, labels=None, index=None, hdr=None, system='mni')[source][source]¶ Load an roi object.
- Parameters
- namestring
Name of the ROI object. If name is ‘brodmann’, ‘aal’ or ‘talairach’ a predefined ROI object is used and vol, index and labels are ignored.
- volarray_like | None
ROI volume. Sould be an array with three dimensions.
- labelsarray_like | None
Array of labels. A structured array can be used (i.e labels=np.zeros(n_sources, dtype=[(‘brodmann’, int), (‘aal’, object)])).
- indexarray_like | None
Array of index that make the correspondance between the volume values and labels. The length of index must be the same as labels.
- hdrarray_like | None
Array of transform source’s coordinates into the volume space. Must be a (4, 4) array.
- system{‘mni’, ‘tal’}
The system of the volume. Can either be MNI (‘mni’) or Talairach (‘tal’).
-
slice_to_pos
(self, sl, axis=None, hdr=None)[source]¶ Return the position from slice in the volume space.
-
property
transform
¶ Get the transform value.
-
property
translucent
¶ Get the translucent value.
-
property
vertices
¶ Get the vertices value.
-
property
visible_obj
¶ Get the visible_obj value.
-
where_is
(self, patterns, df=None, union=True, columns=None, exact=False, case_sensitive=False)[source][source]¶ Find a list of string patterns in a DataFrame.
- Parameters
- patternslist
List of string patterns to search.
- dfpd.DataFrame | None
The DataFrame to use. If None, the DataFrame of the ROI are going to be used by default.
- unionbool | True
Take either the union of matching patterns (True) or the intersection (False).
- columnslist | None
List of specific column names to search in. If None, this method search through the entire DataFrame.
- exactbool | False
Specify if the pattern to search have to be exact matching (True) or if the pattern is only a part of the result.
- case_sensitivebool | False
Specify if the search have to be case sensitive.
- Returns
- idxlist
List of index that match with the list of patterns.