Add signals.hrv module

[rafaelscsilva]

This PR updates the signals subpackage with the hrv.py module, created to perform Heart Rate Variability (HRV) analysis. It allows the extraction of several features in time, frequency and non-linear domains, and to visualize the results. The main features include:

• A main function to extract features and visualize a summary of the results, as shown below (hrv.hrv, plotting.plot_hrv)
• Compute RR Intervals from a list of R-peaks (hrv.compute_rri)
• Filter and interpolate a sequence of RR Intervals (hrv.rri_filter, hrv.rri_correction)
• Detrend a sequence of RR Intervals using smoothness priors (hrv.detrend_window, tools.detrend_smoothness_priors)
• Extract time-domain features (e.g., mean, median, RMSSD, pNN50, SDNN, HTI, TINN) (hrv.hrv_timedomain, hrv.compute_geometrical)
• Plot time-domain results (plotting.plot_rri, plotting.plot_hrv_hist)
• Extract frequency-domain features from frequency bands (e.g., peak frequency, absolute power, relative power, LF/HF ratio) (hrv._hrv_frequencydomain)
• Plot frequency-domain results (plotting.plot_hrv_fbands)
• Extract non-linear features from Poincaré plot (e.g., S, SD1, SD2) and from entropy measures (sample entropy and approximate entropy) (hrv.hrv_nonlinear, hrv.compute_poincare, hrv.sample_entropy, hrv.approximate_entropy)
• Visualize the Poincaré plot (plotting.plot_poincare)

Also, an example file containing a sequence of RR Intervals was added to the example files (./examples/rri.txt)

Note: since some HRV features coincide with features from the features sub-package, a reformatting of this module should be considered. Also, because the testing and validation of this module is still ongoing, users are encouraged to be mindful of the obtained results and regularly check for updates. The branch should not be deleted after merge.

[rafaelscsilva]

Thank you @MarianaAbreu for your timely revision!

Regarding your first comment, could you provide the exact error message that you are getting? This could help me understand the origin of the error.

Concerning your last two observations, I believe this could be due to the detrending of the RRI sequence. In the hrv_nonlinear function, the default parameter for detrending (_detrendrri) is set to True, which will replace the original RRI sequence by the detrended one, thus impacting the computation of some features such as the ones computed by the compute_poincare and sample_entropy. If this is indeed the source of the differences you obtain, would you recommend to set the _detrendrri default value to False in the hrv_nonlinear function? I think the same applies to the hrv_timedomainand hrv_frequencydomain.

[MarianaAbreu]

Hi Rafael,

Regarding the first comment, I was using the python version3.8.16, and here is the screenshot of the error.

Regarding the other comments, I agree that the difference should be related to the RRi detrend, I think we should send a warning in the hrv functions to alert for this difference, so that non-experienced users can be aware and decide whether or not they want to use the function.

[rafaelscsilva]

Thank you @MarianaAbreu for your reply!

I believe I identified the origin of the error, and the _rridet in that line is now an array (https://github.com/scientisst/BioSPPy/pull/19/commits/0d8e9f8445724278e1937fce100439805bb5e5ba)

Regarding the warning suggestion, I added prints that alert the user whenever the RRI sequence was detrended in each domain function: hrv_timedomain, hrv_frequencydomain and hrv_nonlinear (https://github.com/scientisst/BioSPPy/pull/19/commits/e55158e4d532e111f59cb45d21fb5045af3f930d). Tell me if you agree with this approach.