Create initial version of JOSS paper

[EwoutH]

Discussion is continued in:

• Tracking issue: JOSS paper #2559

---

The initial version of a paper for JOSS. It follows the JOSS Paper Format, and intents to capture the most important aspects of Mesa and Mesa 3.0.

The order of names is open for discussion.

@rht you have made significant contributions to Mesa 3.0, would you like to be included as author? If so, under which name and/or ORCID?

TODO:

• (everyone) Check names and ORCIDs
  • @EwoutH
  • @quaquel
  • @Corvince
  • @tpike3
  • @rht
  • @wang-boyu
  • @jackiekazil
• (optionally) add affiliations
• Add references (in bibtex)

cc @projectmesa/maintainers. Feel free to directly edit the paper on this PR branch.

[tpike3]

@ewout this is great, I am good with what you have written. I put some comments which were really just my thoughts when I was reading it. Feel free to ignore or include at your leisure.

For my affiliation as I am transitioning I would just do

name: Independent Researcher, USA
index: 1

[tpike3]

Some bibtex for consideration

@book{epstein_axtell_1996,
author = {Joshua M. Epstein and Robert Axtell},
title = {Growing Artificial Societies: Social Science from the Bottom Up},
year = {1996},
publisher = {Brookings Institution Press and MIT Press},
address = {Washington, DC, and Cambridge, MA},
isbn = {9780262550253},
}

@inproceedings{Dra_gulescu_2003,
title={Statistical Mechanics of Money, Income, and Wealth: A Short Survey},
volume={661},
ISSN={0094-243X},
url={http://dx.doi.org/10.1063/1.1571309},
DOI={10.1063/1.1571309},
booktitle={AIP Conference Proceedings},
publisher={AIP},
author={Drǎgulescu, Adrian A.},
year={2003},
pages={180–183} }

@book{schelling_2006,
author = {Thomas C. Schelling},
title = {Micromotives and Macrobehavior},
year = {2006},
publisher = {W. W. Norton & Company},
address = {New York},
edition = {Revised},
isbn = {9780393329469},
}

[wang-boyu]

Would you like to try a GitHub action to compile the paper into a pdf file: https://joss.readthedocs.io/en/latest/paper.html#github-action?

I don't know whether it will work with this PR, and it may not be needed after the paper is accepted.

[EwoutH]

@wang-boyu done.

[quaquel]

This is my feedback on the current draft. This is written from the perspective of a reviewer.

Why center the story on 3.0, rather than present MESA in its 3.0 incarnation? I checked a large number of papers in JOSSS, and all of them just introduce a library. The storyline of this manuscript, in contrast, focuses a lot on 3.0 and what is new. I would advocate against that narrative. Instead, I would introduce MESA, mention in passing that this reflects the 3.x version, and then explain how mesa is structured.

Practically, this implies a few things

1. Add a short 1 paragraph description of agent-based modeling at the start. So something along the lines of a simulation approach for simulating the actions and interactions of heterogenous autonomous agents positioned in some space. This paragraph should structure the rest: so, agents and agent management/activation, the representation of space(s), and something on time advancement.
2. When we introduce agent management, it is fine to mention that this is new in mesa 3, but mainly just focus on how it works and why it was designed that way.
3. Give a slightly broader introduction to spaces in mesa before mentioning property layers. I personally would center this more on the new-style spaces and just ignore old-style spaces since these will be deprecated over the next releases.
4. I would modify data collection and analysis and rephrase this to be about computational experimentation with MESA. Here we could explain that the focus of MESA is on model building. We only offer rudimentary support for experimentation. Next, we can refer to other libraries like numpy.qmc, salib, and ema_workbench that can easily be combined with mesa for more sophisticated experimentation. This is a fundamental departure from other ABM software that tries to do everything (e.g., NetLogo behavior space). We can then discuss what hooks mesa offers: so, just create a new model instance for a given seed and experiment. How data gathering works with collectors, etc.
5. I am not sure how I would handle experimental features. This, to me, is more of an implementation concern. One option is to weave them into the rest of the story instead of being in a stand-alone section.

Implementing these suggested changes is pretty straightforward. It would require rephrasing stuff in various places. Structurally, It would mean splitting key features into three parts: abm framework, visualization, and experimentation. ABM framework would then break down into agents and their management, spaces, and management of time.

[EwoutH]

Thanks for your extended perspective. This is really high-quality, thoughtful feedback.

Why center the story on 3.0, rather than present MESA in its 3.0 incarnation?

This was something I was in doubt with as well. I think a paper has to have an intended audience, and I see two possible audiences in our case:

1. People who are unfamiliar with Mesa, and want to have an recent "overview" on it.
2. Users who have used Mesa before, read an earlier paper or are some, and would like an "update" publication on Mesa.

So basically we have to choose a little between "overview" or "new since last paper". I think a case can be made for both. If we plan to do a new paper every 2 or 3 years, I might think that option two offers more novelty for each paper, because the overlap is smaller. On the other hand option 2 is less readable standalone.

Both are also provided already in our docs (which are kept up to date better than a paper), so it needs to be considered what's most useful for our academic audience.

Personally I'm still contemplating what the best way to go is. @projectmesa/maintainers I would really love to hear which audience you think we should target.

[wang-boyu]

I would go for option 1), so that interested people only need to read this one latest paper. Even for users who are already quite faimilar with Mesa, they may not remember what was there in earlier papers.

If we plan to do a new paper every 2 or 3 years

Looks like we are doing it every 5 years - previous papers were published in 2015 and 2020, with this one most likely to be published in 2025. Of course this may change if things move faster in the future.

Some comments from my side:

1. Shall we have an Acknowledgements section to acknowledge and thank the contributions from the community, like how it was done in pervious Mesa and Mesa-Geo papers? Particularly if @rht doesn't respond regarding his authorship, we could at least acknowledge and thank his efforts these years in this section.
2. For affiliations shall we put both @tpike3 and @Corvince as "Independent Researcher"? Not sure about @jackiekazil though.
3. Is it too much to ask for an updated component diagram for Mesa? Something similar to Fig. 1 in the last Mesa paper, and Fig. 1, 2, & 3 in the Mesa-Geo paper. I found it very helpful in understanding how Mesa works when I first read the Mesa paper.
4. I would also suggest to add some more references for the applications of Mesa. We can also cite the Mesa-Geo paper (sadly a mesa-frames paper is not yet ready).

I know it is a lot of work to draft the paper. Thanks @EwoutH for your efforts!

[quaquel]

I like @wang-boyu suggestions. I might be able to create some time over the christmas break to contribute if needed.

[jackiekazil]

@EwoutH do you prefer to get comments on individual sections or PR w/ suggested edits to your fork?

[EwoutH]

Here's what I propose:

1. I'm going to merge this PR into the paper_2024 branch.
2. I'm going to rewrite it into an paper that's readable standalone.
3. I will add an Acknowledgements section.

Then there are some other tasks:

• Create an components diagram
• Source more relevant references
• Provide further feedback and improvements

From my perspective, everyone can open PRs into the paper_2024 branch to update certain components. When reviewing, you can also use the "suggestions" feature in GitHub (see Incorporating feedback in your pull request).

[jackiekazil]

I am not sure I understand this and would like to help get this done. I know the holidays are upon us, and the meeting on Tuesday didn't happen. I don't have time to meet today at a reasonable time. Can you meet tomorrow (Thursday) at our regular Tuesday time (8:30 EST / 2:30 CST) to quickly work through this?

[EwoutH]

That time won’t work, a few hours later might (between 16:00 and 18:00 CET).

[jackiekazil]

Had a quick discussion... it seems the normal time on Friday will work -- so we will meet then. If anyone else would like to join, we will be on matrix.

[EwoutH]

I transferred most of the discussion to a new tracking issue:

• Tracking issue: JOSS paper #2559

Merging this PR into the paper_2024 branch, let's continue the discussion in the tracking issue!