Skip to content

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.

Community Model Library

Our model library contains models built by Epistemix as well as models submitted by the user community. Each model includes FRED code and an .ipynb notebook that will run the simulation and visualize the output. You can learn more about the community library and how to contribute here.

The model library may be accessed within the IDE from the launcher pane. If you would like to jump right in, the following classic ABM examples are included:

  • "The Epstein Rebellion Model" - Civil violence in Grand Isle County, Vermont
  • "The Schelling Housing Model" - Housing segregation by block group in Kewaunee County, Wisconsin
  • "Simple Flu" - Transmission of a simple respiratory disease with an SEIR model 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

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.

Additional Resources

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.