{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n\n# Built-in plotting methods for Raw objects\n\nThis tutorial shows how to plot continuous data as a time series, how to plot the\nspectral density of continuous data, and how to plot the sensor locations and projectors\nstored in `~mne.io.Raw` objects.\n\nAs usual we'll start by importing the modules we need, loading some\n`example data `, and cropping the `~mne.io.Raw` object to just 60\nseconds before loading it into RAM to save memory:\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "# Authors: The MNE-Python contributors.\n# License: BSD-3-Clause\n# Copyright the MNE-Python contributors." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import os\n\nimport mne\n\nsample_data_folder = mne.datasets.sample.data_path()\nsample_data_raw_file = os.path.join(\n sample_data_folder, \"MEG\", \"sample\", \"sample_audvis_raw.fif\"\n)\nraw = mne.io.read_raw_fif(sample_data_raw_file)\nraw.crop(tmax=60).load_data()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We've seen in `a previous tutorial ` how to plot data\nfrom a `~mne.io.Raw` object using :doc:`matplotlib `,\nbut `~mne.io.Raw` objects also have several built-in plotting methods:\n\n- `~mne.io.Raw.plot`\n- `~mne.io.Raw.plot_sensors`\n- `~mne.io.Raw.plot_projs_topomap`\n\nThe first one is discussed here in detail; the last two are shown briefly\nand covered in-depth in other tutorials. This tutorial also covers a few\nways of plotting the spectral content of :class:`~mne.io.Raw` data.\n\n\n## Interactive data browsing with ``Raw.plot()``\n\nThe `~mne.io.Raw.plot` method of `~mne.io.Raw` objects provides\na versatile interface for exploring continuous data. For interactive viewing\nand data quality checking, it can be called with no additional parameters:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "raw.plot()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "It may not be obvious when viewing this tutorial online, but by default, the\n`~mne.io.Raw.plot` method generates an *interactive* plot window with\nseveral useful features:\n\n- It spaces the channels equally along the y-axis.\n\n - 20 channels are shown by default; you can scroll through the channels\n using the :kbd:`\u2191` and :kbd:`\u2193` arrow keys, or by clicking on the\n colored scroll bar on the right edge of the plot.\n\n - The number of visible channels can be adjusted by the ``n_channels``\n parameter, or changed interactively using :kbd:`page up` and :kbd:`page\n down` keys.\n\n - You can toggle the display to \"butterfly\" mode (superimposing all\n channels of the same type on top of one another) by pressing :kbd:`b`,\n or start in butterfly mode by passing the ``butterfly=True`` parameter.\n\n- It shows the first 10 seconds of the `~mne.io.Raw` object.\n\n - You can shorten or lengthen the window length using :kbd:`home` and\n :kbd:`end` keys, or start with a specific window duration by passing the\n ``duration`` parameter.\n\n - You can scroll in the time domain using the :kbd:`\u2190` and\n :kbd:`\u2192` arrow keys, or start at a specific point by passing the\n ``start`` parameter. Scrolling using :kbd:`shift`:kbd:`\u2192` or\n :kbd:`shift`:kbd:`\u2190` scrolls a full window width at a time.\n\n- It allows clicking on channels to mark/unmark as \"bad\".\n\n - When the plot window is closed, the `~mne.io.Raw` object's\n ``info`` attribute will be updated, adding or removing the newly\n (un)marked channels to/from the `~mne.Info` object's ``bads``\n field (A.K.A. ``raw.info['bads']``).\n\n- It allows interactive :term:`annotation ` of the raw data.\n\n - This allows you to mark time spans that should be excluded from future\n computations due to large movement artifacts, line noise, or other\n distortions of the signal. Annotation mode is entered by pressing\n :kbd:`a`. See `annotations-tutorial` for details.\n\n- It automatically applies any :term:`projectors ` before plotting\n the data.\n\n - These can be enabled/disabled interactively by clicking the ``Proj``\n button at the lower right corner of the plot window, or disabled by\n default by passing the ``proj=False`` parameter. See\n `tut-projectors-background` for more info on projectors.\n\nThese and other keyboard shortcuts are listed in the Help window, accessed\nthrough the ``Help`` button at the lower left corner of the plot window.\nOther plot properties (such as color of the channel traces, channel order and\ngrouping, simultaneous plotting of :term:`events`, scaling, clipping,\nfiltering, etc.) can also be adjusted through parameters passed to the\n`~mne.io.Raw.plot` method; see the docstring for details.\n\n\n## Plotting spectral density of continuous data\n\nTo visualize the frequency content of continuous data, the `~mne.io.Raw`\nobject provides a :meth:`~mne.io.Raw.compute_psd` method to compute\n`spectral density`_ and the resulting :class:`~mne.time_frequency.Spectrum`\nobject has a :meth:`~mne.time_frequency.Spectrum.plot` method:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "spectrum = raw.compute_psd()\nspectrum.plot(average=True, picks=\"data\", exclude=\"bads\", amplitude=False)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If the data have been filtered, vertical dashed lines will automatically\nindicate filter boundaries. The spectrum for each channel type is drawn in\nits own subplot; here we've passed the ``average=True`` parameter to get a\nsummary for each channel type, but it is also possible to plot each channel\nindividually, with options for how the spectrum should be computed,\ncolor-coding the channels by location, and more. For example, here is a plot\nof just a few sensors (specified with the ``picks`` parameter), color-coded\nby spatial location (via the ``spatial_colors`` parameter, see the\ndocumentation of `~mne.time_frequency.Spectrum.plot` for full details):\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "midline = [\"EEG 002\", \"EEG 012\", \"EEG 030\", \"EEG 048\", \"EEG 058\", \"EEG 060\"]\nspectrum.plot(picks=midline, exclude=\"bads\", amplitude=False)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "It is also possible to plot spectral power estimates across sensors as a\nscalp topography, using the :class:`~mne.time_frequency.Spectrum`'s\n:meth:`~mne.time_frequency.Spectrum.plot_topomap` method. The default\nparameters will plot five frequency bands (\u03b4, \u03b8, \u03b1, \u03b2, \u03b3), will compute power\nbased on magnetometer channels (if present), and will plot the power\nestimates on a dB-like log-scale:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "spectrum.plot_topomap()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Alternatively, you can plot the PSD for every sensor on its own axes, with\nthe axes arranged spatially to correspond to sensor locations in space, using\n`~mne.time_frequency.Spectrum.plot_topo`:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "spectrum.plot_topo()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This plot is also interactive; hovering over each \"thumbnail\" plot will\ndisplay the channel name in the bottom left of the plot window, and clicking\non a thumbnail plot will create a second figure showing a larger version of\nthe selected channel's spectral density (as if you had called\n`~mne.time_frequency.Spectrum.plot` with that channel passed as ``picks``).\n\nBy default, `~mne.time_frequency.Spectrum.plot_topo` will show only the MEG\nchannels if MEG channels are present; if only EEG channels are found, they\nwill be plotted instead:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "spectrum.pick(\"eeg\").plot_topo()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "

Note

Prior to the addition of the :class:`~mne.time_frequency.Spectrum` class,\n the above plots were possible via::\n\n raw.plot_psd(average=True)\n raw.plot_psd_topo()\n raw.pick('eeg').plot_psd_topo()\n\n (there was no ``plot_topomap`` method for :class:`~mne.io.Raw`). The\n :meth:`~mne.io.Raw.plot_psd` and :meth:`~mne.io.Raw.plot_psd_topo` methods\n of :class:`~mne.io.Raw` objects are still provided to support legacy\n analysis scripts, but new code should instead use the\n :class:`~mne.time_frequency.Spectrum` object API.

\n\n\n## Plotting sensor locations from ``Raw`` objects\n\nThe channel locations in a `~mne.io.Raw` object can be easily plotted\nwith the `~mne.io.Raw.plot_sensors` method. A brief example is shown\nhere; notice that channels in ``raw.info['bads']`` are plotted in red. More\ndetails and additional examples are given in the tutorial\n`tut-sensor-locations`.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "raw.plot_sensors(ch_type=\"eeg\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n## Plotting projectors from ``Raw`` objects\n\nAs seen in the output of `mne.io.read_raw_fif` above, there are\n:term:`projectors ` included in the example `~mne.io.Raw`\nfile (representing environmental noise in the signal, so it can later be\n\"projected out\" during preprocessing). You can visualize these projectors\nusing the `~mne.io.Raw.plot_projs_topomap` method. By default it will\nshow one figure per channel type for which projectors are present, and each\nfigure will have one subplot per projector. The three projectors in this file\nwere only computed for magnetometers, so one figure with three subplots is\ngenerated. More details on working with and plotting projectors are given in\n`tut-projectors-background` and `tut-artifact-ssp`.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "raw.plot_projs_topomap(colorbar=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ".. LINKS\n\n\n" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.2" } }, "nbformat": 4, "nbformat_minor": 0 }