.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_tutorials/plot_00_quickstart.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_tutorials_plot_00_quickstart.py: .. _tut-quickstart: Quickstart: from a raw recording to clean epochs ================================================ This tutorial takes one EEG recording through the whole of meeg-utils: check how well it was recorded, clean it with a recommended pipeline, look at what every step did, cut it into epochs and save the result. We use the EEG of MNE's ``sample`` recording (60 channels, an auditory and visual oddball-like task, 277 s). The first run downloads the dataset (1.6 GB) into ``~/mne_data``. .. GENERATED FROM PYTHON SOURCE LINES 15-17 .. code-block:: Python :dedent: 1 .. GENERATED FROM PYTHON SOURCE LINES 20-33 .. code-block:: Python import matplotlib.pyplot as plt import mne import meeg_utils as meu mne.set_log_level("ERROR") data_path = mne.datasets.sample.data_path() raw = mne.io.read_raw_fif(data_path / "MEG" / "sample" / "sample_audvis_raw.fif") raw.pick(["eeg", "eog", "stim"]).load_data() raw.info["line_freq"] = 60.0 # recorded in the US; BIDS data carry it in the sidecar raw .. raw:: html
General
Filename(s) sample_audvis_raw.fif
MNE object type Raw
Measurement date 2002-12-03 at 19:01:10 UTC
Participant Unknown
Experimenter MEG
Acquisition
Duration 00:04:38 (HH:MM:SS)
Sampling frequency 600.61 Hz
Time points 166,800
Channels
EEG and
EOG
Stimulus
Head & sensor digitization 146 points
Filters
Highpass 0.10 Hz
Lowpass 172.18 Hz


.. GENERATED FROM PYTHON SOURCE LINES 34-45 meeg-utils never guesses facts about a recording: the power-line frequency above is read from BIDS sidecars when there are any, and an error asks for it when there are none. :func:`meeg_utils.io.read` reads any file MNE reads, with its BIDS sidecars. 1. Check the recording ---------------------- :func:`meeg_utils.qc.inspect` runs every acquisition check that applies to the recording and gives each finding a level: ``fail`` and ``warn`` are problems, ``ok`` passed, and ``info`` is a measurement reported without a verdict (its normal range depends on the participants and the setup). .. GENERATED FROM PYTHON SOURCE LINES 45-48 .. code-block:: Python report = meu.qc.inspect(raw) print(report) .. rst-class:: sphx-glr-script-out .. code-block:: none ok amplitude ok bridging warn outlier_channels - outlying EEG channels (LOF > 1.5): 1 (> 0); EEG 007 warn narrowband_noise - EEG channels with unusually strong line noise: 1 (> 0); check their contact: EEG 025 info muscle info blinks ok digitization ok events skip impedance: found no impedances in the recording (pass impedances=...) skip heart_rate: needs an ECG channel (or MEG magnetometers) skip squid_jumps: needs MEG channels skip head_movement: needs MEG channels skip chpi_snr: needs MEG channels skip empty_room: needs MEG channels skip bids_metadata: the recording is not in a BIDS dataset .. GENERATED FROM PYTHON SOURCE LINES 49-51 Every check can draw what it measured. The spectrum shows the 60 Hz line noise and its harmonics, and how strong the line noise is per channel: .. GENERATED FROM PYTHON SOURCE LINES 51-53 .. code-block:: Python figs = report.checks["narrowband_noise"].plot() .. rst-class:: sphx-glr-horizontal * .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_001.png :alt: Raw spectrum: line harmonics (red dotted), other peaks (orange), EEG :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_001.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_001_2_00x.png 2.00x :class: sphx-glr-single-img * .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_002.png :alt: EEG line noise at 60 Hz per channel :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_002.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_002_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 54-59 2. Clean it ----------- A preset is an ordinary :class:`~meeg_utils.Pipeline`. ``eeg-erp`` is the recommended EEG pipeline; each step's parameters come from the literature or from MNE-BIDS-Pipeline, with the sources listed in the presets guide. .. GENERATED FROM PYTHON SOURCE LINES 59-62 .. code-block:: Python pipe = meu.Pipeline.preset("eeg-erp") pipe .. raw:: html
#StepConfiguration (changed parameters)
0bridgedBridgedElectrodes()
1highpassFilter(h_freq=None, l_freq=0.1)
2line_noiseLineNoise()
3badsBadChannels(method='prep')
4interpolateInterpolate()
5referenceReference()
6icaICA(labeler='iclabel', n_components=0.999999, picks='eeg')


