[REVIEW]: HRV: a Pythonic package for Heart Rate Variability Analysis

[whedon]

Submitting author: @rhenanbartels (Rhenan Bartels) Repository: https://github.com/rhenanbartels/hrv Version: 0.2.8 Editor: @Kevin-Mattheus-Moerman Reviewers: @paulvangentcom, @Kevin-Mattheus-Moerman Archive: 10.5281/zenodo.3960216

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/62c8ad17a3fdb61dcb73b34f61ef0f18"><img src="https://joss.theoj.org/papers/62c8ad17a3fdb61dcb73b34f61ef0f18/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/62c8ad17a3fdb61dcb73b34f61ef0f18/status.svg)](https://joss.theoj.org/papers/62c8ad17a3fdb61dcb73b34f61ef0f18)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@hooman650 & @PGomes92 & @paulvangentcom, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @Kevin-Mattheus-Moerman know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @hooman650

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [ ] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [ ] Contribution and authorship: Has the submitting author (@rhenanbartels) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [ ] Functionality: Have the functional claims of the software been confirmed?
• [ ] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [ ] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [ ] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [ ] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [ ] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [ ] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [ ] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [ ] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [ ] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @PGomes92

Conflict of interest

• [ ] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [ ] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [ ] Repository: Is the source code for this software available at the repository url?
• [ ] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [ ] Contribution and authorship: Has the submitting author (@rhenanbartels) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [ ] Installation: Does installation proceed as outlined in the documentation?
• [ ] Functionality: Have the functional claims of the software been confirmed?
• [ ] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [ ] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [ ] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [ ] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [ ] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [ ] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [ ] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [ ] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [ ] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @paulvangentcom

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@rhenanbartels) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @Kevin-Mattheus-Moerman

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@rhenanbartels) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @hooman650, @PGomes92, @paulvangentcom it looks like you're currently assigned to review this paper :tada:.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[Kevin-Mattheus-Moerman]

@hooman650, @PGomes92, @paulvangentcom thanks for agreeing to review this work. You have instructions and check-boxes at the top of this issue to guide you through the process. You can comment on this submission in this review issue. For longer/larger issue we suggest you open an issue on the project repository instead and link to it here. We also encourage you to make use of checkboxes in your comments so it is easy to keep track of steps/comments the author still needs to work on. You can do this using - [ ].

Let me know if you have questions.

[Kevin-Mattheus-Moerman]

@hooman650, @PGomes92, @paulvangentcom thanks for your help in reviewing this work! Can you give an update on review progress? @paulvangentcom I see you've started and have been ticking boxes. Please list any issues you've identified if any, so @rhenanbartels can start working on them. Tanks!

[hooman650]

I have opened an issue in the toolbox repository. There are many HRV toolboxes available that exactly perform the same computations (time, frequency and nonlinearity analysis). I recommend adding a few subroutines for preprocessing RR intervals and removing artifacts. I have opened an issue and made a few recommendations there.

Additionally, contribution guidelines are missing.

[danielskatz]

👋 @Kevin-Mattheus-Moerman - How is this review going?

[paulvangentcom]

Thanks for the reminder. I'll wrap up the review tomorrow.

[paulvangentcom]

I think the paper can benefit from additional integration with existing literature, especially a more recent state of the field.

Although many toolboxes exist to work with PPG, ECG, or the resulting tachograms, I think hrv can play a role here as an accessible toolbox for those already having tachograms available and only need to analyse these.

The software needs to be documented with proper docstrings in the code, and the documentation be migrated to for example readthedocs. Unit tests are missing as is continuous integration and an overview of the Python versions that are supported.

I'll open issues for this on the repo.

[Kevin-Mattheus-Moerman]

@rhenanbartels can you respond to the reviewers comments/issues and summarize your actions here? Thanks :christmas_tree:

[rhenanbartels]

Hi @Kevin-Mattheus-Moerman, regarding issue 16 and Issue 17, I've implemented features for artifact and baseline trend removal, and I've worked on documentation-related and CI features, respectively:

Already concluded

Issue 16 - Suggested by @hooman650

Filter

• threshold_filter: inspired in Kubios threshold based artefact correction algorithm, each RRi is compared to a local value consisting of the median of adjacent RRi. If the difference between RRi and the local median is greater than a given threshold in milliseconds this RRi is considered an ectopic beat. Ectopic RRi values are replaced with cubic spline interpolation of the entire tachogram.

Trend removal

