-
-
Notifications
You must be signed in to change notification settings - Fork 41
[REVIEW]: GeneNetwork: framework for web-based genetics #25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
/ 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 Reviewer instructions
Any questions, please ask for help by commenting on this issue! 🚀 |
✋ I am reviewing this |
This is how software papers I like to read should look like!
|
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). |
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. |
Ooops, sorry for not posting before, I'm reviewing this.
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. |
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'
@krother I have addressed these in the following commits:
genenetwork/genenetwork2@e241d27
genenetwork/genenetwork2@9669b09
genenetwork/genenetwork2@3788a3a
Yes, the code is being developed in this repo: https://github.com/genenetwork/gn_server |
documentation and testing materials openjournals/joss-reviews#25
@krother, @agarie I think I addressed most JOSS requirements by updating the README with: 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. |
I find the README.md much more informative now. Thanks! |
@krother and @agarie: when it comes to installation, GN2 installation reflects that it is a rather complex product with a huge number of dependencies. It includes a recent R with packages. It includes Python with packages. It includes C++ modules. It will include OpenCL dependencies soon. Even so, GNU Guix provides a reliable byte-identical installation path with source and binary deployment. If GN2 was part of the GNU Guix project proper it would simply be one command: guix package -i genenetwork2 and all software would be installed on any Linux. Unfortunately genenetwork2 will never make it into GNU Guix. This is because some software components are dated (one python package had the last update in the 90s!) and we include large data files. Guix, however, allows you to pull in your own packages using a GUIX_PACKAGE_PATH, so we created a git repo for that named https://github.com/genenetwork/guix-bioinformatics/tree/gn-latest (the gn-latest branch is the one we deploy). Additionally, to ascertain byte-identical deployment we also have to fixate the GNU Guix package tree itself. This is done in yet another git repository named https://github.com/genenetwork/guix/tree/gn-latest (again the gn-latest branch). To run these trees, after instaling GNU Guix itself, some environment variables need to be set properly This is all described in the installation docs as a step-by-step instruction, but I am just giving the overview here to explain why it is non-trivial at this point. Even so it is a formal deployment path and we and others have successfully installed GN2 and are happily developing against it. We include the IRC log to show it is doable - I would like to keep it there until we have a single install command. To achieve the latter we are working with the GNU Guix project to make installation easier. I am not sure the reviewers want to go through the full installation (the website also runs online), but if you do, please tell me where you are stuck and we will resolve it. It is also an opportunity for me to improve the docs ;). One thing you may gain in this process: GNU Guix is a great way of deploying bioinformatics software! To make things easier we could deploy GN2 inside a Docker container, but we don't think that is the right way of going about deployment. Docker containers are opaque and a security risk. |
The improved README is good! I tried to build everything but couldn't download the tarball for I navigated through the live site in order to experiment with the platform and I think both functionality and performance are OK. The documentation and the other checks are also OK. I would say that the API-level docs are sparse, but the software is meant to be used on a browser, not as a library. Even then, this documentation can come in handy for new contributors and anyone experiencing problems (or just being curious), but this is mostly a suggestion for the coming months, not a necessary revision for acceptance. The JOSS reviewer guidelines explicitly say that reviewers are expected to be able to install the software. If my understanding of guix is correct, I expect to be able to install GN2 after I get a key for the caching server ( |
@agarie, thanks, building from source can fail when upstream package maintainers remove a tar source ball. In Guix recently infrastructure was added to cache source tar balls too - so this will soon be a thing from the past. The use of our binary caching guix server makes installation a lot easier and faster - because you don't have to build everything. This is a limited guix server since it only contains GN2 related binaries. The public key to trust this http://guix.genenetwork.org:8080 server is:
I'll add the access key for our caching server to the docs. On the API: we are building up the API as a new Elixir based REST service with https://github.com/genenetwork/gn_server. Documentation will be generated from both the API and the included unit tests. There exists an old REST API which is documented at http://www.genenetwork.org/CGIDoc.html, but we want to discourage the use of that. We are adding documentation, in particular on database layout etc. to help people get started. |
Thanks @agarie! I am really glad you succeeded because there are quite a few steps. Not surprising for a web framework with a host of dependencies. Even so, I think I can turn it into a cookbook approach - line by line. During the installation, what were the hurdles? So we can focus on those and improve the documentation. The obvious one is the use of the Guix key for the binary caching server. I realise the Guix installation is a bit involved. With time it should get better because GNU Guix is getting better. Now we are using git checkouts to fixate the dependency graph. This is something that can be handled transparently in the future. @krother do you want have a go this week? I, myself, have time to help. To get GN installed it may take half an hour up to two hours of your time (if we hit an unexpected snag, such as a proxy server). |
Yeah, the key was the biggest problem — this was my first time trying out guix, but the documentation explaining how to setup guix, your notes, and the installation instructions from genenetwork2 did the job. Not that it was easy, but it's definitely doable... maybe an installation "from scratch" beginning with a quick guix install + setup? Or at least links to a tutorial with just that? |
Yes I'd like to give it a try as well. |
@krother I wrote a 'quick installation recipe' which does not require building the software. See https://github.com/pjotrp/genenetwork2/tree/paper/doc#quick-installation-recipe Only alternative I can think of is a binary tarball or a Docker image. But I don't think that is in the spirit of JOSS. |
BTW we also have a plant database available now (3GB). I should add that to the paper. |
The GTK+ fix in the recipe is actually a known bug in Guix: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=21888. Mentioned workaround does fix it. |
To get an idea of the complexity of GN2, see the graph of dependencies at http://biobeat.org/gn2.svg. I added the graph to the README. |
@krother I updated the docs and reran the installation with success in a fresh and basic Debian VM. If you follow the instructions it takes a few minutes of keyboard actions (copy-paste only). Please try Downloading the software takes an hour on my 5 Mbs connection. Mind, the download activity is mesmerizing, so you may spend more time looking at the scrollling screen than is considered healthy ;). |
Hi, I have to report that I am stuck with the installation of guix (got a 'unknown locale' at step 7). Given the amount of operations on root level, I am also concerned about the health of my system. Is it possible to install the whole thing in some kind of sandbox? |
@krother you can ignore the locale error. It is just a warning and harmless. Your system is safe because guix itself and its packages are installed in /gnu/store - which is isolated from the rest of your system. A database is installed in /var/guix and an access key in /etc/acl. Nothing else gets installed. One of the great things about guix is that it runs on top of any existing Linux system. Even so, if you prefer, you can install in a VM, such as KVM or VirtualBox. We do that all the time. I would suggest to continue where you are now. If you come on IRC we can help you. Use https://webchat.freenode.net/ and use the #genenetwork channel. You can use any nick name. We are there. |
If I may jump in.. @krother: The locale error is not a problem actually. Some special characters may not display in the output of programs, which does not hinder the actual programs (it's only an output-to-shell problem). You could fix that by updating the I am also in the #genenetwork channel on freenode.net, available to help you there. |
Thanks for the quick reply. I'll try VirtualBox .. have been looking for an excuse to try that for some time :-) |
In general a wise idea when installing and testing software from other parties, though you are safe with Guix. If you get stuck I'll try to document those VirtualBox steps too. |
Hi @krother, given that this installation seems to be causing significant trouble for you and that @agarie has managed to install the application already I'm happy to stop here if that makes things easier? Also, I would note that the submitting authors have gone to significant lengths to improve installation documentation ⚡ If you agree, we can (I believe) move forward to accept. |
Yes, I have seen a lot improving, and in my opinion the review process has worked well. I just checked the examples in the documentation and ticked the two remaining boxes in 'Documentation'. I agree with your suggestion to move forward to accept. |
👍 thanks @krother. @pjotrp - do you want to make a new Zenodo release with your changes or has this already been done? |
👍 thanks for the review @krother & @agarie. @pjotrp - your DOI is http://dx.doi.org/10.21105/joss.00025 ⚡ 🚀 💥 |
@arfon thanks for the great journal! In the paper there is a typo in Prof. Wiliams' name and I amended a URL to point to the master branch. Can you fix that, please? |
Sure thing. That should be fixed now. |
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:
Reviewer questions
Conflict of interest
General checks
Functionality
Documentation
Software paper
Paper PDF: 10.21105.joss.00025.pdf
paper.md
file include a list of authors with their affiliations?The text was updated successfully, but these errors were encountered: