ethicalgardeners.metricscollector.MetricsCollector

class ethicalgardeners.metricscollector.MetricsCollector(out_dir_path, export_on, send_on, wandb_run=None, **wandb_params)[source]

Bases: object

Collects, tracks and exports metrics from the Ethical Gardeners simulation.

This class is responsible for gathering various performance metrics during simulation runs, storing them internally, and optionally exporting them to files or sending them to external monitoring services like WandB.

Metrics are updated at each step of the simulation and can be reset when the environment is reset.

out_dir_path

Directory path where metrics will be exported when export_on is True.

Type:

str

export_on

Flag indicating whether metrics should be exported to local files like CSV files.

Type:

bool

send_on

Flag indicating whether metrics should be sent to external services like WandB.

Type:

bool

metrics

Dictionary containing all collected metrics, including:

  • step (int): Current step in the simulation.

  • episode (int): Current episode number.

  • total_planted_flowers (int): Total number of flowers planted by all agents.

  • num_planted_flowers_per_agent (dict): Flowers planted per agent.

  • total_harvested_flowers (int): Total number of flowers harvested.

  • num_harvested_flowers_per_agent (dict): Flowers harvested per agent.

  • avg_pollution_percent (float): Average pollution percentage across all cells.

  • num_cells_pollution_above_90 (int): Number of cells with pollution > 90%.

  • num_cells_pollution_above_75 (int): Number of cells with pollution > 75%.

  • num_cells_pollution_above_50 (int): Number of cells with pollution > 50%.

  • num_cells_pollution_above_25 (int): Number of cells with pollution > 25%.

  • rewards (dict): Current rewards for each agent.

  • accumulated_rewards (dict): Cumulative rewards for each agent.

  • agent_selection (str): Currently selected agent.

Type:

dict

run

An WandB run instance for logging metrics. Can be provided externally or created internally if send_on is True.

Type:

wandb.run

_run_id

Unique identifier for the run, used for file naming during export.

Type:

int

__init__(out_dir_path, export_on, send_on, wandb_run=None, **wandb_params)[source]

Create the metrics collector.

Parameters:

  • out_dir_path (str) – Directory path where metrics will be exported when export_on is True.

  • export_on (bool) – Flag indicating whether metrics should be exported to local files like CSV files.

  • send_on (bool) – Flag indicating whether metrics should be sent to external services like WandB.

  • wandb_run (wandb.run, optional) – An existing WandB run instance to use for logging metrics. If None, a new run will be created if send_on is True.

  • **wandb_params – Additional parameters to pass to wandb.init() if a new run is created. This can include project name, entity, config, etc.

Methods

__init__(out_dir_path, export_on, send_on[, ...])

Create the metrics collector.

close()

Close the metrics collector.

export_metrics()

Export collected metrics to a local file.

finish_episode()

Finish the current episode.

reset_metrics()

Reset all metrics to their initial values.

send_metrics()

Send collected metrics to Weights and Biases (WandB).

update_metrics(grid_world, rewards, ...)

Update all tracked metrics based on the current state of the simulation.
_prepare_metrics()[source]

Prepare a formatted dictionary of metrics for export or sending.

Returns:

Dictionary containing all metrics in a format ready for export/logging

Return type:

dict

close()[source]

Close the metrics collector.

This method finishes the current WandB run if send_on is True. It should be called when the metrics collector is no longer needed to ensure all resources are properly released.

export_metrics()[source]

Export collected metrics to a local file.

This method exports the current metrics to a CSV file in the specified output directory if export_on is True. A new file is created for each run of the program, and metrics are appended to this file at each call.

finish_episode()[source]

Finish the current episode.

This method finishes the current WandB run and creates a new run_id. It should be called at the end of a simulation run to properly close the WandB session and ensure all metrics are saved.

reset_metrics()[source]

Reset all metrics to their initial values.

This method should be called when the environment is reset to ensure metrics are tracked correctly for each new simulation run.

send_metrics()[source]

Send collected metrics to Weights and Biases (WandB).

This method sends the current metrics to WandB for visualization and experiment tracking if send_on is True. It automatically handles WandB initialization if needed and logs all relevant metrics from the current simulation state.

update_metrics(grid_world, rewards, agent_selection: str)[source]

Update all tracked metrics based on the current state of the simulation.

This method computes and updates various metrics including flower planting/harvesting statistics, pollution levels, rewards. It should be called after each step of the simulation.

Parameters:

  • grid_world (GridWorld) – The current state of the world grid.

  • rewards (dict) – Dictionary of rewards for each agent.

  • agent_selection (str) – Currently selected agent.