Module and Function reference

Reslice module reference

SUIT toolbox reslice module

Basic functionality for resample image into atlas

reslice.reslice_image(source_image, deformation, mask=None, interp=1, voxelsize=None, imagedim=None, affine=None)
[summary]
source_image: (NIFTI Image, str, or iterable of NIFTI)

Images to reslice

deformation: (NIFTI, str):

Nonlinear deformation file (y_xxx.nii)

mask (NIFTI, str):

Optional masking image (defaults to None)

interp (int):

0: nearest neighbor, 1:trilinear

voxelsize (tuple):

Desired voxel size - defaults to deformation image [THROW A WARNING IF BOTH VOXEL SIZE AND AFFINE MAT ARE SPECIFIC]

imagedim (tuple):

desired image dimensions: Defaults to deformation image

affine (ndaray)”

affine transformation matrix of target image

Returns:

image (NIFTI image or list of NIFTI Images)

reslice.reslice_img(img, deformation, mask, interp, imagedim, affine)

Resample image

Parameters:

  • img – (NIFTI Image) Images to reslice

  • deformation – (NIFTI): Nonlinear deformation file (y_xxx.nii)

  • mask (NIFTI) – Optional masking image (defaults to None)

  • interp (int) – 0: nearest neighbor, 1:trilinear

  • imagedim (tuple) – desired image size

  • affine (ndarray) – Affine transformation matrix of desired target image

Returns:

image (NIFTI image or list of NIFTI Images)

Flatmap module reference

SUIT toolbox flatmap module

Basic functionality for mapping and plotting functional Data for the cerebellum

@authors jdiedrichsen, maedbhking, eliu72, dzhi1993, switt

flatmap.map_to_rgb(data, scale=None, threshold=[0, 0, 0])

Maps data to RGB

Parameters:

  • data (_type_) – List of vectors or 3xP ndarray. use [data,None,None] to skip color channels

  • scale (list) – maximum brightness

  • threshold (list) – Threshold [0,0,0].

Returns:

rgba (ndarray) – Nx4 array of RGBA values

flatmap.plot(data, surf=None, underlay='SUIT.shape.gii', undermap='Greys', underscale=[-0.5, 0.5], overlay_type='func', threshold=None, cmap=None, cscale=None, label_names=None, borders='borders.txt', bordercolor='k', bordersize=2, alpha=1.0, render='matplotlib', hover='auto', new_figure=True, colorbar=False, cbar_tick_format='%.2g', backgroundcolor='w', frame=[-110, 110, -110, 110])

Visualize cerebellar activity on a flatmap

Parameters:

  • data (np.array, giftiImage, or name of gifti file) – Data to be plotted, should be a 28935x1 vector

  • surf (str or giftiImage) – surface file for flatmap (default: FLAT.surf.gii in SUIT pkg)

  • underlay (str, giftiImage, or np-array) – Full filepath of the file determining underlay coloring (default: SUIT.shape.gii in SUIT pkg)

  • undermap (str) – Matplotlib colormap used for underlay (default: gray)

  • underscale (array-like) – Colorscale [min, max] for the underlay (default: [-1, 0.5])

  • overlay_type (str) – ‘func’: functional activation (default) ‘label’: categories ‘rgb’: RGB(A) values (0-1) directly specified. Alpha is optional

  • threshold (scalar or 2-element array) – Threshold for functional overlay. If one value is given, only values above are shown If two values are given, values below lower threshold or above upper threshold are shown

  • cscale (ndarray or list) – Colorscale [min, max] for the overlay (default: [data.min, data.max])

  • cmap (str) – A Matplotlib colormap or an equivalent Nx3 or Nx4 floating point array (N rgb or rgba values). (defaults to ‘jet’ if none given)

  • label_names (list) – labelnames (default is None - extracts from .label.gii )

  • borders (str) – Full filepath of the borders txt file or workbench border file (default: borders.txt in SUIT pkg)

  • bordercolor (char or matplotlib.color) – Color of border - defaults to ‘k’

  • bordersize (int) – Size of the border points - defaults to 2

  • alpha (float) – Opacity of the overlay (default: 1)

  • render (str) – Renderer for graphic display ‘matplot’ / ‘plotly’. Dafault is matplotlib

  • hover (str) – When renderer is plotly, it determines what is displayed in the hover label: ‘auto’, ‘value’, or None

  • new_figure (bool) – If False, plot renders into matplotlib’s current axis. If True, it creates a new figure (default=True)

  • colorbar (bool) – By default, colorbar is not plotted into matplotlib’s current axis (or new figure if new_figure is set to True)

  • cbar_tick_format – str, optional Controls how to format the tick labels of the colorbar, and for the hover label. Ex: use “%i” to display as integers. Default=’%.2g’ for scientific notation.

  • backgroundcolor (str or matplotlib.color) – Axis background color (default: ‘w’)

  • frame (ndarray) – [L,R,T,B] of the area of flatmap that is rendered Defaults to entire flatmap

Returns:

  • ax (matplotlib.axis) – If render is matplotlib, the function returns the axis

  • fig (plotly.go.Figure) – If render is plotly, it returns Figure object

flatmap.save_colorbar(gifti, outpath)

plots colorbar for gifti object (*.label.gii) and saves it to outpath :param gifti: Nibabel Gifti image :type gifti: gifti image :param outpath: outpath for colorbar image :type outpath: str

flatmap.vol_to_surf(volumes, space='SUIT', ignore_zeros=False, depths=[0, 0.2, 0.4, 0.6, 0.8, 1.0], stats='nanmean', outer_surf_gifti=None, inner_surf_gifti=None)

Maps volume data onto a surface, defined by inner and outer surface.

Function enables mapping of volume-based data onto the vertices of a surface. For each vertex, the function samples the volume along the line connecting the two surfaces. The points along the line are specified in the variable ‘depths’. default is to sample at 5 locations between white an gray matter surface. Set ‘depths’ to 0 to sample only along the white matter surface, and to 0.5 to sample along the mid-gray surface. The averaging across the sampled points for each vertex is dictated by the variable ‘stats’. For functional activation, use ‘mean’ or ‘nanmean’. For discrete label data, use ‘mode’.

Parameters:

  • volumes (list or nib obj) – List of filenames/nib objs, or nib obj to be mapped

  • space (string) – Normalization space: ‘SUIT’ (default), ‘FSL’, ‘SPM’

  • ignore_zeros (bool) – Should zeros be ignored in mapping? default: False

  • depths (array-like) – Depths of points along line at which to map (0=white/gray, 1=pial). DEFAULT: [0.0,0.2,0.4,0.6,0.8,1.0]

  • stats (lambda function) – function that calculates the Statistics to be evaluated. ‘nanmean’: default and used for activation data ‘mode’: used when discrete labels are sampled. The most frequent label is assigned.

  • outer_surf_gifti (string or nibabel.GiftiImage) – optional pial surface, filename or loaded gifti object, overwrites space

  • inner_surf_gifti (string or nibabel.GiftiImage) – White surface, filename or loaded gifti object, overwrites space

Returns:

mapped_data (numpy.array) – A Data array for the mapped data

Datasets module reference

Downloading Cerebellum neuroImaging datasets: atlas datasets

@author: maedbhking

A lot of the functionality was based on nilearn.datasets.atlas https://github.com/nilearn/nilearn/blob/main/nilearn/datasets/atlas.py`

atlas.fetch_buckner_2011(data_dir=None, base_url=None, resume=True, verbose=1)

Download and return file names for the Buckner et al. (2011) atlas The provided images are in SUIT and MNI spaces

Parameters:

  • data_dir (pathlib.Path or str, optional) – Path where data should be downloaded. By default, files are downloaded in home directory.

  • base_url (string, optional) – base_url of files to download (None results in default base_url).

  • resume (bool, optional) – Whether to resume download of a partly-downloaded file. Default=True.

  • verbose (int, optional) – Verbosity level (0 means no message). Default=1.

Returns:

data (data dict) –

