bcds.phison.sim
Class SxSeriesToGnuPlot

java.lang.Object
  bcds.phison.sim.StatsExporterBase
      bcds.phison.sim.SxSeriesToGnuPlot

All Implemented Interfaces:

StatsExporter, WithEnvParams

public class SxSeriesToGnuPlot
extends StatsExporterBase

The SxSeriesToGnuPlot generates a GNU Plot script for each group of statistical collectors whose members are instances of Series. Besides the .gnuplot file, one data file per series is also generated. Those files are referenced by the plot command embedded in the .gnuplot file.

Although the is a number of environment parameters that controls some aspects of the script generation, it is assumed that the user will further personalize the script (remove titles, added grid lines, define explicit ranges, etc).

By default, the plot type is lines, the output terminal is PDF (in enhanced, color mode). The data files are compressed by default (in the GZIP format). Each row contains the following data: key average stddev count min max where key is the x-value. The above text is printed as a comment on the first line of each series data file. The separator between columns is a single space character, and the US locale is used always. This is a deliberate decision so that fractional values always use a dot as a decimal separator.

Files are generated in a user-specified directory, which by default is the current directory. Files are always overwritten, so any previous content is lost.

See getEnvParams() for further details on environment parameters.

Author:

Juan Segovia S.

Constructor Summary

SxSeriesToGnuPlot()

Method Summary

java.lang.Object[]	getEnvParams() Returns the environment parameters used by this class.
void	run() Iterates over the statistical collectors and generates the GnuPlot script files and data files.
void	setup(SimStatsCollector stats, Environ env) Initializes this exporter.

Methods inherited from class bcds.phison.sim.StatsExporterBase

getEnviron, getName, sanitizeFilename, stats

Methods inherited from class java.lang.Object

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

Constructor Detail

SxSeriesToGnuPlot

public SxSeriesToGnuPlot()

Method Detail

setup

public void setup(SimStatsCollector stats,
                  Environ env)

Initializes this exporter. Environment parameters are checked and cached. The following actions are performed:

• The regular expression for selecting group names is compiled, so that invalid patterns are detected at this stage.
• The output directory is checked to make sure that it exists and actually is a directory. If it is not, an runtime error is thrown. If it does not exist, an attempt is made to create the full path. If that fails, a runtime exception is thrown. Note not throwing an exception at this stage regarding the output directory does not guarantee that there will not be errors at the time the actual files are generated. For example, the given path might not be writable, and that is not cheched here.
• Make sure that the replacement character is not empty. If it is, a runtime exception is thrown. If it has more than one character, only the first one is used.
• The boolean environment parameters stddev_in_expr and compress_data are cached.
• If the enviroment parameter plot_style ends with errorbars, a flag is activated to include the standard deviation in the data files.

Specified by:

setup in interface StatsExporter

Overrides:

setup in class StatsExporterBase

Throws:

java.lang.IllegalArgumentException - if:

• the group name selector does not compile.
• the replacement character is empty.
• if the path given as output directory exists and is not a directory, or if it does not exist but cannot be created.

run

public void run()

Iterates over the statistical collectors and generates the GnuPlot script files and data files. Collectors whose group name does not match the pattern given in the respective environment parameter are skipped as well as those that do not contain instances of Series.

The actual generation of files are performed by calling generateFiles(java.lang.String, java.util.Set).

getEnvParams

public java.lang.Object[] getEnvParams()

Returns the environment parameters used by this class. The parameters are prefixed with "SxSeriesToGnuPlot.":

• compress_data (default: true): the series' data are written in a GZIP-compressed format. When running the generated GNUPlot scripts, the gunzip command must be available for the data to be decompressed on the fly.
• filename_sanitizer_char (default: _, an underscore character). File names are generated based on the group's name (the GNUPlot script file) and the series' names (series data files). As those names may contain characters that are invalid in filenames, this parameter provides a substitution character for anything that is not a letter of the English alphabet (both uppercase and lowercase), a digit, an underscore (_) or a dash (-). This parameter must have at least one character; if more than one is given, only the first one is taken into account. Note that no check is performed to make sure that the replacement character itself is valid.
• groups_selector (default: .*): a regular expression that can be used to select a subset of groups of series by name. For a group to be exported, its name must completely match the groups selector pattern; a partial match is not sufficient. Thus, if groups whose name contain the work time want to be exported, for example, the selector pattern must be .*time.*. The given default pattern covers all non-empty group names. The pattern must comply with Pattern.
• output_dir (default: ., the current directory): the directory where to put the generated files. An empty string also indicated the current directory. The path separator is automatically added, so that /tmp/ and /tmp are functionally equivalent, for example. If the given path does not exist, it is created at setup time; any non-existant intermediate directory is also created. On the other hand, if the path exists, it must be a directory. Note that directories may be created even if finally no output files are generated.
• plot_style (default: lines): the plot style that in GNUPlot is indicated with the clause ...with TYPE of the plot command. The value can be anything; no validation is performed in this class. Typical styles include: lines, dots, linespoints, boxes, as well as candlestick, yerrorbars and other variants with error bars. Please consult your GNUPlot manual for further details.
• stddev_in_expr (default: false): when true, the generated GNUPlot script references the third columns in the data files, which corresponds to the standard deviation of the variable. The value of that column is used by GNUPlot to display the error bars. When plot_style ends with errorbars, this parameter is automatically set to true, independently of what is assigned by the user.
• terminal_type (default: pdf): the terminal type, as required by GNUPlot. Any value is acceptable; no validation is performed in this class. Consult your GNUPLot manual for the list of available terminal types. By default, the type is set to enhanced PDF. The names ps and postscript are used as synonym for EPS (again, the enhanced mode is activated). If this parameter is set to the empty string, the terminal type and the filename is included as comment in the generated script, thus, both are effectively left unassigned.

Additionally, it accepts GraphMetric.target as a hint. See GraphMetric.run().

Specified by:

getEnvParams in interface WithEnvParams

Overrides:

getEnvParams in class StatsExporterBase