Note

You can download this demonstration as a Jupyter Notebook here

Exploratory modelling and analysis (EMA)

This guide shows how to use agentpy models together with the EMA Workbench. Similar to the agentpy Experiment class, this library can be used to perform experiments over different parameter combinations and multiple runs, but offers more advanced tools for parameter sampling and analysis with the aim to support decision making under deep uncertainty.

Converting an agentpy model to a function

Let us start by defining an agent-based model. Here, we use the wealth transfer model from the model library.

import agentpy as ap
from agentpy.examples import WealthModel

To use the EMA Workbench, we need to convert our model to a function that takes each parameter as a keyword argument and returns a dictionary of the recorded evaluation measures.

wealth_model = WealthModel.as_function()

help(wealth_model)

Help on function agentpy_model_as_function in module agentpy.model:

agentpy_model_as_function(**kwargs)
    Performs a simulation of the model 'WealthModel'.

    Arguments:
        **kwargs: Keyword arguments with parameter values.

    Returns:
        dict: Reporters of the model.

Let us test out this function:

wealth_model(agents=5, steps=5)

{'gini': 0.32}

Using the EMA Workbench

Here is an example on how to set up an experiment with the EMA Workbench. For more information, please visit the documentation of EMA Workbench.

from ema_workbench import (IntegerParameter, Constant, ScalarOutcome,
                           Model, perform_experiments, ema_logging)

if __name__ == '__main__':

    ema_logging.LOG_FORMAT = '%(message)s'
    ema_logging.log_to_stderr(ema_logging.INFO)

    model = Model('WealthModel', function=wealth_model)
    model.uncertainties = [IntegerParameter('agents', 10, 100)]
    model.constants = [Constant('steps', 100)]
    model.outcomes = [ScalarOutcome('gini')]

    results = perform_experiments(model, 100)

performing 100 scenarios * 1 policies * 1 model(s) = 100 experiments
performing experiments sequentially
10 cases completed
20 cases completed
30 cases completed
40 cases completed
50 cases completed
60 cases completed
70 cases completed
80 cases completed
90 cases completed
100 cases completed
experiments finished

results[0]

	agents	scenario	policy	model
0	70.0	0	None	WealthModel
1	44.0	1	None	WealthModel
2	77.0	2	None	WealthModel
3	87.0	3	None	WealthModel
4	51.0	4	None	WealthModel
...	...	...	...	...
95	38.0	95	None	WealthModel
96	26.0	96	None	WealthModel
97	59.0	97	None	WealthModel
98	94.0	98	None	WealthModel
99	75.0	99	None	WealthModel

100 rows × 4 columns

results[1]

{'gini': array([0.67877551, 0.61880165, 0.6392309 , 0.62491743, 0.65820838,
        0.62191358, 0.61176471, 0.66986492, 0.6134068 , 0.63538062,
        0.69958848, 0.63777778, 0.61862004, 0.6786    , 0.6184424 ,
        0.61928474, 0.6446281 , 0.6358    , 0.7283737 , 0.60225922,
        0.6404321 , 0.59729448, 0.63516068, 0.515     , 0.58301785,
        0.66780045, 0.6321607 , 0.58131488, 0.6201873 , 0.70083247,
        0.7       , 0.58666667, 0.58131382, 0.5964497 , 0.56014692,
        0.6446281 , 0.59146814, 0.70919067, 0.61592693, 0.59736561,
        0.52623457, 0.64604402, 0.56790123, 0.65675193, 0.49905482,
        0.55250979, 0.62606626, 0.49864792, 0.63802469, 0.62722222,
        0.65500945, 0.69010417, 0.64160156, 0.67950052, 0.60207612,
        0.63115111, 0.64246914, 0.65162722, 0.65759637, 0.66392948,
        0.63971072, 0.57375   , 0.55310287, 0.58692476, 0.59410431,
        0.61950413, 0.6228125 , 0.52444444, 0.59119898, 0.63180975,
        0.6592    , 0.6540149 , 0.60133914, 0.67884977, 0.57852447,
        0.58739596, 0.52040816, 0.52077562, 0.66304709, 0.59750567,
        0.57692308, 0.65189289, 0.64697266, 0.68507561, 0.66874582,
        0.67857143, 0.59410431, 0.55953251, 0.63651717, 0.62809917,
        0.61111111, 0.6328    , 0.64003673, 0.65140479, 0.65972222,
        0.62465374, 0.65384615, 0.64464234, 0.61588954, 0.63111111])}