Jointly: A Python Package for synchronizing multiple sensors with accelerometers

[enra64]

Submitting Author: Arne Herdick (@enra64)
All current maintainers: @enra64, @arianesasso
Package Name: Jointly
One-Line Description of Package: Jointly is a python package for synchronizing sensors with accelerometer data
Repository Link: https://github.com/hpi-dhc/jointly
Version submitted: 1.0.2
Editor: @xmnlab
Reviewer 1: @AlexS12
Reviewer 2: @arthur-e
Archive:
JOSS DOI: N/A
Version accepted: 1.0.3
Date Accepted: 12/29/2021

---

Description

• Include a brief paragraph describing what your package does:

jointly is a python package for synchronizing devices that contain accelerometer sensors. For example, if you shake all your devices together before and after a study, jointly will find these shakes, remove any temporal offset between the sensors, and stretch the data so every clock aligns to a reference sensor. Jointly ingests and produces pandas' DataFrame objects.

Scope

• Please indicate which category or categories this package falls under:
  • Data retrieval
  • Data extraction
  • Data munging
  • Data deposition
  • Reproducibility
  • Geospatial
  • Education
  • Data visualization*

* Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see notes on categories of our guidebook.

• Explain how the and why the package falls under these categories (briefly, 1-2 sentences):
  This package was developed to synchronize multiple sensors together. Our usecase was to synchronize 6 IMUs to an ECG sensor with an IMU, all of which were worn by a participant during our study.

• Who is the target audience and what are scientific applications of this package?
  The target audience is fellow researchers trying to achieve high-quality synchronization for multiple study devices that also have an Accelerometer.

• Are there other Python packages that accomplish the same thing? If so, how does yours differ?

To our current knowledge, none exist.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has an OSI approved license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.

Publication options

• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI:

Note: Do not submit your package separately to JOSS

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Code of conduct

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

P.S. *Have feedback/comments about our review process? Leave a comment here

Editor and Review Templates

Editor and review templates can be found here

[lwasser]

hey there @enra64 !! thank you for this submission! we will review it and get back to you with next steps. Welcome to pyopensci!

[enra64]

Thank you 🙂

[lwasser]

hi @enra64 @xmnlab will serve as your fearless editor for this submission... more from them soon!

[xmnlab]

@enra64 thank you for submitting your package to PyOpenSci!
I will start to check some points today and I will keep you updated here :)

[enra64]

Thanks @xmnlab and @lwasser, looking forward to it :)

[xmnlab]

Editor checks:

• Fit: The package meets criteria for fit and overlap.
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service.
  • GitHub Actions
• Documentation: Package has documentation setup (ReadTheDocs, JupyterBook, website,etc.).
  • https://jointly.readthedocs.io/
• License: The package has an OSI accepted license
  • - MIT
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

Thank you @enra64 for submitting your project to PyOpenSci! I have some experience with data acquisition and I am very happy to be acting here as editor.

Do you have any suggestion for a reviewer? We often select one reviewer suggested by the package's author and another one will be selected by us. If you don't have any suggestion then I will look for two.

Thank you so much!

---

Reviewers: Alejandro Sáez Mollejo (@AlexS12) and Arthur Endsley (@arthur-e)
Due date: 2021-12-13

[xmnlab]

@AlexS12 as we talked some days ago, we are very happy to have you here reviewing Jointly. thank you!

The PyOpenSci contributing guide is here https://www.pyopensci.org/contributing-guide/intro.html and this is the guide specifically for reviewers: https://www.pyopensci.org/contributing-guide/open-source-software-submissions/reviewer-guide.html

Feel free to ping me anytime when you need any information or help.

I am waiting for the confirmation of one more reviewer and after that, I will update the schedules for this review.

thank you so much for your support :)

[xmnlab]

@enra64 not sure if you were able to check my comment here: #45 (comment).

We often select one reviewer suggested by the package's author and another one will be selected by us. If you don't have any suggestions then I will look for another one. Thank you so much.

[enra64]

