# labs.viz_tools.activation_maps

## Module: `labs.viz_tools.activation_maps`

Functions to do automatic visualization of activation-like maps.

For 2D-only visualization, only matplotlib is required. For 3D visualization, Mayavi, version 3.0 or greater, is required.

For a demo, see the ‘demo_plot_map’ function.

## Functions

nipy.labs.viz_tools.activation_maps.demo_plot_map(do3d=False, **kwargs)

  Demo activation map plotting.

nipy.labs.viz_tools.activation_maps.plot_anat(anat=None, anat_affine=None, cut_coords=None, slicer='ortho', figure=None, axes=None, title=None, annotate=True, draw_cross=True, black_bg=False, dim=False, cmap=<matplotlib.colors.LinearSegmentedColormap object>, **imshow_kwargs)

  Plot three cuts of an anatomical image (Frontal, Axial, and Lateral)

  Parameters:
    anat 3D ndarray, optional

      The anatomical image to be used as a background. If None is given, nipy tries to find a T1 template.

    anat_affine 4x4 ndarray, optional

      The affine matrix going from the anatomical image voxel space to MNI space. This parameter is not used when the default anatomical is used, but it is compulsory when using an explicit anatomical image.

    figure integer or matplotlib figure, optional

      Matplotlib figure used or its number. If None is given, a new figure is created.

    cut_coords: None, or a tuple of floats

      The MNI coordinates of the point where the cut is performed, in MNI coordinates and order. If slicer is ‘ortho’, this should be a 3-tuple: (x, y, z) For slicer == ‘x’, ‘y’, or ‘z’, then these are the coordinates of each cut in the corresponding direction. If None is given, the cuts is calculated automatically.

    slicer: {‘ortho’, ‘x’, ‘y’, ‘z’}

      Choose the direction of the cuts. With ‘ortho’ three cuts are performed in orthogonal directions

    figure integer or matplotlib figure, optional

      Matplotlib figure used or its number. If None is given, a new figure is created.

    axes matplotlib axes or 4 tuple of float: (xmin, ymin, width, height), optional

      The axes, or the coordinates, in matplotlib figure space, of the axes used to display the plot. If None, the complete figure is used.

    title string, optional

      The title displayed on the figure.

    annotate: boolean, optional

      If annotate is True, positions and left/right annotation are added to the plot.

    draw_cross: boolean, optional

      If draw_cross is True, a cross is drawn on the plot to indicate the cut plosition.

    black_bg: boolean, optional

      If True, the background of the image is set to be black. If you wish to save figures with a black background, you will need to pass “facecolor=’k’, edgecolor=’k’” to pyplot’s savefig.

    dim: float, optional

      If set, dim the anatomical image, such that vmax = vmean + (1+dim)*ptp if black_bg is set to True, or vmin = vmean - (1+dim)*ptp otherwise, where ptp = .5*(vmax - vmin)

    cmap: matplotlib colormap, optional

      The colormap for the anat

    imshow_kwargs: extra keyword arguments, optional

      Extra keyword arguments passed to pyplot.imshow

  Notes

  Arrays should be passed in numpy convention: (x, y, z) ordered.

nipy.labs.viz_tools.activation_maps.plot_map(map, affine, cut_coords=None, anat=None, anat_affine=None, slicer='ortho', figure=None, axes=None, title=None, threshold=None, annotate=True, draw_cross=True, do3d=False, threshold_3d=None, view_3d=(38.5, 70.5, 300, (-2.7, -12, 9.1)), black_bg=False, **imshow_kwargs)

  Plot three cuts of a given activation map (Frontal, Axial, and Lateral)

  Parameters:
    map 3D ndarray

      The activation map, as a 3D image.

    affine 4x4 ndarray

      The affine matrix going from image voxel space to MNI space.

    cut_coords: None, int, or a tuple of floats

      The MNI coordinates of the point where the cut is performed, in MNI coordinates and order. If slicer is ‘ortho’, this should be a 3-tuple: (x, y, z) For slicer == ‘x’, ‘y’, or ‘z’, then these are the coordinates of each cut in the corresponding direction. If None or an int is given, then a maximally separated sequence ( with exactly cut_coords elements if cut_coords is not None) of cut coordinates along the slicer axis is computed automatically

    anat 3D ndarray or False, optional

      The anatomical image to be used as a background. If None, the MNI152 T1 1mm template is used. If False, no anat is displayed.

    anat_affine 4x4 ndarray, optional

      The affine matrix going from the anatomical image voxel space to MNI space. This parameter is not used when the default anatomical is used, but it is compulsory when using an explicit anatomical image.

    slicer: {‘ortho’, ‘x’, ‘y’, ‘z’}

      Choose the direction of the cuts. With ‘ortho’ three cuts are performed in orthogonal directions

    figure integer or matplotlib figure, optional

      Matplotlib figure used or its number. If None is given, a new figure is created.

    axes matplotlib axes or 4 tuple of float: (xmin, ymin, width, height), optional

      The axes, or the coordinates, in matplotlib figure space, of the axes used to display the plot. If None, the complete figure is used.

    title string, optional

      The title displayed on the figure.

    threshold a number, None, or ‘auto’

      If None is given, the maps are not thresholded. If a number is given, it is used to threshold the maps: values below the threshold are plotted as transparent. If auto is given, the threshold is determined magically by analysis of the map.

    annotate: boolean, optional

      If annotate is True, positions and left/right annotation are added to the plot.

    draw_cross: boolean, optional

      If draw_cross is True, a cross is drawn on the plot to indicate the cut plosition.

    do3d: {True, False or ‘interactive’}, optional

      If True, Mayavi is used to plot a 3D view of the map in addition to the slicing. If ‘interactive’, the 3D visualization is displayed in an additional interactive window.

    threshold_3d:

      The threshold to use for the 3D view (if any). Defaults to the same threshold as that used for the 2D view.

    view_3d: tuple,

      The view used to take the screenshot: azimuth, elevation, distance and focalpoint, see the docstring of mlab.view.

    black_bg: boolean, optional

      If True, the background of the image is set to be black. If you wish to save figures with a black background, you will need to pass “facecolor=’k’, edgecolor=’k’” to pyplot’s savefig.

    imshow_kwargs: extra keyword arguments, optional

      Extra keyword arguments passed to pyplot.imshow

  Notes

  Arrays should be passed in numpy convention: (x, y, z) ordered.

  Use masked arrays to create transparency:

  > import numpy as np map = np.ma.masked_less(map, 0.5) plot_map(map, affine)