Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.plotting.plot_carpet

nilearn.plotting.plot_carpet(img, mask_img=None, mask_labels=None, t_r=None, detrend=True, output_file=None, figure=None, axes=None, vmin=None, vmax=None, title=None, cmap='gray', cmap_labels='gist_ncar', standardize=True)[source]

Plot an image representation of voxel intensities across time.

This figure is also known as a “grayplot” or “Power plot”.

Parameters:
imgNiimg-like object

See Input and output: neuroimaging data representation. 4D image.

mask_imgNiimg-like object or None, default=None

Limit plotted voxels to those inside the provided mask. If a 3D atlas is provided, voxels will be grouped by atlas value and a colorbar will be added to the left side of the figure with atlas labels. If not specified, a new mask will be derived from data. See Input and output: neuroimaging data representation.

mask_labelsdict or None, default=None

If mask_img corresponds to an atlas, then this dictionary maps values from the mask_img to labels. Dictionary keys are labels and values are values within the atlas.

t_rfloat or int or None, default=None

Repetition time, in seconds (sampling period). Set to None if not provided.

Note

If t_r is not provided, it will be inferred from img’s header (img.header.get_zooms()[-1]).

Added in Nilearn 0.9.1: Prior to this, t_r would be inferred from img without user input.

detrendbool, default=True

Detrend and z-score the data prior to plotting.

output_filestr or pathlib.Path or None, optional

The name of an image file to export the plot to. Valid extensions are .png, .pdf, .svg. If output_file is not None, the plot is saved to a file, and the display is closed.

figureint, or matplotlib.figure.Figure, or None, optional

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

axesmatplotlib.axes.Axes, or 4 tuple of float: (xmin, ymin, width, height), default=None

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

vminfloat or obj:int or None, optional

Lower bound of the colormap. The values below vmin are masked. If None, the min of the image is used. Passed to matplotlib.pyplot.imshow.

vmaxfloat or obj:int or None, optional

Upper bound of the colormap. The values above vmax are masked. If None, the max of the image is used. Passed to matplotlib.pyplot.imshow.

titlestr, or None, default=None

The title displayed on the figure.

cmapmatplotlib.colors.Colormap, or str, optional

The colormap to use. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. Default=`gray`.

cmap_labelsmatplotlib.colors.Colormap, or str, default=`gist_ncar`

If mask_img corresponds to an atlas, then cmap_labels can be used to define the colormap for coloring the labels placed on the side of the carpet plot.

standardizeany of: ‘zscore_sample’, ‘zscore’, ‘psc’, True, False or None; default=True

Strategy to standardize the signal:

  • 'zscore_sample': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses sample std.

  • 'zscore': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses population std by calling default numpy.std with N - ddof=0.

    Deprecated since Nilearn 0.10.1: This option will be removed in Nilearn version 0.14.0. Use zscore_sample instead.

  • 'psc': Timeseries are shifted to zero mean value and scaled to percent signal change (as compared to original mean signal).

  • True: The signal is z-scored (same as option zscore). Timeseries are shifted to zero mean and scaled to unit variance.

    Deprecated since Nilearn 0.13.0dev: In nilearn version 0.15.0, True will be replaced by 'zscore_sample'.

  • False: Do not standardize the data.

    Deprecated since Nilearn 0.13.0dev: In nilearn version 0.15.0, False will be replaced by None.

Deprecated since Nilearn 0.10.1: The default will be changed to 'zscore_sample' and 'zscore' will be removed in in version 0.14.0.

Deprecated since Nilearn 0.15.0dev: The default will be changed to 'zscore_sample' in version 0.15.0.

Note

Added to control passing value to standardize of signal.clean to call new behavior since passing “zscore” or True (default) is deprecated. This parameter will be changed to “zscore_sample” in version 0.14 and removed in version 0.15.

Returns:
figurematplotlib.figure.Figure

Figure object with carpet plot.

Notes

This figure was originally developed in Power[1].

In cases of long acquisitions (>800 volumes), the data will be downsampled to have fewer than 800 volumes before being plotted.

References

Examples using nilearn.plotting.plot_carpet

Visualizing global patterns with a carpet plot

Visualizing global patterns with a carpet plot