burlap.behavior.stochasticgames.auxiliary.performance

Class MultiAgentExperimenter

java.lang.Object

burlap.behavior.stochasticgames.auxiliary.performance.MultiAgentExperimenter

public class MultiAgentExperimenter
extends java.lang.Object

This class is used to simplify the comparison of agent performance in a stochastic game world. This class takes as input a WorldGenerator and a list of AgentFactoryAndType objects which can be used to generate agents and play them against each other in a world. Performance over multiple trials is plotted using the MultiAgentPerformancePlotter WorldObserver object and the results can also be printed out to CSV files using the writeEpisodeDataToCSV(String), writeStepDataToCSV(String), or writeStepAndEpisodeDataToCSV(String) methods. If only the CSV data is desired without plotting, the plotting may be disabled using the toggleVisualPlots(boolean) method.

To set up the metrics and plots that will be displayed, use the setUpPlottingConfiguration(int, int, int, int, TrialMode, PerformanceMetric...) method. If this method is not called, but plots are not disabled, then my default the cumulative reward will be displayed.

The length of a trial can have two interpretations, either the number of episodes, or the total number of steps taken across multiple episodes. By default, the trial length will be interpreted as the number of episodes in a trial, but this interpretation can be changed with the toggleTrialLengthInterpretation(boolean)

To start an experiment once everything is configured, use the startExperiment() method.

Author:

James MacGlashan

Field Summary

Fields

Modifier and Type	Field and Description
protected AgentFactoryAndType[]	agentFactoriesAndTypes The agent factories for the agents to be tested
protected boolean	completedExperiment Whether the experimenter has completed.
int	debugCode The debug code used for debug printing.
protected boolean	displayPlots Whether the performance should be visually plotted (by default they will)
protected int	nTrials The number of trials that each agent is evaluted
protected double	plotCISignificance The signficance value for the confidence interval in the plots.
protected int	plotRefresh The delay in milliseconds between autmatic refreshes of the plots
protected MultiAgentPerformancePlotter	plotter The performance plotter object
protected TerminalFunction	tf The terminal function defining when episodes in a trial end
protected int	trialLength The length of each trial
protected boolean	trialLengthIsInEpisodes Whether the trial length specifies a number of episodes (which is the default) or the total number of steps
protected WorldGenerator	worldGenerator A world generated for created a new world for each testing trial

Constructor Summary

Constructors

Constructor and Description
MultiAgentExperimenter(WorldGenerator worldGenerator, TerminalFunction tf, int nTrials, int trialLength, AgentFactoryAndType... agentFactoriesAndTypes) Initializes.

Method Summary

Modifier and Type	Method and Description
protected void	runEpisodewiseTrial(World w) Runs a trial where trial length is interpreted as the number of episodes in a trial.
protected void	runStepwiseTrial(World w) Runs a trial where the trial lenght is interpreted as the number of total steps taken.
void	setPlotCISignificance(double significance) Sets the significance used for confidence intervals.
void	setPlotRefreshDelay(int delayInMS) Sets the delay in milliseconds between automatic plot refreshes
void	setUpPlottingConfiguration(int chartWidth, int chartHeight, int columns, int maxWindowHeight, TrialMode trialMode, PerformanceMetric... metrics) Setsup the plotting confiruation.
void	startExperiment() Starts the experiment and runs all trails for all agents.
void	toggleTrialLengthInterpretation(boolean lengthRepresentsEpisodes) Changes whether the trial length provided in the constructor is interpreted as the number of episodes or total number of steps.
void	toggleVisualPlots(boolean shouldPlotResults) Toggles whether plots should be displayed or not.
void	writeEpisodeDataToCSV(java.lang.String filePath) Writes an step-wise data to a csv file.
void	writeStepAndEpisodeDataToCSV(java.lang.String pathAndBaseNameToUse) Writes the step-wise and episode-wise data to CSV files.
void	writeStepDataToCSV(java.lang.String filePath) Writes an episode-wise data to a csv file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tf

protected TerminalFunction tf

The terminal function defining when episodes in a trial end

worldGenerator

protected WorldGenerator worldGenerator

A world generated for created a new world for each testing trial

agentFactoriesAndTypes

protected AgentFactoryAndType[] agentFactoriesAndTypes

The agent factories for the agents to be tested

nTrials

protected int nTrials

The number of trials that each agent is evaluted

trialLength

protected int trialLength

The length of each trial

trialLengthIsInEpisodes

protected boolean trialLengthIsInEpisodes

Whether the trial length specifies a number of episodes (which is the default) or the total number of steps

plotter

protected MultiAgentPerformancePlotter plotter

The performance plotter object

displayPlots

protected boolean displayPlots

Whether the performance should be visually plotted (by default they will)

plotRefresh

