Improve Epochs docs (and more)

Based on my question in the forum, I suggest to clarify the preload parameter to make it clear that preloading does not depend on the status of raw.preload (which I assumed was the case).

I’d change the preload description as follows:

Load all epochs from disk into memory when creating the object or wait before accessing each epoch (more memory efficient but can be slower).

In addition, I’d add the following note:

Epochs are preloaded based on the value of the preload argument. Even if the raw argument has already been preloaded, the returned Epochs object will not be preloaded by default. This means that bad epochs (e.g. epochs with not enough data) will not be dropped immediately, so the number of good epochs displayed may change once the epochs are preloaded.

@hoechenberger @larsoner @agramfort @drammock since this is such a widely used object I’d be grateful if you commented and edited my suggestion if necessary.

Furthermore, I noticed that preload is used inconsistently across BaseEpochs, Epochs, EpochsArray, and EpochsFIF classes:

• BaseEpochs: Doesn’t have a preload parameter but preload_at_end - what’s the reason to use a different parameter?
• Epochs: preload=False
• EpochsArray: Has neither preload nor preload_at_end parameters.
• EpochsFIF: preload=True

I think it would be great to double-check these inconsistencies - there are probably good reasons, but if not we should discuss changing accordingly.

Finally, @hoechenberger suggested to discuss preload=None as a default, meaning that this would re-use its raw.preload value.

[cbrnr]

Type checking with isinstance is exactly the point of ABCs, so yes, it works. It should be as simple as inheriting from collections.ABC and slapping @abstractmethod decorators on methods, but we’ll have to see if it is really that painless. I can try and run the test suite to see if this works.

[cbrnr]

Other people won’t bother us with these questions again 😄. It’s just a matter of style, you don’t have to do it, but this is a classic example of an abstract base class, so we could as well declare it as such.