• polynomial_detrend: fits a polynomial model of a given degree to the tachogram and remove it from each RRi values.
• smoothness_priors: widely used in hrv analyses, acts as a lowpass filter and remove complex trends from the RRi series
  • sg_detrend: uses the savitzky-golay lowpass filter to remove low-frequency trends from the RRi series

Issue 17 - Suggested by @paulvangentcom

• A Docstring for every main function of the submodules
• The project to travis-ci and added the badge to README
• The project to codecov with tests coverage status and its respective badge
• The Badge telling the supported Python version
• Sample data: i.e from hrv.sampledata import load_rest_rri
• Moved the documentation to readthedocs

Next steps

During the following days, I will work on the improvements (suggested by @paulvangentcom) of the article's text and I will add the new features available in the 0.2.5 version of the hrv module, such:

• Add the Ponicaré Plot
• Add a Pre-processing section
• Improve the Non-linear analysis section
• Emphasize the importance of the hrv module

Cheers,

Rhenan

[rhenanbartels]

Hi @Kevin-Mattheus-Moerman,

I've just put the finishing touches on the article`s text. It is already available in the develop branch in the repo. What is the next step?

Best, Rhenan

[Kevin-Mattheus-Moerman]

@hooman650, @PGomes92, @paulvangentcom thanks for your help so far. The author has made various changes to address your comments. Can you please pick up the review at this point and review these changes? Please summarize any remaining issues you might have. Thanks!

[Kevin-Mattheus-Moerman]

@hooman650, @PGomes92, @paulvangentcom :point_up: can you check the above? Thanks

[Kevin-Mattheus-Moerman]

@hooman650, @paulvangentcom can you check on the above?

[Kevin-Mattheus-Moerman]

@PGomes92 are you still able to assist with this review? If so, when do you think you will be able to complete your side of the review? Thanks.

[paulvangentcom]

@Kevin-Mattheus-Moerman I outlined two final points to Rhenan, and pending these two small changes I'm satisfied with the made changes

[Kevin-Mattheus-Moerman]

@paulvangentcom thanks for your help here! I take it these are issues posted on the project repository? It would be great if you could link to them here. @rhenanbartels Are you able to follow up on @paulvangentcom 's comments/issues? Thanks!

[rhenanbartels]

@Kevin-Mattheus-Moerman Sure! I will work on the suggestions in the upcoming days.

[paulvangentcom]

@Kevin-Mattheus-Moerman yes these are on the repo, appended to the same issue as before

[Kevin-Mattheus-Moerman]

@rhenanbartels any updates on progress?

[rhenanbartels]

Hi @Kevin-Mattheus-Moerman, I've just pushed the suggestions made by @paulvangentcom.

Cheers,

Rhenan

[Kevin-Mattheus-Moerman]

@paulvangentcom can you check these new developments? :point_up:

[paulvangentcom]

Yes agreed, the changes are good as far as I'm concerned. Thanks for guiding the process @Kevin-Mattheus-Moerman , and thanks for the work @rhenanbartels

[Kevin-Mattheus-Moerman]

Thanks @paulvangentcom!

[Kevin-Mattheus-Moerman]

@hooman650 can you also review the recent changes and summarize any remaining points you have. Thanks!

[Kevin-Mattheus-Moerman]

@PGomes92 please can you finalize your review as soon as possible. Thanks

[arfon]

Dear authors and reviewers

We wanted to notify you that in light of the current COVID-19 pandemic, JOSS has decided to suspend submission of new manuscripts and to handle existing manuscripts (such as this one) on a "best efforts basis". We understand that you may need to attend to more pressing issues than completing a review or updating a repository in response to a review. If this is the case, a quick note indicating that you need to put a "pause" on your involvement with a review would be appreciated but is not required.

Thanks in advance for your understanding.

Arfon Smith, Editor in Chief, on behalf of the JOSS editorial team.

[arfon]

:wave: @PGomes92 @hooman650, just a friendly check-in to see how things are going with your reviews?

[Kevin-Mattheus-Moerman]

@PGomes92 @hooman650 can you please finalize the review process or else let us know if you are still able to review this submission? Thanks.

[Kevin-Mattheus-Moerman]

@PGomes92 @hooman650 I hope and yours are doing well. Can you give an indication as to when you can resume this review? Thanks again for your help.

[Kevin-Mattheus-Moerman]

@PGomes92 @hooman650 if you are still able to help with this review please indicate this to us now. If I do not hear from you within the next 2 days I will proceed to unfortunately remove you as reviewers for this submission.

