[REVIEW]: GeneNetwork: framework for web-based genetics

[whedon]

Submitting author: @pjotrp (Pjotr Prins)
Repository: https://github.com/genenetwork/genenetwork2
Version: 2.0-a8fcff4
Editor: @arfon
Reviewer: @krother, @agarie
Archive: 10.5281/zenodo.53740

Status

Status badge code:

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

Reviewer questions

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

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 (2.0-a8fcff4)?
• Archive: Does the software archive resolve?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: Have the 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 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

Paper PDF: 10.21105.joss.00025.pdf

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

[arfon]

/ cc @openjournals/joss-reviewers - would anyone be willing to review this submission?

If you would like to review this submission then please comment on this thread so that others know you're doing a review (so as not to duplicate effort). Something as simple as :hand: I am reviewing this will suffice.

Reviewer instructions

• Please work through the checklist at the start of this issue.
• If you need any further guidance/clarification take a look at the reviewer guidelines here http://joss.theoj.org/about#reviewer_guidelines
• Please make a publication recommendation at the end of your review

Any questions, please ask for help by commenting on this issue! 🚀

[krother]

✋ I am reviewing this

[krother]

This is how software papers I like to read should look like!
I have a number of small suggestions:

• 1st par: "experimental data" could be fleshed out in 2-3 words for the biologist reader (is it SNPs, microarray data, NGS, Y2H or manually counted individuals?)
• 2nd par: "can be found in ___ guix-bioinformatics", please insert 'the article', 'the package', 'the lab fridge labeled'.. whichever is aproppriate ;-)
• last par: "Python" is spelled with a capital 'P'
• REST API looks like a very good idea.

[pjotrp]

Thanks @krother for reviewing this very complex project! We'll clarify the text.

Also @agarie promised to review. Do we need a second reviewer?

[krother]

Not necessarily. I think a few of the points above (contribution, mini-summary) could be spelled out in the README.

Apart from that, I'm looking forward to see the software in action. At the moment, I'm trying to install guix (binary tarball is 404, Github issue pending).

[pjotrp]

We can support you on the #genenetwork IRC channel (irc.freenode.net - there is a web interface) if you like. Guix binary reproducible installs can be a bit daunting the first time because there are quite a few newish concepts.

[agarie]

Ooops, sorry for not posting before, I'm reviewing this.

• You could add a CONTRIBUTING.md file, as explained in Setting guidelines for repository contributors. Specifically, what are your requirements re: testing and documentation?
• How do I run the tests?
• As @krother said, these points could be added to the README.
• I think you could move that huge IRC log to another file inside doc/ and leave some highlights or brief quotes in the installation docs.

I read the installation instructions on doc/README.org, but I'm on a MacBook right now. I'll try to install GN2 on my linux desktop at home tonight and report back my impressions and suggestions about the process.

[pjotrp]

@krother I have addressed these in the following commits:

1st par: "experimental data" could be fleshed out in 2-3 words for the biologist reader (is it SNPs, microarray data, NGS, Y2H or manually counted individuals?)

genenetwork/genenetwork2@e241d27

2nd par: "can be found in ___ guix-bioinformatics", please insert 'the article', 'the package', 'the lab fridge labeled'.. whichever is aproppriate ;-)

genenetwork/genenetwork2@9669b09

last par: "Python" is spelled with a capital 'P'

genenetwork/genenetwork2@3788a3a

REST API looks like a very good idea.

Yes, the code is being developed in this repo: https://github.com/genenetwork/gn_server

[pjotrp]

@krother, @agarie I think I addressed most JOSS requirements by updating the README with:
genenetwork/genenetwork2@e3fc8d1

That includes a statement of work, contact and how to contribute. We do not prescribe guidelines for coding standards etc. Maybe that will come in the future.

Note: the testing framework is new and still limited in scope and @Brainiarc7 is working on that. We want to achieve full coverage in the coming month(s).

Note: the user level documentation is mostly from GN1 days. We need to update them for GN2, this is a slow work in process. Meanwhile the GN1 docs are still usable.

Note: Example use of GN can be found in the many publications by users mentioning GN on pubmed and Google Scholar. We never had a publication on the software itself that did justice to the work of the contributing developers.

[krother]

I find the README.md much more informative now. Thanks!