Let’s Run Some Agent Based Models!

About the Epistemix Platform

The Epistemix Platform is a web-based integrated development environment that will enable you to design, run, and analyze agent-based models (ABMs) with FRED - the Framework for Reconstructing Epidemiological Dynamics.

The Epistemix Platform provides access to our new FRED modeling language version, a custom ABM data management system, and a detailed synthetic population of the USA, all designed for flexible and efficient modeling of large-scale, real-world, social dynamics.

The Epistemix Platform embeds our most recent FRED ABMs within a Python-based Jupyter notebook, a convenient environment for model development. Users who are fluent in Python and/or Jupyter should find it easy to navigate, but even users who are not data scientists can run and understand all of the models presented here by following the instructions provided below.

Introductory Models

A variety of introductory ABMs are provided here. You can easily run each ABM, and then examine the FRED code behind the simulation. We will discuss how to do so in greater detail later. If you would like to jump right in, the following introductory ABMs are available:

• “The Epstein Rebellion Model” - Civil violence in Grand Isle County, Vermont

• “Influenza – Mitigations” - Staying home by income in Kewaunee County, Wisconsin

• “The Schelling Housing Model” - Racial segregation in Kewaunee County, Wisconsin

• “Synthesizing Agent Variables” - Music listening behaviors in Butte County Idaho

• “User Product Journey” - App purchasers in Kewaunee County, Wisconsin

Note: To keep these introductory model runtimes as low as possible, all of the ABM simulations presented here have intentionally been set in small US counties, but you should know that, with sufficient memory, every FRED model can be run on any county in the USA using exactly the same FRED code on the specific synthetic population for that county.

Getting Started

Running an Epistemix ABM in a Jupyter Notebook

To open an Introductory Model, click on the folder menu to the left to navigate to the model that you want. Once in a the subdirectory of the desired model, click on the file with the orange, Jupyter notebook icon () to open the simulation’s notebook. The Jupyter notebook simulation page displays explanatory text, cells that contain code written in Python, and cells that display model output results.

Next, to run the model, on the notebook’s menu bar, click to expand the “Run” tab, and then click “Run All Cells.” For more information about Jupyter Notebooks see here.

Modifying a Jupyter Notebook

The Jupyter notebook page for any given model displays a series of cells that contain Python code for executing the FRED program. Users who are fluent in Python can modify the inputs, execution, and outputs of the FRED model as they wish. Those not fluent in Python can ignore this code for now, and just run the models.

Viewing the FRED Code for a Model

The FRED code is not displayed directly on the Python-based Jupyter notebook page. To see the FRED code behind the model, click on the folder for the model you want, then click on the code files marked by the Epistemix logo () and which end in “.fred.” Most FRED ABMs consist of several modular FRED code files, most of which are hierarchically linked to others.

Editing the FRED Code for a Model

The FRED Modeling Language Guide can be accessed here. If you area already familiar with FRED and wish to modify these models, you can do so by opening the FRED code file, modifying it, then saving it by pressing CMD/CTRL + S.

Next, go back to the main menu on the left, reopen the Jupyter notebook page for the model, and run the model again. To restore all the FRED code on the Epistemix Platform to its unmodified state, you can go to the top folder in the menu on the left and run the Reset-Guides function. Note that new visitors should probably not try to modify the FRED code.

Tracking the Progress of an ABM Run

Once a FRED model run has started, you can track its progress by watching the small circle in the upper right corner of the notebook’s menu bar (next to “Python 3 ipykernel”). Note that this circle will not be visible when editing other file types.

The circle will be empty before the run, change to white when the model is accessed, and once the run is started it will show a clocklike wedge that expands as the model moves toward completion. By hovering your cursor over the circle, a text box will appear showing the number of Jupyter notebook cells executed and the elapsed runtime.

Learn FRED with the Epistemix Quickstart Guide

The Epistemix Quickstart Guide is a series of ten step-by-step lessons on how to use FRED, each of which is illustrated with an interesting, new, short tutorial FRED model. The user can navigate these lessons by following instructions above for Running, Viewing, Modifying, and Tracking FRED. To begin the lessons, go the menu on the left, click on the most recent version of the Quickstart Guide, and begin with lesson 001.

The lessons are as follows:

• 001 - Minimal FRED

• 002 - Conditions and States

• 003 - Agents

• 004 - Multiple Conditions

• 005 - Places

• 006 - Interactions

• 007 - Transmission

• 008 - Agents and Places

• 009 - Control Structures

• 010 - Data Input and Output

• 011 - Running FRED Through the Client Object

Creating Your Own FRED Models

This Epistemix Platform can be used to create entirely new FRED models. To do this, go to the main menu folder on the left, right click to add a new folder. In that newly created folder, right click again to add a new Jupyter Notebook page, and name the folder and Notebook.

Add the necessary Python code to the cells in the Jupyter Notebook, and write the FRED code as one or more text files, which you should then save as FRED files by replacing the file extension (.txt) with .fred before you save it.

You may find it convenient to borrow blocks of Python code or FRED code from the numerous Introductory, Quickstart, and Demonstration models that are already available on the Platform.

Synthetic Population

Below you will find a list of synthetic populations that are freely available synthetic on the platform.

County	State	FIPS Code	2010 Population
Park	Colorado	08093	15960
Clarke	Georgia	13059	107247
Butte	Idaho	16023	2838
New York	New York	36061	1515118
Lenoir	North Carolina	37107	57824
Erie	Pennsylvania	42049	266460
Jefferson	Pennsylvania	42065	44594
Loving	Texas	48301	70
Grand Isle	Vermont	50013	6965
Dane	Wisconsin	55025	473566
Kewaunee	Wisconsin	55061	20259

Epistemix Resources

Documentation

Users can access the Epistemix Documentation at docs.epistemix.com. This site provides useful information about how to build models using FRED.

• Documentation Home Page

• FRED Modeling Language Guide

• FRED Language Alphabetical Lookup

Additional Resources

• Discourse Forum

• Epistemix Blog

For any other questions, please email learning@epistemix.com.

Parting Notes

Changes made by the user to the contents of the ABMs in the pre-populated folders on this site are not considered permanent. Updates made by Epistemix to the folders containing these guides can cause any changes that you may have made to them to be overwritten. When editing, duplicating, or writing a model, ensure that you are not working in a subdirectory of one of the pre-populated folders.

Caution should be exercised when running models that have an extremely large population. If insufficient memory is available to run the model, the process may be killed.

Latest Updates

• 2022-02-08

  Added “Introductory-Models” folder to the platform.