Hey, sorry, I forgot about it. I have to say that I don't have a suggested reviewer.

[xmnlab]

no worries at all! So, I will search for one more and I will keep you updated about that. thanks

[xmnlab]

Hi @arthur-e! thank you so much for accepting to be a reviewer for the package Jointly!

I sent you some links but here there are two links you can check before you start.

• The PyOpenSci contributing guide: https://www.pyopensci.org/contributing-guide/intro.html
• The guide specifically for reviewers: https://www.pyopensci.org/contributing-guide/open-source-software-submissions/reviewer-guide.html

Feel free to ping me anytime when you need any information or help.

thank you so much for your support :)

[xmnlab]

@enra64 we have already two reviewers for Jointly, @AlexS12 and @arthur-e!

So, we are now starting the review process, and the deadline for this first stage is on December, 13th.

In general, we aim for 3 weeks for review, 2 weeks for subsequent changes, and 1 week for reviewer approval of changes.

Let me know if you have any questions or comments, please.

[xmnlab]

@AlexS12 and @arthur-e, just a friendly reminder about this review. Let me know if you have any problems with that. thanks

[arthur-e]

Package Review

• As the reviewer I confirm that there are no conflicts of interest for me to review this work.

Documentation

The package must be improved with regards to the following criteria:

• Function Documentation: for all user-facing functions
  • There is a page that lists the functions but there is no documentation.
• Examples for all user-facing functions
  • Perhaps @xmnlab could elaborate here... I'm not sure if these examples are supposed to be in the API documentation or if a comprehensive "vignette" is sufficient.

The package could be improved with regards to the following criteria:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README
  • Both the "problems" and the "target audience" could be elaborated in the first paragraph of the README. Currently, this paragraph describes (adequately) what the package does, but does not describe the wider scientific and technical environment.
• Installation instructions: for the development version of package and any non-standard dependencies in README
  • I was not able to install the package locally (in "editable" mode) due to a lack of support for poetry-core>=1.2.0 in Python 3.8.12. The minimum Python version should probably be specified. As jointly could be installed from PyPI (pip install jointly), perhaps poetry-core>=1.2.0 is not a hard requirement and could be changed.
  • There are "development version" instructions in CONTRIBUTING.rst, however.

The package includes all the following forms of documentation:

• Vignette(s) demonstrating major functionality that runs successfully locally
  • Vignette from the README works great. However, I think that the plot that appears from jointly.plot_reference_columns() should have the axes labeled.
• Community guidelines including contribution guidelines in the README or CONTRIBUTING.
• Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a setup.py file or elsewhere.

README Requirements

The package meets the README requirements below:

• Package has a README.md file in the root directory.
  • (The README is an RST file.)

"The README should include, from top to bottom:"

The package could be improved with regards to:

• The package name
  • I think that "jointly" would be nicer to see at the top instead of "jointly readme".
• Badges for continuous integration and test coverage, a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.)
• Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
  • There is no API documentation beyond what is in the vignette in the README. See "must improve" above.
  • There are very helpful descriptive sections of the documentation (e.g., "Usage", "Background") that should be linked here, e.g., in a bulleted list that could help end-users find them faster; e.g., "How to sync sensors"
• Installation instructions
• Any additional setup required (authentication tokens, etc)
  • Not applicable
• Brief demonstration usage
• Direction to more detailed documentation (e.g. your documentation files or website).
  • Documentation is higher up in the README, which I prefer
• If applicable, how the package compares to other similar packages and/or how it relates to other packages
  • Authors should indicate whether or not this applies.
• Citation information
  • Authors should add a DOI at the top and the example citation at the bottom.

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
Package structure should follow general community best-practices. In general please consider:

• The documentation is easy to find and understand
• The need for the package is clear
• All functions have documentation and associated examples for use

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
  • @xmnlab I have no experience with accelerometers or their data outputs, so I am unable to completely validate the functional claims. However, I have run the vignette and used ipdb to interrogate different data structures. Everything looks busy and interesting!
• Performance: Any performance claims of the software been confirmed.
  • No performance claims were made and the software both installs and runs very quickly.
• Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
  • Please add information to the README on how to run the tests. I have run to Python scripts in the tests folder but there is no output so I don't know if they were successful. A standard test suite framework should have some kind of standard output display. It would also be helpful is there was a single test suite that encompassed all tests (so as to avoid running each test suite separately and possible missing one).
• Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
  • Does not appear to use CI. @xmnlab can you comment on the expectations here? Many CI services are not free, and I would hate for that to be a barrier to any software published in PyOpenSci.
• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.
  • This would seem to be the sum of every other effort described here, so I would check this off when everything else is done.

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 1 hour (so far).

---

Review Comments

The software itself appears to be of high quality as it both installs and runs quickly and there is judicious use of modularization (at the development level, not user level), abstraction, and type hinting. The code could benefit from more in-line comments and both class-level and module-level docstings, however.

Please comment on "If applicable, how the package compares to other similar packages and/or how it relates to other packages."

[xmnlab]

@arthur-e thank you for your detailed review. I really appreciate that.

I will check detailed the points you mentioned me and I will give more feedback soon.

About CI, generally, the common CI platforms have a free tier with some limitations, but for small projects that is enough.

Jointly is using github actions and you can check that here https://github.com/hpi-dhc/jointly/actions

And the configuration files are available here https://github.com/hpi-dhc/jointly/tree/master/.github/workflows

Let me know if you need any extra information about that or if you have any comment.

Thank you so much!

[enra64]

Hey, thank you very much for the review! As @xmnlab already mentioned, we do use CI, and it's with GitHub actions. Additionally, I would like to mention that we have the relevant metadata in pyproject.toml, which is kinda the equivalent of setup.py for poetry.

As we use the pytest framework, tests can be run by calling py.test in the repository root. I've added this information to CONTRIBUTING.rst.

It's a good hint that the code reference is broken! I've fixed the generation now.

We do have a CITATION.cff file, let me know if that's not sufficient.

[arthur-e]

@enra64 Thanks for fixing the API documentation! It looks like there is an object, jointly.segement_selector, that may not actually exist in the code base. It appears in the documentation, under-specified, because it is written in docs/reference.rst.

[arthur-e]

@enra64 Finally, please add information to the README on how you would like people to cite their use of jointly. For example, some libraries have DOIs that are automatically generated, e.g., by Zenodo, for specific releases and, in addition to a citation example in the README, the DOI is displayed as a badge at the top of the README.

[enra64]

Alright, will do - @arianesasso, can you take over from here?

[arianesasso]

@enra64 @arthur-e Just added the Zenodo badge + the citation at the README :).

[arthur-e]

Great! My recommendation is to accept.

[xmnlab]

thanks @arthur-e for the review and thank you @arianesasso and @enra64 for addressing the points from the review :)

PS: we are still waiting for @AlexS12 's review.

[AlexS12]

Hi there! Sorry for my absence. I have been really busy the last month. Now with Christmas holidays I expect I can finish my review before new year. Would that be ok for you?

Hope to help and sorry again for a so so late response!

[lwasser]

that is just fine @AlexS12 !! thank you for reviewing for us!

[AlexS12]

Hi there! I was starting my review work today and I am having some problems with running the tests. I have just opened an issue hpi-dhc/jointly#10

[AlexS12]

EDIT1: I have added some more comments. New comments are marked with ✏️
EDIT2: Check all missing marks and mark additions with 🖊️

Hi! Here you can find the first round of my review. It is mainly based on the first contact with the package installation and documentation reading (more to come soon). I have left some suggestions below. Not many blocking aspects so far.

I have enjoyed a lot reviewing your package thanks for the contribution!

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README

• Installation instructions: for the development version of package and any non-standard dependencies in README

  • (Could be improved) Add a link to CONTRIBUTING.rst for development installation.

• Vignette(s) demonstrating major functionality that runs successfully locally

  • (Could be improved) Some plots can be added to show the not-synched vs the synched data, peak identification...

