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.

8.11.15. 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=<matplotlib.colors.LinearSegmentedColormap object>)[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-output. 4D image.

mask_imgNiimg-like object or None, optional

Limit plotted voxels to those inside the provided mask (default is None). 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 http://nilearn.github.io/manipulating_images/input_output.html.

mask_labelsdict, optional

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 None, optional

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

Note

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

New in version 0.9.1.dev: Prior to this, t_r would be inferred from img without user input.

detrendbool, optional

Detrend and z-score the data prior to plotting. Default=True.

output_filestr, 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 tupleof 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.

vminfloat, optional

Lower bound of the colormap. If None, the min of the image is used. Passed to matplotlib.pyplot.imshow.

vmaxfloat, optional

Upper bound of the colormap. If None, the max of the image is used. Passed to matplotlib.pyplot.imshow.

titlestr, or None, optional

The title displayed on the figure. Default=None.

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.

Note

This argument is used only if an atlas is used.

Default=`plt.cm.gist_ncar`.

Returns
figurematplotlib.figure.Figure

Figure object with carpet plot.

Notes

This figure was originally developed in 1.

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

References

1

Jonathan D. Power. A simple but useful way to assess fmri scan qualities. NeuroImage, 154:150–158, 2017. Cleaning up the fMRI time series: Mitigating noise with advanced acquisition and correction strategies. URL: https://www.sciencedirect.com/science/article/pii/S1053811916303871, doi:https://doi.org/10.1016/j.neuroimage.2016.08.009.

8.11.15.1. Examples using nilearn.plotting.plot_carpet