Dictionary, contains keys:

  • data_dir: Absolute path of downloaded folder

  • files: list of string. Absolute paths of downloaded files on disk.

  • description: A short description of data and some references.

Notes

For more details, see https://github.com/DiedrichsenLab/cerebellar_atlases/tree/master/Buckner_2011

atlas.fetch_diedrichsen_2009(data_dir=None, base_url=None, resume=True, verbose=1)

Download and return file names for the Diedrichsen et al. (2009) atlas

The provided images are in SUIT and MNI spaces

Parameters:

  • data_dir (pathlib.Path or str, optional) – Path where data should be downloaded. By default, files are downloaded in home directory.

  • base_url (string, optional) – base_url of files to download (None results in default base_url).

  • resume (bool, optional) – Whether to resume download of a partly-downloaded file. Default=True.

  • verbose (int, optional) – Verbosity level (0 means no message). Default=1.

Returns:

data (data dict) –

Dictionary, contains keys:

  • data_dir: Absolute path of downloaded folder

  • files: list of string. Absolute paths of downloaded files on disk.

  • description: A short description of data and some references.

Notes

For more details, see https://github.com/DiedrichsenLab/cerebellar_atlases/tree/master/Diedrichsen_2009

atlas.fetch_ji_2019(data_dir=None, base_url=None, resume=True, verbose=1)

Download and return file names for the Ji et al. (2019) atlas The provided images are in SUIT and MNI spaces

Parameters:

  • data_dir (pathlib.Path or str, optional) – Path where data should be downloaded. By default, files are downloaded in home directory.

  • base_url (string, optional) – base_url of files to download (None results in default base_url).

  • resume (bool, optional) – Whether to resume download of a partly-downloaded file. Default=True.

  • verbose (int, optional) – Verbosity level (0 means no message). Default=1.

Returns:

data (data dict) –

Dictionary, contains keys:

  • data_dir: Absolute path of downloaded folder

  • files: list of string. Absolute paths of downloaded files on disk.

  • description: A short description of data and some references.

Notes

For more details, see https://github.com/DiedrichsenLab/cerebellar_atlases/tree/master/Ji_2019

atlas.fetch_king_2019(data='con', data_dir=None, base_url=None, resume=True, verbose=1)

Download and return file names for the King et al. (2019) atlas or contrast images set by data. The provided images are in SUIT and MNI spaces

Parameters:

  • data (str, optional) – Options are ‘atl’, ‘con’ Default=’atl’

  • data_dir (pathlib.Path or str, optional) – Path where data should be downloaded. By default, files are downloaded in home directory.

  • base_url (string, optional) – base_url of files to download (None results in default base_url).

  • resume (bool, optional) – Whether to resume download of a partly-downloaded file. Default=True.

  • verbose (int, optional) – Verbosity level (0 means no message). Default=1.

Returns:

data (data dict) –

Dictionary, contains keys:

  • data_dir: Absolute path of downloaded folder

  • files: list of string. Absolute paths of downloaded files on disk.

  • description: A short description of data and some references.

Notes

For more details, see https://github.com/DiedrichsenLab/cerebellar_atlases/tree/master/King_2019

atlas.fetch_xue_2021(data_dir=None, base_url=None, resume=True, verbose=1)

“Download and return file names for the Xue et al. (2021) atlas

The provided images are in SUIT and MNI spaces

Parameters:

  • data_dir (pathlib.Path or str, optional) – Path where data should be downloaded. By default, files are downloaded in home directory.

  • base_url (string, optional) – base_url of files to download (None results in default base_url).

  • resume (bool, optional) – Whether to resume download of a partly-downloaded file. Default=True.

  • verbose (int, optional) – Verbosity level (0 means no message). Default=1.

Returns:

data (data dict) –

Dictionary, contains keys:

  • data_dir: Absolute path of downloaded folder

  • files: list of string. Absolute paths of downloaded files on disk.

  • description: A short description of data and some references.

Notes

For more details, see

https://github.com/DiedrichsenLab/cerebellar_atlases/tree/master/Xue_2021