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.

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.

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

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.
describe_tree() Tree description.
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, size]) Previsualize the result.
project_sources(s_obj[, project, radius, …]) Project source’s activity or repartition onto ROI.
remove() Remove the volume template.
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, exact]) Find a list of string patterns in a DataFrame.
alpha

Get the alpha value.

camera

Get the camera value.

cmap

Get the cmap value.

color

Get the color value.

faces

Get the faces value.

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

Get the mask value.

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), **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(s_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 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.
remove()[source]

Remove the volume template.

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)[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).
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 volumne 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 volumne. 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)[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 inspect every columns in the DataFrame.

exact : bool | False

Specify if the pattern to search have to be exact matching.
Returns:
idx : list

List of index that match with the list of patterns.