Feature request: incremental updates to an `mne.Report`

This is something that came up when writing the huge analysis pipeline for the conpy project:

I think the Report object of MNE-Python could be made even more useful if we could write incremental updates to it.

As the analysis progresses, more and more figures are incrementally added to the report. Every time the report is saved, the .html file is updated. This would make it super easy to add visual checks to each step of the analysis. Easier than the current situation where we have to make one giant make_report.py file at the end of the pipeline that reads in all the intermediate results and plots them.

Say I have three analysis scripts:

01_filter_raw.py
02_make_epochs.py
03_grand_average.py

It would be cool if each of these scripts could add/update figures in a shared Report object, for example like this:

# Somewhere in 01_filter_raw.py
report = mne.read_report('subject1_report.pickle')  # Loads existing or creates new
report.add_figs_to_section([raw.plot_psd()], ['PSD plot'], 'preprocessing')
report.pickle()  # since report.save() is already taken

# Somewhere in 02_make_epochs.py
report = mne.read_report('subject1_report.pickle')
report.add_figs_to_section([epochs.average.plot()], ['Evokeds'], 'preprocessing')
report.pickle()

# Somewhere in 03_grand_average.py
report = mne.read_report('subject1_report.pickle')
report.add_figs_to_section([grand_average.plot()], ['Grand average'], 'preprocessing')
report.pickle()

Even implement __enter__() and __exit__() blocks so we can do this:

with mne.read_report('subject1_report.pickle') as report:
     report.add_figs_to_section(...)
# report is automatically saved when exiting the block

For this to be used as intended, there needs to be a way to overwrite existing figures.

[larsoner]

From what I understand pickling is a bad way to get long-term persistence. I’d rather use hdf5, in theory it shouldn’t add too many lines beyond what the pickle does.

[wmvanvliet]

maybe use save and decide what to use based on file extension?

that’s a good idea!