surfplot.plotting.Plot

class surfplot.plotting.Plot(surf_lh=None, surf_rh=None, layout='grid', views=None, mirror_views=False, flip=False, size=(500, 400), zoom=1.5, background=(1, 1, 1), label_text=None, brightness=0.5)[source]

Plot brain surfaces with data layers

Parameters

  • surf_lh (str or os.PathLike or BSPolyData, optional) – Left and right hemisphere cortical surfaces, either as a file path to a valid surface file (e.g., .gii. .surf) or a pre-loaded surface from brainspace.mesh.mesh_io.read_surface(). At least one hemisphere must be provided. Default: None

  • surf_rh (str or os.PathLike or BSPolyData, optional) – Left and right hemisphere cortical surfaces, either as a file path to a valid surface file (e.g., .gii. .surf) or a pre-loaded surface from brainspace.mesh.mesh_io.read_surface(). At least one hemisphere must be provided. Default: None

  • layout ({'grid', 'column', 'row'}, optional) – Layout in which to plot brain surfaces. ‘row’ plots brains as a single row ordered from left-to-right hemispheres (if applicable), ‘column’ plots brains as a single column descending from left-to-right hemispheres (if applicable). ‘grid’ plots surfaces as a views-by-hemisphere (left-right) array; if only one hemipshere is provided, then ‘grid’ is equivalent to ‘row’. By default ‘grid’.

  • views ({'lateral', 'medial', 'dorsal', 'ventral', 'anterior',) – ‘posterior’}, str or list[str], optional Views to plot for each provided hemisphere. Views are plotted in in the order they are provided. If None, then lateral and medial views are plotted. Default: None

  • mirror_views (bool, optional) – Flip the order of the right hemisphere views for ‘row’ or ‘column’ layouts, such that they mirror the left hemisphere views. Ignored if surf_rh is None and layout is ‘grid’.

  • flip (bool, optional) – Flip the display order of left and right hemispheres in grid or row layouts, if applicable. Useful when showing only ‘anterior` or ‘inferior’ views. Default: False

  • size (tuple of int, optional) – The size of the space to plot surfaces, defined by (width, height). Note that this differs from figsize in Plot.build(), which determines the overall figure size for the matplotlib figure. Default: (500, 400)

  • zoom (int, optional) – Level of zoom to apply. Default: 1.5

  • background (tuple, optional) – Background color, default: (1, 1, 1)

  • label_text (dict[str, array-like], optional) – Brainspace label text for column/row. Possible keys are {‘left’, ‘right’, ‘top’, ‘bottom’}, which indicate the location. See brainspace.plotting.surface_plotting.plot_surf for more details Default: None.

  • brightness (float, optional) – Brightness of plain gray surface. 0 = black, 1 = white. Default: .5

Raises

ValueError – Neither surf_lh or surf_rh are provided

_add_colorbars(location='bottom', label_direction=None, n_ticks=3, decimals=2, fontsize=10, draw_border=True, outer_labels_only=False, aspect=20, pad=0.08, shrink=0.3, fraction=0.05)[source]

Draw colorbar(s) for applicable layer(s)

Parameters

  • location ({'left', 'right', 'top', 'bottom'}, optional) – The location, relative to the surface plot. If location is ‘top’ or ‘bottom’, then colorbars are horizontal. If location is’left’ or ‘right’, then colorbars are vertical.

  • label_direction (int or None, optional) – Angle to draw label for colorbars, if provided. Horizontal = 0, vertical = 90. If None and location is ‘top’ or ‘bottom’, labels are drawn horizontally. If None and location is ‘left’ or ‘right’, labels are drawn vertically. Default: None

  • n_ticks (int, optional) – Number of ticks to include on colorbar, default: 3 (minimum, maximum, and middle values)

  • decimals (int, optional) – Number of decimals to show for colorbal tick values. Set 0 to show integers. Default: 2

  • fontsize (int, optional) – Font size for colorbar labels and tick labels. Default: 10

  • draw_border (bool, optional) – Draw ticks and black border around colorbar. Default: True

  • outer_labels_only (bool, optional) – Show tick labels for only the outermost colorbar. This cleans up tick labels when all colorbars are the same scale. Default: False

  • pad (float, optional) – Space that separates each colorbar. Default: .08

  • aspect (float, optional) – Ratio of long to short dimensions. Default: 20

  • shrink (float, optional) – Fraction by which to multiply the size of the colorbar. Default: .3

  • fraction (float, optional) – Fraction of original axes to use for colorbar. Default: .05

add_layer(data, cmap='viridis', alpha=1, color_range=None, as_outline=False, zero_transparent=True, cbar=True, cbar_label=None)[source]

Add plotting layer to surface(s)

Parameters

  • data (str or os.PathLike, numpy.ndarray, dict, nibabel.gifti.gifti.GiftiImage, or nibabel.cifti2.cifti2.Cifti2Image) – Vertex data to plot on surfaces. Must be a valid file path of a GIFTI or CIFTI image, a loaded GIFTI or CIFTI image, a numpy array with length equal to the total number of vertices in the provided surfaces (e.g., 32k in left surface + 32k in right surface = 64k total), or a dictionary with ‘left’ and/or ‘right keys. If a numpy array, vertices are assumed to be in order of left-to-right, if applicable. If a dictionary, then values can be any of the possible types mentioned above, assuming that the vertices match the vertices of their respective surface.

  • cmap (matplotlib colormap name or object, optional) – Colormap to use for data, default: ‘viridis’

  • alpha (float, optional) – Colormap opacity (0 to 1). Default: 1

  • color_range (tuple[float, float], optional) – Minimum and maximum value for color map. If None, then the minimum and maximum values in data are used. Default: None

  • as_outline (bool, optional) – Plot only an outline of contiguous vertices with the same value. Useful if plotting regions of interests, atlases, or discretized data. Not recommended for continous data. Default: False

  • zero_transparent (bool, optional) – Set vertices with value of 0 to NaN, which will turn them transparent on the surface. Useful when value of 0 has no importance (e.g., thresholded data, an atlas). Default: True

  • cbar (bool, optional) – Show colorbar for layer, default: True

  • cbar_label (str, optional) – Label to include with colorbar if shown. Note that this is not required for the colorbar to be drawn. Default: None

Raises

  • ValueError – data keys must be ‘left’ and/or ‘right’

  • TypeError – data is neither an instance of str or os.PathLike, numpy.ndarray, dict, nibabel.gifti.gifti.GiftiImage, or nibabel.cifti2.cifti2.Cifti2Image

build(figsize=None, colorbar=True, cbar_kws=None, scale=(2, 2))[source]

Build matplotlib figure of surface plot

Parameters

  • figsize (tuple, optional) – Overall figure size, specified by (width, height). Default: None, which will determine the figure size based on the size parameter.

  • colorbar (bool, optional) – Draw colorbars for each applicable layer, default: True

  • cbar_kws (dict, optional) – Keyword arguments for _add_colorbar(). Default: None, which will plot the default colorbar parameters.

  • scale (tuple, optional) – Amount to scale the surface plot. Default: (2, 2), which is a good baseline for higher resolution plotting.

Returns

matplotlib.pyplot.figure – Surface plot figure

render(offscreen=True)[source]

Generate surface plot with all provided layers

Parameters

offscreen (bool, optional) – Render offscreen. Default: True

Returns

brainspace.plotting.base.Plotter – Surface plot

show(embed_nb=False, interactive=True, transparent_bg=True, scale=(1, 1))[source]

View Brainspace vtk surface rendering

Notes

This only shows the plot created by brainspace.plotting.surface_plotting.plot_surf, and will not include colorbars created by plot() or any other matplotlib components.

Parameters

  • embed_nb (bool, optional) – Whether to embed figure in notebook. Only used if running in a notebook. Default: False

  • interactive (bool, optional) – Whether to enable interaction, default: True

  • scale (tuple, optional) – Amount to scale the surface plot, default: (1, 1)

Returns

Ipython Image or vtk panel – Brainspace surface plot rendering