[REVIEW]: ospgrillage: A bridge deck grillage analysis preprocessor for OpenSeesPy

[editorialbot]

Submitting author: @ccaprani (Colin C. Caprani)
Repository: https://github.com/MonashSmartStructures/ospgrillage
Branch with paper.md (empty if default branch):
Version: v0.2.1
Editor: @prashjha
Reviewers: @vsangelidakis, @dbrizard
Archive: 10.5281/zenodo.7034267

Status

Status badge code:

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

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

@vsangelidakis & @dbrizard, 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 @dbrizard

📝 Checklist for @vsangelidakis

[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.40 s (247.6 files/s, 264549.0 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
SVG                              8              8             26          37962
HTML                            16           4115             50          24985
JavaScript                       9           2405           2464           9206
Python                          21           1220           2261           8014
Jupyter Notebook                 5              0           8997            952
CSS                              3            207             57            834
reStructuredText                16            610            599            717
YAML                            11             60             46            312
Markdown                         5            111              0            274
JSON                             2              0              0            197
TeX                              1              7              0             78
DOS Batch                        1              8              1             26
TOML                             1              3              0             14
make                             1              4              7              9
-------------------------------------------------------------------------------
SUM:                           100           8758          14508          83580
-------------------------------------------------------------------------------


gitinspector failed to run statistical information for the repository

[editorialbot]

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

OK DOIs

- 10.1109/MCSE.2011.66 is OK
- 10.1016/j.softx.2017.10.009 is OK
- 10.4231/D3PK0727C is OK
- 10.1061/(ASCE)0887-3801(2008)22:4(264) is OK
- 10.15446/dyna.v87n212.80143 is OK
- 10.1533/9780857099754.331 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

Wordcount for paper.md is 1245

[editorialbot]

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

[prashjha]

Dear @vsangelidakis and @dbrizard, 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!

[dbrizard]

Review checklist for @dbrizard

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 https://github.com/MonashSmartStructures/ospgrillage?
• 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 (@ccaprani) 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?

[vsangelidakis]

Review checklist for @vsangelidakis

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 https://github.com/MonashSmartStructures/ospgrillage?
• 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 (@ccaprani) 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?

[dbrizard]

This is a detail, but the enforcement section of the code of conduct has not been personalised.
https://github.com/MonashSmartStructures/ospgrillage/blob/main/.github/CODE_OF_CONDUCT.md

[dbrizard]

Two references should be improved, even though they are not so hard to find (because it is not possible to guess what type of reference it is from the bibliography alone):

• Almutairi et al: I suggest adding the report number and the institution;
• Yang et al: add the proceeding title and the place.

[dbrizard]

Even if I am not in the "brigdes" field, I believe this software is a important contribution to the community.
The code is very clean, well organised, the documentation is exhaustive and with many examples which greatly facilitates the understanding and getting started phase. This software is worth being published to JOSS 👍

[vsangelidakis]

I am also satisfied to see a well-implemented Python package, detailed documentation and a clear manuscript. Seeing the docs hosted on github pages (rather than using a third-party domain) makes me confident about their longevity.

One comment regarding the State of the Field item of the reviewing TODO list above: the authors state "there is no established interface to import such models into OpenSees framework" and I completely agree that no pre-processor exists for grillage models specifically.

I would like to bring to your attention that other pre-processors do exist for OpenSees, e.g. (1) generic GUI tools such as GiD-OpenSees https://github.com/rclab-auth/gidopensees or (2) for bridges in general, such as the Bridge-Wizard (https://research-information.bris.ac.uk/en/publications/bridge-wizard-expert-system-for-finite-element-modeling-and-post-); although I could only find binaries and not the source code itself for the latter (see https://www.asextos.net/bridge-wizard.html).

I leave it to the judgement of the authors; you can either leave the manuscript as is or mention how ospgrillage is an improvement compared to existing pre-processing tools like the ones above. Either way, @ccaprani please let me know your intention.

[vsangelidakis]

A small point for improvement: The documentation describes how to generate multi-span models (https://monashsmartstructures.github.io/ospgrillage/notebooks/multi_span.html), while the manuscript mentions "the roadmap allows for curved and multi-span bridge decks..". Is this feature developed/operational or ongoing? Please clarify either the manuscript or the documentation.

[prashjha]

Hi, @dbrizard, thank you for reviewing the submission. Is your review complete?

[dbrizard]

@prashjha yes, provided the references are updated according to my suggestion #4404 (comment)
otherwise everything is ok for me.

[prashjha]

@dbrizard, got it. thanks.

[ccaprani]

Hi all,
Thank you so much for your valuable time and for the useful and constructive reviews. We've now released v0.2 with completion of the curved and multi-span meshes and a major update of the documentation.
@vsangelidakis thank you - we've updated the documentation now with more extensive description of these features. Those other pre-processors mentioned all address different domains. Further, they are either aimed at commercial software, or are not open-source.
@dbrizard thanks - these are updated.
@prashjha I think that is everything but please do let me know if there is anything else to be addressed.

[vsangelidakis]

Great, @ccaprani thank you for addressing all comments. @prashjha my review is complete.

[prashjha]

@editorialbot check references

[editorialbot]

Checking the BibTeX entries failed with the following error:

Failed to parse BibTeX on value "booktitle" (NAME) [#<BibTeX::Bibliography data=[2]>, "@", #<BibTeX::Entry >, {:author=>["Wang, Yuandong and Ibarra, L and Pantelides, Chris"], :year=>["2017"], :month=>["01"], :pages=>[""], :title=>["Seismic Assessment for Retrofitted Skewed Reinforced Concrete Bridges with Buckling Restrained Braces"]}]

[prashjha]

@editorialbot generate pdf

[editorialbot]

⚠️ An error happened when generating the pdf.

[prashjha]

Hi, @ccaprani, I am going through the draft one final time before I recommend your paper for a final decision by Editor in Chief. As you can see above, there is an error in your reference and the editorialbot is not able to generate a pdf. Please see if you can correct it.

[ccaprani]

@editorialbot generate pdf

[editorialbot]

⚠️ An error happened when generating the pdf.

[editorialbot]

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

OK DOIs

- 10.1109/MCSE.2011.66 is OK
- 10.1016/j.softx.2017.10.009 is OK
- 10.4231/D3PK0727C is OK
- 10.1061/(ASCE)0887-3801(2008)22:4(264) is OK
- 10.15446/dyna.v87n212.80143 is OK
- 10.1533/9780857099754.331 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[prashjha]

@editorialbot generate pdf

[editorialbot]

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

[prashjha]

Hi, @ccaprani; the paper is well written and informative. My only suggestion is to replace Dr with Dr. in line 102 of the draft.

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.

[ccaprani]

Thank you @prashjha ; those final tweaks are done; v0.2.1 released, and archived at .

I appreciate your time on this, and hope for a decision soon. Thanks.

[prashjha]

@editorialbot generate pdf

[editorialbot]

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

[prashjha]

@editorialbot check references

[prashjha]

Hi @ccaprani, thanks. One last thing, could you change the title of your zenodo archive to match the title of your JOSS paper?

[prashjha]

@editorialbot set v0.2.1 as version

[editorialbot]

Done! version is now v0.2.1

[prashjha]

@editorialbot set 10.5281/zenodo.7034267 as archive

[editorialbot]

Done! Archive is now 10.5281/zenodo.7034267

[ccaprani]

@prashjha , thank you, that's done now!

[prashjha]

Thanks, @ccaprani

[prashjha]

Dear @vsangelidakis and @dbrizard , thank you for your efforts in reviewing this submission. I truly appreciate it.

[prashjha]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[editorialbot]

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

OK DOIs

- 10.1109/MCSE.2011.66 is OK
- 10.1016/j.softx.2017.10.009 is OK
- 10.4231/D3PK0727C is OK
- 10.1061/(ASCE)0887-3801(2008)22:4(264) is OK
- 10.15446/dyna.v87n212.80143 is OK
- 10.1533/9780857099754.331 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

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

Check final proof 👉📄 Download article

If the paper PDF and the deposit XML files look good in openjournals/joss-papers#3489, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[arfon]

@editorialbot accept

[editorialbot]

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

[editorialbot]

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

[editorialbot]

🚨🚨🚨 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.04404 joss-papers#3497
1. Wait a couple of minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.04404
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...

[arfon]

@vsangelidakis, @dbrizard – many thanks for your reviews here and to @prashjha for editing this submission! JOSS relies upon the volunteer effort of people like you and we simply wouldn't be able to do this without you ✨

@ccaprani – your paper is now accepted and published in JOSS ⚡🚀💥

[editorialbot]

🎉🎉🎉 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.04404/status.svg)](https://doi.org/10.21105/joss.04404)

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

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

This is how it will look in your documentation:

We need your help!

The 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