[REVIEW]: Nanomesh: A Python workflow tool for generating meshes from image data

[editorialbot]

Submitting author: @stefsmeets (Stef Smeets) Repository: https://github.com/hpgem/nanomesh Branch with paper.md (empty if default branch): joss_paper Version: 0.9.0 Editor: @prashjha Reviewers: @jameshgrn, @vijaysm Archive: Pending

Status

Status badge code:

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

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

@jameshgrn & @vijaysm, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @prashjha 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 ✨

Checklists

📝 Checklist for @vijaysm

📝 Checklist for @jameshgrn

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

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

@editorialbot commands

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

@editorialbot generate pdf

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.88  T=0.46 s (323.0 files/s, 228854.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          62           1636           1944           4321
Markdown                        26            988              0           2438
Jupyter Notebook                20              0          90560            948
reStructuredText                24            258            342            225
YAML                             7             30             16            218
TeX                              1             12              0            138
DOS Batch                        2              8              1             28
Bourne Shell                     2              0              0             22
make                             1              5              3             22
TOML                             1              0              0              3
SVG                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                           147           2937          92866           8364
-------------------------------------------------------------------------------


gitinspector failed to run statistical information for the repository

[editorialbot]

Wordcount for paper.md is 1244

[editorialbot]

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

[editorialbot]

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

OK DOIs

- 10.1145/2629697 is OK
- 10.21105/joss.01450 is OK
- 10.1007/bfb0014497 is OK
- 10.5281/zenodo.1173115 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.7717/peerj.453 is OK
- 10.1103/PhysRevLett.94.033903 is OK
- 10.1103/PhysRevB.72.153102 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[prashjha]

Dear @jameshgrn and @vijaysm, please read the first couple of comments in this thread and create your review checklist. You can read the reviewer guidelines here. Also, you can browse the closed "REVIEW" issues on the "joss-reviews" repository to get some ideas on how to complete the reviews. Good luck!

[vijaysm]

Review checklist for @vijaysm

Conflict of interest

• [x] 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

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

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/hpgem/nanomesh?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@stefsmeets) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

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 functionality 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] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] 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, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] 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?

[jameshgrn]

Review checklist for @jameshgrn

Conflict of interest

• [x] 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

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

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/hpgem/nanomesh?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@stefsmeets) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

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 functionality 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] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] 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, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] 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?

[jameshgrn]

This is a very well written piece of software! congrats to the authors. The use case is well demonstrated and the software is very well documented. It's a nice interplay of computer vision, data engineering, and user functionality. I particularly enjoyed the inclusion of the metrics submodule, including metrics is something that you don't have to do, but makes your user's experience that much better, cheers. The one missing item from my checklist is the community guidelines section. Based on the journal requirements, my recommendation is CONDITIONAL ACCEPT after the authors add in a page or section about contribution guidelines. The Development Notes section is helpful but technical, a more accessible contributions section prefacing it is required, see the blurb from JOSS below

There should be clear guidelines for third-parties wishing to:

• Contribute to the software
• Report issues or problems with the software
• Seek support

I also strongly encourage the authors to consider how arguments are passed to their functions and to document them without referring to another webpage, commandline style arguments should be in the realm of CLIs, whereas readable arguments are the norm in python.

Congrats on the great piece of user-centered software.

PAPER

General Comments: I think the authors demonstrate need effectively and have delivered a well-written paper.

Specific Comments:

• L 48 Typo - "nananomesh"
• L 73 Typo - "guassian"

SOFTWARE

Specific Comments: -the way opts are passed seems somewhat cumbersome and not well documented (though documentation is linked). For example, Why not make 'generate_mesh()' take two separate arguments fro minimum angle and size of triangles? I'm sure this has been considered, but it seems to be not quite as 'pythonic' FWIW. On some further reading, I see it mimics the likely familiar commandline usage, but then maybe just have a CLI (or provide classic arguments and then your string format style)? Sorry to harp on this point but I think its important.

[vijaysm]

The paper is well written. But I think it can be improved by fixing several spelling mistakes in the text and some missing punctuation.

Some specific comments:

• P2. L48: "Nananomesh" to "Nanomesh"
• P2. L60: "using the apply() method, which guarantees an object of the same time will be returned". Here do you mean "same type" ?
• What is the "li" method? Is that an acronym? If there is a reference, please provide one.
• Is there a better way to provide thresholds in Nanomesh to capture finer features more accurately, and differentiate it from the background? I see the description about max_edge_dist in P3, but it is unclear from the text whether this will yield a finer resolution of the contour.
• Is the contour returned a discrete one? I see that Figure (2) shows that the triangulation is constrained on the contour boundary.
• P3. L84: "snipped" should be "snippet"

[stefsmeets]

@jameshgrn @vijaysm Thanks for reviewing Nanomesh and the feedback! I have addressed the spelling mistakes, clarified the text and update the contributing guidelines. I addressed the more in-depth comments and feedback below.

The Development Notes section is helpful but technical, a more accessible contributions section prefacing it is required, see the blurb from JOSS below.

I agree. I have revised the contributing guidelines and made them available from the documentation as well as the readme.