• Function Documentation: for all user-facing functions

  • (Must be improved) jointly.helpers.get_segment_data: documentation is missing.
  • (Must be improved) jointly.helpers.get_stretch_factor: only looking at the documentation, it is not clear for me what should be passed as a segment and timeshift. Doc could be improved or an example might be necessary.
  • ✏️ (Must be improved): https://jointly.readthedocs.io/en/latest/reference.html#module-jointly.helpers Helpers section description starts with "Contains plotting helpers". However, no plotting helpers documentation is found here. Given that functions in helpers_plotting.py have a docstring I would add them to the documentation.
  • (Could be improved) jointly.helpers.normalize: normalization formula might be added to doc.
  • (Must be improved) jointly.segment_selectoris empty.

• Examples for all user-facing functions

  • (Could be improved) It might be interesting to show get_sync_params information in the usage example.
  • (Could be improved) Some graphical examples showing successfull and unsuccessfull ShakeExtractor configurations might be useful to understand how the sakes are identified ie. a wrong configuration that might throw a ShakeMissingException. ✏️ I see that functions in helpers_plotting.py might exactly do this.
  • (Could be improved) Examples are missing for:
    • get_equidistant_signals
    • get_max_ref_frequency
    • get_segment_data
    • get_stretch_factor

• Community guidelines including contribution guidelines in the README or CONTRIBUTING.

  • https://jointly.readthedocs.io/en/latest/contributing.html#get-started Good guide! I find that commenting some lines with a small description of what each command is doing might be useful for newcomers.
  • Some projects prefer developers to submit an issue with the new feature suggestion before pull requests with new implementations. If that is your case I would suggest to add an indication.
  • History section is good! I find it more useful when the pull request link is found next to the new features/bugs corrections when applicable. Might be a good idea to incorporate that to the contributing guidelines.
  • Nice to see your code of conduct!! =)

• Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a setup.py file or elsewhere.

Readme requirements
The package meets the readme requirements below:

• Package has a README.md file in the root directory.

The README should include, from top to bottom:

• The package name
• Badges for continuous integration and test coverage, a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.)
• Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
• Installation instructions
• Any additional setup required (authentication tokens, etc)
  • Not applicable.
• Brief demonstration usage
• Direction to more detailed documentation (e.g. your documentation files or website).
• If applicable, how the package compares to other similar packages and/or how it relates to other packages
  • Not applicable.
• Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
Package structure should follow general community best-practices. In general please consider:

• The documentation is easy to find and understand
• The need for the package is clear
• All functions have documentation and associated examples for use
  • See Documentation section in this review.

Functionality

• Installation: Installation succeeds as documented.
  • Problems found to run the tests locally as described in contributing section: ModuleNotFoundError when trying to run pytest hpi-dhc/jointly#10
• Functionality: Any functional claims of the software been confirmed.
  • ✏️ Pending
  • ✏️ See Fix some issues hpi-dhc/jointly#1
  • ✏️ (Could be improved) An equivalent function to plot_reference_columns could be added to plot reference columns on synched_data. That might be helpful to check synchronization.
• Performance: Any performance claims of the software been confirmed.
  • ✏️ Pending
  • ✏️ No performance issues found while using the package.
• Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
  • See ModuleNotFoundError when trying to run pytest hpi-dhc/jointly#10
• Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

✏️ I consider that the initial review is finished. I will keep waiting for the discussion on the open topics to finally approve 🎉
🖊️ Thanks for considering my comments. It has been a pleasure to review your package. Congrats and thank you for the contribution! 🍾

Estimated hours spent reviewing:

• First round: 2 hours
• Second round: 2 hours
• Final checks: 1 hour

[enra64]

Hey @AlexS12, thank you very much for the very detailed review! Regarding the documentation: some of those functions are expected to be used only internally, so the documentation or parameters might seem a bit weird. I've added this information to get_stretch_factor as that might seem especially weird. The test-running examples have been updated, it would be nice if you could test again using conda as I don't have that installed 😅

The changes will be merged via PR hpi-dhc/jointly#12

[xmnlab]

