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

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)

vol : array_like | None

ROI volume. Sould be an array with three dimensions.

labels : array_like | None

Array of labels. A structured array can be used (i.e label=np.zeros(n_sources, dtype=[(‘brodmann’, int), (‘aal’, object)])).

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

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

transform : VisPy.visuals.transforms | None

VisPy transformation to set to the parent node.

parent : VisPy.parent | None

ROI object parent.

verbose : string

Verbosity level.

kw : dict | {}

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:
step : float | 1.

Rotation step.

interval : float | ‘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.

iterations : int | -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:
select : list

List of indices of ROIs. Must be a list or tuple of integers.
Returns:
xyz : array_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_path : str | 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:
xyz : array_like

Array of source’s coordinates of shape (n_sources, 3)

source_name : array_like/list | None

List of source’s names.

replace_bad : bool | True

Replace bad values (True) or not (False).

bad_patterns : list | [None, -1, ‘undefined’, ‘None’]

Bad patterns to replace if replace_bad is True.

replace_with : string | ‘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:
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.

mpl : bool | False

Use Matplotlib to display the object. This result in a non interactive figure.

kwargs : dict | {}

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

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

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.

to_overlay : int | 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:
name : string

Name of the gif file (e.g ‘myfile.gif’)

n_pic : int | 10

Number of pictures to use to render the gif.

bgcolor : string, tuple, list | None

Background color.
remove()[source]

Remove the volume template.

render()[source]

Render the canvas.

Returns:
img : array_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:
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.
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:
select : int, float, list | .5

Threshold for extracting vertices from isosuface method.

unique_color : bool | False

Use a random unique color for each ROI.

roi_to_color : dict | None

Color of specific ROI using a dictionary i.e {1: ‘red’, 2: ‘orange’}.

smooth : int | 3

Smoothing level. Must be an odd integer (smooth % 2 = 1).

translucent : bool | 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:
name : string

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.

vol : array_like | None

ROI volume. Sould be an array with three dimensions.

labels : array_like | None

Array of labels. A structured array can be used (i.e labels=np.zeros(n_sources, dtype=[(‘brodmann’, int), (‘aal’, object)])).

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

hdr : array_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:
patterns : list

List of string patterns to search.

df : pd.DataFrame | None

The DataFrame to use. If None, the DataFrame of the ROI are going to be used by default.

union : bool | True

Take either the union of matching patterns (True) or the intersection (False).

columns : list | None

List of specific column names to search in. If None, this method search through the entire DataFrame.

exact : bool | 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_sensitive : bool | False

Specify if the search have to be case sensitive.
Returns:
idx : list

List of index that match with the list of patterns.