Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Requested Edits from JOSS #2666

Open
33 of 41 tasks
jackiekazil opened this issue Feb 6, 2025 · 10 comments
Open
33 of 41 tasks

Requested Edits from JOSS #2666

jackiekazil opened this issue Feb 6, 2025 · 10 comments
Assignees
Labels
docs Release notes label

Comments

@jackiekazil
Copy link
Member

jackiekazil commented Feb 6, 2025

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

References:


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)

Comments on the introductory tutorial (@tpike3)

  • 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.

  • [from Marti] In the "Agent management" section, the AgentSet class is mentioned but doesn't appear explicitly in the code. It should be clarified that it's instantiated automatically with the models and then made available through the agents attribute. This applies to both the paper and the introductory tutorial.

  • [from Marti] The introductory and visualization tutorials would be better served as self-contained notebooks with a "pip install" cell to install the tutorial's requirements. For instance, the introductory tutorial only requires pip install mesa whereas the visualization tutorial requires pip install "mesa[viz]". This may seem obvious but not if someone jumpstarts to the tutorials without going to "Installation Options" section on the documentation index.

Comments on the visualization tutorial (@tpike3)

  • 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.

  • [from Marti] Similar to the previous point, it's difficult to know which MoneyModel to use in the visualization tutorial. Many MoneyModel classes are defined in the introductory tutorial, so it would be better to include the class definition in the visualization tutorial, even if repetitive.

Comments on the code

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

  • Typing
    (split off in Missing Agent type hints #2716)

    • 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)
  • [from Marti] Question about packaging: The source distribution is quite big (2.4 MB), is that intended? In most Python libraries the docs are excluded from the source distribution (the docs account for 2.5 out of the total 3.4 MB). Also, are the basic examples packaged as a core mesa module for a particular reason?
    Resolved in Clean-up old images, compress wolf-sheep image, remove version switch artifact #2717

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. (@jackiekazil)

  • l41 For consistency with the other sections, please add a code example of instantiating a model and passing a seed paper: Add code examples and clarify terminology #2719

  • l46 Similarly, please add a code example of instantiating and subclassing an agent paper: Add code examples and clarify terminology #2719

  • 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. paper: Add code examples and clarify terminology #2719

  • l109 I would suggest to move the "Applications" section to the start of the paper (@jackiekazil)

  • l134 Acknowledgements are usually placed after the conclusions (@jackiekazil)

  • [from Marti] Review of related tools is missing. Besides agentpy, potential candidates include Melodie (which also has a JOSS paper), helipad, pythonabm, and bptk_py. These merit consideration and should potentially be referenced in the paper.

    • The paper is already on the (very) long side for a JOSS paper, I think that would make the paper too long.
  • [from Marti] Typos and minor syntactic comments: (@jackiekazil)

    • line 21: missing space between "NetLogo" and "in"
    • line 34: "everything" seems too informal, suggest changing to something like "has been applied to modeling a wide range of phenomena from economics ..."
    • line 126: broken SolaraViz link

Smaller comments on the paper

@jackiekazil
Copy link
Member Author

jackiekazil commented Feb 6, 2025

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
Copy link
Member

EwoutH commented Feb 6, 2025

@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
Copy link
Member

EwoutH commented Feb 9, 2025

@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.

@jackiekazil
Copy link
Member Author

@wang-boyu, for the stuff that was merged in #2678, can you mark it off in the list above, so we know it is complete?

@wang-boyu
Copy link
Member

Done!

@EwoutH
Copy link
Member

EwoutH commented Mar 6, 2025

@projectmesa/maintainers I updated the first post in this issue with the new comments from Martí Bosch, our second reviewer. Those have the prefix [from Marti].

Now, let's try to distribute some task. Please mark your checkbox if you're okay with picking this up, and if not or if you have an other idea or thing you want to do, let us know.

  • I will pick up the documentation comments
  • @jackiekazil can you pick up the remaining comments on the paper itself?
  • @tpike3 are you willing to pick up the comments on the introduction tutorial, the visualisation tutorial, or both?
  • @wang-boyu are you willing to pick up the typing comments or one of the tutorials?

@quaquel I know you are very busy right now, but maybe you could review some of the incoming PRs on the paper.

@martibosch, I temporarily invited you to become a Triager in Mesa, please consider accepting so you can also review these PRs. This will only be for the duration of the paper review.

@Sahil-Chhoker if you want to contribute anything to our paper as collaborator, I'm good with that. We can mention you in the acknowledgements, if that matters to you.

Let's wrap it up!

@jackiekazil
Copy link
Member Author

The line numbers are quite helpful in the comments, but with all the edits -- I am struggling to track down which line. Does anyone know how to refer to a previous version of the paper?

Example of what I am struggling to identify specifically (but this probably won't be the only one) --
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

@EwoutH
Copy link
Member

EwoutH commented Mar 11, 2025

@jackiekazil
Copy link
Member Author

@EwoutH It looks like the links to the papers -- link to the same paper. So the links do no update but the paper is updated when it is rebuilt. Trying to figure out another way without digging into git history, but maybe that is it. Can you do a sanity check for me?

@EwoutH
Copy link
Member

EwoutH commented Mar 12, 2025

No it's just a version from git history I'm afraid.

Our CI does build a PDF on every change, so for every commit there should be a PDF available in our CI here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Release notes label
Projects
None yet
Development

No branches or pull requests

4 participants