From f6408aa75dd45dcbd91076f84e5028e833dec98a Mon Sep 17 00:00:00 2001 From: JoelForamitti <57440945+JoelForamitti@users.noreply.github.com> Date: Thu, 27 May 2021 14:11:35 +0200 Subject: [PATCH] Update docs --- docs/changelog.rst | 20 ++++++++++---------- docs/comparison.rst | 15 ++++++++------- docs/conf.py | 2 -- docs/guide_interactive.ipynb | 28 ++++++++++++++-------------- docs/index.rst | 4 ++-- 5 files changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index ca4e2c5..a9af989 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -14,7 +14,7 @@ The most notable API changes are described below. Object creation ............... -The methods :func:`add_agents`, :func:`add_env`, etc. have been depreciated. +The methods :func:`add_agents`, :func:`add_env`, etc. have been removed. Instead, new objects are now created directly or through :doc:`reference_sequences`. This allows for more control over data structures (see next point) and attribute names. For example:: @@ -36,16 +36,16 @@ It also comes with a method :func:`AgentDList.buffer` that allows for save deletion of agents from the list while it is iterated over -The structure of :class:`AttrList` has also been changed to an iterable over its -source list. This improves performance and makes it possible to change +:class:`AttrList` has been replaced by :class:`AttrIter`. +This improves performance and makes it possible to change agent attributes by setting new values to items in the attribute list (see :class:`AgentList` for an example). In most other ways, the class still behaves like a normal list. +There are also two new classes :class:`AgentIter` and :class:`AgentDListIter` that are returned by some of the library's methods. Environments ............ -The three environment classes have undergone a major revision, -aiming for better consistency and higher performance. +The three environment classes have undergone a major revision. The :func:`add_agents` functions have been extended with new features and are now more consistent between the three environment classes. The method :func:`move_agents` has been replaced by :func:`move_to` and :func:`move_by`. @@ -72,8 +72,8 @@ For example, agents in an environment can be set up as follows:: The agent methods `move_to`, `move_by`, and `neighbors` have also been removed. Instead, agents can access these methods through their environment. -In the above example, a given agent `a` could for example access their -neighbors through calling `a.mygrid.neighbors(a)`. +In the above example, a given agent `a` could for example access their position +through `a.mygrid.positions[a]` or their neighbors through calling `a.mygrid.neighbors(a)`. Parameter samples ................. @@ -84,7 +84,7 @@ Parameter dictionaries with these classes can be used to create samples, but can also be passed to a normal model, which will then use default values. The sampling methods :func:`sample`, :func:`sample_discrete`, and :func:`sample_saltelli` -have been depreciated and integrated into the new class :class:`Sample`, +have been removed and integrated into the new class :class:`Sample`, which comes with additional features to create new kinds of samples. Random number generators @@ -107,13 +107,13 @@ Parameters are now stored in the two categories `constants` and `sample`. Variables are stored in separate dataframes based on the object type. The dataframe's index is now separated into `sample_id` and `iteration`. -The function :func:`sensitivity_sobol` has been depreciated and is replaced +The function :func:`sensitivity_sobol` has been removed and is replaced by the method :func:`DataDict.calc_sobol`. Interactive visualization interface ................................... -The method :func:`Experiment.interactive` has been depreciated and is replaced +The method :func:`Experiment.interactive` has been removed and is replaced by an interactive simulation interface that is being developed in the separate package `ipysimulare `_. This new package provides interactive javascript widgets with parameter sliders diff --git a/docs/comparison.rst b/docs/comparison.rst index a0979b4..85acaf9 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -40,20 +40,21 @@ of each framework (:doc:`Agentpy ` & Finally, the following table provides a comparison of the main features of each framework. -========================== =================================== =================================== +========================== =================================== ====================================== **Feature** **Agentpy** **Mesa** -| Agent management | Sequence classes | Scheduler classes for - | like AgentList and AgentDList | different activation orders +| Containers | Sequence classes | Scheduler classes for + | like AgentList and AgentDList | different activation orders | Topologies | Spatial grid, continuous space, | Spatial grid, continuous space, | network | network | Data recording | Recording methods for variables | DataCollector class that can | of agents, environments, and | collect variables of agents | model; as well as reporters | and model -| Parameter sampling | Classes for sample generation | Custom sample has to be defined - | and variable parameter ranges | +| Parameter sampling | Classes for sample generation + | and parameter ranges | Multi-run experiments | Experiment class that supports | BatchRunner class that supports | multiple iterations, parameter | multiple iterations and parameter - | samples, and parallel processing | samples + | samples, randomization, | samples + | and parallel processing | Output data | DataDict class to store, save, | Methods to generate dataframes | load, and re-arrange output data | | Visualization | Plots, animations, | Plots and interactive visualization @@ -61,4 +62,4 @@ Finally, the following table provides a comparison of the main features of each | within IPython/Jupyter | Analysis | Tools for data arrangement and | sensitivity analysis -========================== =================================== =================================== \ No newline at end of file +========================== =================================== ====================================== \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 8f5e203..9ba592c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,8 +12,6 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('../examples')) - # -- Project information ----------------------------------------------------- project = 'agentpy' diff --git a/docs/guide_interactive.ipynb b/docs/guide_interactive.ipynb index ea312ac..048fe19 100644 --- a/docs/guide_interactive.ipynb +++ b/docs/guide_interactive.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "concrete-bench", + "id": "constitutional-statement", "metadata": {}, "source": [ "# Interactive simulation interface" @@ -10,7 +10,7 @@ }, { "cell_type": "markdown", - "id": "moderate-night", + "id": "exterior-assistant", "metadata": {}, "source": [ "The exploration of agent-based models can often be guided through an interactive simulation interface that allows users to visualize the models dynamics and adjust parameter values while a simulation is running. Examples are the traditional interface of [NetLogo](https://ccl.northwestern.edu/netlogo/), or the browser-based visualization module of [Mesa](https://mesa.readthedocs.io/). \n", @@ -20,8 +20,8 @@ }, { "cell_type": "code", - "execution_count": 1, - "id": "accurate-arabic", + "execution_count": 6, + "id": "acceptable-mobile", "metadata": {}, "outputs": [], "source": [ @@ -34,7 +34,7 @@ }, { "cell_type": "markdown", - "id": "discrete-rendering", + "id": "vulnerable-brass", "metadata": {}, "source": [ "To begin we create an instance of the agentpy [wealth transfer model](https://agentpy.readthedocs.io/en/stable/agentpy_wealth_transfer.html) without passing any parameters." @@ -43,7 +43,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "creative-pottery", + "id": "seasonal-drinking", "metadata": {}, "outputs": [], "source": [ @@ -52,7 +52,7 @@ }, { "cell_type": "markdown", - "id": "boring-punch", + "id": "executive-necessity", "metadata": {}, "source": [ "We then create an ipysimulate control panel with the model and a set of parameters. Parameters that are given as ranges will appear as interactive widgets. The parameter `fps` (frames per second) will be used automatically to indicate the speed of the simulation. We further pass two variables `t` (time-steps) and `gini` to be displayed live during the simulation." @@ -61,7 +61,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "interracial-vacation", + "id": "abroad-painting", "metadata": {}, "outputs": [], "source": [ @@ -75,7 +75,7 @@ }, { "cell_type": "markdown", - "id": "devoted-community", + "id": "distributed-ballet", "metadata": {}, "source": [ "Next, we create a lineplot of the variable `gini` that is connected to the control panel." @@ -84,7 +84,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "phantom-whale", + "id": "exact-malawi", "metadata": {}, "outputs": [], "source": [ @@ -93,7 +93,7 @@ }, { "cell_type": "markdown", - "id": "coordinated-platinum", + "id": "compound-destiny", "metadata": {}, "source": [ "Finally, we want to display our two widgets `control` and `lineplot` next to each other. For this, we can use the [layout templates](https://ipywidgets.readthedocs.io/en/stable/examples/Layout%20Templates.html) from ipywidgets. " @@ -102,7 +102,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "relevant-slovak", + "id": "cutting-works", "metadata": {}, "outputs": [ { @@ -131,7 +131,7 @@ }, { "cell_type": "markdown", - "id": "agreed-chemistry", + "id": "dental-valve", "metadata": {}, "source": [ "![test](graphics/ips_example.png)" @@ -139,7 +139,7 @@ }, { "cell_type": "markdown", - "id": "prescription-ground", + "id": "alert-repair", "metadata": {}, "source": [ "Note that this widget is not displayed interactively if viewed in the docs. To view the widget, please download the Jupyter Notebook at the top of this page or launch this notebook as a binder." diff --git a/docs/index.rst b/docs/index.rst index ca9fed8..a973877 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ .. currentmodule:: agentpy ======================================== -Agentpy - Agent-based modeling in Python +AgentPy - Agent-based modeling in Python ======================================== .. image:: https://img.shields.io/pypi/v/agentpy.svg @@ -20,7 +20,7 @@ Agentpy - Agent-based modeling in Python \chapter{Introduction} -Agentpy is an open-source library for the development and analysis of agent-based models in Python. +AgentPy is an open-source library for the development and analysis of agent-based models in Python. The framework integrates the tasks of model design, interactive simulations, numerical experiments, and data analysis within a single environment, and is optimized for interactive computing with `IPython `_ and `Jupyter `_.