plotting#

plot#

neurotools.plotting.plot(data, space=None, hemi=None, verbose=0, returns=False, **kwargs)#

The most automated magic plotting function avaliable, used to plot a wide range of neuroimaging data (volumes / surfs).

Parameters

  • data (str, array, dict, ect...) –

    The data in which to plot, either statistical map or parcellaction, as broadly either a single surface, collage of surfaces, a single volume, or collage with surfaces and volume, or as pandas series of ROIs and values.

    Data can be passed in many ways:

    • As array-like input representing a single surface hemisphere, concatenated hemispheres, concatenated hemispheres + flattened sub-cortical values, or just flattened volumetric values.

    • As a str, representing the file location with saved values for any of the above array options. A large number of different file formats are accepted.

    • As a dictionary. If passed as a dictionary, this allows the user most control over how data is specified. Dictionary keys must be one or more of ‘lh’, ‘rh’ and ‘vol’, where values can be either array-like, file locations or nibabel objects. Note that if you are trying to plot data in native subject space, it must be passed in this dictionary style, along with, if a surface, a proper value for surf_mesh.

    • As a list or array-like of length 3, indicating internally that the passed values represent in the first index the file location or array values of a left hemisphere surface, and in the second index, the right hemisphere surface.

    • As a list or array-like of length 3, indicating internally that the first two passed index are left and right hemisphere surface data, and the last is subcortical / volumetric data, all to be plotted together in a collage.

    • As a Nifti1Image to be plotted volumetrically.

    • experimental support for pandas Series of ROI names.

  • space (None or str, optional) –

    This argument defines the “space” in which surface data is plotted. If left as default (None), the space in which the data to plot is in will be automatically inferred, otherwise this parameter can be manually set, overriding the automatically detected choice. Current supported options are:

    • ’fsaverage’ : freesurfer average standard space.

    • ’fsaverage5’ : freesurfer5 downsampled average standard space.

    • ’fsaverage4’ : freesurfer3 downsampled average standard space.

    • ’fsaverage3’ : freesurfer3 downsampled average standard space.

    • ’41k_fsaverage’ : Matched to CIVET 41k vertex freesurfer space.

    • ’4k_fs_LR’ : HCP standard 4k vertex space.

    • ’8k_fs_LR’ : HCP standard 8k vertex space.

    • ’32k_fs_LR’ : HCP standard 32k vertex space.

    • ’59k_fs_LR’ : HCP standard 59k vertex space.

    • ’164k_fs_LR’ : HCP standard 164k vertex space. Note, while this space has the same number of vertex as fsaverage space, it is not the same.

    • ’civet’ : Standard space with 41k vertex used by CIVET.

    • ’native’ : This is set if the passed number of values don’t correspond to any of the saved defaults, and refers to that the space to plot is in some non-standard space.

    default = None

  • hemi (None, 'lh' or 'rh', optional) –

    This parameter is only used when plotting any surface data. Further, this parameter is only relevant the surface data being plotted represents a single hemispheres data.

    If left as default, None, then this option will be automatically set to plot left hemisphere data.

    default = None

  • verbose (int, optional) –

    Plotting includes a many, many of parameters, which is why this function is helpful as it automates a large number of choices. That said, it can helpful to be aware of what choices are being made, which is what this verbose parameter controls. The following levels are made avaliable:

    • <0 : Nothing, not even warnings are shown.

    • 0 : Only warnings are shown.

    • 1 : Information on which steps are automatically decided are shown.

    • >1 : Automatic choices are shown as well as additional helper text.

  • returns (bool, optional) –

    If the figure, axis / grid and smfs should be returned from the base function calls or not.

    default = False

  • kwargs (keyword arguments) –

    There are number of different plotting specific arguments that can optionally be modified. The default values for these arguments may change also depending on different auto-detected settings, i.e., if plotting a single surface vs. surface collage, or if plotting a volumetric image. The remaining parameters below are these kwargs.

    • surf_mesh : str or array

      A str indicator specifying a valid surface mesh, with respect to the current space, or a two dimensional array with information about the coordinates and vertex-faces in which to plot the data on. The default for freesurfer spaces is ‘inflated’ and for fs_LR spaces is ‘very_inflated’. If you wish to plot surface data in native subject space, then this argument must be supplied with a loaded 2D array / valid mesh, and data must be passed in dictionary style.

      This parameter is only relevant when plotting surfaces.

    • bg_map : str or 2D array

      This argument specifies a background map to be used when plotting. This should be passed as either a str indicator specifying a valid file within the current surface space, or as a valid array of values, again, with respect to the current space. This map is plotted in greyscale underneath the data points, often used for realistic shading. The default for when plotting is ‘sulc’.

    • cmap : str or matplotlib.colors.Colormap

      This should be pass as an instance of matplotlib.colors.Colormap or str representing the name of a matplotlib colormap. This will be the color map in which the values are plotted according to. When plotting surface parcellations, the default cmaps are ‘prism’ if plotting rois, ‘Reds’ if plotting not symmetric statistical maps, and ‘cold_white_hot’ if plotting symmetric statistical maps (e.g., values above and below 0). In case of not sym plotting, and plotting negative numbers, will switch from ‘Reds’ to ‘Blues_r’.

    • vol_plot_type : {‘glass’, ‘stat’, ‘roi’}

      This parameter control the type of volumetric plot in which to generate, with valid values as one of ‘glass’, ‘stat’ and ‘roi’. By default, if detected to be plotting a parcellation, the value ‘roi’ is used. Otherwise, the default volumetric plotting type is ‘glass’. The corresponding back-end nilearn functions used are:

      This parameter is only used when plotting volumetric data.

    • bg_on_data : bool or float If True, and a bg_map is specified, the data to plot is multiplied by the background image, so that e.g. sulcal depth is visible beneath the surf_data.

      If passed as a float value, then that will trigger multiplying the data to plot by the background image times the passed bg_on_data value. So for example passing True is equivalent to passing 1 and passing False is the same as passing 0.

      This allows for fine tuning how much the background image is melded with the data shown. The default value is .25.

      This parameter is only used when plotting surfaces.

    • view : str

      If plotting a single surface hemisphere, this parameter must be one of:

      {‘lateral’, ‘medial’, ‘dorsal’, ‘ventral’, ‘anterior’, ‘posterior’}

      Where ‘lateral’ is the default view if none is set.

      If instead plotting a collage of surface views, then valid view parameters are one of:

      {‘standard’, ‘front back’, ‘front’, ‘back’}

      which correspond to different preset collections of surface views. The default if not specified in this case is ‘standard’.

      Note: If plotting a collage of surface and volumetric views, it is reccomended to keep the default collage ‘standard’ view, as the other views have not yet been properly formatted yet.

    • colorbar : bool

      This option dictates if a colorbar should be added along with the requested plot, regardless of type. By default a colorbar will be added (True) unless a parcellation is being plotted, in which the default is to not add a colorbar (False).

      There are a number of extra more detailed colorbar style kwargs, used in certain cases, with certain plots to customize the look and size of the colorbar. See below.

    • rois : bool

      If passed, can force plot either is rois case or stat map case. Ussually the auto settings will be fine, but this exists if need to override without overriding all of the other little settings. Default is just automatically detected based on percent of unique values being plotted.

    • avg_method : ‘mean’, ‘median’, ‘min’, ‘max’ or custom function

      This option defines how to average vertex values to derive face values, and is only used when plotting surfaces.

      • ’mean’: results in smooth boundaries

      • ’median’: results in sharp boundaries

      • ’min’ or ‘max’: for sparse matrices

      • custom function: You can also pass a custom function

      If plotting roi’s the default will be ‘median’. Otherwise, the default will be set based on the ratio between the number of unique values to data points. So if more than 5% of data points are unique, ‘mean’ will be used, otherwise ‘median’ will be used. This is to try and accurately detect when parcellations are being plotted.

    • alpha : float or ‘auto’

      This parameter is only used when plotting surface data. It refers to the alpha level of the mesh. By default, this is left as ‘auto’, which will default to .5 if no bg_map and 1 if a bg_map is passed. This parameter is just multiplied by the face colors before plotting.

      Note: this keyword is used for plotting surfaces, though alpha is also used as a parameter for plotting the volumetric glass brain. To access this parameter for the volumetric function, see the vol_alpha parameter.

    • vol_alpha : float between 0 and 1

      This controls the alpha transparency only when plotting volumetric data according to the vol_plot_type=’glass’ option. The default value is 0.7.

    • darkness : float between 0 and 1

      This parameter specified the darkness of the background image, when plotting a single or multiple surfaces. Where a value of 1 indicates that the original values are used, and .5 would mean the values are halved. If plotting in an fsaverage space the default value is 1, if plotting in an fs_LR space, the default value is .5.

    • symmetric_cbar : bool or ‘aut’

      Specifies whether the colorbar should range from -vmax to vmax or from vmin to vmax. Setting to ‘auto’ will select the latter if the range of the whole image is either positive or negative. There are some other automatic cases, but in general this parameter can just be used to override any automatic choices.

    • threshold : float, None or ‘auto’

      If None, the image is not thresholded. If a float, or other numberic value, that value will be used to threshold the image. This threshold is treated as an absolute value in the case of a symmetric_cbar. If ‘auto’ is passed, it will attempt to automatically set the threshold to a reasonable value.

      The default is typically ‘auto’, but in some cases changes, for example if plotting a parcellation the default value will be None.s

    • figsize : ‘default’ or (int, int)

      This parameter is used when axes are not passed, and a new figure is being generated. It represents the size of the underlying matplotlib figure to plot on. The default value for this function varies based on what type of plot is being made (e.g., not the same for surface collage vs. single surface).

    • wspace : float

      This parameter refers to the width spacing between items at the top level of whatever collage is being plotted. So, if plotting only a single surface or volume, this parameter will be ignored. Otherwise, for example if plotting a collage of 4 surface views, then this parameter will control the amount of horizontal space between each brain view. Instead, if plotting a combined collage of surface views and volumetric views, then the top level of the collage that this parameter controls the spacing of is the set of all surface views, all volumetric views and colorbar. In this case, to override values between for example just the surface views, you would have to use special extra keyword ‘surf_wspace’, which let’s you set both parameters if desired.

      The default values hover around 0, and vary a great deal based on the type of plot and requested view.

    • hspace : float

      This parameter refers to the height spacing between items at the top level of whatever collage is being plotted. So, if plotting only a single surface or volume, this parameter will be ignored. Otherwise, for example if plotting a collage of 4 surface views, then this parameter will control the amount of vertical space between each brain view. Instead, if plotting a combined collage of surface views and volumetric views, then the top level of the collage that this parameter controls the spacing of is the set of all surface views, all volumetric views and colorbar. In this case, to override values between for example just the surface views, you would have to use special extra keyword ‘surf_hspace’, which let’s you set both parameters if desired.

      The default values hover around 0, and vary a great deal based on the type of plot and requested view.

    • surf_wspace : float

      See ‘wspace’. This parameter is only used when there are multiple levels of collage and further control is still required for specifically the nested collage of surface plots.

    • surf_hspace : float

      See ‘hspace’. This parameter is only used when there are multiple levels of collage and further control is still required for specifically the nested collage of surface plots.

    • surf_to_vol_ratio : float or ‘default’

      In the case of plotting a collage of both surfaces and volumetric data, this parameter can optionally be set. It defines the size ratio between the grouping of surface collages and the volumetric plots. If left as ‘default’, will be set to either .9 in base plotting stat volume case and 1.1 when plotting glass brain.

Notes

The creation of carefully constructed multi-figures can be a little tricky, which is why it is helpful that so many of the default values have been set. That said, it is likely the interested user could do better than the defaults with say for example plotting a multi-figure surface + volume collage. In this instance, if they wanted to tweak the positioning of the different sub figures relative to each other, they could make use of the following parameters:

  • hspace

  • wspace

  • surf_hspace

  • surf_wspace

  • surf_to_vol_ratio

  • cbar_fig_ratio

  • figsize