[REVIEW]: TUM Open Infra Platform: an open source package for simultaneous viewing and analysis of digital models in the civil engineering domain

whedon commented 3 years ago

Submitting author: !--author-handle-->@pjanck@hugoledoux<!--end-editor-- Reviewers: @aothms, @CBenghi, @abdoulayediak Archive: 10.5281/zenodo.6488493

: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 badge code:

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

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

@aothms & @CBenghi, @Abdoulayediak please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

Make sure you're logged in to your GitHub account
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 @hugoledoux 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 @aothms

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 repository url?
[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 (@pjanck) 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: 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?
[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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[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?

Review checklist for @CBenghi

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 repository url?
[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 (@pjanck) 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: 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?
[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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[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?

Review checklist for @Abdoulayediak

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 repository url?
[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 (@pjanck) 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: 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?
[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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[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?

pjanck commented 3 years ago

Hi @hugoledoux - I believe we'll take the summer to improve on the few open points as mentioned by @CBenghi and @aothms - you can put this on pause. Apologies for taking this long, but it is quite a package :)

hugoledoux commented 3 years ago

Hi @hugoledoux - I believe we'll take the summer to improve on the few open points as mentioned by @CBenghi and @aothms - you can put this on pause. Apologies for taking this long, but it is quite a package :)

I understand. Let us know here when you've fixed these core issues.

danielskatz commented 3 years ago

👋 @pjanck - Any news on this as we move out of the summer?

pjanck commented 3 years ago

Hi @danielskatz & @hugoledoux

a short update - we're updating to VS 2019 and have been quite successful in the recent weeks (https://github.com/tumcms/Open-Infra-Platform/pull/449). We've decided to pull this through together with this publication.

You can expect a comprehensive answer to other listed issues by the reviewers in the next days.

jschlenger commented 2 years ago

Hi @CBenghi, @hugoledoux , @aothms, @abdoulayediak & @danielskatz

sorry for the late response. We've been struggling with the update to Visual Studio 2019 way longer than we expected, but now everything seems to be working fine. I went through your comments, and down below, I put a list of your comments together with a response on how and where we tackled the raised issues. Please take another look and let us know in case you have further comments.

The platform is aimed at providing a development platform, but there is no information about how to use the platform as such

→ Addition of a markdown file describing the overall software architecture to give developers a better understanding of how the OIP works and how they can adapt exiting modules to their needs (see Software Architecture).

The paper text mentions a cross platform solution, but only Windows is currently supported. This needs to be better documented and perhaps explained: why only 64bit, why only msvc 2015/17

Another point is the Windows-only support. Although I can see that the "cross-platform" claim was removed from the paper, it would be definitely valuable to state it early somewhere in the ReadMe of the repo.

→ Update to Visual Studio 2019 in the most recently merged pull request (see github.com/tumcms/Open-Infra-Platform/pull/319); Adjustment was made to the main Readme file and the paper that currently only Windows is supported.

The documentation gives very little detail on geometry interpretation (which entities are supported and mapped to what geometric/topological entities).

→ List with all supported entities was produced.

Looking at the authors Contribution and authorship concerns I wonder if you have properly considered the contribution of Cara Coetzee

→ Code contributions have been addressed properly in Contribution and Authorship file. Since this project is older than the repository itself (2013 vs 2017) there are also many authors' contributions not visible in the git history (we had some shenanigans with moving from one host to another, changing from hg to git, etc.). The decision was made, that only product managers would be the authors of the paper. The contributions of other (student) authors that worked on the project are acknowledged in the aforementioned file.

Perhaps connected to the previous point, on line 57 you mention the specific focus on preliminary Express schemas. This uniqueness could be better highlighted in the project documentation, providing instructions for custom schema implementation.

→ Explanation is given in the software architecture how one can introduce schema files of an IFC version (see Software Architecture).

Mentioning limitations of OIP in comparison to other frameworks could better serve the research community (e.g. what you mentioned about the single IFC version at a time).

→ Some limitations of OIP were added in the documentation (see here). Please advice if more is needed.

Installation documentation could be slightly improved to clarify that plenty of warnings in cmake should be expected.

→ Update of the installation documentation because of the update to VS2019 also mentioning the warnings that can be expected from cmake was introduced (see here and here).

I've noticed a few apps in the solution that support your testing and QA. I would invite you to produce a quick readme markdown that might help developers understand their purpose and contribute cases.

→ A new markdown file was added giving short explanations about the apps that are shipped together with OIP and what they can be used for.

jschlenger commented 2 years ago

@whedon generate pdf from branch joss_submission

whedon commented 2 years ago

Attempting PDF compilation from custom branch joss_submission. Reticulating splines etc...

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:

hugoledoux commented 2 years ago

👋 @CBenghi @aothms @abdoulayediak

the author fixed the issues you discussed, and modified the paper. Could you please have another look and let us know here if you're happy (also by clicking in the tickboxes above)?

hugoledoux commented 2 years ago

@whedon re-invite @aothms as reviewer

whedon commented 2 years ago

The reviewer already has a pending invite.

@aothms please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations

hugoledoux commented 2 years ago

@whedon invite @aothms as reviewer

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

hugoledoux commented 2 years ago

@whedon add @aothms as reviewer

whedon commented 2 years ago

OK, @aothms is now a reviewer

aothms commented 2 years ago

Dear authors, thank you for your efforts here, I think the paper + repo improved substantially. I just have the following two points that are a bit hard to check off in the current state:

I still find the following really minimal (if any):

State of the field: Do the authors describe how this software compares to other commonly-used packages?

For:

Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

I did see unit tests, but I didn't find a line in the docs with some background info and how to run them.

jschlenger commented 2 years ago

Hi @aothms,

thank you for your comments!

We kept the comparison with other software very minimal since the papers by Hecht & Jaud (2019) and Valero et al. (2020) did a thorough comparison with various software tools. We directly mention them as source of information about OIP compared to other software.

I just added a new section to the documentation about unit tests and how to run them (see github.com/tumcms/Open-Infra-Platform/pull/519)

aothms commented 2 years ago

Ok. thanks for clarifying. Good enough for me @hugoledoux

CBenghi commented 2 years ago

Hello all, Just a quick note from me about the timing of the review. I'm currently on leave and will be able to review the update just after Xmas. Happy holidays, Claudio

Il Gio 23 Dic 2021, 11:18 jschlenger @.***> ha scritto:

Hi @aothms https://github.com/aothms,

thank you for your comments!

We kept the comparison with other software very minimal since the papers by Hecht & Jaud (2019) and Valero et al. (2020) did a thorough comparison with various software tools. We directly mention them as source of information about OIP compared to other software.

I just added a new section to the documentation about unit tests and how to run them (see github.com/tumcms/Open-Infra-Platform/pull/519 https://github.com/tumcms/Open-Infra-Platform/pull/519)

— Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/3061#issuecomment-1000194842, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABJY7MIFXCDKZTJTSTIP2D3USLZQNANCNFSM4YESREPQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were assigned.Message ID: @.***>

jschlenger commented 2 years ago

Hi all (@hugoledoux @CBenghi @abdoulayediak @aothms),

just a short reminder that this review is still open. I believe we are quite close to the end, only a few boxes that are left tick. So I kindly remind the reviewers that haven't completed their review yet to take a look at our latest changes. In case there are questions or things that are unclear just let me know and I'll do my best to clarify them.

CBenghi commented 2 years ago

Hello @jschlenger, thanks for the reminder, I got to it straight away and checked the final boxes. The review is complete as far as I'm concerned. Congratulations to @pjanck and the rest of the team!

pjanck commented 2 years ago

Hi @hugoledoux - is there anything required from our side to complete this review? We're happy to resolve any last concerns.

hugoledoux commented 2 years ago

@editorialbot generate pdf

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

hugoledoux commented 2 years ago

a HUGE sorry is in order here @pjanck : I don't know how I let that go, but I seriously dropped the ball on that one. I thought it was done but no. Sorry.

I'm wrapping this up today, I'm going over the paper and proposing some fixes.

One thing I just noticed: the link above the first letter of your name is missing because it's a special char, but in previous it was there right? I just tried with a new paper and it should be there. Do you know what could be going on?

hugoledoux commented 2 years ago

@editorialbot generate pdf

hugoledoux commented 2 years ago

@editorial check references

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

hugoledoux commented 2 years ago

@editorialbot check references

editorialbot commented 2 years ago

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

OK DOIs

- 10.1061/(ASCE)CP.1943-5487.0000592 is OK
- 10.21105/joss.00473 is OK
- 10.1061/9780784480823.017 is OK
- 10.1061/9780784482421 is OK
- 10.22260/ISARC2020/0033 is OK

MISSING DOIs

- 10.1016/s0740-0020(08)00208-6 may be a valid DOI for title: IFC++

INVALID DOIs

- None

hugoledoux commented 2 years ago

I went through the paper, please check my recommendations: https://github.com/tumcms/Open-Infra-Platform/pull/540

The \v{S} is something on our side, I'll see how this can be fixed... not action on your side needed.

At this point could you:

[ ] Accept the PR above
[ ] Make a tagged release of your software, and list the version tag of the archived version here.
[ ] Archive the reviewed software in Zenodo or a similar service (e.g., figshare, an institutional repository)
[ ] Check the archival deposit (e.g., in Zenodo) has the correct metadata. This includes the title (should match the paper title) and author list (make sure the list is correct and people who only made a small fix are not on it). You may also add the authors' ORCID.
[ ] Please list the DOI of the archived version here.

I can then move forward with accepting the submission.

jschlenger commented 2 years ago

@hugoledoux I will start working on your ToDo list next week. I'll let you know as soon as I'm finished.

pjanck commented 2 years ago

10.1016/s0740-0020(08)00208-6 may be a valid DOI for title: IFC++

I can't seem to find this DOI anywhere. Also, IFC++ webpage does not list any publications that we could cite, or where a DOI could be identified. Deciding to ignore the comment.

jschlenger commented 2 years ago

I am not able to edit the review description. The tag is: release-v4.0.0

jschlenger commented 2 years ago

We have archived the release with Zenodo. The DOI is: 10.5281/zenodo.6488493

pjanck commented 2 years ago

@hugoledoux I believe we've completed all remaining actions. Thank you for your support!

hugoledoux commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:warning: An error happened when generating the pdf.

hugoledoux commented 2 years ago

@editorialbot generate pdf

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

hugoledoux commented 2 years ago

@editorialbot check references

editorialbot commented 2 years ago

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

OK DOIs

- 10.1061/(ASCE)CP.1943-5487.0000592 is OK
- 10.21105/joss.00473 is OK
- 10.1061/9780784480823.017 is OK
- 10.1061/9780784482421 is OK
- 10.22260/ISARC2020/0033 is OK

MISSING DOIs

- 10.1016/s0740-0020(08)00208-6 may be a valid DOI for title: IFC++

INVALID DOIs

- None

hugoledoux commented 2 years ago

@editorialbot set 10.5281/zenodo.6488493 as archive

editorialbot commented 2 years ago

Done! Archive is now 10.5281/zenodo.6488493

hugoledoux commented 2 years ago

@editorialbot set release-v4.0.0 as version

editorialbot commented 2 years ago

Done! version is now release-v4.0.0

hugoledoux commented 2 years ago

@editorialbot recommend-accept

editorialbot commented 2 years ago

Attempting dry run of processing paper acceptance...

editorialbot commented 2 years ago

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

OK DOIs

- 10.1061/(ASCE)CP.1943-5487.0000592 is OK
- 10.21105/joss.00473 is OK
- 10.1061/9780784480823.017 is OK
- 10.1061/9780784482421 is OK
- 10.22260/ISARC2020/0033 is OK

MISSING DOIs

- 10.1016/s0740-0020(08)00208-6 may be a valid DOI for title: IFC++

INVALID DOIs

- None

editorialbot 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/3176

If the paper PDF and the deposit XML files look good in https://github.com/openjournals/joss-papers/pull/3176, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

openjournals / joss-reviews