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

[whedon]

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

⚠️ JOSS reduced service mode ⚠️

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

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

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?
• Contribution and authorship: Has the submitting author (@lungsi) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

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

• 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 core 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 functionality 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

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of Need' that clearly states what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

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

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

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?
• Contribution and authorship: Has the submitting author (@lungsi) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

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

• 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 core 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 functionality 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

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of Need' that clearly states what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

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

⚠️ JOSS reduced service mode ⚠️

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.

⭐ Important ⭐

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:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/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]

Wordcount for paper.md is 1119

[whedon]

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]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- None

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[whedon]

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

[whedon]

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

[khinsen]

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

[khinsen]

@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]

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

[oyvinht]

@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]

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

@whedon commands

[oyvinht]

@whedon commands

[whedon]

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]

@whedon list reviewers

[whedon]

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

[mjsottile]

@whedon add @oyvinht as reviewer

[whedon]

OK, @oyvinht is now a reviewer

[mjsottile]

@whedon set 10.5281/zenodo.5837630 as archive

[whedon]

OK. 10.5281/zenodo.5837630 is the archive.

[lungsi]

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

• line 38 : incorporates unit -> incorporate units
• line 40 : unit of measure -> units of measure
• line 41 : which allows floats and integers annotation with statically-typed unit metadata -> which allows annotating floating point and integer values with statically-typed unit metadata
• line 45 : include ideas of type theory -> is based on ideas from type theory
• the bibliography entry for Kennedy (2010) needs to be fixed ...

[lungsi]

@whedon generate pdf

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[mjsottile]

@whedon recommend-accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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]

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

Check final proof 👉 openjournals/joss-papers#2883

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#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]

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

[danielskatz]

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

[lungsi]

@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]

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

[khinsen]

@danielskatz Done! Nice to see this published!

[danielskatz]

great, thanks @oyvinht and @khinsen !

[danielskatz]

@whedon recommend-accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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]

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

Check final proof 👉 openjournals/joss-papers#2887

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#2887, 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]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.03735 joss-papers#2888
1. Wait a couple of minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.03735
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[danielskatz]

Congratulations to @lungsi (B. Lungsi Sharma)!!

And thanks to @oyvinht and @khinsen for reviewing, and to @mjsottile for editing!
We couldn't do this without all your efforts!

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

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

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

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.03735">
  <img src="https://joss.theoj.org/papers/10.21105/joss.03735/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.03735/status.svg
   :target: https://doi.org/10.21105/joss.03735

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:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[lungsi]

Thank you very much (reviewers: @oyvinht and @khinsen, and editors: @mjsottile and @danielskatz).

Comments by @oyvinht and @khinsen were very helpful, I learned some new stuffs. I really appreciated the generous comments from @khinsen, it was very encouraging. I would also like to point out that @mjsottile 's feedback greatly improved the manuscript.

Overall, my experience with JOSS has been highly rewarding (regardless of the paper being accepted, although this helps :) ).