.. GENERATED FROM PYTHON SOURCE LINES 63-66 ``fit_transform`` learns what each step needs from this recording (bad channels, the ICA decomposition, ...) and applies it. The input is not modified. .. GENERATED FROM PYTHON SOURCE LINES 66-68 .. code-block:: Python clean = pipe.fit_transform(raw) .. GENERATED FROM PYTHON SOURCE LINES 69-72 3. See what every step did -------------------------- Every fitted step has ``qc_`` metrics, collected in ``pipe.qc_``: .. GENERATED FROM PYTHON SOURCE LINES 72-74 .. code-block:: Python pipe.qc_["bads"]["eeg"]["bads"], pipe.qc_["ica"]["excluded"] .. rst-class:: sphx-glr-script-out .. code-block:: none (['EEG 008', 'EEG 009', 'EEG 015', 'EEG 018', 'EEG 019', 'EEG 023'], [0, 4, 9, 12, 14, 19, 20, 21, 23, 24, 26, 29]) .. GENERATED FROM PYTHON SOURCE LINES 75-77 and can draw figures. ZapLine-plus removed the line noise without notching the spectrum: .. GENERATED FROM PYTHON SOURCE LINES 77-79 .. code-block:: Python pipe["line_noise"].plot("psd")["psd"] .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_003.png :alt: Line noise (zapline-plus, 60 Hz), EEG :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_003.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_003_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 80-82 ICLabel classified the independent components; those labelled as artifacts with a probability of at least 0.8 were removed: .. GENERATED FROM PYTHON SOURCE LINES 82-84 .. code-block:: Python pipe["ica"].plot("labels")["labels"] .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_004.png :alt: ICA labels (iclabel); x = excluded :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_004.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_004_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 85-87 .. code-block:: Python figs = pipe["ica"].plot("components") .. rst-class:: sphx-glr-horizontal * .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_005.png :alt: ICA000 eye blink 0.99, ICA001 brain 1.00, ICA002 brain 0.99, ICA003 brain 1.00, ICA004 muscle artifact 0.94, ICA005 brain 1.00, ICA006 brain 0.97, ICA007 brain 0.99, ICA008 brain 0.99, ICA009 muscle artifact 0.93, ICA010 brain 1.00, ICA011 brain 1.00, ICA012 muscle artifact 0.81, ICA013 heart beat 0.71, ICA014 muscle artifact 0.94, ICA015 brain 0.78, ICA016 brain 1.00, ICA017 brain 1.00, ICA018 brain 0.89, ICA019 muscle artifact 0.99 :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_005.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_005_2_00x.png 2.00x :class: sphx-glr-single-img * .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_006.png :alt: ICA020 muscle artifact 0.93, ICA021 muscle artifact 0.96, ICA022 brain 1.00, ICA023 muscle artifact 0.90, ICA024 muscle artifact 0.99, ICA025 other 0.43, ICA026 muscle artifact 0.95, ICA027 brain 0.94, ICA028 brain 0.52, ICA029 muscle artifact 0.90, ICA030 brain 0.98, ICA031 brain 0.46, ICA032 brain 0.53, ICA033 brain 0.98, ICA034 brain 0.77, ICA035 other 0.52, ICA036 brain 0.85, ICA037 muscle artifact 0.50, ICA038 brain 0.83, ICA039 other 0.63 :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_006.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_006_2_00x.png 2.00x :class: sphx-glr-single-img * .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_007.png :alt: ICA040 brain 0.43, ICA041 brain 0.42, ICA042 other 0.74, ICA043 other 0.39, ICA044 muscle artifact 0.73, ICA045 other 0.81, ICA046 other 0.52, ICA047 brain 0.37, ICA048 other 0.78, ICA049 other 0.77, ICA050 other 0.38, ICA051 brain 0.74 :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_007.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_007_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 88-92 4. Epochs --------- Epoching is a second stage, applied to each preprocessed run. The sample recording marks its stimuli on a stimulus channel: .. GENERATED FROM PYTHON SOURCE LINES 92-97 .. code-block:: Python event_id = {"auditory/left": 1, "auditory/right": 2, "visual/left": 3, "visual/right": 4} ep = meu.Pipeline.preset("eeg-erp", stage="epochs", event_id=event_id) epochs = ep.fit_transform(clean) epochs .. raw:: html
General
MNE object type Epochs
Measurement date 2002-12-03 at 19:01:10 UTC
Participant Unknown
Experimenter MEG
Acquisition
Total number of events 283
Events counts auditory/left: 71
auditory/right: 72
visual/left: 70
visual/right: 70
Time range -0.200 – 0.499 s
Baseline -0.200 – 0.000 s
Sampling frequency 600.61 Hz
Time points 421
Metadata No metadata set
Channels
EEG
EOG
Stimulus
Head & sensor digitization 146 points
Filters
Highpass 0.10 Hz
Lowpass 40.00 Hz


.. GENERATED FROM PYTHON SOURCE LINES 98-99 autoreject repaired or dropped the epochs with artifacts left: .. GENERATED FROM PYTHON SOURCE LINES 99-101 .. code-block:: Python ep["autoreject"].plot("reject_log")["reject_log"] .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_008.png :alt: plot 00 quickstart :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_008.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_008_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 102-106 .. code-block:: Python evoked = epochs["visual"].average() evoked.plot_joint(times=[0.1, 0.17], title="Visual stimuli") plt.show() .. image-sg:: /auto_tutorials/images/sphx_glr_plot_00_quickstart_009.png :alt: Visual stimuli, 0.100 s, 0.170 s :srcset: /auto_tutorials/images/sphx_glr_plot_00_quickstart_009.png, /auto_tutorials/images/sphx_glr_plot_00_quickstart_009_2_00x.png 2.00x :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 107-119 5. Save ------- :func:`meeg_utils.io.save_derivative` writes the data in BIDS derivative layout with a JSON sidecar holding the pipeline configuration, software versions and every QC metric: .. code-block:: python meu.io.save_derivative(clean, source, "bids/derivatives/meu", pipeline=pipe) For a whole BIDS dataset, :func:`meeg_utils.process_dataset` or the ``meu`` command does all of the above run by run (see :ref:`tut-datasets`). .. rst-class:: sphx-glr-timing **Total running time of the script:** (3 minutes 41.344 seconds) .. _sphx_glr_download_auto_tutorials_plot_00_quickstart.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_00_quickstart.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_00_quickstart.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_00_quickstart.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_