Observing agents

There are different ways of observing your agents:

Trade Logging:
ABCE by default logs all trade and creates a SAM or IO matrix.
Manual in agent logging:
An agent is instructed to log a variable with log() or a change in a variable with log_change().
Aggregate Data:
aggregate() save agents possessions and variable aggregated over a group
Panel Data:
panel() creates panel data for all agents in a specific agent group at a specific point in every round. It is set in start.py

How to retrieve the Simulation results is explained in retrieval

Trade Logging

By default ABCE logs all trade and creates a social accounting matrix or input output matrix. Because the creation of the trade log is very time consuming you can change the default behavior in world_parameter.csv. In the column ‘trade_logging’ you can choose ‘individual’, ‘group’ or ‘off’. (Without the apostrophes!).

Manual logging

All functions except the trade related functions can be logged. The following code logs the production function and the change of the production from last year:

output = self.produce(self.inputs)
self.log('production', output)
self.log_change('production', output)

Log logs dictionaries. To log your own variable:

self.log('price', {'input': 0.8, 'output': 1})

Further you can write the change of a variable between a start and an end point with: observe_begin() and observe_end().

class abce.Database[source]

Bases: object

The database class

log(action_name, data_to_log)[source]

With log you can write the models data. Log can save variable states and and the working of individual functions such as production, consumption, give, but not trade(as its handled automatically).

Args:
‘name’(string):
the name of the current action/method the agent executes
data_to_log:
a variable or a dictionary with data to log in the the database

Example:

self.log('profit', profit)

self.log('employment_and_rent', {'employment': self.possession('LAB'),
                                 'rent': self.possession('CAP'), 'composite': self.composite})

self.log(self.produce_use_everything())
See also:
log_nested():
handles nested dictianaries
log_change():
loges the change from last round

observe_begin():

log_change(action_name, data_to_log)[source]

This command logs the change in the variable from the round before. Important, use only once with the same action_name.

Args:
‘name’(string):
the name of the current action/method the agent executes
data_to_log:
a dictianary with data for the database

Examples:

self.log_change('profit', {'money': self.possession('money')]})
self.log_change('inputs', {'money': self.possessions(['money', 'gold', 'CAP', 'LAB')]})
log_dict(action_name, data_to_log)[source]

same as the log function, only that it supports nested dictionaries see: log().

log_value(name, value)[source]

logs a value, with a name

Args:
‘name’(string):
the name of the value/variable
value(int/float):
the variable = value to log
observe_begin(action_name, data_to_observe)[source]

observe_begin and observe_end, observe the change of a variable. observe_begin(...), takes a list of variables to be observed. observe_end(...) writes the change in this variables into the log file

you can use nested observe_begin / observe_end combinations

Args:
‘name’(string):
the name of the current action/method the agent executes
data_to_log:
a dictianary with data for the database

Example:

self.log('production', {'composite': self.composite,
                        self.sector: self.final_product[self.sector]})

... different method ...

self.log('employment_and_rent', {'employment': self.possession('LAB'),
                                'rent': self.possession('CAP')})
observe_end(action_name, data_to_observe)[source]

This command puts in a database called log, whatever values you want values need to be delivered as a dictionary:

Args:
‘name’(string):
the name of the current action/method the agent executes
data_to_log:
a dictianary with data for the database

Example:

self.log('production', {'composite': self.composite,
                        self.sector: self.final_product[self.sector]})

... different method ...

self.log('employment_and_rent', {'employment': self.possession('LAB'),
                                'rent':self.possession('CAP')})

Panel Data

Simulation.panel(group, possessions=[], variables=[])[source]
panel(.) writes a panel of variables and possessions

of a group of agents into the database, so that it is displayed in the gui. Aggregate must be declared before the agents are build. (‘agent_group’, ‘panel’) must be in the action_list, so that the simulation knows when to make the aggregate snapshot.

Args:
group:
can be either a group or ‘all’ for all agents
possessions (list, optional):
a list of all possessions you want to track as ‘strings’
variables (list, optional):
a list of all variables you want to track as ‘strings’

Example in start.py:

simulation_parameters.build_agents(Firm, 'firm', number=5)

...

simulation.panel('firm', possessions=['money', 'input'],
                         variables=['production_target', 'gross_revenue'])

for round in simulation.next_round():
    firms.do('produce_and_sell)
    firms.do('panel')
    households.do('buying')

Aggregate Data

Simulation.aggregate(group, possessions=[], variables=[])[source]
aggregate(.) writes summary statistics of variables and possessions

of a group of agents into the database, so that it is displayed in the gui. Aggregate must be declared before the agents are build. (‘agent_group’, ‘aggregate’) must be in the action_list, so that the simulation knows when to make the aggregate snapshot.

Args:
group:
can be either a group or ‘all’ for all agents
possessions (list, optional):
a list of all possessions you want to track as ‘strings’
variables (list, optional):
a list of all variables you want to track as ‘strings’

Example in start.py:

simulation_parameters.build_agents(Firm, 'firm', number=5)

...

simulation.aggregate('firm', possessions=['money', 'input'],
                         variables=['production_target', 'gross_revenue'])

for round in simulation.next_round():
    firms.do('produce_and_sell)
    firms.do('aggregate')
    households.do('buying')

Network logging

class abce.networklogger.NetworkLogger[source]

Bases: object

NetworkLogger logs a network. It has to be initialized in start.py. In the agents log_network has to be called. Optionally log_agent, can be called in order to save agent attributes.

Simulation.network(frequency=1, savefig=False, savegml=True, figsize=(24, 20), dpi=100, pos_fixed=False, alpha=0.8)

network(.) prepares abce to write network data.

Args:
frequency:
the frequency with which the network is written, default=1
savefig:
wether to save a png file, default=False
savegml:
wether to save a gml file, default=True
figsize:
size of the graph in inch. (see matplotlib)
dpi:
resulution of the picture
pos_fixed:
positions are fixed after the first round

Example:

simulation.network(savefig=True)
log_agent(color='blue', style='filled', shape='circle')[source]

log_agent is optional. It can log agent attributes.

Args:
color:
matplotlib color, default=’blue’
shape:
shape can be one of the folling signs: ”.,ov^<>12348sp*hH+xDd|_” others can be found at http://matplotlib.org/api/markers_api.html
log_network(list_of_nodes)[source]

loggs a network. List of nodes is a list with the numbers of all agents, this agent is connected to.

Args:
list_of_nodes:
list of nodes that the agent is linked to. A list of noteds must have the following format: [(‘agent_group’, agent_id), (‘agent_group’, agent_id), ...] If your
color:
integer for the color
style(True/False):
filled or not
shape(True/False):
form of the bubble

Retrieval of the simulation results

Agents can log their internal states and the simulation can create panel data. abce.database.

the results are stored in a subfolder of the ./results/ folder. The exact path is in simulation.path. So if you want to post-process your data, you can write a function that changes in to the simulation.path directory and manipulates the CSV files there. The tables are stored as ‘.csv’ files which can be opened with excel.

The same data is also as a sqlite3 database ‘database.db’ available. It can be opened by ‘sqlitebrowser’ in ubuntu.

Example:

In start.py

simulation = abce.Simulation(...)
...
simulation.run()

os.chdir(simulation.path)
firms = pandas.read_csv('aggregate_firm.csv')
...