[REVIEW]: PySD: System Dynamics Modeling in Python

[editorialbot]

Submitting author: @rogersamso (Roger Samsó)
Repository: https://github.com/SDXorg/pysd
Branch with paper.md (empty if default branch): paper_pysd
Version: v3.7.1
Editor: @pdebuyl
Reviewers: @blsqr, @sixpearls
Archive: 10.5281/zenodo.7094483

Status

Status badge code:

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

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

@blsqr & @andrecieplinski, 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 @pdebuyl 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 @blsqr

📝 Checklist for @sixpearls

[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.19 s (472.2 files/s, 142175.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          49           4086           4817          14281
SVG                              1              1              1            909
reStructuredText                19            510            285            729
Jupyter Notebook                 1              0            626            444
make                             2             38              7            183
TeX                              1             12              0            120
Markdown                         4             50              0            115
XML                              7              0              0             79
YAML                             3             13              8             62
SQL                              3              0              0             21
INI                              1              0              0              2
-------------------------------------------------------------------------------
SUM:                            91           4710           5744          16945
-------------------------------------------------------------------------------


gitinspector failed to run statistical information for the repository

[editorialbot]

Wordcount for paper.md is 1178

[editorialbot]

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

OK DOIs

- 10.1016/j.rser.2020.110105 is OK
- 10.1016/j.esr.2020.100582 is OK
- 10.1002/sdr.1474 is OK
- 10.1088/1748-9326/ac2f62 is OK
- 10.1002/sdr.1695 is OK
- 10.5281/zenodo.5654824 is OK
- 10.1016/j.jmsy.2019.10.004 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

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

[blsqr]

Review checklist for @blsqr

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/JamesPHoughton/pysd/?
• 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 (@rogersamso) 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?

[blsqr]

I have opened a first issue regarding the software paper over in the PySD project.

FYI: The next two weeks I will not be available for review or questions, but will pick up the review some time in the middle of May.

[rogersamso]

Thank you for for the review. I answered on the issue you created in the PySD repo. In brief, we have made a couple of commits with which we expect to have answered all your comments. Thanks again!

[blsqr]

@editorialbot generate pdf

[editorialbot]

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

[rogersamso]

@editorialbot generate pdf

[editorialbot]

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

[pdebuyl]

Hi @blsqr thanks for the review! Please make sure (both author and reviewer) to let me know in this issue page about further progress (as I am not subscribed to the issue discussion).

[andrecieplinski]

Hi @rogersamso, I finally managed to use pysd and run some simple models. However, I am having some trouble converting a more complex model. I am not sure if I am trying to upload a model with features not supported in pysd or doing something wrong.
Also I a not sure if this is where I should ask this, sorry, still trying to figure out Github.

I get the following message:
"model = pysd.read_vensim('model.mdl')
Traceback (most recent call last):

File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\translation\vensim\vensim2py.py", line 470, in get_equation_components
tree = parser.parse(equation_str)

File "C:\Users\UTENTE\anaconda3\lib\site-packages\parsimonious\grammar.py", line 115, in parse
return self.default_rule.parse(text, pos=pos)

File "C:\Users\UTENTE\anaconda3\lib\site-packages\parsimonious\expressions.py", line 122, in parse
raise IncompleteParseError(text, node.end, self)

IncompleteParseError: Rule 'entry' matched in its entirety, but it didn't consume all the text. The non-matching portion of the text begins with ' [mining],[petroleum' (line 1, column 36).

During handling of the above exception, another exception occurred:

Traceback (most recent call last):

File "", line 1, in
model = pysd.read_vensim('model.mdl')

File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\pysd.py", line 129, in read_vensim
py_model_file = translate_vensim(mdl_file, split_views, encoding, **kwargs)

File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\translation\vensim\vensim2py.py", line 1957, in translate_vensim
translate_section(section, macro_list, sketch, root_path, subview_sep)

File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\translation\vensim\vensim2py.py", line 1627, in translate_section
entry.update(get_equation_components(entry["eqn"], root_path))

File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\translation\vensim\vensim2py.py", line 475, in get_equation_components
raise ValueError(

ValueError: Subs_RES_fossil_SRF_i[ind] :EXCEPT: [mining],[petroleum],[electricity],[transport]= 0

Error when parsing definition:
Subs_RES_fossil_SRF_i[ind] :EXCEPT: [mining],[petroleum],[electricity],[transport]= 0

probably used definition is invalid or not integrated...
See parsimonious output above."

thanks a lot,

andré

[enekomartinmartinez]

Hi Andre, The error is because of a missing feature. As the parser stops with a list of subscript ranges I suposse that this will be part of an :EXCEPT: declaration. If this is the case, this bug is already fixed in a branch and will be solved in a future release. Please, could you share the full equation where the string '[mining],[petroleum' appears? Thank you, Eneko Andre Cieplinski ***@***.***> igorleak hau idatzi zuen (2022 api. 27, az. 23:28):

…

Hi @rogersamso <https://github.com/rogersamso>, I finally managed to use pysd and run some simple models. However, I am having some trouble converting a more complex model. I am not sure if I am trying to upload a model with features not supported in pysd or doing something wrong. Also I a not sure if this is where I should ask this, sorry, still trying to figure out Github. I get the following message: "model = pysd.read_vensim('model.mdl') Traceback (most recent call last): File "C:\Users\UTENTE\anaconda3\lib\site-packages\pysd\translation\vensim\vensim2py.py", line 470, in get_equation_components tree = parser.parse(equation_str) File "C:\Users\UTENTE\anaconda3\lib\site-packages\parsimonious\grammar.py", line 115, in parse return self.default_rule.parse(text, pos=pos) File "C:\Users\UTENTE\anaconda3\lib\site-packages\parsimonious\expressions.py", line 122, in parse raise IncompleteParseError(text, node.end, self) IncompleteParseError: Rule 'entry' matched in its entirety, but it didn't consume all the text. The non-matching portion of the text begins with ' [mining],[petroleum' (line 1, column 36)." thanks a lot, andré — Reply to this email directly, view it on GitHub <#4329 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOTSLBZKGTTA33U7A2VQGSLVHG5QFANCNFSM5T4ZZWHQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[rogersamso]

Dear @andrecieplinski thanks for contacting. As @enekomartinmartinez mentions, this new feature will be added in the upcoming release 3.0 of pysd. Please let's not continue this discussion here. Either open a new issue in the pysd repo, or drop as an email. Thanks again.

[rogersamso]

Dear @pdebuyl and @andrecieplinski , I just realized @andrecieplinski was assigned as reviewer for the paper. I see a potential conflict of interest, as @andrecieplinski is collaborating in the same research project than us (h2020 LOCOMOTION). please let us know if this may cause problems.
Regards

[pdebuyl]

Hi @rogersamso thanks for mentioning this. I'll check with other editors whether this is a problem or not.

[pdebuyl]

Hi all, we may proceed the review with @andrecieplinski , the association only by being member of a funding consortium -- provided there was no direct collaboration -- is not a sufficient conflict of interest for JOSS.

[blsqr]

I opened another issue in the PySD project regarding the remaining review points for the documentation.

[blsqr]

Regarding the list of authors: Could you briefly explain the role of Jordi Solé in the creation of PySD and this paper?

[rogersamso]

Apart from being the one who bet on the use of PySD in the H2020 projects MEDEAS and LOCMOTION, which led to the major changes that took place from 0.9 to the newest 3.0, Jordi Solé has been part of all design decisions that have been taken during the whole process. He has also reviewed the paper several times, and is now following the revision process.

[Kevin-Mattheus-Moerman]

@pdebuyl thanks for handling this submission. In the future please ensure you ask authors to amend the archive meta-data to match that of the paper (e..g title and authors).

[Kevin-Mattheus-Moerman]

@rogersamso

In relation to the archive:

• Please manually edit the ZENODO archive listing so that the meta-data matches that of the paper. In particular fix the title and the author list. Furthermore you can ensure the correct license is listed and may opt to add the author ORCID fields.

On the paper

• Please add city and country information to all affiliations (do not use acronyms for countries)

[pdebuyl]

Hi @Kevin-Mattheus-Moerman sorry about this, I normally check the zenodo record but forgot this time.

[Kevin-Mattheus-Moerman]

@pdebuyl no worries 👍

[Kevin-Mattheus-Moerman]

@rogersamso 👋 ☝️

[rogersamso]

Hi @Kevin-Mattheus-Moerman, sorry for the lack of response. We'll look into it asap.

[enekomartinmartinez]

@editorialbot generate pdf

[editorialbot]

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

[enekomartinmartinez]

Please manually edit the ZENODO archive listing so that the meta-data matches that of the paper. In particular fix the title and the author list. Furthermore you can ensure the correct license is listed and may opt to add the author ORCID fields.

@JamesPHoughton can you take care of this please?

[JamesPHoughton]

I've taken a crack at it, let me know if it isn't correct. =)

[kyleniemeyer]

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

[kyleniemeyer]

Congratulations @rogersamso @enekomartinmartinez and @JamesPHoughton on your article's publication in JOSS!

Many thanks to @blsqr and @sixpearls for reviewing this, and @pdebuyl for editing.

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

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

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

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

[pdebuyl]

Thanks @kyleniemeyer :-)

[rogersamso]

Thanks @kyleniemeyer @pdebuyl @blsqr and @sixpearls ! Publishing in JOSS was such an awesome experience! Thank you all for helping us improve PySD!

[enekomartinmartinez]

Thanks to all of you for all the work!!! 🎉

[JamesPHoughton]

Thanks everyone, especially to @enekomartinmartinez. =)