Adjust vmin/vmax parameters in epochs image in report to rejection limits

[SophieHerbst]

When checking the reports for the cleaned epochs, I would like to set the scale limits to the defined epochs rejection thresholds. Otherwise, when the scale limits are set automatically it is impossible to interpret the colors and figure out quickly whether the thresholds were high enough. If I am not mistaken, this requires an adjustement in mne.report.add_epochs, to hand down the rejection limits? In the pipeline, I would suggest to make it the default that the epochs images are scaled to the rejection limits when clean epochs are displayed in the report. WDYT?

[larsoner]

One disadvantage is that if people have their thresholds set very high because they know they only want to exclude artifacts are huge (or because autoreject sets them that way), but their signals of interest are small (and SNR high other than the large artifacts that get rejected), then the range of the epochs images will end up being compressed (all white)

[SophieHerbst]

I see your point. Is there a custom way for me to adjust them in the report created by the pipeline to have the same limits for all my participants?

[SophieHerbst]

any insights on how to do this @hoechenberger ?

[hoechenberger]

@SophieHerbst It would require a change to MNE-Python and subsequently to the Pipeline. Nothing difficult, but still a bit of work:

• First, add a new parameter image_kwargs to Report.add_epochs() here: https://github.com/mne-tools/mne-python/blob/70455902ba834bec75ae1fd0f7f5b2fc48455cf8/mne/report/report.py#L1095 (consistent with the existing topomap_kwargs)
• Add and pass it down to Report._add_epochs(), https://github.com/mne-tools/mne-python/blob/70455902ba834bec75ae1fd0f7f5b2fc48455cf8/mne/report/report.py#L1141
• Inside _add_epochs(), pass it to plot_image() as **image_kwargs: https://github.com/mne-tools/mne-python/blob/70455902ba834bec75ae1fd0f7f5b2fc48455cf8/mne/report/report.py#L3939

Then we could do Report.add_epochs(..., image_kwargs={"vmin": ..., "vmax": ...})

Once we have this, we'd need to expose this functionality (or a more restricted subset of it) via the Pipeline configuration.

[SophieHerbst]

Mh, ok, it sounds like a bit of work, but I would find it very useful. Shall I give it a try?

[hoechenberger]

Shall I give it a try?

Sure, if you have the time, please feel free to take a stab at this!

[SophieHerbst]

Now the change in MNE is done, we need to decide how to set vmin/vmax in the pipeline. It feels a bit too much to add them as possible configuration parameters, but I do not see another way. Defaults: None?

Then we could do Report.add_epochs(..., image_kwargs={"vmin": ..., "vmax": ...})

Once we have this, we'd need to expose this functionality (or a more restricted subset of it) via the Pipeline configuration.

[larsoner]

I think something like report_add_epochs_kwargs: Optional[dict] = None and in your use case you'd do

report_add_epochs_kwargs = dict(image_kwargs=dict(...))

could work

[SophieHerbst]

@larsoner I realize that we need to be able to pass vmin and vmax for all channel types. This requires to also pick them for channel types when plotting the epochs image in mne's report.py, l 3898, right? .pick(ch_type, verbose=False)

[SophieHerbst]

In my config, I would have this:

report_add_epochs_kwargs = dict(image_kwargs=dict(grad = dict(vmin=-reject['grad'], vmax=-reject['grad']), 
                                                  mag = dict(vmin=reject['mag'], vmax=reject['mag'])))

[larsoner]

Sure but we could consider adding a convenience alias report_add_epochs_kwargs = 'reject' if you want. This would have the advantage of also potentially working with stuff like autoreject-set limits, which you wouldn't have access to in the config.py file itself.

[hoechenberger]

I think this was resolved via #859