sample_rate vs sample_frequency: how to continue?

[skjerns]

There is confusions about the two terms and how they are implemented in pyedflib and also edflib. I'd like you'r opinion on how to continue. @DimitriPapadopoulos @cbrnr @holgern @raphaelvallat @LucaCerina @cfranklin11

EDF specs

In the specs the following is defined:
* 8 ascii : duration of a data record, in seconds -> we call this internally record_duration
*ns * 8 ascii : ns * nr of samples in each data record (per channel) -> we call this internally smp_per_record

There is no sample_frequency or sample_rate within the EDF specs. However, these can be derived by dividing smp_per_record by record_duration.

edflib

edflib, introduces samplefrequency (equal to smp_per_record/record_duration, not always Hz) and samplerate (Hz), which is not actually implemented to set, just mentioned in the docstrings. There's an inconsistency as Hz is defined as cycle per second, but this isn't always reflected in edflib:

• For example, if you want to use a samplerate of 0.5 Hz, set the samplefrequency to 5 Hz and the datarecord duration to 10 seconds, or set the samplefrequency to 1 Hz and the datarecord duration to 2 seconds."

pyedflib

In pyedflib, sample_rate was initially like edflib's samplefrequency. Later, sample_frequency was introduced to represent Hz, simplifying the user experience. The definition of sample_frequency in Hz is also how it is done in `python-edf.

Solutions

In principle I think nobody cares about the record_duration or how things are implemented internally. People want to set and retrieve a sampling rate in Hz and be done. You should not have to think about the record_duration unless you have good reason to. Imo the decision to be made is which of the two terms to keep.

Options:

A) Keep both terms, eventually removing sample_rate. This is user-friendly but inconsistent with edflib.

B) Revert to sample_rate only, aligning with edflib but disrupting recent changes. Treat sample_rate as Hz.

C) Align with edflib: use sample_frequency for smp_per_record and sample_rate for Hz, which could confuse users.

Personally I think A&B seem to be the best options, with A the least disrupting. If the unfortunate introduction of sample_frequency would not have been done, I would favour B, but that's too late now. What do you think?

[cbrnr]

I agree with you, and since sample_rate and sample_frequency are synonymous (at least in general, i.e. not talking about some specific implementation details), I would vote for B. I don't think it's too late for that, you can just deprecate sample_frequency and go back to sample_rate.

[raphaelvallat]

I prefer sample_frequency over sample_rate, which is more consistent with scipy.signal and MNE. My vote is for A :)

[skjerns]

Any more opinions? @DimitriPapadopoulos @holgern @LucaCerina @cfranklin11

[cbrnr]

BTW I'm also fine with A as long as there's only one term (eventually after a deprecation cycle).

[LucaCerina]

I would go with A.
Looking at EDFlib their definition of samplefrequency forcing an integer value is a bit weird and I think it's ok to not align with that