Revamp HTML reprs of Raw, Epochs, Evoked, and Info

[hoechenberger]

For example, the Evoked repr contained the number of channels, but failed to subtract or report any bads.

Also I believe reporting the number of sampling points is quite pointless , so I removed that as well.

The table layout wasn't up-to-date either.

main (striped layout only added by VS Code, actually not present in the tables we produce!)

This PR:

For comparison, Epochs:

MWE:

# %%
import mne

sample_dir = mne.datasets.sample.data_path()
sample_fname = sample_dir / "MEG" / "sample" / "sample_audvis_raw.fif"

raw = mne.io.read_raw_fif(sample_fname)
raw.crop(tmax=60)

events = mne.find_events(raw, stim_channel="STI 014")
raw.pick("eeg")

epochs = mne.Epochs(raw, events=events, preload=True)
epochs

# %%
evoked = epochs.average()
evoked

[agramfort]

you're aligning to the minimum info by dropping number of channels and time points. I find it useful to know the duration and how many channels are available.

[hoechenberger]

@agramfort Are you suggesting to add number of samples and channels to the Epochs repr instead, then? I could do that, no problem

[agramfort]

yes I would have done that if you push for consistency.

…

Message ID: ***@***.***>

[hoechenberger]

Ok i'll take a look!

[hoechenberger]

Ok, so I've now touched the Raw, Epochs, and Evoked HTML reprs to make things more consistent. Here's a comparison of what we have in main and what's in this PR branch now:

[drammock]

I'm generally quite happy with the improved consistency. Thanks! Nitpicks:

• I find "digitized head and sensor positions" doesn't quite make sense (the headshape points aren't "head positions" in the sense that we normally use that term). I'd revert to "digitized points"
• the "data kind" field is only in evoked; is that meant to communicate "avg" vs "stdev"? Does it make sense to collapse that into one field with nave (something like "average of NN epochs" or "standard deviation of NN epochs")?

[hoechenberger]

I'm generally quite happy with the improved consistency. Thanks! Nitpicks:

• I find "digitized head and sensor positions" doesn't quite make sense (the headshape points aren't "head positions" in the sense that we normally use that term). I'd revert to "digitized points"

I was worried this could be confused with "sampling points" on the time axis … I had first thought of labeling it "digitized had shape and sensor positions", but it's too long. I'm okay with changing it back to "digitized points", but it's not my favorite – maybe if we brainstorm a little, we can come up with a better idea?

• the "data kind" field is only in evoked; is that meant to communicate "avg" vs "stdev"?

Yes, it was there before and I'm actually not sure if it's really needed?

Does it make sense to collapse that into one field with nave (something like "average of NN epochs" or "standard deviation of NN epochs")?

Good idea, I can do that!

[hoechenberger]

@drammock Another thing we may need to address – these tables are quite long now, and I haven't added collapsible sections like we have for Raw (which essentially just prints out Info). Is that a problem for the tutorial rendering?

[mscheltienne]

+1 for digitized points, unless someone comes up with a clearer alternative. Thanks for the upgrade, it looks great!

[mscheltienne]

It's actually a bit better 😆

[drammock]

it looks beautiful @hoechenberger 😍 And the refactoring of the Jinja templates resolves a big pain point --- it will be much easier to make other object types have consistent HTML reprs now too.

I left a couple minor inline comments/suggestions, here are three other tiny suggestions/ideas from looking at the rendered output:

1. In the "general" section, "Data type" feels like not quite the right name (to me "data type" means float, int, complex, etc). Maybe "object type"?
2. I'm very slightly bothered by the title of the "Data" section (seems too generic of a title). At first I thought "Times" (to parallel the "channels" section) would work instead --- for raw and epochs, the "data" section is all about time-domain things (duration, sfreq, events; events is not strictly about time, but if you squint it could make sense under a "times" heading). Sadly this doesn't work for evokeds, because there we also get "aggregation" and "condition" entries. I think it's OK to leave as "data" for now unless someone has a quick idea about a better alternative.
3. I think it's confusing for "good channels" to say "59 EEG" (a count) and "bad channels" to say "EEG 053" (a channel name that looks a lot like a count of channels of a particular type). A couple possible repairs:
   a. channel names are always enquoted
   b. when there are few enough channels to be worth writing them individually, write a count followed by names in parentheses (e.g., bad channels: 1 (EEG 053)).

All of these are small enough that they can be done later / are not blockers for me

[drammock]

does %Z not work here?
https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes

[hoechenberger]

This could work, yes
I can try it out

[hoechenberger]

This seems to work!

While we're at it: WDYT about a date representation like this:

2002-12-03 at 19:01:10 UTC

(YYYY-MM-DD)

[drammock]

YYYY-MM-DD

That is my personal preferred date format, so I'm fine with it :)
It's also what ISO 8601 stipulates, so it's as good a choice as any

[hoechenberger]

@drammock I addressed this in fd976a5

I didn't implement "full" ISO-8601, because it's not super human-readable when you have a datetime string; but I took inspiration from that standard. Please LMK what you think

[hoechenberger]

@drammock I agree with all of these, including the naming of the "Data" section and the inconsistencies re the good / bad channels. However this is already present in main so I didn't really dare to touch it. But if we can come up with better ideas, I can certainly include them in this PR!

(Re Data: I actually spent a while thinking about it and exploring different names, but couldn't come up with anything better… happy to keep on brainstorming though!)

[agramfort]

thanks @hoechenberger !

[hoechenberger]

@drammock FYI when I started with this work, I named the Data section Recording, which seemed nice until I realized for an Info object, it seemed kinda odd, because it doesn't have any "recorded" data attached.

That said, one could argue that a Data section is just as inappropriate there.

So what do you say, shall we rename Data -> Recording? I can push a commit so you can take a look at the rendered reprs to get a better idea of what it "feels" like

[hoechenberger]

• In the "general" section, "Data type" feels like not quite the right name (to me "data type" means float, int, complex, etc). Maybe "object type"?

I have addressed this in aacb2c4 and renamed it to "MNE object time", WDYT?

[hoechenberger]

3. I think it's confusing for "good channels" to say "59 EEG" (a count) and "bad channels" to say "EEG 053" (a channel name that looks a lot like a count of channels of a particular type). A couple possible repairs:
a. channel names are always enquoted
b. when there are few enough channels to be worth writing them individually, write a count followed by names in parentheses (e.g., bad channels: 1 (EEG 053)).

I'll look into this. Thanks to the refactoring I've done here, I believe now I only have to touch the _format_channels() function (i.e., all is in one place). Neat!

[hoechenberger]

@drammock FYI when I started with this work, I named the Data section Recording, which seemed nice until I realized for an Info object, it seemed kinda odd, because it doesn't have any "recorded" data attached.

That said, one could argue that a Data section is just as inappropriate there.

So what do you say, shall we rename Data -> Recording? I can push a commit so you can take a look at the rendered reprs to get a better idea of what it "feels" like

I renamed Data to Acquisition

[drammock]

I renamed Data to Acquisition

that's an improvement I think. The number averaged in an Evoked isn't really "acquisition" but I think it's OK.