[MRG] ENH/DOC: demo custom spectrum creation

[dengemann]

What does this implement/fix?

Explain your changes.

A simple example of how to put custom power spectral data into an average Spectrum class.
A proper SpectrumArray class could follow if there is interest.

Additional information

Any additional information you think is important.

Discussed with @drammock @hoechenberger in past 2 office hours.

[dengemann]

@drammock I put this for illustration purposes. Are there any expectations in the Spectrum code regarding this field? It was 'Averaged EEG' in my concrete case on which this example is based.

[drammock]

right now it is only used in the repr of the object. I don't have any concrete plans to use it in any other way (and I would actively avoid using it in if clauses to triage different flavors of spectrum, it's probably not reliable to do so)

[drammock]

native values for this are Fourier Coefficients, Power Spectrum, and Averaged Power Spectrum. Averaged Fourier Coefficients is not supported, see

mne-python/mne/time_frequency/spectrum.py

Lines 1109 to 1118 in 18474b1

	# averaging unaggregated spectral estimates are not supported
	if hasattr(self, '_mt_weights'):
	raise NotImplementedError(
	'Averaging complex spectra is not supported. Consider '
	'averaging the signals before computing the complex spectrum.')
	elif 'segment' in self._dims:
	raise NotImplementedError(
	'Averaging individual Welch segments across epochs is not '
	'supported. Consider averaging the signals before computing '
	'the Welch spectrum estimates.')

[drammock]

CircleCI failure is this:

Traceback (most recent call last):
  File "/home/circleci/project/tutorials/simulation/10_array_objs.py", line 243, in <module>
    spectrum.plot(picks=[0, 1])
  File "/home/circleci/project/mne/time_frequency/spectrum.py", line 606, in plot
    _plot_psd(self, fig, self.freqs, psd_list, picks_list, titles_list,
  File "/home/circleci/project/mne/viz/utils.py", line 2297, in _plot_psd
    _plot_lines(psd_array, info, picks, fig, ax_list, spatial_colors,
  File "/home/circleci/project/mne/viz/evoked.py", line 472, in _plot_lines
    warn('Channel locations not available. Disabling spatial '
  File "/home/circleci/project/mne/utils/_logging.py", line 400, in warn
    warnings.warn_explicit(
RuntimeWarning: Channel locations not available. Disabling spatial colors.

it's just a warning, but it's annoying when this breaks our CIs. Makes me wonder if we should either (1) make it a logger.info or (2) make spatial_colors='auto' somehow.

[drammock]

changes LGTM. +1 for merge when CIs are green.

My one hesitation is about data_type: I might be more comfortable sticking with Power Spectrum here, since our tutorials are implicitly supposed to demonstrate best practices and Power Spectrum would be the most consistent description of what the data are.

[dengemann]

Comments addressed, CIs green. Good to go from my side.

[hoechenberger]

The only thing I'd change is the indentation of the custom function header; I would blackify it