Merge pull request #49 from ABSESpy/dev

Improve the overview of ABSESpy docs

docs/home/license.md

@@ -13,4 +13,4 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
-`ABSESpy` bundles portions of `Mesa`, `mesa-geo`, `pandas`, `NumPy`, and `Xarray`; the full text of these licenses are included in the licenses directory.
+`ABSESpy` bundles portions of `Mesa`, `Mesa-Geo`, `pandas`, `NumPy`, and `Xarray`; the full text of these licenses are included in the licenses directory.

docs/paper/paper.md

@@ -28,55 +28,49 @@ bibliography: "../refs.bib"
 
 ## Summary
 
-`ABSESpy` is a novel agent-based modeling (ABM) framework that enhances socio-ecological systems (SES) research fidelity. Addressing critical needs in SES study, such as complex decision-making, scaling, and data integration, it features a Branch-Leaf architecture for clear separation and integration of human and natural subsystems, promoting replicability and model coupling. `ABSESpy` also supports modeling human behavior through well-recognized workflows of perception, decision-making definitions, and responses. Moreover, it advances real-world modeling with multiple time operating modes, accommodating the diverse temporal scales of SES phenomena and integrating time-sensitive event simulations. These innovations position `ABSESpy` as a crucial tool in addressing current gaps in SES research, fostering more ABMs for real-world SES issues.
+`ABSESpy` is a novel agent-based modeling (ABM) framework that facilitates socio-ecological systems (SES) research. It serves as an extension package of `Mesa`, the most popular ABM framework, and further enhances agents' interactions with other components, especially grid-like spaces. With a configuration file for managing parameters and an improved data Input/Output system, `ABSESpy`'s modularity and low-coupling design enable elegant maintenance of large modeling projects. In addition, `ABSESpy` includes a schedule that aligns models' tick with the calendar time. These innovations position `ABSESpy` as a valuable tool in fostering more ABMs for real-world SES issues. Its ultimate aim is to become the go-to choice for ABM when working with a human-involved changing world.
 
 ## Statement of need
 
-Social-ecological systems (SES) represent an integrated concept that recognizes the complex and interdependent dynamics between human societies and ecological systems [@folke2010]. Consisting of decision-making agents (representing people, communities, organizations, and environmental components) capable of following heterogeneous objectives [@levin2013], SES has specific needs for research support from agent-based modeling.
+Social-ecological systems (SES) are integrated concepts recognizing the complex and interdependent dynamics between human societies and ecological systems [@folke2010]. SES consists of decision-making actors (i.e., agents representing people, communities, organizations, and environmental components) capable of following heterogeneous objectives [@levin2013]. As such, SES has specific needs for research support from agent-based modeling (ABM).
 
-However, ABMs' potential is yet to be fully realized in SES researches. Current challenges, such as incorporating human decision-making, portraying socio-ecological networks, and modeling real-world systems, must be addressed [@schulze2017]. Additionally, issues related to data availability, model validation, replicability, and transparency must be systematically tackled to enhance the reliability and applicability of ABM in this field [@gotts2019].
+However, since few models can effectively represent the real-world SES problem, the potential of ABMs has yet to be fully realized in SES research [@schulze2017]. One reason is the variability of actors' interaction with each other or geographic spaces, including learning, decision-making, and contagion across social networks [@reyers2018]. Another reason is the complexity of managing data, parameters, and social and natural processes, which makes it hard to maintain large projects [@davidson2024]. Therefore, facilitating SES research with ABM requires novel tools to implement the interactions between actors and real-world-like natural processes with manageability and reproducibility.
 
-Developing and refining ABM approaches for social-ecological systems are crucial in light of these needs and challenges [@reyers2018]. At the heart of this should be a modeling framework that is portable, scale-flexible, and capable of expressing the interaction of the decision-making agent with the natural environment or ecosystem. `ABSESpy` represents a significant advancement in this regard, offering several features that address the current gaps in SES modeling.
+The popular programming language `Python` is among the first choices for scientists who care about ABM, and `Mesa` is the most widely used implementation framework. It remains extensible for different domains while providing the core functionality of ABM. Therefore, customizing `Mesa` by enhancing real-world representation could be a good start for specializing in SES research. It includes expressing decision-making actors' interactions, social-ecological networks, calendar time, raster data, and extensible sub-systems. To this end, `ABSESpy` is a `Mesa` package and an advanced framework that fills gaps in SES modeling with these features.
 
 ## Design structures
 