Specific Comments: -the way opts are passed seems somewhat cumbersome and not well documented (though documentation is linked). For example, Why not make 'generate_mesh()' take two separate arguments fro minimum angle and size of triangles? I'm sure this has been considered, but it seems to be not quite as 'pythonic' FWIW. On some further reading, I see it mimics the likely familiar commandline usage, but then maybe just have a CLI (or provide classic arguments and then your string format style)? Sorry to harp on this point but I think its important.

I agree that this is important. I have not been able to find the right interface for this, but not for a lack of trying. Many of the CLI parameters for tetgen and triangle are overloaded with different functions or are somehow coupled. This makes untangling this into a consistent API a bit of a rabbit hole that is difficult to get right. In the end we decided to stay as close to the well-documented CLI interface and spend our time elsewhere.

Is there a better way to provide thresholds in Nanomesh to capture finer features more accurately, and differentiate it from the background? I see the description about max_edge_dist in P3, but it is unclear from the text whether this will yield a finer resolution of the contour.

I'm not aware of a better way to do this more accurately. Defining the threshold depends on the quality and contrast of the image. We expose the methods available in scikit-image that the user can choose from. Ultimately, the users know best how a feature is defined.

The max_edge_dist provides a way to tune the contour. Ideally the meshing algorithm decides the resolution of the contour based on the requested mesh size. Sometimes, a contour has a straight edge defined by (too) many points. This parameter redefines the edge to have points no more than x pixels apart. Being able to tune this is necessary, because meshing algorithms will not remove input points. I updated the text to make this a bit more clear.

Is the contour returned a discrete one? I see that Figure (2) shows that the triangulation is constrained on the contour boundary.

Yes, it is a discrete contour.

[prashjha]

Hello, @jameshgrn and @vijaysm. Could you please suggest if you are satisfied with the response and if there are no further comments for the author to address? Also, please provide your decision on acceptance of this submission. Thank you!!

[jameshgrn]

Fine with me: Accept!

[vijaysm]

I am happy with the responses of the author to address all the questions I've raised. The software and the manuscript are in good shape now as well. I recommend the submission be accepted for publication. I have also marked all pending items as complete in my review. Congratulations @stefsmeets !

[prashjha]

Thank you both for your quick response!!

[prashjha]

@editorialbot check references

[editorialbot]

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

OK DOIs

- 10.1145/2629697 is OK
- 10.21105/joss.01450 is OK
- 10.1007/bfb0014497 is OK
- 10.5281/zenodo.1173115 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.7717/peerj.453 is OK
- 10.1103/PhysRevLett.94.033903 is OK
- 10.1103/PhysRevB.72.153102 is OK

MISSING DOIs

- None

INVALID DOIs

- https://doi.org/10.1016/0031-3203(93)90115-D is INVALID because of 'https://doi.org/' prefix

[prashjha]

@stefsmeets could you please update the JOSS article to fix the above DOI error?

[prashjha]

@editorialbot generate pdf

[editorialbot]

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

[prashjha]

@stefsmeets I have made a pull request that fixes the doi error...feel free to either accept it or do your own fix. :)

[prashjha]

Hi, @stefsmeets; while you fix the doi error, I will go over the JOSS paper. If there are suggestions on the draft, I will share them here. Once you have incorporated them, I will hand the paper to the editor-in-chief for a final decision.

[stefsmeets]

Cheers, I just accepted the PR, letme know if there is anything else I can do :-)

[prashjha]

Hi, @stefsmeets, see if these suggestions make sense for your draft:

• L18. Many meshing libraries ... in this sentence, you may want to say meshing libraries from images (??) so that the following sentence on not many software being available makes sense? Otherwise, for simple meshing given the definition of the domain, there are many open source software.
• L21. Should you have a comma after primitive?
• L32. Remove extra the.
• L43. '... in MeshContainers; this is ...'?
• L67. Contour finding and?
• L68. Triangulation.?
• L65. I think you should have a sentence something like The code below creates contours around the features(??) just above the code listing below L76.

After you have updated the draft, can you also do (if not done already) a 'tagged' release of your code and archive the release using zenodo or other methods? Make sure that the zenodo archive's title matches this JOSS submission's title.

Once you are done, I will hand your paper to EiC for the final decision.

[stefsmeets]

Hi @prashjha Thanks for the useful suggestions, I tried to incorporate all of them in the final draft.

I created a new release: https://github.com/hpgem/nanomesh/tree/0.9.1 and uploaded it to Zenodo: https://zenodo.org/record/7157382

Let me know if there if there are any remaining issues.

[prashjha]

@editorialbot check references

[editorialbot]

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

OK DOIs

- 10.1145/2629697 is OK
- 10.21105/joss.01450 is OK
- 10.1007/bfb0014497 is OK
- 10.5281/zenodo.1173115 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.7717/peerj.453 is OK
- 10.1103/PhysRevLett.94.033903 is OK
- 10.1103/PhysRevB.72.153102 is OK
- 10.1016/0031-3203(93)90115-D is OK

MISSING DOIs

- None

INVALID DOIs

- None

[prashjha]

@editorialbot generate pdf

[editorialbot]

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

[prashjha]

@editorialbot set 0.9.1 as version