Joss-reviews: [REVIEW]: dit: a Python package for discrete information theory

Created on 16 May 2018  Â·  31Comments  Â·  Source: openjournals/joss-reviews

Submitting author: @Autoplectic (Ryan G. James)
Repository: https://github.com/dit/dit
Version: v1.2.0
Editor: @arfon
Reviewer: @kczimm, @stsievert
Archive: 10.5281/zenodo.1255350

Status

status

Status badge code:

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

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

@kczimm & @stsievert, 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 @arfon know.

Review checklist for @kczimm

Conflict of interest

Code of Conduct

General checks

  • [x] Repository: Is the source code for this software available at the repository url?
  • [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
  • [x] Version: Does the release version given match the GitHub release (v1.2.0)?
  • [x] Authorship: Has the submitting author (@Autoplectic) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

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

  • [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
  • [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
  • [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
  • [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
  • [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
  • [x] 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

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

Review checklist for @stsievert

Conflict of interest

Code of Conduct

General checks

  • [x] Repository: Is the source code for this software available at the repository url?
  • [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license? (well, a LICENSE.txt file)
  • [x] Version: Does the release version given match the GitHub release (v1.2.0)?
  • [x] Authorship: Has the submitting author (@Autoplectic) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

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

  • [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
  • [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
  • [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
  • [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
  • [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
  • [x] 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

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

Most helpful comment

Looks like we've got the thumbs!

picture Autoplectic on 27 May 2018
👍2

All 31 comments

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @kczimm, it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

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:

watching

  1. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

notifications

For a list of things I can do to help you, just type:

@whedon commands
whedon picture whedon on 16 May 2018 
Attempting PDF compilation. Reticulating splines etc...
whedon picture whedon on 16 May 2018

--> Check article proof :page_facing_up: <--

whedon picture whedon on 16 May 2018

@afron I am still testing the functionality of this software package. In the meantime, I've a few questions. I'm not familiar with DOI or how to answer the following question: "Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?" I didn't see anything in the reviewer guidelines that could help my understanding of this question. Also, my minor feedback for the authors at this time is to increase the statement of need and intended audience in their documentation. Is this minor feedback worth creating an issue in their repository? Thanks in advance for the help.

kczimm picture kczimm on 18 May 2018

@Autoplectic I'm guessing @chebee7i is Christopher J. Ellison and James P. Crutchfield is your advisor. Is that correct?

stsievert picture stsievert on 18 May 2018

@afron I am still testing the functionality of this software package. In the meantime, I've a few questions. I'm not familiar with DOI or how to answer the following question: "Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?"

Basically, if possible we want a DOI associated with each of the references. If you can check the reference and find a DOI (and the author hasn't listed one), we'd like you to identify that.

arfon picture arfon on 20 May 2018

I've gone through this repo, and have a couple comments. This software looks good and almost ready for acceptance, but I have a couple comments.

  • I didn't see a clear statement of need in the paper or in the docs. This should clearly list the problems your software solves (not just the functions it provides) and the target audience. https://github.com/dit/dit/issues/141
  • I didn't see any DOIs linked in paper.bib though the references were complete (and I would consider suitable for another academic journal). @afron is this acceptable?
  • I didn't see any guidelines for users to contribute to your software. I think this is most often in CONTRIBUTING.md, which GitHub has support for.
  • The dependency list confused me, especially the optional dependencies. There weren't any reasons why some dependencies were optional, and some of them were out of date. I've filed https://github.com/dit/dit/issues/144 for this.
  • I didn't find steps to test the software, thought I figured it out and filed https://github.com/dit/dit/pull/146

I've put in some other issues and PRs too, but these are the most important issues right now.

stsievert picture stsievert on 21 May 2018

I didn't see any DOIs linked in paper.bib though the references were complete (and I would consider suitable for another academic journal). @afron is this acceptable?

@stsievert - references without DOIs are acceptable provided they _don't actually have one_, i.e. a journal publications such as this one is missing this DOI: https://doi.org/10.1016/j.physleta.2011.10.066

@Autoplectic - please go through your paper.bib and add a DOI for each entry where you can find a DOI.

arfon picture arfon on 21 May 2018

@Autoplectic I'm guessing @chebee7i is Christopher J. Ellison and James P. Crutchfield is your advisor. Is that correct?

Largely. CJE & I were both graduate students under JPC. CJE is now in industry, and I am back with JPC as a postdoc.

Autoplectic picture Autoplectic on 21 May 2018

I have added DOIs where possible.

Autoplectic picture Autoplectic on 21 May 2018
👍1

I believe I have addressed all the reviewers concerns at this point.

Autoplectic picture Autoplectic on 21 May 2018

scratch that --- working on an issue with the docs. the custom mathjax works fine under docs.dit.io, but fails under dit.readthedocs.io

Autoplectic picture Autoplectic on 21 May 2018

OK, the docs work fine at http://dit.readthedocs.io and at http://docs.dit.io, which is the official link. I'm not sure why it doesn't work at https://dit.readthedocs.io. Since it works at the official link, which is the only one in the readme and such, things should be ok.

Autoplectic picture Autoplectic on 21 May 2018

Thanks @Autoplectic, both for the quick response and handling these issues well.

Maybe I'm missing it, but have you addressed contributing issue mentioned in https://github.com/openjournals/joss-reviews/issues/738#issuecomment-390523494?

stsievert picture stsievert on 22 May 2018

@stsievert The information about contributing is at the bottom of the readme. I've also added a CONTRIBUTING.md as you have suggested.

Thank you @stsievert, @kczimm, and @arfon for your help shepherding this submission through!

Autoplectic picture Autoplectic on 22 May 2018

I had many of the same comments as @stsievert. I don't have any other comments or suggestions at this time.

kczimm picture kczimm on 22 May 2018
👍1

I've also added a CONTRIBUTING.md as you have suggested.

Could you add a line for people seeking support? This could be a link to a Gitter channel, a tip to stackoverflow with some tag or file an issue.

Here's the GitHub support for CONTRIBUTING.md: https://blog.github.com/2012-09-17-contributing-guidelines/

It's easy to check off boxes when everything (or most things) are done right.

stsievert picture stsievert on 22 May 2018

@stsievert i've added to the contributing.md file!

Autoplectic picture Autoplectic on 22 May 2018

OK, I think we're good to go here. If I could just get a final :+1: from @kczimm, @stsievert that we're good to accept I'll move forward with this submission.

arfon picture arfon on 23 May 2018
👍2

@whedon generate pdf

Autoplectic picture Autoplectic on 23 May 2018 
Attempting PDF compilation. Reticulating splines etc...
whedon picture whedon on 23 May 2018

--> Check article proof :page_facing_up: <--

whedon picture whedon on 23 May 2018

Looks like we've got the thumbs!

Autoplectic picture Autoplectic on 27 May 2018
👍2

@Autoplectic - At this point could you make an archive of the reviewed software in Zenodo/figshare/other service and update this thread with the DOI of the archive? I can then move forward with accepting the submission.

arfon picture arfon on 29 May 2018

doi: 10.5281/zenodo.1255350

Autoplectic picture Autoplectic on 29 May 2018

@whedon set 10.5281/zenodo.1255350 as archive

arfon picture arfon on 30 May 2018

OK. 10.5281/zenodo.1255350 is the archive.

whedon picture whedon on 30 May 2018

@Autoplectic - I get the following error when compiling the doc:

pandoc-citeproc: reference Allen2014 not found

Can you check this reference? Is it missing in the bibtex or just cited incorrectly in the paper.md

arfon picture arfon on 30 May 2018

Fixed. I updated the bib file to reference the published version of that paper, but hadn't fix the ref in the paper.

Autoplectic picture Autoplectic on 31 May 2018
👍1

@kczimm, @stsievert - many thanks for your reviews here ✨

@Autoplectic - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00738 :zap: :rocket: :boom:

arfon picture arfon on 31 May 2018

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

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

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

This is how it will look in your documentation:

DOI

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:

whedon picture whedon on 31 May 2018
Was this page helpful?
0 / 5 - 0 ratings

Related issues

whedon picture whedon  Â·  6Comments
whedon picture whedon  Â·  10Comments
whedon picture whedon  Â·  13Comments
whedon picture whedon  Â·  12Comments
whedon picture whedon  Â·  12Comments