docs: Update the intro tutorial with extended analysis #1625

EwoutH · 2023-03-28T21:22:45Z

Update the intro tutorial. Use Seaborn for more flexible and easier to read and manipulate plots. Add parts about analysing agent reporters and showing some different kinds of plots.

Also make seaborn a required dependency
Also let the DataCollector save index name(s) for the DataFrames returned. This enables not manually having to label the x-axis each time when the time step is used on the x-axis, and improved unstacking.

For now I only updated the Jupyter Notebook, I will convert to .rst and update all the images once everybody agrees on the updated context.

I was also thinking about an more extensive experimental and analysis tutorial with a more complex model, but that's for another time.

Update the intro tutorial. Use Seaborn for more flexible and easier to read and manipulate plots. Add parts about analysing agent reporters and showing some different kinds of plots. - Also make seaborn a required dependency - Also let the DataCollector save index name(s) for the DataFrames returned. This enables not manually having to label the x-axis each time when the time step is used on the x-axis, and improved unstacking.

codecov · 2023-03-28T21:27:13Z

Codecov Report

Patch coverage: 100.00% and project coverage change: +0.02 🎉

Comparison is base (9a07a48) 81.81% compared to head (ac24f5e) 81.84%.

❗ Current head ac24f5e differs from pull request most recent head 597ba4e. Consider uploading reports for the commit 597ba4e to get more accurate results

Additional details and impacted files

@@              Coverage Diff               @@
##           doc_builds    #1625      +/-   ##
==============================================
+ Coverage       81.81%   81.84%   +0.02%     
==============================================
  Files              18       18              
  Lines            1386     1388       +2     
  Branches          271      271              
==============================================
+ Hits             1134     1136       +2     
  Misses            206      206              
  Partials           46       46

Impacted Files	Coverage Δ
mesa/datacollection.py	`90.80% <100.00%> (+0.21%)`	⬆️

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

EwoutH · 2023-03-29T21:25:25Z

@jackiekazil, @tpike3, @rht, @Tortar and others, if you could find the time this week (or weekend) to review the changes to the tutorial that would be awesome. Now it’s still fresh in my head so making changes is relatively fast and easy.

tpike3 · 2023-04-01T10:59:28Z

docs/tutorials/intro_tutorial.ipynb

@EwoutH Can you please clear your outputs in your kernel? Otherwise there is a significant numbers of changes that are not substantive.

Yes, I can definitely do that if preferred. It might be a bit harder to see the results from the changes however.

Are your running the make html command so it updates the read the docs/ sphinx for the tutorial? This way you tutorial changes will be visible as part of the tutorial.

Not yet. I have no experience with make html, for converting Jupyter notebooks I normally use nbconvert.

The current format is .rst, does make html convert to that format (ReStructuredText) by default? Where/how do I run it?

So make html is part of Sphinx which will autobuilds the docs. If you don't want go through that process, no worries, just make changes to the .ipynb (plese clear your cell outputs) and then when I am updating the docs as part of 2.0 I will take care of it (but it may be a few weeks before it shows up).

tpike3 · 2023-04-01T11:10:09Z

setup.py

@@ -8,7 +8,7 @@

 from setuptools import find_packages, setup

-requires = ["click", "cookiecutter", "networkx", "numpy", "pandas", "tornado", "tqdm"]
+requires = ["click", "cookiecutter", "networkx", "numpy", "pandas", "tornado", "tqdm", "seaborn"]


I will raise this at the dev meeting today, but generally, adding dependencies is a considered a very big deal as we try and keep Mesa as lean as possible to reduce complexity and dependency issues.

Yes, I understand. Since matplotlib itself also isn't an dependency, we can also introduce an optional "plotting" dependency which includes matplotlib and seaborn.

The dev meeting got pushed to the 15th, however, instead of adding to ore dependencies can you add to the requirements.txt? Please see comments in the .ipynb file.

The requirements.txt of Mesa itself or of the boltzman wealth model in mesa-examples?

Of the Boltzman wealth please this way we keep Mesa lean. So matplotlib and seaborn will just be a dependency for the tutorial and not for Mesa.

Yeah, Matplotlib/Seaborn shouldn't be a required dependency to install Mesa. I think the ModuleNotFoundError is a sufficient error message, that we shouldn't have a requirements.txt that is specific to the tutorial.

tpike3 · 2023-04-01T12:58:25Z

mesa/datacollection.py

@@ -244,6 +246,7 @@ def get_agent_vars_dataframe(self):
            columns=["Step", "AgentID", *rep_names],
            index=["Step", "AgentID"],
        )
+        df.index.names = ["Step", "AgentID"]


Why do you need to add line 249; line 247 makes the index "Step" and "AgentID"

tpike3 · 2023-04-01T13:14:14Z

mesa/datacollection.py

-        return pd.DataFrame(self.model_vars)
+        df = pd.DataFrame.from_dict(self.model_vars)
+        df.index.name = "Step"
+        return df


Two comments/questions:

This change would explicitly show that the index is the "Step"? I don't have any issues with this change as it is consistent with principle of least surprise and makes it constant with agent dataframe. But could you also please update docstrings as this would make it no longer implicit.

pd.DataFrame(self.model_vars) and pd.DataFrame.from_dict(self.model_vars) is there a particular reason for changing it?

tpike3 · 2023-04-02T12:49:12Z

docs/tutorials/intro_tutorial.ipynb

    "```\n",
    "\n",
    "When you do that, it will install Mesa itself, as well as any dependencies that aren't in your setup yet. Additional dependencies required by this tutorial can be found in the **examples/boltzmann_wealth_model/requirements.txt** file, which can be installed directly form the github repository by running:\n",
    "\n",
    "```bash\n",
-    "    $ pip install -r https://raw.githubusercontent.com/projectmesa/mesa/main/examples/boltzmann_wealth_model/requirements.txt\n",
+    "    $ pip install --upgrade -r https://raw.githubusercontent.com/projectmesa/mesa/main/examples/boltzmann_wealth_model/requirements.txt\n",
    "```\n",


@EwoutH this link is broken since we moved the examples to the mesa-examples repo.

Could you fix the boltzman wealth link and instead of adding in seaborn to the Mesa dependencies why not just add seaborn to the requirements.txt file? (Although we need to update this a pipfile) but that can be later on down the road and should not hold up this merge.

Good catch, done!

tpike3 · 2023-04-02T12:55:42Z

@EwoutH thanks for doing and sorry my comments have been a little chaotic. I have had some work deadlines have had to dig in piecemeal.

- Update the dependency installation link in the tutorial to https://github.com/projectmesa/mesa-examples/blob/main/examples/boltzmann_wealth_model_network/requirements.txt - Update the DataCollector to remove redundant changes (adding index names and the to_dict().

rht · 2023-04-25T14:06:43Z

The plots definitely look more closer to ggplot2 plots. The DataFrames are optional in some of them, and there is virtually no added complication either. I haven't had the time to review the whole intro_tutorial.ipynb content because the diff is huge, with some sections being rewritten, and some being added.

jackiekazil · 2023-04-25T16:45:50Z

@EwoutH we have some tutorial changes at PyCon US sprints. Changes will probably slow down after this week.
I have repointed this to doc_builds to make sure they build correctly before they go directly into main.

Most of the changes at PyCon are textual in nature -- basically writing a smoother & more welcoming tutorial.

EwoutH · 2023-04-26T11:06:39Z

Thanks for getting back. Do you need anything from me at this moment? What's now the next step?

rht · 2023-05-07T05:41:58Z

docs/tutorials/intro_tutorial.ipynb

   "source": [
-    "Lastly, we want to take a look at the development of the Gini coefficient over the course of one iteration. Filtering and printing looks almost the same as above, only this time we choose a different episode."
-   ]
+    "In this case it looks like the Gini coefficient increases slower for smaller populations. This can be because of different things, either because the Gini coefficient is a measure of inequality and the smaller the population, the more likely it is that the agents are all in the same wealth class, or because there are less interactions between agents in smaller populations, which means that the wealth of an agent is less likely to change."


👍 for the analysis.

rht · 2023-05-07T05:46:45Z

@EwoutH do you mind updating intro_tutorial.rst with the changes? It's easier to see the diff there.

EwoutH · 2023-05-10T09:20:20Z

This will be another major effort to rebase.

Now it’s still fresh in my head so making changes is relatively fast and easy.

This is now over a month ago. This PR got closed without a clear motivation.

I find it for some reason really difficult to contribute to Mesa, and it really demotivates me to make the effort. And that sucks, because I think we need to have a good ABM package in an accessible programming language.

rht · 2023-05-10T09:31:26Z

You don't have to rebase. I can handle that later. What do you think of transitioning the tutorial to mainly .rst files + image files? This way, no Jupyter notebooks with heavy diffs, no computational states recorded, and the plots are separated from the texts. If this is more practical?

rht · 2023-05-10T09:31:58Z

And that sucks, because I think we need to have a good ABM package in an accessible programming language.

I agree with this statement.

tpike3 · 2023-05-13T12:16:38Z

And that sucks, because I think we need to have a good ABM package in an accessible programming language.

I agree with this statement.

I have been chewing this for a couple days and have few good answers. I will put this as the top priority for the next dev meeting, but to excel in the Open Source we need to figure this out. I will also do some research on best habits so I come with proposals.

rht · 2023-05-14T19:46:28Z

With #1694 (nbsphinx) merged, now the .ipynb files will be executed by Sphinx and have their output shown in readthedocs.org. This way, there will be no base64-encoded png files to clutter the diff, and no 2 different representations of the content either (previously .ipynb and .rst). The computed output should be viewable in the RTD CI. This should simplify the workflow.

See readthedocs/readthedocs.org#10279

rht · 2023-06-17T05:04:17Z

I reopened this PR as #1716.

tpike3 reviewed Apr 1, 2023

View reviewed changes

tpike3 reviewed Apr 2, 2023

View reviewed changes

jackiekazil changed the base branch from main to doc_builds April 25, 2023 18:15

jackiekazil deleted the branch projectmesa:doc_builds April 26, 2023 01:03

jackiekazil closed this Apr 26, 2023

rht reviewed May 7, 2023

View reviewed changes

rht reopened this May 14, 2023

rht added 3 commits May 14, 2023 15:59

Clear output

a4529f5

docs: Use nbsphinx on adv_tutorial

0a671b2

fix: Restrict Sphinx to be <7

597ba4e

See readthedocs/readthedocs.org#10279

rht force-pushed the doc_builds branch from fad2671 to 96fc2e4 Compare May 15, 2023 08:24

rht closed this Jun 17, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Update the intro tutorial with extended analysis #1625

docs: Update the intro tutorial with extended analysis #1625

EwoutH commented Mar 28, 2023

codecov bot commented Mar 28, 2023 •

edited

Loading

EwoutH commented Mar 29, 2023

tpike3 Apr 1, 2023

EwoutH Apr 1, 2023

tpike3 Apr 2, 2023

EwoutH Apr 2, 2023

tpike3 Apr 3, 2023

tpike3 Apr 1, 2023

EwoutH Apr 1, 2023

tpike3 Apr 2, 2023

EwoutH Apr 2, 2023

tpike3 Apr 3, 2023 •

edited

Loading

rht Apr 25, 2023

tpike3 Apr 1, 2023 •

edited

Loading

tpike3 Apr 1, 2023 •

edited

Loading

tpike3 Apr 2, 2023 •

edited

Loading

EwoutH Apr 2, 2023

tpike3 commented Apr 2, 2023

rht commented Apr 25, 2023

jackiekazil commented Apr 25, 2023 •

edited

Loading

EwoutH commented Apr 26, 2023

rht May 7, 2023

rht commented May 7, 2023

EwoutH commented May 10, 2023

rht commented May 10, 2023

rht commented May 10, 2023

tpike3 commented May 13, 2023 •

edited

Loading

rht commented May 14, 2023

rht commented Jun 17, 2023

docs: Update the intro tutorial with extended analysis #1625

docs: Update the intro tutorial with extended analysis #1625

Conversation

EwoutH commented Mar 28, 2023

codecov bot commented Mar 28, 2023 • edited Loading

Codecov Report

EwoutH commented Mar 29, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tpike3 Apr 3, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tpike3 Apr 1, 2023 • edited Loading

Choose a reason for hiding this comment

tpike3 Apr 1, 2023 • edited Loading

Choose a reason for hiding this comment

tpike3 Apr 2, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tpike3 commented Apr 2, 2023

rht commented Apr 25, 2023

jackiekazil commented Apr 25, 2023 • edited Loading

EwoutH commented Apr 26, 2023

Choose a reason for hiding this comment

rht commented May 7, 2023

EwoutH commented May 10, 2023

rht commented May 10, 2023

rht commented May 10, 2023

tpike3 commented May 13, 2023 • edited Loading

rht commented May 14, 2023

rht commented Jun 17, 2023

codecov bot commented Mar 28, 2023 •

edited

Loading

tpike3 Apr 3, 2023 •

edited

Loading

tpike3 Apr 1, 2023 •

edited

Loading

tpike3 Apr 1, 2023 •

edited

Loading

tpike3 Apr 2, 2023 •

edited

Loading

jackiekazil commented Apr 25, 2023 •

edited

Loading

tpike3 commented May 13, 2023 •

edited

Loading