search

openjournals / joss-reviews

Reviews for the Journal of Open Source Software
Creative Commons Zero v1.0 Universal
697 stars 36 forks source link

[REVIEW]: diman: A Clojure package for dimensional analysis #3735

Closed whedon closed 2 years ago

whedon commented 2 years ago

Submitting author: @lungsi (B. Lungsi Sharma) Repository: https://github.com/neuralgraphs/diman Version: v1.1.0 Editor: @mjsottile Reviewers: @oyvinht, @khinsen Archive: 10.5281/zenodo.5837630

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

status

Status badge code:

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

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) by leaving comments 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

@oyvinht & @khinsen, 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.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @mjsottile know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @oyvinht

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review checklist for @khinsen

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

whedon commented 2 years ago

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @oyvinht, @khinsen it looks like you're currently assigned to review this paper :tada:.

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

: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

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf
whedon commented 2 years ago

Wordcount for paper.md is 1119

whedon commented 2 years ago 
Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.04 s (1390.8 files/s, 136824.8 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Clojure                         42            263            307           2711
AsciiDoc                         5            230              0            762
reStructuredText                 5            327             73            584
Markdown                         3             40              0            147
TeX                              1              6              0             59
-------------------------------------------------------------------------------
SUM:                            56            866            380           4263
-------------------------------------------------------------------------------

Statistical information for the repository '24d781e8500357939b423da2' was
gathered on 2021/09/17.
No commited files with the specified extensions were found.
whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- None

MISSING DOIs

- None

INVALID DOIs

- None
whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

whedon commented 2 years ago

:wave: @oyvinht, please update us on how your review is going (this is an automated reminder).

whedon commented 2 years ago

:wave: @khinsen, please update us on how your review is going (this is an automated reminder).

khinsen commented 2 years ago

Review update: I am looking at the code and playing with it. Interacting with the author via issues on the code repository.

khinsen commented 2 years ago

@lungsi @mjsottile Here comes my review!

The software described by this submission can be characterized as a highly specialized computer algebra system, in that is performs symbolic rather then the more common (in science) numeric computations. The field of application is dimensional analysis, which is a very useful but so far underappreciated tool in scientific computing. The software does exactly what the documentation and the paper promise, and the documentation is sufficient not only to learn how to use the software, but even to learn about the techniques that the software implements.

The unchecked points in my reviewer checklist are all related, and ultimately due to the fact that this software package does not exactly fit JOSS' ideas of what it wants to publish. However, I believe that software packages like this one should be published, and I don't see any particular reason why they should not be published in JOSS. So in the end, this paper requires an editorial policy decision.

The first point of hesitation is "Substantial scholarly effort". Looking at the list of criteria, this package is at the edge. It's relatively small, and was developed by a single person in a relatively short timeframe. But this does not mean it is trivial, it is merely very focused: a small tool for a very particular use case.

A related point is the absence of community guidelines. It would be trivial for the author to add some boilerplate along the lines of "contribute via GitHub features". But the real point is that this package doesn't have a community and doesn't need one. It's small enough to be understood by a single person, even someone else than the author. I wouldn't mind using it for a research project even if I knew for sure there were no support at all. But it is nevertheless a useful contribution to science, because it is much less effort to use this package than to develop my own. In fact, I believe that packages such as this should be published because they make underappreciated techniques more accessible.

The final unchecked point is "state of the field". I am now aware of any similar package, and assuming that @lungsi doesn't either, he/she could simply add a sentence stating this. But that misses the point that the main reason for publishing this package is the lack of any other tools that implement the same techniques.

mjsottile commented 2 years ago

:wave: @oyvinht Let me know if you are blocked on anything with respect to this review that I can assist with.

oyvinht commented 2 years ago

@whedon @lungsi @mjsottile Here is my review:

Background Diman is a software package for dimension analysis of symbolic formulas and equations. The package basics include the necessary mechanisms for defining these constructs in a programming language (Clojure). All of the seven SI units for dimensions are covered. The gist of the package is tools for automated derivation of dimensionless products of formulae and checking for dimensional homogeneity of equations.

Relevance The package would provide useful for anyone wanting to simplify or verify dimensional expressions (such as in engineering or science or building tools for these users) or possibly as a code basis for adding similar features to other automated symbolic processing systems (such as GNU Octave). From reading the statement of need, it also appears that the package is very likely to be cited as a tool in future publications from research in the field of dimensional analysis.

Code guidelines Code builds and runs. There are a number of tests provided. The size of the project points to substantial work done by the author (apparently one person). The following notes should be taken:

1) Tests do not cover all of the code.

2) src/diman/analyze.clj: This file includes code that make a good example of a type of cleanup that the package could benefit from. The function "clean-dimnames" builds on three other functions "remove-empty-string", "replace-empty-string-by-nil" and "replace-plus-by-empty-string". For succinctness I believe it would be better to replace the first of these with the built-in "(remove empty? ..." (though the resulting list would be reversed). The second function seems to be a step that could be removed by just by removing 'nil instead of empty strings. Then again, the "replace-plus-by-empty-string" is (currently) just used this one place, so it appears unclear if there is any reason not to just reduce the whole procedure to "(remove empty? (clojure.string/split dimnames #"+| "))".

3) src/diman/dimensions.clj: It is the reviewers opinion that the strings used to identify units should be replaced by symbols in the diman.dimensions namespace. Development tools would benefit from this (e.g. code completion) and typos could easily be identified by the compiler, making the tool easier to use and more robust. It would also allow for expressing formulae as standard s-expressions, pertaining to the beneficial homoiconicity that Lisps provide. It would also allow for the use of the excellent symbol metadata features of Clojure.

