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

1(1,2,3)

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__(name[, vol, labels, index, hdr, …])

Init.

animate([step, interval, iterations])

Animate the object.

copy()

Get a copy of the object.

describe_tree()

Tree description.

get_centroids(select)

Get the (x, y, z) coordinates of the center of a ROI.

get_labels([save_to_path])

Get the labels associated with the loaded ROI.

list([file])

Get the list of installed volumes.

localize_sources(xyz[, source_name, …])

Localize source’s using this ROI object.

pos_to_slice(pos[, axis, hdr])

Return the slice from position.

preview([bgcolor, axis, xyz, show, obj, …])

Previsualize the result.

project_sources(s_obj[, project, radius, …])

Project source’s activity or repartition onto ROI.

record_animation(name[, n_pic, bgcolor])

Record an animated object and save as a *.gif file.

remove()

Remove the volume template.

render()

Render the canvas.

reset()

Reset the RoiObject.

save([tmpfile])

Save the volume template.

screenshot(saveas[, print_size, dpi, unit, …])

Take a screeshot of the scene.

select_roi([select, unique_color, …])

Select several Region Of Interest (ROI).

set_data(name[, vol, labels, index, hdr, system])

Load an roi object.

set_shortcuts_to_canvas(canvas)

Set shortcuts to a VisbrainCanvas.

slice_to_pos(sl[, axis, hdr])

Return the position from slice in the volume space.

to_dict()

Return a dictionary of all colorbar args.

to_kwargs([addisminmax])

Return a dictionary for input arguments.

update()

Fonction to run when an update is needed.

update_from_dict(kwargs)

Update attributes from a dictionary.

where_is(patterns[, df, union, columns, …])

Find a list of string patterns in a DataFrame.
alpha

Get the alpha value.

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

camera

Get the camera value.

cmap

Get the cmap value.

color

Get the color value.

copy()[source]

Get a copy of the object.

data_folder

Get the data_folder value.

faces

Get the faces value.

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

list(file=None)[source]

Get the list of installed volumes.

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

mask_color

Get the mask_color value.

name

Get the name value.

normals

Get the normals value.

parent

Get the parent value.

pos_to_slice(pos, axis=None, hdr=None)[source]

Return the slice from position.

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

remove()[source]

Remove the volume template.

render()[source]

Render the canvas.

Returns
imgarray_like

Array of shape (n_rows, n_columns, 4) where 4 describes the RGBA components.

reset()[source][source]

Reset the RoiObject.

save(tmpfile=False)[source]

Save the volume template.

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
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(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(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(sl, axis=None, hdr=None)[source]

Return the position from slice in the volume space.

transform

Get the transform value.

translucent

Get the translucent value.

vertices

Get the vertices value.

visible_obj

Get the visible_obj value.

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