thanks @AlexS12 for the review and thank you @enra64 for addressing the points so quickly.

[AlexS12]

I have just edited my review comments. ✔️ All green from my side! Thanks for your patience... 😳 It has been a pleasure. Congrats and thank you for your contribution! 🍾

[xmnlab]

---

🎉 Jointly has been approved by pyOpenSci! Thank you @enra64 for submitting Jointly and many thanks to @AlexS12 and @arthur-e for reviewing this package! 😸

There are a few things left to do to wrap up this submission:

• Activate Zenodo watching the repo if you haven't already done so.
• Tag and create a release to create a Zenodo version and DOI.
• Add the badge for pyOpenSci peer-review to the README.md of Jointly. The badge should be [![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/45)
• Add Jointly to the pyOpenSci website. @enra64 , please open a pr to update this file: to add your package and name to the list of contributors
• @enra64 @arthur-e @AlexS12, if you have time and are open to being listed on our website, please add yourselves to this file via a pr so we can list you on our website as contributors!

All -- if you have any feedback for us about the review process please feel free to share it here. We are always looking to improve our process and our documentation in the contributing-guide. We have also been updating our documentation to improve the process so all feedback is appreciated!

@lwasser let me know if there is anything else missing from the editor side :)
thank you for all the guidance :)

Thanks everyone! it was a pleasure to be acting here as editor
I hope you all have a great new year 🎉 🎉 🎉

[arianesasso]

Dear @xmnlab, @arthur-e, @AlexS12, and @lwasser, thank you so much for your great work and help!

I hope you had a good start of the year!

I have activated the Zenodo watch, created the release, added the badge, and created the PR :). This review process is awesome and I am looking forward to contributing again 🙌

[xmnlab]

dear @arianesasso, thank you so much. It was great to be acting here as editor :)
I think that the review process is complete now, so I am closing this issue.
feel free to ping me if there is anything missing or any other question.

all the best!

[astrojuanlu]

@xmnlab You forgot to hit the Close button!

[NickleDave]

Maybe @xmnlab wanted to leave this open so everyone could appreciate a nice review 😼

[lwasser]

wow awesome y'all!! @xmnlab thank you for your expert editor leadership here and thank you to all reviewers @arthur-e, @AlexS12 and @arianesasso for this submission to pyopensci!

[xmnlab]

@xmnlab You forgot to hit the Close button!

@astrojuanlu thanks for catching that. I was very sick yesterday and I am still recovering :) so I am a bit slow today XD

@NickleDave thanks for closing the issue :)

[lwasser]

hey 👋 @enra64 @xmnlab @arthur-e @AlexS12 ! I hope that you are all well. I am reaching out here to all reviewers and maintainers about pyOpenSci now that i am working full time on the project (read more here). We have a survey that we'd like for you to fill out so we can:

🔗 HERE IS THE SURVEY LINK 🔗

1. invite you to our slack channel to participate in our community (if you wish to join - no worries if that is not how you prefer to communicate / participate).
2. Collect information from you about how we can improve our review process and also better serve maintainers.
   The survey should take about 10 minutes to complete depending upon how much you decide to write. This information will help us greatly as we make decisions about how pyOpenSci grows and serves the community. Thank you so much in advance for filling it out.

NOTE: this is different from the form designed for reviewers to sign up to review.
IMPORTANT: If there are other maintainers for this project, please ping them here and ask them to fill out the survey as well. It is important that we ensure packages are supported long term or sunsetted with sufficient communication to users. Thus we will check in with maintainers annually about maintenance.

Thank you in advance for doing this and supporting pyOpenSci.

[lwasser]

Good morning @AlexS12 and @enra64 ! just a friendly reminder to take 5-10 minutes to fill out our survey . We really appreciate it. Arne if you can have all of the maintainers of your package fill it out that would be great. We will stay in touch with package authors - checking in 1-2 times a year to ensure the package continues to be maintained and see better understand challenges that you face. Thank you in advance for helping us by filling out the survey!! 🙌

🔗 HERE IS THE SURVEY LINK 🔗