Improve and update .hea example

[briangow]

This PR improves the .hea examples by adding descriptions for each element from a header line. It also updates the example header lines to show a multi-frequency record. This gives users additional insight into how frames, samples per frame, and total samples can be garnered from the .hea.

I've also added a reference to the detailed header documentation for easy reference.

[tompollard]

The confusing thing about the current header structure is that the location/order of fields is inconsistent, depending on whether or not an optional field is provided. I like the idea of adding a bulleted list below the examples, which I think partly addresses this issue.

I think it is much better to use real-life examples if possible. I hadn't made it clear (and we should do this) but the example I provided was from the MIT-BIH Arrhythmia Database if remember correctly (though it seems I may have modified a couple of the fields, which I probably shouldn't have done: https://physionet.org/content/mitdb/1.0.0/100.hea).

[briangow]

@tompollard , thanks for your thoughts!

The confusing thing about the current header structure is that the location/order of fields is inconsistent, depending on whether or not an optional field is provided. I like the idea of adding a bulleted list below the examples, which I think partly addresses this issue.

I completely agree, which is why I like the idea of providing the explanation below the examples. It certainly isn't a comprehensive solution but should get people started.

I think it is much better to use real-life examples if possible.

I agree but I wasn't able to find good multi-frequency WFDB examples on PN. I personally like showing this capability as it gives insight into some of the fields that get brushed over with simpler examples. I also anticipate that CHoRUS will make use of the multi-frequency design, so there will be real-world example data sooner than later. CHoRUS will probably also create multi-segment records but providing examples of these does get significantly more involved.

It isn't always clear where to strike a balance with all of this. This is one of the reasons I provided a link to the detailed header documentation which does have additional examples. On the wfdb.io site, do you think we should give examples from multiple records? If so, do we want these examples:

• one sample rate for all channels, not multi-segment (could use the old example you had)
• unique sample rates per channel, not multi-segment (example I give in this PR, until we can identify a real-world example)
• unique sample rates per channel, multi-segment record (MIMIC-IV Waveforms - example with only 2 segments: https://physionet.org/content/mimic4wdb/0.1.0/waves/p100/p10082591/84050536 )

[tompollard]

Not directly related to the PR, but another confusing aspect of WFDB is that the format specification is not well separated from the software documentation. This was on my mind again when reviewing #10.

My preference is to make this website (or a new specification website) the primary location for detailed specification of the format. Then we link out to documentation for the individual software implementations (as we do now at https://wfdb.io/software/).

I agree but I wasn't able to find good multi-frequency WFDB examples on PN. I personally like showing this capability as it gives insight into some of the fields that get brushed over with simpler examples.

Your new multi-frequency example is useful and if we can't find a real example then using synthetic values is good with me. I just felt like it supplemented the previous example, so it would be better to keep both (and add additional examples as needed, e.g. the MIMIC-IV Waveforms one you mention).

[briangow]

@tompollard , I've updated this to include both an example from the file you referenced previously and the multi-frequency example. For consistency, I switched the MIT-BIH example that you were using back to the exact settings in the header file. I also mention that the file comes from that database, so people can further explore it if desired. I added explanations for the elements in that example also.

If we do end up adding a multi-segment example, we'll probably need to create collapsable elements (using <detail> tags). I've found this only creates cleanly formatted output if the entire example is contained inside html elements. My opinion is that using these collapsable elements isn't necessary for just the 2 examples we currently have.

[tompollard]

Thanks Brian, sorry more comments than I'd expected to make. I'll approve the PR, but I think it would be good to address some or all of the comments before merging, if possible.

[tompollard]

Thanks for taking the time to address these comments!