Requested Edits from JOSS

[jackiekazil]

A review with requested edits have come in from JOSS. The checklist is below. Let's use this ticket for tracking.

References:

• Requested edits with full comment: [REVIEW]: Mesa 3: Agent-based modelling with Python in 2024 openjournals/joss-reviews#7668 (comment)
• Parent ticket: Tracking issue: JOSS paper #2559

---

Major comments

• Experimental features: cell spaces and event-based scheduling (lines 76 & 86) (paper: Clearly mark experimental features #2675)
  • I believe these features should be completed before publication. Publishing a work in progress is not ideal, particularly since this is not the first paper on this package and these features appear to be close to a stable release.
  • Additionally, when I attempted to test these new features - which I find to be very interesting innovations - I found the online documentation lacking sufficient information.
  • If completing these features before publication is not feasible, I recommend moving them to a dedicated section such as Future Plans or Next Steps.

Comments on the documentation (@EwoutH)

• On the index page, I would add a sentence explaining what the "rec" and "all" extensions are needed for respectively (e.g. the visualization package?). docs: Clarify recommended dependencies in installation guide #2672

• I would suggest to put the "Overview of the MESA library" section within "Getting started" as a seperate page, as it is a handy reference that is more accessible than the API documentation, also after getting started. docs: Split off the overview page, extend with spaces/activation #2673

• In addition, it would be great for the overview to cover all features of MESA. Compared to the paper, spaces and time advancement are missing here. docs: Split off the overview page, extend with spaces/activation #2673

Comments on the introductory tutorial

• In the introductory tutorial, it is a bit confusing what is supposed to go in the jupyter or the python file. For simplification of the tutorial, I would recommend for the whole tutorial to be within the jupyter file. If you want to keep the recommendation to split up files, I would add it as a tipp in "Best practices".

• For the setup, using code cells with terminal commands "!pip install --upgrade mesa[rec]" (note the exclamation mark at the start) enables installation within the jupyter file, removing the need for special instructions for google collab.

• Please put line breaks into the comments that are longer than 79 characters, allowing the documentation do be read on half-screen.

• Some sentences do not start capitalized.

Comments on the visualization tutorial

• In the visualization tutorial, I would put the whole code of "MoneyModel.py" within the jupyter notebook, removing the need to search through the first tutorial for a file that is not really described.

• Maybe mention that the visualization needs the "rec" dependencies in the installation?

• I find the "Choose version" button at the top confusing, as it does not display the currently chosen version and there is already an indication on the bottom right.

Comments on the code

• The quality of the code and tests seem very good!

• Typing

  • One thing that could be positively highlighted is that MESA is using type hints. However, some additions would be needed for it to be able to run in a strongly typed environment.
  • In the introductory tutorial, chapter "Agents Exchange"/"Running your first model", I get a type error for "other_agent.wealth"/"a.wealth". It seems that model.agents does not return the correct agent type.
  • Same with using self.model within agent, the Agent does not know about the model types. (e.g. model.grid)

Comments on the paper

• l16 The Statement of Need could be more clearly structured. Currently, it reads more like a historical recap. I recommend organizing it along these lines: (1) Why such a package is needed, (2) The current state of the field, and (3) What MESA contributes — focusing on its present state rather than its 2014 origins. Additionally, please refer to the Statement of Need and State of the Field requirements outlined in the JOSS checklist above to ensure alignment with the journal's expectations.

• l41 For consistency with the other sections, please add a code example of instantiating a model and passing a seed

• l46 Similarly, please add a code example of instantiating and subclassing an agent

• l80 & l86 Maybe call these two 'modes' "discrete time" and "continuous time", if I understood it correctly? I think that would make it easier to understand.

• l109 I would suggest to move the "Applications" section to the start of the paper

• l134 Acknowledgements are usually placed after the conclusions

Smaller comments on the paper

• l15 Change to 2025 (@wang-boyu)

• l17 Not all ABMs represent artificial societies, here it is an implied synonym (@wang-boyu)

• l20 The two references need to be placed into the same bracket (@wang-boyu)

• l28 I think it should say here: "an" improved visualization framework (@wang-boyu)

• l34 What does pure python mean? Does it not also use C, JS/React, etc.?

• l35 Markdown mistake in list formatting (@wang-boyu)

• l43 Word repetition: "instantiates" (@wang-boyu)

• l46 Please add a sentence describing agent types, to understand what the types mean later at "Data collection"

• l62-64 Please shortly explain these terms or add a reference

• l94 Markdown mistake, close bracket for link (@wang-boyu)

• l96 Please add a link or reference regarding the Solara package

• l97 Please use a code example and screenshot that correspond to each other, demonstrating what kind of code creates what kind of visualization.

• l98 Maybe add a sentence how this visualization module aligns or differs with the established standard of NetLogo.

• l126 Markdown mistake in list formatting (@wang-boyu)

• l133 Maybe add a sentence on which range of topics are covered by these community extensions and add a link or reference to a list or overview of these extensions and tutorials same as with the example models

• l143 Maybe say "want" instead of "need"?

[jackiekazil]

I am going to do a sweep of the smaller comments -- probably this weekend.
If anyone wants to help and they pick something up -- PLEASE edit the ticket and put your name behind the bullet, so double work isn't done.
Also - please make sure all PRs are linked.
/cc @quaquel, @tpike3, @wang-boyu

[EwoutH]

@jofmi thanks a lot for your detailed and thorough review! It’s really nice to have a fresh sets of eyes on it.

Jackie thanks for creating the tracking issue.

At some point we had experimental split out in a separate section, maybe we could revert to that. Also, we’re stabilizing the cell space so that shouldn’t be an issue. I see a few options for the other features:
1. We could split them out in a separate section (like earlier).
2. We clearly mark all experimental features with an experimental label, in the current structure.

Curious what everybody (including @jofmi) thinks about both.

As on the other feedback (please check if you can work on it):

• @tpike3 since you worked on the tutorials recently, would you like to pick this up?
• @quaquel would you like to work on typing?
• I can take some of the documentation issues
• @jackiekazil could you take on the comments on the paper itself?

[EwoutH]

@jofmi @martibosch I invited you both as "Triager" of the Mesa repo, so you can directly review PRs related to the JOSS paper.

@projectmesa/maintainers please let me know if you can pick up the points above. @wang-boyu if you see anything you could pick up, also please let me know.