4) The authors might consider utilizing (reader?) macros to provide an easier way of defining formulae and equations. As an example, I think I (and many other Clojure users) would enjoy being able to generate an equation with something like:

(with-variables (E dim/ENERGY
                 m dim/MASS
         v dim/VELOCITY)
  (= E (* 1/2 m v v)))

Summary I recommend accepting the article given that point 1 is amended, and that a general clean up is done on the code, so as to heighten the quality of the published code, and avoid unnecessary complexity "bugs" (as exemplified by 2 above) in an otherwise well crafted package.

Points 3 and 4 above are more about "taste", but it is my belief that most Clojure users would consider the code more idiomatic if they were adhered to.

whedon commented 2 years ago

I'm sorry human, I don't understand that. You can see what commands I support by typing:

@whedon commands
oyvinht commented 2 years ago

@whedon commands

whedon commented 2 years ago

Here are some things you can ask me to do:

# List Whedon's capabilities
@whedon commands

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

EDITORIAL TASKS

# Compile the paper
@whedon generate pdf

# Compile the paper from alternative branch
@whedon generate pdf from branch custom-branch-name

# Ask Whedon to check the references for missing DOIs
@whedon check references

# Ask Whedon to check repository statistics for the submitted software
@whedon check repository
oyvinht commented 2 years ago

@whedon list reviewers

whedon commented 2 years ago

Here's the current list of reviewers: https://bit.ly/joss-reviewers

mjsottile commented 2 years ago

@whedon add @oyvinht as reviewer

whedon commented 2 years ago

OK, @oyvinht is now a reviewer

mjsottile commented 2 years ago

@oyvinht Sorry about that - occasionally reviewers aren’t automatically assigned correctly in the review issue even if their checklist is present. I believe you’re now assigned and can edit it.

oyvinht commented 2 years ago

@oyvinht Sorry about that - occasionally reviewers aren’t automatically assigned correctly in the review issue even if their checklist is present. I believe you’re now assigned and can edit it.

Thank you, it works well now!

mjsottile commented 2 years ago

@lungsi I apologize - it appears that I lost track of your review due to a weird schedule on my end during November. It looks like you addressed the reviewer issues that were raised, so I will take a look at the state of the review and let you know what next steps are necessary. I should be able to complete that this week.

mjsottile commented 2 years ago

@whedon generate pdf

mjsottile commented 2 years ago

@whedon check references

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- None

MISSING DOIs

- None

INVALID DOIs

- None
mjsottile commented 2 years ago

@lungsi I've finished my review and it looks like you have addressed the reviewers. I have the following final tasks for you to complete for us to push the submission to the final phase for acceptance.

The paper has a few very minor typos to correct:

Regarding related work:

Once you have addressed these points, the final steps are:

Once you've provided that information I can issue the final commands to pass the submission to an EIC for final processing.

mjsottile commented 2 years ago

@lungsi I just wanted to check in on my last message - I assume it may have been missed or forgotten with the holidays. Once you'd addressed those final points we can move on to the next step of the process. Let me know if you have any questions.

lungsi commented 2 years ago

@mjsottile Thank you so much for the feedback. Below are all the changes made in the revised version.

In addition I have also done the following.

lungsi commented 2 years ago

@whedon generate pdf

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

lungsi commented 2 years ago

@whedon check references

whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1007/978-3-642-17685-2_8 is OK

MISSING DOIs

- None

INVALID DOIs

- None
mjsottile commented 2 years ago

@whedon set v1.1.0 as version

whedon commented 2 years ago

OK. v1.1.0 is the version.

mjsottile commented 2 years ago

@lungsi Excellent - I think the added text talking about related work helps a lot in positioning your work with respect to other projects. There are just a couple of grammatical issues in the new text. Otherwise, it looks like we're good to go.

mjsottile commented 2 years ago

@lungsi Also, the bibliography entry for Kennedy (2010) needs to be fixed. The capitalization of place names is incorrect (the city and country names should be capitalized, as well as the name "European"). I am assuming this is a side effect of BiBTeX or LaTeX formatting your original text when generating the PDF. You should put curly braces around capital letters to force them to be upper case in the rendered output. Let me know if you have trouble getting the capitalization fixed for that entry.

mjsottile commented 2 years ago

@whedon set 10.5281/zenodo.5837630 as archive

whedon commented 2 years ago

OK. 10.5281/zenodo.5837630 is the archive.

lungsi commented 2 years ago

@mjsottile Thank you very much. I have made the changes as suggested.

lungsi commented 2 years ago

@whedon generate pdf

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

mjsottile commented 2 years ago

@whedon recommend-accept

whedon commented 2 years ago 
Attempting dry run of processing paper acceptance...
whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1007/978-3-642-17685-2_8 is OK

MISSING DOIs

- None

INVALID DOIs

- None
whedon commented 2 years ago

:wave: @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/2883

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/2883, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true
danielskatz commented 2 years ago

@lungsi - I've suggested some small changes in https://github.com/neuralgraphs/diman/pull/10 - please merge this or let me know what you disagree with.

danielskatz commented 2 years ago

👋 @khinsen, @oyvinht - there are unchecked items in both of your checklists. Can you check them off now?

lungsi commented 2 years ago

@lungsi - I've suggested some small changes in neuralgraphs/diman#10 - please merge this or let me know what you disagree with.

I have merged it. Thanks @danielskatz

oyvinht commented 2 years ago

@danielskatz The last two items have now been checked off.

khinsen commented 2 years ago

@danielskatz Done! Nice to see this published!