-`ABSESpy` introduces a Branch-Leaf architecture central to its functionality. It facilitates a clear separation of the human and natural subsystems within SES research, aligning with the requisite to enhance replicability and extensibility (**Figure 1**).
+`ABSESpy`'s low-coupling design enables the implementation of maintainable projects by separating the human and natural subsystems within SESs (**Figure 1**). While the human subsystem manages actors (i.e., agents) and their interactions, the natural submodule typically handles how actors live in, move through, and interact with grid-like patch layers. This architecture also supports adding specialized submodules in each subsystem to represent varying processes with modularity.
 
-![Structure of main components of `ABSESpy` and its Branch-Leaf architecture of modules.](structure.png)
+`ABSESpy` includes the default schedule, data collector, and batch runner utilities, available as a `Mesa` package but somehow enhanced. It also introduces a calendar-like time driver and supports configuration management through `.yaml` files. In addition, the packages `Xarray` and `Mesa-Geo` are embedded to implement an Input/Output driver for different geographic datasets (`.tif`, `.nc`, `.json`, `.shp`, and others). The design focuses on two core improvements: (1) handling actors and their interactions and (2) enhancing reality and manageability of ABMs.
 
-Integrated by the `MainModel`, the two primary base modules are named as `Base Human` and `Base Nature`, corresponding to components of a typical SES [@reyers2018]. By this architecture, `ABSESpy` enables the addition of specialized sub-modules, thus promoting a tailored modeling approach. The extension `mesa-geo` is embedded as the base driver for the nature subsystem so that most of the different geographic datasets are compatible (`.tif`, `.nc`, `.json`, `.shp`, et al.).
+![Diagram of the Application Programming Interface (API) of ABSESpy](api_diagram.png)
 
-In the SES context, `ABSESpy` conceptualizes agents as `Actors` managed within a unique `ActorsContainer` and can be referred from a temporary `ActorsList`. In human sub-modules, users can define a series of `Actor`'s references by or link each other (between agent and patch, or agent and agent) by inputting advanced query. It simplifies the agents' organization, ensuring each actor can be searched, operated, and able to access global information.
+## Handling actors and their interactions
 
-## Human-behavior modeling framework
+Under the context of SES, `ABSESpy` conceptualizes "agents" as `Actor`s managed within a global `ActorsContainer` and can be manipulated in batches through any `ActorsList`. Users can also query, select, or apply a function to a subset of actors by `ActorsList`. Furthermore, whenever users link some `Actor`s with others or some `PatchCell`s, `Networkx` can automatically convert these linkages into a graph. Thus, it enables actors to interact through social networks or implement a social-ecological network analysis.
 
-`ABSESpy` recognizes the centrality of human behavior in SES and, as such, prioritizes the workflow approaching its simulation. To this end, the framework provides an integrative approach based on popular theories of conceptualizing human decision-making (**Figure 2**) [@schluter2017], [@beckage2022].
+Since `ABSESpy` recognizes the centrality of human behavior in SES studies, it also provides a standard workflow based on a popular theoretical framework for decision-making (**Figure 2**) [@schluter2017], [@beckage2022]. The following main steps can be implemented seamlessly when working with `ABSESpy`:
 
-![Decision-making workflow for simulating human behavior.](decision-making.png)
-
-When practicing, `ABSESpy` provides an advanced behavior simulation framework, including the following main steps:
-
-1. **Perceptions**: From direct environmental observations to social communications, users can define a `perception` variable to represent how agents gather information and form their understanding of the environment.
-2. **Decision-making**: By evaluating the potential choices of a decision, decision-making logic can be implemented to capture how human agents might process information and select courses of action.
-3. **Response**: Consequent to decision-making, agents exhibit responses for actualizing their strategies —e.g., spatial relocation, attribute changes, altering environment, or other forms of interaction.
+1. **Perceptions**:  An `Actor` holds perceptions of natural and human subsystems by observing global/environmental variables (cognition) or learning from links with others (contagion). `ABSESpy` helps users dynamically define an expression to update perceptions as `Actor`s' attributes.
+2. **Decision-making**: `Actor`s evaluate potential options to determine how to act in the current situation. `ABSESpy` includes utilities for pre-defined options, thus enabling auto-triggering actions by passing an evaluating function.
+3. **Response**: Some actions may lead to feedback towards human or natural subsystems as a response. Besides many available actions, such as spatial relocation and setting attributes, `ABSESpy` also includes tools to avoid the feedback that causes a nested loop.
 
-By translating theoretical constructs into user-friendly, operational components, `ABSESpy` empowers researchers to bridge the gap between conceptual models and their tangible application in SES.
+![Decision-making workflow for simulating human behavior.](decision-making.png)
 
-## Real-world SES modeling enhancements
+## Enhancing reality and manageability of ABMs
 
-`ABSESpy` integrates an innovative time control mechanism to bridge the gap between ABMs and real-world SESs. These are attributions from a `TimeDriver` module that manages the association of ABM with real-world time (**Figure 3**).
+To enhance reality, `ABSESpy` provides an innovative time control mechanism to bridge the gap between the association of ABM and real-world time (**Figure 3**). In addition to `Mesa`'s standard tick-based time advancement, users can implement calendar temporal modes to match the diverse scales of SES phenomena with `ABSESpy`. By defining the calendar time for each simulation step, the model can represent time intervals from minutes to years. This flexibility is crucial when modeling real-world events like natural cycles or periodic human activities.
 
 ![Calendar time module enhances real-world social-ecological system modeling approaches.](real-world.png)
 
-In addition to the standard tick-based time advancement, users can implement two temporal modes for matching the diverse scales of SES phenomena. (1) In a "Duration Mode," users can define the length of time that each simulation step represents, thus allowing for variable temporal resolutions. This capability enables the model to represent time intervals vary from minutes to years, depending on the specific requirements of the SES being modeled. (2) The "Irregular Mode" addresses the non-uniformity of specific SES processes; this mode allows for irregular time steps, whereby different simulation intervals can represent varying lengths of time. This flexibility is crucial when modeling events that do not follow a linear timeline, such as erratic ecological phenomena or sporadic human activities.
-
-A calendar schedule enables `ABSESpy` to import and utilize dynamic, temporal datasets. `ABSESpy` automates the updating of variables with time-series data, negating the need for manual data refreshes and recalculations. It supports real-time data feeds, ensuring that the model reflects current conditions. The `ABSESpy` introduces a time-based event handler (`time_condition` decorator) based on the same idea. By leveraging this decorator, temporal conditions for executing events can be set, enabling simulations to react to time-specific triggers. This aspect is especially pertinent for phenomena with distinct temporal patterns, like migratory behaviors or seasonal cycles.
+`ABSESpy` includes utilities for manageability purposes based on the above time control mechanism. The commonly used one is automatically importing and updating temporal time series datasets like monthly or daily weather. Users can also specify time conditions to apply or not apply any model method, such as customizing a namely `get_up()` method to `Actor` and only calling it at 8:00 am in a one-hour-per-step model. Finally, all parameters can be stored in `.yaml` configuration files with readable expressions. For example, passing parameters `{"start": '2022-12-31', "end": 2024-01-01, year: 1}` to the 'time' module means the simulation starts at the end of 2022 and ends when the beginning of 2024 is reached. Since each step represents a year, the model only goes one step.
 
 ## Positioning and comparison
 
-`ABSESpy` facilitates independent module creation, enabling an advanced human behavior framework and providing sophisticated time control and data integration tools. `ABSESpy` allows a more accurate and nuanced representation of SES dynamics, meeting the intricate requirements of real-world problem-solving and decision-making support. Its goal is to become a specialized package for the emerging SES field based on the `mesa` project, similar to the existing `abce` (a package aimed at providing an economic problem modeling framework, also a `mesa` package) [@taghawi-nejad2017]. Therefore, `ABSESpy` can take advantage of most of the benefits from the related projects (e.g., `mesa` [@kazil2020a] and `mesa-geo` [@wang_mesa-geo_2022]), such as visualization and geographic data processing.
+By translating theoretical constructs into user-friendly, operational components, `ABSESpy` empowers researchers to bridge the gap between conceptual models and their tangible application in SES. As a specialized `Mesa` package for the emerging SES field, `ABSESpy` can take advantage of most of the benefits from the related projects (e.g., model visualization from `Mesa` [@kazil2020a] and geo-data processing from `Mesa-Geo` [@wang_mesa-geo_2022]). `ABSESpy` aims to become the go-to choice for ABM when working with a human-involved, changing world. This vision is similar to the existing `ABCE`, which aims to provide an economic problem modeling framework (also a `Mesa` package) [@taghawi-nejad2017], but it targets real-world SES problems.
 
-A possible competitor is `AgentPy`, but its goal remains to be a general ABM framework. Due to the need for more mature geographic data processing extensions like `mesa-geo`, building `ABSESpy` on top of the `mesa` project allows users to deal with real-world SES problems while putting less coding effort into setting up their model projects. Currently, many open-source SES models are published on the platform `CoMSES` [@janssen2008]; they primarily serve as heuristic models using `netlogo` [@tisue2004netlogo] software as their modeling foundation. The visible advantage of `ABSESpy` lies in its well-structured design, which is suitable for large-scale SES modeling projects. It calls upon vast amounts of actual data for real-world problem modeling rather than merely heuristic modeling. Its tree-like structure allows `ABSESpy` users to couple models together, maximizing Python's advantages as a "glue language".
+Many open-source SES models are published on `CoMSES` [@janssen2008] and use `NetLogo` [@tisue2004netlogo] software. However, users might struggle to maintain its all-in-one structure when data input/output and parameters become extensive. The visible advantage of `ABSESpy` lies in its modularity and low-coupling design, which is suitable for large-scale SES modeling projects. It calls upon vast amounts of actual data for real-world problem modeling. With a separate configuration file, `ABSESpy` makes it easier to maintain a large project, allowing users to couple sub-modules and maximize `Python`'s advantages as a "glue language." In `Python`, another possible competitor is `AgentPy`, whose goal is a general ABM framework and is thus more concerned with agents (in other words, the "human" part). Due to more geographic data processing extensions like `Mesa-Geo`, `ABSESpy` allows users to handle grid-like spaces and calendar-like schedules more efficiently. Thus, facing real-world SES problems, building on `ABSESpy` will require less coding effort to simulate interactions between humans and nature.
 
 ## Acknowledgment
 

docs/tutorial/beginner/fire_tutorial.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Fire Spread Simulation\n",
     "## Introduction\n",
-    "This notebook is based on the `fire` model implementation with Netlogo. You can find the original implementation at https://ccl.northwestern.edu/netlogo/models/Fire. This model aims to showcase basic methods that allow interactions between agents. \n",
+    "This notebook is based on the `fire` model implementation with NetLogo. You can find the original implementation at https://ccl.northwestern.edu/netlogo/models/Fire. This model aims to showcase basic methods that allow interactions between agents. \n",
     "\n",
     "The model simulates the spread of a fire in a forest. The fire spreads from tree to nearby trees. The model consist of a grid of any given size, where each cell may contain either one or no tree. The fire spreads to nearby trees only. The state of each tree is then represented graphically by the color of the cell. Untouched trees appear on green patches, burning trees appear on red patches, and burnt trees appear on orange patches. Whenever there is no tree on a patch, the patch is colored black."
    ]

docs/tutorial/beginner/hotelling_tutorial.ipynb

@@ -76,7 +76,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Following the netlogo implementation, each agent will begin at a random position. It will have a market area or share depending on its price and position. Each cell or patch of the grid is considered a customer with inelastic demand for the product. Each customer will make a choice as to what shop is prefered based on the price and distance to each shop. In the original paper (1929) the distance to the shop introduces transportation costs.\n",
+    "Following the `NetLogo` implementation, each agent will begin at a random position. It will have a market area or share depending on its price and position. Each cell or patch of the grid is considered a customer with inelastic demand for the product. Each customer will make a choice as to what shop is prefered based on the price and distance to each shop. In the original paper (1929) the distance to the shop introduces transportation costs.\n",
     "\n",
     "We first may wish to work out all the setup: **create a grid layer and randomly set shop agents on the layer**."
    ]