matrx.logger.logger

Module Contents

class GridWorldLogger(log_strategy=1, save_path='/logs', file_name='', file_extension='.csv', delimiter=';')

A class to log data during a running world.

Loggers are meant to collect, process and write data to files during a running world. They can be added through the matrx.world_builder.WorldBuilder.add_logger() method. We refer to that method on how to add a logger to your world.

Note that a world can have multiple loggers, each resulting in their own unique log file. So you have the option to create a single large log file with a single logger, or segment the data in some way over different files with multiple loggers. Another reason for more then one logger is a difference in logging strategy. For instance to have a logger that logs only at the start or end of the world and a logger that logs at every tick.

Parameters
log_strategyint, str (default: 1)

When an integer, the logger is called every that many ticks. When a string, should be GridWorldLogger.LOG_ON_LAST_TICK, GridWorldLogger.LOG_ON_FIRST_TICK or GridWorldLogger.LOG_ON_GOAL_REACHED. Respectively for only logging on the last tick of the world, the first tick of the world or every time a goal is reached.

save_pathstr (default: “/logs”)

The default path were log files are stored. If the path does not exist, it is created. Otherwise log files are added to that path. If multiple worlds are ran from the same builder, the directory will contain sub-folders depicting the world’s number (e.g., “world_1” for the first world, “world_2” for the second, etc.).

file_namestr (default: “”)

The file name prefix. Every log file is always appended by the timestamp (Y-m-d_H:M:S) and the file extension. When an empty string, log file names will thus be only the timestamp.

file_extensionstr (default: “.csv”)

The file name extension to be used.

delimiterstr (default: “;”)

The column delimiter to be used in the log files.

.. deprecated:: 2.1.0

GridWorldLogger will be removed in the future, it is replaced by GridWorldLoggerV2 because the latter works with the matrx.agents.agent_utils.state.State object.

LOG_ON_LAST_TICK = log_last_tick

Log strategy to log on the first tick of a world.

LOG_ON_FIRST_TICK = log_first_tick

Log strategy to log every time a goal is reached or completed.

property file_name(self)

Make the logger filename publicly available

log(self, grid_world, agent_data)

The main method to be overwritten by your own logger class.

This method is called according to the log_strategy set when the logger was added the world builder. For more details on this see matrx.world_builder.WorldBuilder.add_logger().

Parameters
grid_worldGridWorld

The entire grid world instance. Use this to log anything you require to log from the grid world.

agent_datadict

A dictionary of all data coming from all agents’ matrx.agents.agent_brain.get_log_data() methods. This dictionary has as keys the agent ids of all agents. As value there is the dictionary their log methods returned.

Returns
——-
dict

This method should return a dictionary where the keys are the columns and their value a single row. The keys (e.g., columns) should be always the same every consecutive call. If this is not the case an exception is raised.

class GridWorldLoggerV2(log_strategy=1, save_path='/logs', file_name='', file_extension='.csv', delimiter=';')

A class to log data during a running world.

Loggers are meant to collect, process and write data to files during a running world. They can be added through the matrx.world_builder.WorldBuilder.add_logger() method. We refer to that method on how to add a logger to your world.

Note that a world can have multiple loggers, each resulting in their own unique log file. So you have the option to create a single large log file with a single logger, or segment the data in some way over different files with multiple loggers. Another reason for more then one logger is a difference in logging strategy. For instance to have a logger that logs only at the start or end of the world and a logger that logs at every tick.

Parameters
log_strategyint, str (default: 1)

When an integer, the logger is called every that many ticks. When a string, should be GridWorldLogger.LOG_ON_LAST_TICK, GridWorldLogger.LOG_ON_FIRST_TICK or GridWorldLogger.LOG_ON_GOAL_REACHED. Respectively for only logging on the last tick of the world, the first tick of the world or every time a goal is reached.

save_pathstr (default: “/logs”)

The default path were log files are stored. If the path does not exist, it is created. Otherwise log files are added to that path. If multiple worlds are ran from the same builder, the directory will contain sub-folders depicting the world’s number (e.g., “world_1” for the first world, “world_2” for the second, etc.).

file_namestr (default: “”)

The file name prefix. Every log file is always appended by the timestamp (Y-m-d_H:M:S) and the file extension. When an empty string, log file names will thus be only the timestamp.

file_extensionstr (default: “.csv”)

The file name extension to be used.

delimiterstr (default: “;”)

The column delimiter to be used in the log files.

LOG_ON_LAST_TICK = log_last_tick

Log strategy to log on the first tick of a world.

LOG_ON_FIRST_TICK = log_first_tick

Log strategy to log every time a goal is reached or completed.

property file_name(self)

The file name the loggers writes data to.

log(self, world_state, agent_data, grid_world)

The main method to be overwritten by your own logger class.

This method is called according to the log_strategy set when the logger was added the world builder. For more details on this see matrx.world_builder.WorldBuilder.add_logger().

Parameters
world_stateState

The entire world state as a State object. Use this to quickly find and locate data you want to log.

agent_datadict

A dictionary of all data coming from all agents’ matrx.agents.agent_brain.get_log_data() methods. This dictionary has as keys the agent ids of all agents. As value there is the dictionary their log methods returned.

grid_worldGridWorld

The entire grid world instance. Use this to log anything not included into the state, such as the messages send between agents.

Returns
——-
dict

This method should return a dictionary where the keys are the columns and their value a single row. The keys (e.g., columns) should be always the same every consecutive call. If this is not the case an exception is raised.