Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
[REVIEW]: Local clustering #960
Status badge code:
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
@DannyArends, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:
Review checklist for @DannyArends
Conflict of interest
Code of Conduct
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:
For a list of things I can do to help you, just type:
@pjotrp I've gone through the checklist. I think everything is fine, but here are a couple of notes:
Ticked all the boxes I could, in general the software is in a good state. However how to use the library, what the advantages are, and the use-cases of this clustering algorithm compared to already available methods remains a mystery to me.
I would advice the author to additionally take a close look at the language used in the paper (although this is outside of the scope of the review) I added some comments in the additional section below.
Furthermore I was not able to install the software yet, I will do that after the issues listed below are taken care of.
Functionality - Installation
The software only provides a short list of dependencies, no clear install guide is provided. Please provide an install guide outlining the steps needed to be taken by a new user to install the software, even if this is a simple as:
Then what do I need to do ? Do I need to include the library ? does it need compilation/installation ? Do I need to update my path variable ?
Additionally, it is not specified if this requires a certain OS, is this windows, linux, macOSX compatible ? has it been tested on multiple platforms ?
Documentation - A statement of need
No statement of need is provided, please make clear in the readme for whom the software in this repository is useful: e.g. is it aimed at biologist, mathematicians, physics
Documentation - Installation instructions
There is no clear list of dependencies, and dependencies for the library, the demo and the python notebook are different. Furthermore, it is unclear which version of "GraphScraper library" is required, since the readme file links to the pypi version (https://pypi.python.org/pypi/graphscraper) as well as the authors fork of the same software: (https://github.com/volfpeter/graphscraper).
A solution would be to split up the dependencies section into three parts outlining the requirements for: Library, Demo and IPython notebook, and then giving install instructions on how-to install the dependencies.
Documentation - Automated tests
No automated tests are provided, and no instructions are provided in the readme on howto run manual tests of the library.
Documentation - Community guidelines
point 2) Report issues or problems with the software, and point 3) Seek support are to be addressed
Software paper - Authors
Author is listed, but the affiliation is mentioned as "None", if no affiliation exists, it would be more professional to mark the author as "independant developer"
Software paper - A statement of need
Same comment as before in the documenttation section, please provide a statement of need
Software paper - References
No DOIs are provided for the references
The text in the paper is of low quality in some areas, and the author might want to improve the text before publication, for example:
"Here are some ideas for future work:"
Furthermore no comparison is made between the current clustering algorithm and known clustering
To me it is not clear what advantages this clustering algorithm has, and it is not clear what
Furthermore, the phrase "they define a set of requirements cluster definitions must fulfill" is
Hi @volfpeter, you had great momentum. Don't let it slip :). I think @DannyArends has some good points, but they are not intrusive. I think most of the work is to provide a clear install path (we require that) and a bit more contextual information on other clustering algorithms. I don't think a full comparison is required. Also tests are optional.
Hi @pjotrp , I haven't had time last week, but i started working on it this week. I decided to completely rewrite and significantly extend the readme of the project because it was really lacking in some areas and only this review made it obvious to me (it was OK for someone who knew how to use the software, i.e. me, but it was not very useful for others)...
A couple of minor things:
compared with (not the best example, but I think you'll get the idea):
from localclustering.definitions.connectivity import ConnectivityClusterDefinition from localclustering.localengine import LocalClusterEngine
There is a missing space in the README.md: "a detailed descriptionand", as well as a minor spelling error: change 'in' to 'by' in the following sentence: "contact the repository owner in email"
Anyway, it looks good to me, just update the paper (if you want I could proofread it for you) and if @pjotrp confirms his "tests are optional" statement I will check the last box.
Ps. I noticed there is 1 reference without a DOI still, however this paper from 2000 does not have a DOI assigned to it, is this ok @pjotrp ?
I've fixed the readme.
The reference that doesn't have a DOI is a technical report. I have found DOIs for related papers, but i wanted to cite the technical report because that's what i read back in the day.
Regarding the test, the only related thing in the repository is the
One more thing: i've released a new version (0.11) that fixed the setup.py file, so that's the latest version right now.
Hopefully i will have time to finalize and commit the paper today.
@volfpeter I think it's more for regression/CI tests e.g. when using travis.ci
These kinds of tests allow you to know when a change to the code breaks the results compared to a previous version. I use it for the CTLmapping repository, every time I push to the master branch, the code is checked to make sure it can still install, and it runs tests to see if the mapping algorithm still produces the same output as before. See for example:
in this code my own openMP correlation algorithm is compared to the build-in correlation algorithm from R. If my algorithm produces different results compared to the R version:
if(!all(res.ref == res.cor)) stop("ref != cor\n") # When results differ, stop
The test is stopped (stop is R lingo for error), and travis.ci will email me that the latest changes have broken the algorithm.
You could do something like this for the clustering, in which you calculate a base case, which you then test.
@pjotrp Is this a requirement or a nice to have feature for JOSS ?
Additionally it gives you the opportunity to add the nice green "build passing" icon to your repository
Excellent. The submission is slightly over 1000 words at 1200 words, but in this case I think it serves its purpose (@arfon is that OK?).
We need you to deposit a copy of your software repository (including any revisions made during the JOSS review process) with a data-archiving service. To do so:
If you would like to include a link to your paper from your README use the following code snippets:
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: