Update tutorial and fix plotting bug

* Improve text
* Move to docs
* Autogenerate with sphinx
* Fix naming issue `environment.run` (double name)
* Add to tests

.dockerignore

@@ -1,5 +1,7 @@
 **/soil_output
 .*
+**/.*
 **/__pycache__
 __pycache__
 *.pyc
+**/backup

.gitignore

@@ -8,4 +8,5 @@ soil_output
 docs/_build*
 build/*
 dist/*
-prof
+prof
+backup

CHANGELOG.md

@@ -28,6 +28,13 @@ For an explanation of the general changes in version 1.0, please refer to the fi
 ### Removed
 * Any `tsih` and `History` integration in the main classes. To record the state of environments/agents, just use a datacollector. In some cases this may be slower or consume more memory than the previous system. However, few cases actually used the full potential of the history, and it came at the cost of unnecessary complexity and worse performance for the majority of cases.
 
+## [0.20.8]
+### Changed
+* Tsih bumped to version 0.1.8
+### Fixed
+* Mentions to `id` in docs. It should be `state_id` now.
+* Fixed bug: environment agents were not being added to the simulation
+
 ## [0.20.7]
 ### Changed
 * Creating a `time.When` from another `time.When` does not nest them anymore (it returns the argument)

README.md

@@ -4,7 +4,7 @@
 Soil is an extensible and user-friendly Agent-based Social Simulator for Social Networks.
 Learn how to run your own simulations with our [documentation](http://soilsim.readthedocs.io).
 
-Follow our [tutorial](examples/tutorial/soil_tutorial.ipynb) to develop your own agent models.
+Follow our [tutorial](docs/tutorial/soil_tutorial.ipynb) to develop your own agent models.
 
 > **Warning**
 > Soil 1.0 introduced many fundamental changes. Check the [documention on how to update your simulations to work with newer versions](docs/notes_v1.0.rst)
@@ -36,7 +36,6 @@ Follow our [tutorial](examples/tutorial/soil_tutorial.ipynb) to develop your own
 * A command line interface (`soil`), to quickly run simulations with different parameters
 * An integrated debugger (`soil --debug`) with custom functions to print agent states and break at specific states
 
-
 ## Mesa compatibility
 
 SOIL has been redesigned to integrate well with [Mesa](https://github.com/projectmesa/mesa).

docs/conf.py

@@ -31,7 +31,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['IPython.sphinxext.ipython_console_highlighting']
+extensions = [
+    "IPython.sphinxext.ipython_console_highlighting",
+    "nbsphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -64,7 +67,7 @@ release = '0.1'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -152,6 +155,3 @@ texinfo_documents = [
      author, 'Soil', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

docs/index.rst

@@ -2,19 +2,20 @@ Welcome to Soil's documentation!
 ================================
 
 Soil is an opinionated Agent-based Social Simulator in Python focused on Social Networks.
+To get started developing your own simulations and agent behaviors, check out our :doc:`Tutorial <soil_tutorial>` and the `examples on GitHub <https://github.com/gsi-upm/soil/tree/master/examples>`.
+
+Soil can be installed through pip (see more details in the :doc:`installation` page):.
 
 .. image:: soil.png
   :width: 80%
   :align: center
 
-Soil can be installed through pip (see more details in the :doc:`installation` page):
 
 .. code:: bash
 
     pip install soil
 
 
-To get started developing your own simulations and agent behaviors, check out our :doc:`Tutorial <soil_tutorial>` and the `examples on GitHub <https://github.com/gsi-upm/soil/tree/master/examples>.
 
 If you use Soil in your research, do not forget to cite this paper:
 
@@ -46,7 +47,8 @@ If you use Soil in your research, do not forget to cite this paper:
    :caption: Learn more about soil:
 
    installation
-   Tutorial <soil_tutorial>
+   Tutorial <tutorial/soil_tutorial>
+   notes_v1.0
 
 ..
 

docs/notes_v1.0.rst

@@ -1,3 +1,6 @@
+Upgrading to Soil 1.0
+---------------------
+
 What are the main changes in version 1.0?
 #########################################
 

docs/requirements.txt

@@ -1 +1,2 @@
 ipython>=7.31.1
+nbsphinx==0.9.1

examples/newsspread/NewsSpread.ipynb

@@ -2,13 +2,12 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 1,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:30.732107Z",
      "start_time": "2017-11-08T17:22:30.059855+01:00"
-    },
-    "collapsed": true
+    }
    },
    "outputs": [],
    "source": [
@@ -28,24 +27,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 2,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:35.580593Z",
      "start_time": "2017-11-08T17:22:35.542745+01:00"
     }
    },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Populating the interactive namespace from numpy and matplotlib\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
-    "%pylab inline\n",
+    "%matplotlib inline\n",
     "\n",
     "from soil import *"
    ]
@@ -66,7 +57,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 3,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:37.242327Z",
@@ -86,7 +77,7 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 30\r\n",
+      "max_time: 300\r\n",
       "name: Sim_all_dumb\r\n",
       "network_agents:\r\n",
       "- agent_class: DumbViewer\r\n",
@@ -110,7 +101,7 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 30\r\n",
+      "max_time: 300\r\n",
       "name: Sim_half_herd\r\n",
       "network_agents:\r\n",
       "- agent_class: DumbViewer\r\n",
@@ -142,18 +133,18 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 30\r\n",
+      "max_time: 300\r\n",
       "name: Sim_all_herd\r\n",
       "network_agents:\r\n",
       "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    id: neutral\r\n",
+      "    state_id: neutral\r\n",
       "  weight: 1\r\n",
       "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    id: neutral\r\n",
+      "    state_id: neutral\r\n",
       "  weight: 1\r\n",
       "network_params:\r\n",
       "  generator: barabasi_albert_graph\r\n",
@@ -169,13 +160,13 @@
       "  prob_tv_spread: 0.01\r\n",
       "  prob_neighbor_cure: 0.1\r\n",
       "interval: 1\r\n",
-      "max_time: 30\r\n",
+      "max_time: 300\r\n",
       "name: Sim_wise_herd\r\n",
       "network_agents:\r\n",
       "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    id: neutral\r\n",
+      "    state_id: neutral\r\n",
       "  weight: 1\r\n",
       "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
@@ -195,13 +186,13 @@
       "  prob_tv_spread: 0.01\r\n",
       "  prob_neighbor_cure: 0.1\r\n",
       "interval: 1\r\n",
-      "max_time: 30\r\n",
+      "max_time: 300\r\n",
       "name: Sim_all_wise\r\n",
       "network_agents:\r\n",
       "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    id: neutral\r\n",
+      "    state_id: neutral\r\n",
       "  weight: 1\r\n",
       "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
@@ -225,7 +216,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 4,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T18:07:46.781745Z",
@@ -233,7 +224,24 @@
     },
     "scrolled": true
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "ename": "ValueError",
+     "evalue": "No objects to concatenate",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[4], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m evodumb \u001b[38;5;241m=\u001b[39m \u001b[43manalysis\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mread_data\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43msoil_output/Sim_all_dumb/\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mprocess\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43manalysis\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mget_count\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mgroup\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[38;5;28;43;01mTrue\u001b[39;49;00m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mkeys\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m[\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43mid\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m)\u001b[49m;\n",
+      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/soil/analysis.py:14\u001b[0m, in \u001b[0;36mread_data\u001b[0;34m(group, *args, **kwargs)\u001b[0m\n\u001b[1;32m     12\u001b[0m iterable \u001b[38;5;241m=\u001b[39m _read_data(\u001b[38;5;241m*\u001b[39margs, \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mkwargs)\n\u001b[1;32m     13\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m group:\n\u001b[0;32m---> 14\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mgroup_trials\u001b[49m\u001b[43m(\u001b[49m\u001b[43miterable\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m     15\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n\u001b[1;32m     16\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[38;5;28mlist\u001b[39m(iterable)\n",
+      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/soil/analysis.py:201\u001b[0m, in \u001b[0;36mgroup_trials\u001b[0;34m(trials, aggfunc)\u001b[0m\n\u001b[1;32m    199\u001b[0m trials \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(trials)\n\u001b[1;32m    200\u001b[0m trials \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(\u001b[38;5;28mmap\u001b[39m(\u001b[38;5;28;01mlambda\u001b[39;00m x: x[\u001b[38;5;241m1\u001b[39m] \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28misinstance\u001b[39m(x, \u001b[38;5;28mtuple\u001b[39m) \u001b[38;5;28;01melse\u001b[39;00m x, trials))\n\u001b[0;32m--> 201\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mpd\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mconcat\u001b[49m\u001b[43m(\u001b[49m\u001b[43mtrials\u001b[49m\u001b[43m)\u001b[49m\u001b[38;5;241m.\u001b[39mgroupby(level\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m0\u001b[39m)\u001b[38;5;241m.\u001b[39magg(aggfunc)\u001b[38;5;241m.\u001b[39mreorder_levels([\u001b[38;5;241m2\u001b[39m, \u001b[38;5;241m0\u001b[39m,\u001b[38;5;241m1\u001b[39m] ,axis\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m1\u001b[39m)\n",
+      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/util/_decorators.py:331\u001b[0m, in \u001b[0;36mdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.wrapper\u001b[0;34m(*args, **kwargs)\u001b[0m\n\u001b[1;32m    325\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(args) \u001b[38;5;241m>\u001b[39m num_allow_args:\n\u001b[1;32m    326\u001b[0m     warnings\u001b[38;5;241m.\u001b[39mwarn(\n\u001b[1;32m    327\u001b[0m         msg\u001b[38;5;241m.\u001b[39mformat(arguments\u001b[38;5;241m=\u001b[39m_format_argument_list(allow_args)),\n\u001b[1;32m    328\u001b[0m         \u001b[38;5;167;01mFutureWarning\u001b[39;00m,\n\u001b[1;32m    329\u001b[0m         stacklevel\u001b[38;5;241m=\u001b[39mfind_stack_level(),\n\u001b[1;32m    330\u001b[0m     )\n\u001b[0;32m--> 331\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mfunc\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43margs\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43mkwargs\u001b[49m\u001b[43m)\u001b[49m\n",
+      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/core/reshape/concat.py:368\u001b[0m, in \u001b[0;36mconcat\u001b[0;34m(objs, axis, join, ignore_index, keys, levels, names, verify_integrity, sort, copy)\u001b[0m\n\u001b[1;32m    146\u001b[0m \u001b[38;5;129m@deprecate_nonkeyword_arguments\u001b[39m(version\u001b[38;5;241m=\u001b[39m\u001b[38;5;28;01mNone\u001b[39;00m, allowed_args\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mobjs\u001b[39m\u001b[38;5;124m\"\u001b[39m])\n\u001b[1;32m    147\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mconcat\u001b[39m(\n\u001b[1;32m    148\u001b[0m     objs: Iterable[NDFrame] \u001b[38;5;241m|\u001b[39m Mapping[HashableT, NDFrame],\n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m    157\u001b[0m     copy: \u001b[38;5;28mbool\u001b[39m \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;01mTrue\u001b[39;00m,\n\u001b[1;32m    158\u001b[0m ) \u001b[38;5;241m-\u001b[39m\u001b[38;5;241m>\u001b[39m DataFrame \u001b[38;5;241m|\u001b[39m Series:\n\u001b[1;32m    159\u001b[0m \u001b[38;5;250m    \u001b[39m\u001b[38;5;124;03m\"\"\"\u001b[39;00m\n\u001b[1;32m    160\u001b[0m \u001b[38;5;124;03m    Concatenate pandas objects along a particular axis.\u001b[39;00m\n\u001b[1;32m    161\u001b[0m \n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m    366\u001b[0m \u001b[38;5;124;03m    1   3   4\u001b[39;00m\n\u001b[1;32m    367\u001b[0m \u001b[38;5;124;03m    \"\"\"\u001b[39;00m\n\u001b[0;32m--> 368\u001b[0m     op \u001b[38;5;241m=\u001b[39m \u001b[43m_Concatenator\u001b[49m\u001b[43m(\u001b[49m\n\u001b[1;32m    369\u001b[0m \u001b[43m        \u001b[49m\u001b[43mobjs\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    370\u001b[0m \u001b[43m        \u001b[49m\u001b[43maxis\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43maxis\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    371\u001b[0m \u001b[43m        \u001b[49m\u001b[43mignore_index\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mignore_index\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    372\u001b[0m \u001b[43m        \u001b[49m\u001b[43mjoin\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mjoin\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    373\u001b[0m \u001b[43m        \u001b[49m\u001b[43mkeys\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mkeys\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    374\u001b[0m \u001b[43m        \u001b[49m\u001b[43mlevels\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mlevels\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    375\u001b[0m \u001b[43m        \u001b[49m\u001b[43mnames\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mnames\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    376\u001b[0m \u001b[43m        \u001b[49m\u001b[43mverify_integrity\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mverify_integrity\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    377\u001b[0m \u001b[43m        \u001b[49m\u001b[43mcopy\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mcopy\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    378\u001b[0m \u001b[43m        \u001b[49m\u001b[43msort\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43msort\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    379\u001b[0m \u001b[43m    \u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m    381\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m op\u001b[38;5;241m.\u001b[39mget_result()\n",
+      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/core/reshape/concat.py:425\u001b[0m, in \u001b[0;36m_Concatenator.__init__\u001b[0;34m(self, objs, axis, join, keys, levels, names, ignore_index, verify_integrity, copy, sort)\u001b[0m\n\u001b[1;32m    422\u001b[0m     objs \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(objs)\n\u001b[1;32m    424\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(objs) \u001b[38;5;241m==\u001b[39m \u001b[38;5;241m0\u001b[39m:\n\u001b[0;32m--> 425\u001b[0m     \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mNo objects to concatenate\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m    427\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m keys \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m:\n\u001b[1;32m    428\u001b[0m     objs \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(com\u001b[38;5;241m.\u001b[39mnot_none(\u001b[38;5;241m*\u001b[39mobjs))\n",
+      "\u001b[0;31mValueError\u001b[0m: No objects to concatenate"
+     ]
+    }
+   ],
    "source": [
     "evodumb = analysis.read_data('soil_output/Sim_all_dumb/', process=analysis.get_count, group=True, keys=['id']);"
    ]
@@ -721,9 +729,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "venv-soil",
    "language": "python",
-   "name": "python3"
+   "name": "venv-soil"
   },
   "language_info": {
    "codemirror_mode": {
@@ -735,7 +743,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.2"
+   "version": "3.8.10"
   },
   "toc": {
    "colors": {

setup.py

@@ -17,9 +17,9 @@ def parse_requirements(filename):
 install_reqs = parse_requirements("requirements.txt")
 test_reqs = parse_requirements("test-requirements.txt")
 extras_require={
-    'mesa': ['mesa>=0.8.9'],
     'geo': ['scipy>=1.3'],
-    'web': ['tornado']
+    'web': ['tornado'],
+    'ipython': ['ipython==8.12', 'nbformat==5.8'],
 }
 extras_require['all'] = [dep for package in extras_require.values() for dep in package]
 

soil/VERSION

@@ -1 +1 @@
-1.0.0rc1
+1.0.0rc2

soil/agents/__init__.py

@@ -77,7 +77,7 @@ class MetaAgent(ABCMeta):
             else:
                 defaults[attr] = copy(func)
 
-        return super().__new__(mcls=mcls, name=name, bases=bases, namespace=new_nmspc)
+        return super().__new__(mcls, name, bases, new_nmspc)
 
 
 class BaseAgent(MesaAgent, MutableMapping, metaclass=MetaAgent):

soil/analysis.py

@@ -1,12 +1,11 @@
 import os
+import sys
 import sqlalchemy
 import pandas as pd
 from collections import namedtuple
 
 def plot(env, agent_df=None, model_df=None, steps=False, ignore=["agent_count", ]):
     """Plot the model dataframe and agent dataframe together."""
-    if agent_df is None:
-        agent_df = env.agent_df()
     if model_df is None:
         model_df = env.model_df()
     ignore = list(ignore)
@@ -16,9 +15,17 @@ def plot(env, agent_df=None, model_df=None, steps=False, ignore=["agent_count",
         ignore.append("time")
 
     ax = model_df.drop(ignore, axis='columns').plot();
+    if agent_df is None:
+        try:
+            agent_df = env.agent_df()
+        except UserWarning:
+            print("No agent dataframe provided and no agent reporters found. Skipping agent plot.", file=sys.stderr)
+            return
     if not agent_df.empty:
         agent_df.unstack().apply(lambda x: x.value_counts(),
-                                 axis=1).fillna(0).plot(ax=ax, secondary_y=True);
+                                 axis=1).fillna(0).plot(ax=ax,
+                                                        secondary_y=True)
+
 
 Results = namedtuple("Results", ["config", "parameters", "env", "agents"])
 #TODO implement reading from CSV and SQLITE

soil/environment.py

@@ -216,10 +216,11 @@ class BaseEnvironment(Model):
 
     @classmethod
     def run(cls, *,
+            name=None,
             iterations=1,
             num_processes=1, **kwargs):
         from .simulation import Simulation
-        return Simulation(name=cls.__name__,
+        return Simulation(name=name or cls.__name__,
                           model=cls, iterations=iterations,
                           num_processes=num_processes, **kwargs).run()
 

soil/serialization.py

@@ -8,6 +8,8 @@ import importlib.machinery, importlib.util
 from glob import glob
 from itertools import product, chain
 
+from contextlib import contextmanager
+
 import yaml
 import networkx as nx
 
@@ -110,12 +112,12 @@ KNOWN_MODULES = {
 
 MODULE_FILES = {}
 
-def add_source_file(file):
+def _add_source_file(file):
     """Add a file to the list of known modules"""
     file = os.path.abspath(file)
     if file in MODULE_FILES:
         logger.warning(f"File {file} already added as module {MODULE_FILES[file]}. Reloading")
-        remove_source_file(file)
+        _remove_source_file(file)
     modname = f"imported_module_{len(MODULE_FILES)}"
     loader = importlib.machinery.SourceFileLoader(modname, file)
     spec = importlib.util.spec_from_loader(loader.name, loader)
@@ -124,7 +126,7 @@ def add_source_file(file):
     MODULE_FILES[file] = modname
     KNOWN_MODULES[modname] = my_module
 
-def remove_source_file(file):
+def _remove_source_file(file):
     """Remove a file from the list of known modules"""
     file = os.path.abspath(file)
     modname = None
@@ -134,6 +136,18 @@ def remove_source_file(file):
     except KeyError as ex:
         raise ValueError(f"File {file} had not been added as a module: {ex}")
 
+
+@contextmanager
+def with_source(file=None):
+    """Add a file to the list of known modules, and remove it afterwards"""
+    if file:
+        _add_source_file(file)
+    try:
+        yield
+    finally:
+        if file:
+            _remove_source_file(file)
+
 def get_module(modname):
     """Get a module from the list of known modules"""
     if modname not in KNOWN_MODULES or KNOWN_MODULES[modname] is None:

soil/simulation.py

@@ -119,28 +119,23 @@ class Simulation:
         self.logger = logger.getChild(self.name)
         self.logger.setLevel(self.level)
 
-        if self.source_file:
-            source_file = self.source_file
-            if not os.path.isabs(source_file):
-                source_file = os.path.abspath(os.path.join(self.dir_path, source_file))
-            serialization.add_source_file(source_file)
-            self.source_file = source_file
+        if self.source_file and (not os.path.isabs(self.source_file)):
+            self.source_file = os.path.abspath(os.path.join(self.dir_path, self.source_file))
+        with serialization.with_source(self.source_file):
 
-        if isinstance(self.model, str):
-            self.model = serialization.deserialize(self.model)
+            if isinstance(self.model, str):
+                self.model = serialization.deserialize(self.model)
 
-        def deserialize_reporters(reporters):
-            for (k, v) in reporters.items():
-                if isinstance(v, str) and v.startswith("py:"):
-                    reporters[k] = serialization.deserialize(v.split(":", 1)[1])
-            return reporters
+            def deserialize_reporters(reporters):
+                for (k, v) in reporters.items():
+                    if isinstance(v, str) and v.startswith("py:"):
+                        reporters[k] = serialization.deserialize(v.split(":", 1)[1])
+                return reporters
 
-        self.agent_reporters = deserialize_reporters(self.agent_reporters)
-        self.model_reporters = deserialize_reporters(self.model_reporters)
-        self.tables = deserialize_reporters(self.tables)
-        if self.source_file:
-            serialization.remove_source_file(self.source_file)
-        self.id = f"{self.name}_{current_time()}"
+            self.agent_reporters = deserialize_reporters(self.agent_reporters)
+            self.model_reporters = deserialize_reporters(self.model_reporters)
+            self.tables = deserialize_reporters(self.tables)
+            self.id = f"{self.name}_{current_time()}"
 
     def run(self, **kwargs):
         """Run the simulation and return the list of resulting environments"""
@@ -217,10 +212,7 @@ class Simulation:
     ):
         """Run the simulation and yield the resulting environments."""
 
-        try:
-            if self.source_file:
-                serialization.add_source_file(self.source_file)
-
+        with serialization.with_source(self.source_file):
             with utils.timer(f"running for config {params}"):
                 if self.dry_run:
                     def func(*args, **kwargs):
@@ -237,9 +229,6 @@ class Simulation:
                         continue
 
                     yield env
-        finally:
-            if self.source_file:
-                serialization.remove_source_file(self.source_file)
 
     def _get_env(self, iteration_id, params):
         """Create an environment for a iteration of the simulation"""

test-requirements.txt

@@ -2,3 +2,6 @@ pytest
 pytest-profiling
 scipy>=1.3
 tornado
+nbconvert==7.3.1
+nbformat==5.8.0
+jupyter==1.0.0

tests/test_ipython.py

@@ -0,0 +1,18 @@
+from unittest import TestCase
+import os
+import nbformat
+from nbconvert.preprocessors import ExecutePreprocessor
+
+ROOT = os.path.abspath(os.path.dirname(__file__))
+
+class TestNotebooks(TestCase):
+    def test_tutorial(self):
+        notebook = os.path.join(ROOT, "../docs/tutorial/soil_tutorial.ipynb")
+        with open(notebook) as f:
+            nb = nbformat.read(f, as_version=4)
+            ep = ExecutePreprocessor(timeout=60000)
+            try:
+                assert ep.preprocess(nb) is not None, f"Got empty notebook for {notebook}"
+            except Exception:
+                assert False, f"Failed executing {notebook}"
+