protected int plotRefresh

The delay in milliseconds between autmatic refreshes of the plots

plotCISignificance

protected double plotCISignificance

The signficance value for the confidence interval in the plots. The default is 0.05 which correspodns to a 95% CI

completedExperiment

protected boolean completedExperiment

Whether the experimenter has completed.

debugCode

public int debugCode

The debug code used for debug printing. This experimenter will print with the debugger the number of trials completed for each agent.

Constructor Detail

MultiAgentExperimenter

public MultiAgentExperimenter(WorldGenerator worldGenerator,
                              TerminalFunction tf,
                              int nTrials,
                              int trialLength,
                              AgentFactoryAndType... agentFactoriesAndTypes)

Initializes. Trial length is interepted either has the number of episodes per trial or the total number of steps across all episodes. By default the length will be interepted as the number of episodes, but this interpetation can be changed with the toggleTrialLengthInterpretation(boolean) method. The agents will join generated worlds in the order that they appear in the list.

Parameters:

worldGenerator - the world generator used to create a clean world for each trial.

tf - the terminal function used to interpret the end of episodes

nTrials - the number of trials over which performance will be gathered

trialLength - the length of trial

agentFactoriesAndTypes - the agent factories and the type of agent the generated agent will join the world as

Method Detail

setUpPlottingConfiguration

public void setUpPlottingConfiguration(int chartWidth,
                                       int chartHeight,
                                       int columns,
                                       int maxWindowHeight,
                                       TrialMode trialMode,
                                       PerformanceMetric... metrics)

Setsup the plotting confiruation.

Parameters:

chartWidth - the width of each chart/plot

chartHeight - the height of each chart//plot

columns - the number of columns of the plots displayed. Plots are filled in columns first, then move down the next row.

maxWindowHeight - the maximum window height allowed before a scroll view is used.

trialMode - which plots to use; most recent trial, average over all trials, or both. If both, the most recent plot will be inserted into the window first, then the average.

metrics - the metrics that should be plotted. The metrics will appear in the window in the order that they are specified (columns first)

setPlotRefreshDelay

public void setPlotRefreshDelay(int delayInMS)

Sets the delay in milliseconds between automatic plot refreshes

Parameters:

delayInMS - the delay in milliseconds

setPlotCISignificance

public void setPlotCISignificance(double significance)

Sets the significance used for confidence intervals. The default is 0.05 which corresponds to a 95% CI.

Parameters:

significance - the significance for confidence intervals to use

toggleVisualPlots

public void toggleVisualPlots(boolean shouldPlotResults)

Toggles whether plots should be displayed or not.

Parameters:

shouldPlotResults - if true, then plots will be displayed; if false plots will not be displayed.

toggleTrialLengthInterpretation

public void toggleTrialLengthInterpretation(boolean lengthRepresentsEpisodes)

Changes whether the trial length provided in the constructor is interpreted as the number of episodes or total number of steps.

Parameters:

lengthRepresentsEpisodes - if true, interpret length as number of episodes; if false interprete as total number of steps.

startExperiment

public void startExperiment()

Starts the experiment and runs all trails for all agents.

writeStepAndEpisodeDataToCSV

public void writeStepAndEpisodeDataToCSV(java.lang.String pathAndBaseNameToUse)

Writes the step-wise and episode-wise data to CSV files. The episode-wise data will be saved to the file <pathAndBaseNameToUse>Episodes.csv. The step-wise data will. If the experimenter as not been run, then nothing will be saved and a warrning message will be printed to indicate as such. be saved to the file <pathAndBaseNameToUse>Steps.csv

Parameters:

pathAndBaseNameToUse - the base path and file name for the epsidoe-wise and step-wise csv files.

writeStepDataToCSV

public void writeStepDataToCSV(java.lang.String filePath)

Writes an episode-wise data to a csv file. If the file path does not include the .csv extension, it will automatically be added. If the experimenter as not been run, then nothing will be saved and a warrning message will be printed to indicate as such.

Parameters:

filePath - the path to the csv file to write to.

writeEpisodeDataToCSV

public void writeEpisodeDataToCSV(java.lang.String filePath)

Writes an step-wise data to a csv file. If the file path does not include the .csv extension, it will automatically be added. If the experimenter as not been run, then nothing will be saved and a warrning message will be printed to indicate as such.

Parameters:

filePath - the path to the csv file to write to.

runEpisodewiseTrial

protected void runEpisodewiseTrial(World w)

Runs a trial where trial length is interpreted as the number of episodes in a trial.

Parameters:

w - the world object in which the trial will be run

runStepwiseTrial

protected void runStepwiseTrial(World w)

Runs a trial where the trial lenght is interpreted as the number of total steps taken.

Parameters:

w - the world object in which the trial will be run