[Kevin-Mattheus-Moerman]

@whedon generate pdf

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[Kevin-Mattheus-Moerman]

@whedon remove @PGomes92 as reviewer

[whedon]

OK, @PGomes92 is no longer a reviewer

[Kevin-Mattheus-Moerman]

@whedon remove @hooman650 as reviewer

[whedon]

OK, @hooman650 is no longer a reviewer

[rhenanbartels]

Hi @Kevin-Mattheus-Moerman, how are you doing? I hope everything is fine.

Are there any further steps for the paper review? Let me know if there is anything I need to do.

Cheers!

[Kevin-Mattheus-Moerman]

@whedon add @Kevin-Mattheus-Moerman as reviewer

[whedon]

OK, @Kevin-Mattheus-Moerman is now a reviewer

[Kevin-Mattheus-Moerman]

@rhenanbartels I added myself as reviewer since the other reviewers dropped out. I installed the software successfully and have started testing. A couple of boxes are unticked.

• [x] A statement of need Both the readme and the first page of the documentation simply state: hrv is a simple Python module that brings the most widely used techniques to work with RRi series and Heart Rate Variability (HRV) analyses without losing the Power and Flexibility of a native Python object and numpy arrays. Can you expand both to more clearly state what the software functionality addresses?

• [x] Although the documentation seems to cover all functionality it seems to contain mainly snippets of code. Perhaps I am not interacting with your documentation properly but to test things I found myself copy-pasting these into my Spyder IDE to run them. Could you offer test scripts to users in a more direct way? It would be great to have files that test the functionality fully which users can run. Also some of the documentation contains this as example data:

  rri = RRi([800, 810, 815, 750, 753, 905])

  This works for showing how to use the code components but is quite limited for testing the functionality. Could you add in the tests some more advanced examples containing larger test data sets? Or define it more clearly if you have it already? This is just a suggestion but would it be easy to create a single Jupyter notebook that covers all functionality (perhaps combining the code snippets from the documentation) which also loads example datasets?

• [x] Can you tell me where to find and study automated tests? Perhaps consider my above comments and add a testing section to the documentation. I see there is a "running the tests" section, but this seems to be for more advanced users. Perhaps consider (recommendation not requirement) add (e.g. in the form of a jupyter script) a simple test set and demo for new users?

Thanks

[Kevin-Mattheus-Moerman]

@rhenanbartels apologies for the delay with this submission. With the pandemic our journal, editors (myself included), and reviewers have found it challenging to keep things going at a normal pace. Your submission was particularly "badly hit" it seems as unfortunately two reviewers became unresponsive. I just wanted to apologize for this and add that I am committed to provide a fast review here and to also stay on top of editing this submission as fast as possible.

[Kevin-Mattheus-Moerman]

@rhenanbartels did you see my comments :point_up:

[rhenanbartels]

Hi @Kevin-Mattheus-Moerman, yeah!

Thank you very much for the comments. I really liked the idea of creating a Jupyter Notebook with some real use cases. I am going to work on it and on the other suggestions during the following week.

Cheers!

[rhenanbartels]

Hi, @Kevin-Mattheus-Moerman

I've just added a Jupyter notebook containing a walkthrough with the main steps of the pipeline for analyzing RRi/HRV signals (the same first steps we use in our studies in our Lab):

• Reading a file from the File System containing the information of the fluctuations of the heartbeats;
• Inspecting and visualizing the signal to check if everything is according to the expected;
• Filtering ectopic beats;
• Selecting two smaller segments of the filtered signal;
• Extracting Time and Frequency Domain features;
• Comparing the results extracted from each segment.

Additionally, there is also an example of one of the techniques applied to extract information about the dynamics of non-stationary RRi signals.

I will create more Jupyter notebooks as new features are added to the module. It is a great way to show its application in real scenarios and to be more intuitive for new users.

#

Regarding the statement of need, I've added, on both Docs and README, a complementary sentence that expands the description of the software functionality, which is: a module for inspecting, visualizing, pre-process, and analyze HRV analyses written in idiomatic Python.

Thank you very much for your suggestion and let me know if any other update is needed.

Cheers,

Rhenan

[Kevin-Mattheus-Moerman]

@rhenanbartels thanks. I checked out the Jupyter notebook. It looks great! I do get an error on the last two cells:

Any clue as to what is going on?

[Kevin-Mattheus-Moerman]

@whedon generate pdf

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[Kevin-Mattheus-Moerman]

@whedon check references