[REVIEW]: CusToM: a Matlab toolbox for musculoskeletal simulation

[whedon]

Submitting author: @anmuller (Antoine Muller)
Repository: https://github.com/anmuller/CusToM.git
Version: v1.1.0
Editor: @Kevin-Mattheus-Moerman
Reviewers: @modenaxe, @demotu, @nicoguaro
Archive: 10.5281/zenodo.2543645

Status

Status badge code:

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

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) 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

@modenaxe & @demotu, 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.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @Kevin-Mattheus-Moerman know.

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

Review checklist for @modenaxe

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: v1.1.0
• Authorship: Has the submitting author (@anmuller) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @demotu

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: v1.1.0
• Authorship: Has the submitting author (@anmuller) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @nicoguaro

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: v1.1.0
• Authorship: Has the submitting author (@anmuller) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @modenaxe, it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

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

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

--> Check article proof 📄 <--

[Kevin-Mattheus-Moerman]

@modenaxe, @demotu this is where the review will take place. You each have a set of check boxes at the top of this issue to guide you through the review process. Please let me know if you have any questions or check the review guidelines. Thanks! 🚀 🤖

[Kevin-Mattheus-Moerman]

@demotu We will get started here already but it is fine if you join the review process in October. Thanks.

[Kevin-Mattheus-Moerman]

@anmuller this is where the review process takes place so please keep an eye out for notifications from this issue. Here are some initial comments/questions I have:

1. Is this submission compatible with Octave?
2. Can you please work on adding community guidelines? I recommend adding a CONTRIBUTING.md and a CODE_OF_CONDUCT.md file.
   https://help.github.com/articles/setting-guidelines-for-repository-contributors/
   You can get a template for the code of conduct file from here: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
   E.g. check out how my personal project has these files:
   https://github.com/gibbonCode/GIBBON

[anmuller]

@Kevin-Mattheus-Moerman, I am sorry but it is not compatible with Octave. Thank you for your recommendations about community guidelines, I am going to work it.

[modenaxe]

I just started checking the paper and the material. It's the first time I review for JOSS, so please be patient with me @Kevin-Mattheus-Moerman if I involve you at times :)

General checks

• The repository should have a release version number.
• I assume @anmuller has made major contributions to the software, as he is submitting it and the paper cites several publications where he is first author. However, the repository has no history and the functions have no author(s) in the header. @Kevin-Mattheus-Moerman is there some requirement in this respect?

Functionality
I installed the toolbox has described in the documentation (just adding the 'Function' folder to the path and ensuring I have all the toolboxes). Then I run 'GenerateParameters.mlapp': the GUI appears but any attempt to use it generates errors. I will follow up in the toolbox repository opening an issue.

Documentation

• please mention who your target audience is.
• please list explicitly the dependencies of the toolbox. Currently, in the 'installation instructions' section, it is unclear if the additional Matlab Toolboxes are required for having CusToM working or working 'efficiently', e.g. faster processing.
• the title of section 3 should be modified from 'Application Programming Interface' to 'Graphical User Interface'.
• I think you should specify in the guide that 'GenerateParameters' is in the 'Interface' folder (I assume that is the file you suggest to run in the guide).
  I will comment on the rest of the guide after I manage to have the toolbox running.

Software paper
Just few comments:

• missing comma after 'body parts'.
• 'thanks to' I would mention explicitly BTK before citing the paper.
• there is a missing reference just after 'inverse dynamics step'.
• 'Antoine Muller et al. 2017': Please make citation style consistent throughout the manuscript.
• Figure 1 is not referenced in the paper and it would be more clear if it was specified explicitly what the external inputs of the boxes are, as in the similar Figure that you have in Muller, Hearing et al. 2017.

[anmuller]

@modenaxe thank you for your review. What are the errors that appeared when you run 'GenerateParameters.mlapp'?

[modenaxe]

I have posted them as an issue in the repository, let me know if you want more details.

[Kevin-Mattheus-Moerman]

@nicoguaro would you be interested in joining this review process? I can add you as a reviewer if so.

[Kevin-Mattheus-Moerman]

@anmuller can you give an update as to how you are getting on in terms of replying to the issues raised?

[Kevin-Mattheus-Moerman]

@demotu how are you getting on? Could you give an indication as to when you will complete the review process? Thanks.

[modenaxe]

I am updating my comments after testing the revised toolbox. @anmuller my comments follow exactly the guidelines and checkboxes above. @Kevin-Mattheus-Moerman this is currently my complete review, excluding the issues that I will post in the repository directly.

General checks

• The repository should have a release version number.
• I assume @anmuller has made major contributions to the software, as he is submitting it and the paper cites several publications where he is first author. However, the repository has no history and the functions have no author(s) in the header. I would add the author to the file headers.

Functionality
I find challenging to test the functionalities using my own data, mainly due to the documentation, which consists in descriptions of the tabs, but does not help getting started with the toolbox. The included examples do not help much either, as loading the mat file for the analysis and visualisation steps seems to throw errors (which I will report as issues in the repository).

Documentation

• please mention who your target audience is.
• please list explicitly the dependencies of the toolbox. Currently, in the 'installation instructions' section, it is unclear if the additional Matlab Toolboxes are required for having CusToM working or working 'efficiently', e.g. faster processing.
• the title of section 3 should be modified from 'Application Programming Interface' to 'Graphical User Interface'.
• In almost all occasions in which you are referring 'saving/running/modifying a file in the corresponding folder' I think you should specify to which file and folder you are referring to, so helping the users. I will post a related issue about reading c3ds in the repository.
• as mentioned above the documentation is descriptive but does not include a real step-by-step example or automated tests to verify the functionality of the code. i think a step-by-step example is crucial here.
• Community guidelines for contributions/reporting issues/seeking support are currently missing.

Software paper
Just few comments:

• missing comma after 'body parts'.
• 'set of muscles': I would add a reference to the anatomical datasets you implemented here.
• 'thanks to' I would mention explicitly BTK before citing the paper.
• there is a missing reference just after 'inverse dynamics step'.
• 'Antoine Muller et al. 2017': Please make citation style consistent throughout the manuscript.
• Figure 1 is not referenced in the paper and it would be more clear if it was specified explicitly what the external inputs of the boxes are, as in the similar Figure that you have in Muller, Hearing et al. 2017.

[nicoguaro]

@Kevin-Mattheus-Moerman, I think I can. I have a question, though, is MATLAB necessary for the software or can it be used with Octave? If MATLAB is required, what is the minimum version needed?

Also, from just checking the README in the repo I can't find installation instructions for the package. Or a simple example for "starters". I also suggest to format the README to take advantage of Markdown.

[Kevin-Mattheus-Moerman]

@whedon add @nicoguaro as reviewer

[whedon]

OK, @nicoguaro is now a reviewer

[Kevin-Mattheus-Moerman]

@nicoguaro there is now also a checklist for you at the top of this issue. Yes I believe MATLAB is required. @anmuller can you comment on what version is required?

[anmuller]

It was implemented and tested with Matlab2018a. Also the Symbolic Math, the Optimization and the Parallel Computing toolboxes are necessary

[nicoguaro]

@anmuller I have access to Matlab2017a, is that OK.

I can't find installation instructions and a test script to check that things work.

[anmuller]

@nicoguaro Maybe you can use Matlab2017a but I can't ensure you it works.
The installation only consists in adding the folder \CusToM\Functions and its subfolders to the Matlab path. You can check your Matlab version by just running the function "Main" having previously set your current folder as Examples/Cycling or Examples/ROM.
If you are interesting, we created a very quick example of the use of an exemple :
https://drive.google.com/file/d/1_zpWBwQ-S9pBaHbCBJj0qKMDQoVt02PC/view
In the video, all the CusToM folders were added in the path but you have just to add the Functions folders as detailed previously.

[nicoguaro]

@anmuller, I consider that both the installation instructions and example should be in the repo. Hopefully, in the README.

[labarba]

@whedon set v1.1.0 as version

[whedon]

OK. v1.1.0 is the version.

[labarba]

@anmuller — The DOI link on your reference list for Featherstone (2008) points to a book titled "Robot Dynamics Algorithms." Did you get the title wrong?
https://doi.org/10.1007/978-0-387-74315-8

Also, it looks like the book does not have 272 pages—and please use a ~ to get the spacing right: (p.~272).

[labarba]

Finally, journal titles are capitalized in English-language publication. You're mixing English and French conventions. Please capitalize throughout.

[Kevin-Mattheus-Moerman]

@labarba correct there was an issue with Linux and this limitation was added to the descriptions/documentation. Rather than removing the reviewer I thought it best to leave these statements for the record.
Thanks for addressing those additional editorial points that I missed.

[anmuller]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[anmuller]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[anmuller]

@labarba thanks for your comments.
Actually the DOI for the reference Featherstone was wrong and it was corrected. The other changes you mentionned were done. We hope that everything is good.

[labarba]

Great. Glad I caught that reference oops.

I do have a couple more editorial fixes:

• You have a few multi-cites that appear thus: (Yo, 2018) (Fu, 2019) — to get the citations into one set of parenthesis, use Blah blah [@smith04; @doe99] in your source. See Citation Syntax.

Par. 1:

• "performing inverse dynamics based musculoskeletal analyzes" >> performing inverse-dynamics-based musculoskeletal analyses ... (hyphen in the compound modifier, and s in analyses, for the noun 'analysis' in plural: the z is for the verb 'analyze')
• "solve from motion capture data inverse kinematics" >> solve from motion-capture data inverse kinematics (hyphen on compound modifier; otherwise we don't know if it's 'motion-capture data' or 'data-inverse kinematics')
  In fact, I find several places where the compound adjective is without hyphen, making the meaning harder for the reader.

Par. 2:

• The "Then," at start of sentences is superfluous.
• "It consists in finding" >> consists of

Par. 3:

• "CusToM can easily performs" >> perform
• "analyzes" >> analyses (verb vs. noun)
• "let the user being as free" >> let the user be
• "and set of muscles are de ned as bricks customizable and adaptable with each other" >> Huh??

Finally, a gentle suggestion to strip out some of the unnecessary passive voice; e.g., "A user interface has been developed…" >> by whom?
(My favorite reminder is: if you can add "by zombies" at the end of a sentence, it's probably in passive voice!)

[anmuller]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[anmuller]

@labarba thanks again for the comments and for the advices. The changes were done.

[labarba]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof 👉 openjournals/joss-papers#447

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#447, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[labarba]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.00927 joss-papers#448
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.00927
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

[labarba]

Congratulations, @anmuller, your paper is published in JOSS! 🎉

Thank you, gracias, merci to your handling editor, @Kevin-Mattheus-Moerman, and your reviewers, @modenaxe, @demotu, @nicoguaro 🙏

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](http://joss.theoj.org/papers/10.21105/joss.00927/status.svg)](https://doi.org/10.21105/joss.00927)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.00927">
  <img src="http://joss.theoj.org/papers/10.21105/joss.00927/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: http://joss.theoj.org/papers/10.21105/joss.00927/status.svg
   :target: https://doi.org/10.21105/joss.00927

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3Nzk=

[anmuller]

Thanks very much @labarba, @Kevin-Mattheus-Moerman, @modenaxe, @demotu, @nicoguaro for all your advices and the time spent on this review.