Add and clarify RSP features

[zen-juen]

See https://github.com/neuropsychology/NeuroKit/projects/4#card-67978636 and #528

[codecov-commenter]

Codecov Report

Merging #536 (0732ccd) into dev (9bf9532) will increase coverage by 0.00%.
The diff coverage is 89.47%.

@@           Coverage Diff           @@
##              dev     #536   +/-   ##
=======================================
  Coverage   85.30%   85.30%           
=======================================
  Files         199      199           
  Lines        9772     9782   +10     
=======================================
+ Hits         8336     8345    +9     
- Misses       1436     1437    +1     

Impacted Files	Coverage Δ
neurokit2/rsp/rsp_findpeaks.py	77.77% <ø> (ø)
neurokit2/rsp/rsp_fixpeaks.py	100.00% <ø> (ø)
neurokit2/rsp/rsp_peaks.py	100.00% <ø> (ø)
neurokit2/rsp/rsp_process.py	100.00% <ø> (ø)
neurokit2/rsp/rsp_rrv.py	63.79% <80.00%> (ø)
neurokit2/rsp/rsp_eventrelated.py	100.00% <100.00%> (+5.55%)	⬆️
neurokit2/rsp/rsp_plot.py	94.11% <100.00%> (ø)
neurokit2/hrv/hrv_time.py	98.07% <0.00%> (-0.94%)	⬇️
neurokit2/rsp/rsp_simulate.py	93.75% <0.00%> (-0.90%)	⬇️
neurokit2/hrv/hrv_utils.py	71.21% <0.00%> (-0.46%)	⬇️
... and 5 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9bf9532...0732ccd. Read the comment docs.

[zen-juen]

@DominiqueMakowski @shanelindsay I've changed all (I think) instances of "inhalation peaks" and "exhalation troughs", to "peaks (exhalation onsets)" and "troughs (inhalation onsets)" respectively in the docstrings. The explicit labelling of onsets is done only in rsp_plot and I left the namings in the generated signal columns/dictionary info as they are (i.e., RSP_Peaks and RSP_Troughs) since it seems more consistent with our API like that. rsp_rrv() also now correctly uses troughs rather than peaks. However, I was wondering does this affect the computation of respiratory rate using rsp_rate()? 🤔 There are currently two methods:

NeuroKit/neurokit2/rsp/rsp_rate.py

Lines 24 to 28 in c110438

	method : str
	Method can be either "peak" or "xcorr". In "peak" method, rsp_rate is calculated from the
	periods between respiration peaks. In "xcorr" method, cross-correlations between the changes
	in respiration with a bank of sinusoids of different frequencies are caclulated to indentify
	the principal frequency of oscillation.

The latter is independent of the indices but for the former, does it matter whether periods are computed from peaks or troughs?

[zen-juen]

However, I was wondering does this affect the computation of respiratory rate using rsp_rate()? 🤔 There are currently two methods:

To follow up on the question I raised earlier, here's a visualization of the differences in instantaneous rsp rate computed from peaks vs. troughs

[DominiqueMakowski]

orange is peaks or troughs?

[zen-juen]

Oops I can't remember but here's a new short example 😄

rsp = nk.rsp_simulate(duration=100)
rsp_cleaned = nk.rsp_clean(rsp, sampling_rate=1000)
_, info = nk.rsp_peaks(rsp_cleaned, sampling_rate=1000)
rate_from_peaks = nk.signal_rate(info["RSP_Peaks"], sampling_rate=1000, desired_length=len(rsp_cleaned))
rate_from_troughs = nk.signal_rate(info["RSP_Troughs"], sampling_rate=1000, desired_length=len(rsp_cleaned))
nk.signal_plot([rate_from_peaks, rate_from_troughs], labels=['Peaks', 'Troughs'])

[DominiqueMakowski]

I'd go with throughs, since it's true that a "breathing cycle" would start with inspiration (and hence a through), so it would conceptually make sense to have rsp rate defined as trough to trough. But then this is from the top of my head, I'm sure in papers they talk about how they compute it (in the case of respi belts)

[zen-juen]

See https://ieeexplore.ieee.org/abstract/document/7985893 🤔 (and https://www.degruyter.com/document/doi/10.1515/cdbme-2016-0054/html)

Researchers have tried different approaches to estimate the
respiration rate from the extracted respiration signal. Based on
the literature, the use of the signal auto-correlation has proven
to be efficient for respiration rate estimation [13]–[15]. In this
paper, the auto-correlation is used to estimate the respiration
rate from the signals produced by both combining methods, as
well as for the gold standard signal from the belt system