Repository: mne-tools/mne-python

Issue:
Supply "title" kwarg to Report in the Report tutorial
Currently we don't set a title, but it would be nice to have one for didactic reasons but also because it looks nicer.


Discussion:

Resolving patch:
diff --git a/tutorials/intro/70_report.py b/tutorials/intro/70_report.py
--- a/tutorials/intro/70_report.py
+++ b/tutorials/intro/70_report.py
@@ -82,7 +82,7 @@
 raw_path = sample_dir / 'sample_audvis_filt-0-40_raw.fif'
 raw = mne.io.read_raw(raw_path)
 
-report = mne.Report()
+report = mne.Report(title='Raw example')
 report.add_raw(raw=raw_path, title='Raw from Path')
 report.add_raw(raw=raw, title='Raw from "raw"', psd=False)  # omit PSD plot
 report.save('report_raw.html', overwrite=True)
@@ -98,7 +98,7 @@
 events = mne.read_events(events_path)
 sfreq = raw.info['sfreq']
 
-report = mne.Report()
+report = mne.Report(title='Events example')
 report.add_events(events=events_path, title='Events from Path', sfreq=sfreq)
 report.add_events(events=events, title='Events from "events"', sfreq=sfreq)
 report.save('report_events.html', overwrite=True)
@@ -113,7 +113,7 @@
 
 epochs = mne.Epochs(raw=raw, events=events)
 
-report = mne.Report()
+report = mne.Report(title='Epochs example')
 report.add_epochs(epochs=epochs, title='Epochs from "epochs"')
 report.save('report_epochs.html', overwrite=True)
 
@@ -141,7 +141,7 @@
 evokeds = mne.read_evokeds(evoked_path, baseline=(None, 0))
 evokeds_subset = evokeds[:2]  # The first two
 
-report = mne.Report()
+report = mne.Report(title='Evoked example')
 report.add_evokeds(
     evokeds=evokeds_subset,
     titles=['evoked 1',  # Manually specify titles
@@ -163,7 +163,7 @@
 
 cov_path = sample_dir / 'sample_audvis-cov.fif'
 
-report = mne.Report()
+report = mne.Report(title='Covariance example')
 report.add_covariance(cov=cov_path, info=raw_path, title='Covariance')
 report.save('report_cov.html', overwrite=True)
 
@@ -182,7 +182,7 @@
 ecg_proj_path = sample_dir / 'sample_audvis_ecg-proj.fif'
 eog_proj_path = sample_dir / 'sample_audvis_eog-proj.fif'
 
-report = mne.Report()
+report = mne.Report(title='Projectors example')
 report.add_projs(info=raw_path, title='Projs from info')
 report.add_projs(info=raw_path, projs=ecg_proj_path,
                  title='ECG projs from path')
@@ -250,7 +250,7 @@
 )
 ica.exclude = eog_components
 
-report = mne.Report()
+report = mne.Report(title='ICA example')
 report.add_ica(
     ica=ica,
     title='ICA cleaning',
@@ -272,7 +272,7 @@
 # the resulting file size, you may pass the ``decim`` parameter to only include
 # every n-th volume slice.
 
-report = mne.Report()
+report = mne.Report(title='BEM example')
 report.add_bem(
     subject='sample', subjects_dir=subjects_dir, title='MRI & BEM',
     decim=10
@@ -291,7 +291,7 @@
 
 trans_path = sample_dir / 'sample_audvis_raw-trans.fif'
 
-report = mne.Report()
+report = mne.Report(title='Coregistration example')
 report.add_trans(
     trans=trans_path, info=raw_path, subject='sample',
     subjects_dir=subjects_dir, title='Coregistration'
@@ -308,7 +308,7 @@
 
 fwd_path = sample_dir / 'sample_audvis-meg-oct-6-fwd.fif'
 
-report = mne.Report()
+report = mne.Report(title='Forward solution example')
 report.add_forward(forward=fwd_path, title='Forward solution')
 report.save('report_forward_sol.html', overwrite=True)
 
@@ -322,7 +322,7 @@
 
 inverse_op_path = sample_dir / 'sample_audvis-meg-oct-6-meg-inv.fif'
 
-report = mne.Report()
+report = mne.Report(title='Inverse operator example')
 report.add_inverse_operator(
     inverse_operator=inverse_op_path, title='Inverse operator'
 )
@@ -341,7 +341,7 @@
 
 stc_path = sample_dir / 'sample_audvis-meg'
 
-report = mne.Report()
+report = mne.Report(title='Source estimate example')
 report.add_stc(
     stc=stc_path, subject='sample', subjects_dir=subjects_dir,
     title='Source estimate', n_time_points=5
@@ -366,7 +366,7 @@
 mne_init_py_path = Path(mne.__file__)  # __init__.py in the MNE-Python root
 mne_init_py_content = mne_init_py_path.read_text(encoding='utf-8')
 
-report = mne.Report()
+report = mne.Report(title='Code example')
 report.add_code(
     code=mne_init_py_path,
     title="Code from Path"
@@ -397,7 +397,7 @@
 ax.set_ylabel('f(x)')
 ax.legend()
 
-report = mne.Report()
+report = mne.Report(title='Figure example')
 report.add_figure(
     fig=fig, title='A custom figure',
     caption='A blue dashed line reaches up into the sky …',
@@ -435,7 +435,7 @@
     figs.append(fig)
     captions.append(f'Rotation angle: {round(angle, 1)}°')
 
-report = mne.Report()
+report = mne.Report(title='Multiple figures example')
 report.add_figure(fig=figs, title='Fun with figures! 🥳', caption=captions)
 report.save('report_custom_figures.html', overwrite=True)
 
@@ -448,7 +448,7 @@
 # include JPEG, PNG, GIF, and SVG (and possibly others). Like with Matplotlib
 # figures, you can specify a caption to appear below the image.
 
-report = mne.Report()
+report = mne.Report(title='Image example')
 report.add_image(
     image=mne_logo_path, title='MNE',
     caption='Powered by 🧠 🧠 🧠 around the world!'
@@ -472,7 +472,7 @@
 # To toggle the visibility of **all** tags, use the respective checkbox in the
 # ``Filter by tags`` dropdown menu, or press :kbd:`T`.
 
-report = mne.Report()
+report = mne.Report(title='Tags example')
 report.add_image(
     image=mne_logo_path,
     title='MNE Logo',
@@ -489,7 +489,7 @@
 # to edit a report once it's no longer in-memory in an active Python session,
 # save it as an HDF5 file instead of HTML:
 
-report = mne.Report(verbose=True)
+report = mne.Report(title='Saved report example', verbose=True)
 report.add_image(image=mne_logo_path, title='MNE 1')
 report.save('report_partial.hdf5', overwrite=True)
 
@@ -537,7 +537,7 @@
 # :meth:`~mne.Report.parse_folder` and also the ``subject`` and
 # ``subjects_dir`` parameters provided to the :class:`~mne.Report` constructor.
 
-report = mne.Report()
+report = mne.Report(title='parse_folder example')
 report.parse_folder(
     data_path=data_path, pattern='*raw.fif', render_bem=False,
     raw_butterfly=False
@@ -554,7 +554,7 @@
 # the unfiltered data and the empty-room noise recordings).
 
 pattern = 'sample_audvis_filt-0-40_raw.fif'
-report = mne.Report(raw_psd=True, projs=True)
+report = mne.Report(title='parse_folder example 2', raw_psd=True, projs=True)
 report.parse_folder(
     data_path=data_path, pattern=pattern, render_bem=False, raw_butterfly=False
 )
@@ -568,7 +568,9 @@
 # expensive, we'll also pass the ``mri_decim`` parameter for the benefit of our
 # documentation servers, and skip processing the :file:`.fif` files.
 
-report = mne.Report(subject='sample', subjects_dir=subjects_dir)
+report = mne.Report(
+    title='parse_folder example 3', subject='sample', subjects_dir=subjects_dir
+)
 report.parse_folder(data_path=data_path, pattern='', mri_decim=25)
 report.save('report_parse_folder_mri_bem.html', overwrite=True)
 
@@ -596,7 +598,9 @@
 cov_fname = sample_dir / 'sample_audvis-cov.fif'
 pattern = 'sample_audvis-no-filter-ave.fif'
 
-report = mne.Report(baseline=baseline, cov_fname=cov_fname)
+report = mne.Report(
+    title='parse_folder example 4', baseline=baseline, cov_fname=cov_fname
+)
 report.parse_folder(
     data_path, pattern=pattern, render_bem=False, n_time_points_evokeds=5
 )
@@ -612,7 +616,7 @@
 
 pattern = 'sample_audvis-cov.fif'
 info_fname = sample_dir / 'sample_audvis-ave.fif'
-report = mne.Report(info_fname=info_fname)
+report = mne.Report(title='parse_folder example 5', info_fname=info_fname)
 report.parse_folder(
     data_path, pattern=pattern, render_bem=False, n_time_points_evokeds=5
 )


Test patch: