[REVIEW]: Histogram-weighted Networks for Feature Extraction, Connectivity and Advanced Analysis in Neuroscience

[whedon]

Submitting author: @raamana (Pradeep Reddy Raamana)
Repository: https://github.com/raamana/hiwenet
Version: 0.4
Editor: @cMadan
Reviewer: @oesteban
Archive: 10.5281/zenodo.1064012

Status

Status badge code:

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

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 questions

@oesteban, please carry out your review in this issue by updating the checklist below (please make sure you're logged in to GitHub). The reviewer guidelines are available here: http://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @cMadan know.

Conflict of interest

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (such as being a major contributor to the software).

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: Does the release version given match the GitHub release (0.2.2)?
• Authorship: Has the submitting author (@raamana) 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: Have any performance claims of the software been confirmed?

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. I'm here to help you with some common editorial tasks for JOSS. @oesteban 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 as reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all JOSS 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

[cMadan]

@oesteban, it would be great if you could work through the reviewer checklist in the first comment and see if the submission addresses each point sufficiently. If not, please post issues in the submission's repo or here, as makes sense and hopefully @raamana can respond accordingly.

@JohnGriffiths, if you have time, it would still be great if you can also take a look at the submission too (even though you're not officially assigned as a reviewer).

[raamana]

Thanks Chris. Look fwd to hearing from @oesteban and/or @JohnGriffiths .

[oesteban]

I want to get this review done today :). If time does not permit, I will secure tomorrow for it.

…

On Wed, Aug 30, 2017 at 8:26 AM, Pradeep Reddy Raamana < ***@***.***> wrote: Thanks Chris. Look fwd to hearing from @oesteban <https://github.com/oesteban> and/or @JohnGriffiths <https://github.com/johngriffiths> . — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#380 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAkhxibxTdFliKlIMTOfxUcB6Jgkt5Yvks5sdX84gaJpZM4PDqpS> .

[raamana]

Take your time Oscar, no hurry.

[oesteban]

Review comments

General

This submission describes a software tool to calculate histogram weighted networks (HiWiNet). As far as I understood the code, the core of the tool is the extract function which takes an array of features and generates the corresponding network. To do so, the software strongly relies on the histogram distance implementation of medpy. The submission includes a command line interface so that the users can run the software directly on a shell prompt with text files for inputs and outputs.

In my opinion, this submission can be accepted after a Major revision responding to the points raised in the issues enlisted above. Particularly, the editors of JOSS may want to track raamana/hiwenet#8 closely, as I think we hit there an area of JOSS' requirements for submissions which is (at the very least) gray and confusing - just a spoiler: what is a "minor" 'utility'?, what is exactly a utility?, and when a utility is a minor contribution?.

Open questions

• The Paper.md and the README of this project are twins, and I think they should be dissociated. Particularly, because for now there is no clear definition of the functionality of the software, and all descriptions derive from a corresponding pre-print. The statement of need will require some maturation and work to make it explicit and accurate.
• Implementing a real "smoke test" is at reach, and I think necessary for this project.

Items that need work (as per the checklist above)

Functionality

• Functionality: Have the functional claims of the software been confirmed?
• Performance: Have any performance claims of the software been confirmed?

• A more precise definition of the functionality should be done to evaluate this point.
• No performance claims are done, so it would be nice to include some. Particularly interesting is the cross-comparison to the former implementation in Matlab that I suggested.

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?

The statement of need is a bit unclear. I think the automated tests need a "smoke test" at the least.

Software paper

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

The Paper.md needs to be made clearer, more exact and follow closer the guidelines, instead of just mirroring of the README of the project..

[cMadan]

Thank you for the detailed comments, @oesteban! I have provided some additional (and convergent) comments here raamana/hiwenet#8 (comment).

[oesteban]

I think this is finished.

[cMadan]

Everything looks good to me!

@raamana, could you mint a new release and provide me with the associated DOI?

[raamana]

Here is the new final DOI: 10.5281/zenodo.1064012

Thank a lot Oscar and Chris, your review and suggestions helped improve the software greatly.

[raamana]

This DOI corresponds to the latest GitHub release tagged 0.4.

Also wouldn't JOSS be providing another DOI upon publication?

[cMadan]

@whedon set 10.5281/zenodo.1064012 as archive

[whedon]

OK. 10.5281/zenodo.1064012 is the archive.

[cMadan]

@raamana, perfect! I've set the archive DOI and updated the version number. The archive DOI is for the software release, whereas the JOSS DOI will be for the paper. (There are also different kinds of DOIs--DataCite vs. CrossRef--which have differences in how their associated metadata and how they are processed by services like Google Scholar and PubMed.)

@arfon, we're all set to accept here!

[raamana]

Thanks for the clarification and the review oversight.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00380/joss.00380/10.21105.joss.00380.pdf

[raamana]

The PDF produced doesn't look right - image not aligned. I've updated it to try more space around it, and improved the text a bit more. If possible, it may be better to try generate the PDF again.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00380/joss.00380/10.21105.joss.00380.pdf

[arfon]

@raamana - the figure has now flowed onto the next page (which might be OK?). If this works for you, perhaps you should just change the previous sentence to 'Rough scheme of computation shown in Figure 1'

[raamana]

sure, updated it now. thanks.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00380/joss.00380/10.21105.joss.00380.pdf

[arfon]

@oesteban - many thanks for your review here and to @cMadan for editing this submission ✨

@raamana - your submission is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00380 ⚡️ 🚀 💥