icarus.results package

Submodules

icarus.results.plot module

Plot results read from a result set

plot_lines(resultset, desc, filename, plotdir)

Plot a graph with characteristics described in the plot descriptor out of the data contained in the resultset and save the plot in given directory.

Parameters:

rs : ResultSet

Result set

desc : dict

The plot descriptor (more info below)

filename : str

The name used to save the file. The file format is determined by the extension of the file. For example, if this filename is ‘foo.pdf’, the file will be saved in pdf format.

plotdir : str

The directory in which the plot will be saved.

Notes

The plot descriptor is a dictionary with a set of values that describe how to make the plot.

The dictionary can contain the following keys:

• title : str, optional.

  The title of the graph

• xlabel : str, optional

  The x label

• ylabel : str, optional

  The y label

• errorbar : bool, optional

  If True error bars will be plotted. Default value is True

• confidence : float, optional

  The confidence used to plot error bars. Default value is 0.95

• xparam : iterable

  Path to the value of the x axis metric, e.g. [‘workload’, ‘alpha’]

• xvals : list

  Range of x values, e.g. [0.6, 0.7, 0.8, 0.9]

• filter : dict, optional

  A dictionary of values to filter in the resultset. Example: {‘network_cache’: 0.004, ‘topology_name’: ‘GEANT’} If not specified or None, no filtering is executed on the results and possibly heterogeneous results may be plotted together

• ymetrics : list of tuples

  List of metrics to be shown on the graph. The i-th metric of the list is the metric that the i-th line on the graph will represent. If all lines are for the same metric, then all elements of the list are equal. Each single metric (i.e. each element of the list) is a tuple modeling the path to identify a specific metric into an entry of a result set. Normally, it is a 2-value list where the first value is the name of the collector which measured the metric and the second value is the metric name. Example values could be (‘CACHE_HIT_RATIO’, ‘MEAN’), (‘LINK_LOAD’, ‘MEAN_INTERNAL’) or (‘LATENCY’, ‘MEAN’). For example, if in a graph of N lines all lines of the graph show mean latency, then ymetrics = [(‘LATENCY’, ‘MEAN’)]*5.

• ycondnames : list of tuples, optional

  List of condition names specific to each line of the graph. Different from the conditions expressed in the filter parameter, which are global, these conditions are specific to one bar. Ech condition name, different from the filter parameter is a path to a condition to be checked, e.g. (‘topology’, ‘name’). Values to be matched for this conditions are specified in ycondvals. This list must be as long as the number of lines to plot. If not specified, all lines are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• ycondvals : list of tuples, optional

  List of values that the conditions of ycondnames must meet. This list must be as long as the number of lines to plot. If not specified, all lines are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• xscale : (‘linear’ | ‘log’), optional

  The scale of x axis. Default value is ‘linear’

• yscale : (‘linear’ | ‘log’), optional

  The scale of y axis. Default value is ‘linear’

• xticks : list, optional

  Values to display as x-axis ticks.

• yticks : list, optional

  Values to display as y-axis ticks.

• line_style : dict, optional

  Dictionary mapping each value of yvals with a line style

• plot_args : dict, optional

  Additional args to be provided to the Pyplot errorbar function. Example parameters that can be specified here are linewidth and elinewidth

• legend : dict, optional

  Dictionary mapping each value of yvals with a legend label. If not specified, it is not plotted. If you wish to plot it with the name of the line, set it to put yvals or ymetrics, depending on which one is used

• legend_loc : str, optional

  Legend location, e.g. ‘upper left’

• legend_args : dict, optional

  Optional legend arguments, such as ncol

• plotempty : bool, optional

  If True, plot and save graph even if empty. Default is True

• xmin, xmax: float, optional

  The limits of the x axis. If not specified, they’re set to the min and max values of xvals

• ymin, ymax: float, optional

  The limits of the y axis. If not specified, they’re automatically selected by Matplotlib

plot_bar_chart(resultset, desc, filename, plotdir)

Plot a bar chart with characteristics described in the plot descriptor out of the data contained in the resultset and save the plot in given directory.

Parameters:

rs : ResultSet

Result set

desc : dict

The plot descriptor (more info below)

filename : str

The name used to save the file. The file format is determined by the extension of the file. For example, if this filename is ‘foo.pdf’, the file will be saved in pdf format.

plotdir : str

The directory in which the plot will be saved.

Notes

The plot descriptor is a dictionary with a set of values that describe how to make the plot.

The dictionary can contain the following keys:

• title : str, optional.

  The title of the graph

• xlabel : str, optional

  The x label

• ylabel : str, optional

  The y label

• errorbar : bool, optional

  If True error bars will be plotted. Default value is True

• confidence : float, optional

  The confidence used to plot error bars. Default value is 0.95

• filter : tree or dict of dicts, optional

  A tree or nested dictionary of values to include from the resultset. Example: {‘cache_placement’: {‘network_cache’: 0.004}, ‘topology’: {‘name’, ‘GEANT’}}. If not specified or None, no filtering is executed on the results and possibly heterogeneous results may be plotted together.

• xparam : tuple

  The path of the x axis metric, e.g. (‘workload’, ‘alpha’)

• xvals : list

  Range of x values, e.g. [0.6, 0.7, 0.8, 0.9]

• xticks : list, optional

  Names to display as ticks. If not specified, xvals is used instead

• ymetrics : list of tuples

  List of metrics to be shown on the graph. The i-th metric of the list is the metric that the i-th bar on the graph will represent. If all bars are for the same metric, then all elements of the list are equal. Each single metric (i.e. each element of the list) is a tuple modeling the path to identify a specific metric into an entry of a result set. Normally, it is a 2-value list where the first value is the name of the collector which measured the metric and the second value is the metric name. Example values could be (‘CACHE_HIT_RATIO’, ‘MEAN’), (‘LINK_LOAD’, ‘MEAN_INTERNAL’) or (‘LATENCY’, ‘MEAN’). For example, if in a graph of N bars all bar of the graph show mean latency, then ymetrics = [(‘LATENCY’, ‘MEAN’)]*5.

• ycondnames : list of tuples, optional

  List of condition names specific to each bar of the graph. Different from the conditions expressed in the filter parameter, which are global, these conditions are specific to one bar. Ech condition name, different from the filter parameter is a path to a condition to be checked, e.g. (‘topology’, ‘name’). Values to be matched for this conditions are specified in ycondvals. This list must be as long as the number of bars to plot. If not specified, all bars are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• ycondvals : list of values, optional

  List of values that the conditions of ycondnames must meet. This list must be as long as the number of bars to plot. If not specified, all bars are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• placement : (grouped | stacked | [x, y, …])

  Defines how to place bars in the plot. If grouped, defaults, all bars for a specific xval are grouped next to each other, if stacked, they are plot on top of each other. It is also possible to specify a custom grouped+stacked placement with a list of integers, in which the number of items is the number of columns and the actual value of an items is the number of metrics stacked on the column. For example [4,2,3] means plotting 4 + 2 + 3 = 9 metrics: 4 stacked in the first column, 2 stacked on the second and 3 stacked on the third If True, draw all bars of a group stacked on top of each other. Default value is False.

• group_width : float, default: 0.4

  Width of a group of bars

• bar_color : dict, optional

  Dictionary mapping each value of yvals with a bar color

• bar_hatch : dict, optional

  Dictionary mapping each value of yvals with a bar hatch. If set to None all bars will be plotted without hatch. If not set, hatches will be plotted randomly

• legend : dict, optional

  Dictionary mapping each value of yvals with a legend label. If not specified, it is not plotted. If you wish to plot it with the name of the line, set it to put yvals or ymetrics, depending on which one is used

• legend_loc : str, optional

  Legend location, e.g. ‘upper left’

• legend_args : dict, optional

  Optional legend arguments, such as ncol

• plotempty : bool, optional

  If True, plot and save graph even if empty. Default is True

• ymax: float, optional

  The upper limit of the y axis. If not specified, it is automatically selected by Matplotlib

plot_cdf(resultset, desc, filename, plotdir)

Plot a CDF with characteristics described in the plot descriptor out of the data contained in the resultset and save the plot in given directory.

Parameters:

rs : ResultSet

Result set

desc : dict

The plot descriptor (more info below)

filename : str

The name used to save the file. The file format is determined by the extension of the file. For example, if this filename is ‘foo.pdf’, the file will be saved in pdf format.

plotdir : str

The directory in which the plot will be saved.

Notes

The plot descriptor is a dictionary with a set of values that describe how to make the plot.

The dictionary can contain the following keys:

• title : str, optional.

  The title of the graph

• xlabel : str, optional

  The x label

• ylabel : str, optional

  The y label. The default value is ‘Cumulative probability’

• confidence : float, optional

  The confidence used to plot error bars. Default value is 0.95

• metric : list

  A list of values representing the metric to plot. These values are the path to identify a specific metric into an entry of a result set. Normally, it is a 2-value list where the first value is the name of the collector which measured the metric and the second value is the metric name. The metric must be a CDF. Example values could be [‘LATENCY’, ‘CDF’].

• filter : dict, optional

  A dictionary of values to filter in the resultset. Example: {‘network_cache’: 0.004, ‘topology_name’: ‘GEANT’} If not specified or None, no filtering is executed on the results and possibly heterogeneous results may be plotted together

• ymetrics : list of tuples

  List of metrics to be shown on the graph. The i-th metric of the list is the metric that the i-th line on the graph will represent. If all lines are for the same metric, then all elements of the list are equal. Each single metric (i.e. each element of the list) is a tuple modeling the path to identify a specific metric into an entry of a result set. Normally, it is a 2-value list where the first value is the name of the collector which measured the metric and the second value is the metric name. Example values could be (‘CACHE_HIT_RATIO’, ‘MEAN’), (‘LINK_LOAD’, ‘MEAN_INTERNAL’) or (‘LATENCY’, ‘MEAN’). For example, if in a graph of N lines all lines of the graph show mean latency, then ymetrics = [(‘LATENCY’, ‘MEAN’)]*5.

• ycondnames : list of tuples, optional

  List of condition names specific to each line of the graph. Different from the conditions expressed in the filter parameter, which are global, these conditions are specific to one bar. Ech condition name, different from the filter parameter is a path to a condition to be checked, e.g. (‘topology’, ‘name’). Values to be matched for this conditions are specified in ycondvals. This list must be as long as the number of lines to plot. If not specified, all lines are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• ycondvals : list of tuples, optional

  List of values that the conditions of ycondnames must meet. This list must be as long as the number of lines to plot. If not specified, all lines are filtered by the conditions of filter parameter only, but in this case all ymetrics should be different.

• xscale : str, optional

  The scale of x axis. Options allowed are ‘linear’ and ‘log’. Default value is ‘linear’

• yscale : str, optional

  The scale of y axis. Options allowed are ‘linear’ and ‘log’. Default value is ‘linear’

• step : bool, optional

  If True draws the CDF with steps. Default value is True

• line_style : dict, optional

  Dictionary mapping each value of yvals with a line style

• legend : dict, optional

  Dictionary mapping each value of yvals with a legend label. If not specified, it is not plotted. If you wish to plot it with the name of the line, set it to put yvals or ymetrics, depending on which one is used

• legend_loc : str, optional

  Legend location, e.g. ‘upper left’

• legend_args : dict, optional

  Optional legend arguments, such as ncol

• plotempty : bool, optional

  If True, plot and save graph even if empty. Default is True

icarus.results.readwrite module

Functions for reading and writing results

class ResultSet(attr=None)

Bases: object

This class can be used to store results from different experiments, accessed and filtered.

A result set is basically a list of results, one per each experiment. Each entry of the resultset is a 2-tuple referring to a single experiment. In this 2-tuple:

• the first element is a tree with all parameters of the experiment
• the second element is a tree with all results of the experiment

All operations that write data are thread-safe so that this object can be shared by different processes.

Methods

add(parameters, results)	Add a result to the result set.
dump()	Dump all results in a list
filter(condition)	Return subset of results matching specific conditions
json([indent])	Return a JSON representation of the resultset
prettyprint()	Return a human-readable text representation of the resultset.

add(parameters, results)

Add a result to the result set.

Parameters:

parameters : Tree

Tree of experiment parameters

results : Tree

Tree of experiment results

Notes

If parameters and results are dictionaries, this method will attempt to convert them to trees and storing them anyway. It is necessary that parameters and results are saved as trees so that plotting functions can search correctly in them.

dump()

Dump all results in a list

Returns:

results : list

A list of 2-value tuples where the first value is the dictionary of experiment parameters and the second value is the dictionary of experiment results.

filter(condition)

Return subset of results matching specific conditions

Parameters:

condition : dict

Dictionary listing all parameters and values to be matched in the results set. Each parameter, i.e., each key of the dictionary must be an iterable object containing the path in the parameters tree to the required parameter

Returns:

filtered_results : ResultSet

List of 2-tuples of filtered results, where the first element is a tree of all experiment parameters and the second value is a tree with experiment results.

json(indent=None)

Return a JSON representation of the resultset

Parameters:

indent : int, optional

If non-negative, pretty print the output with specified indentation

Returns:

json : str

String containing the JSON representation of the object

prettyprint()

Return a human-readable text representation of the resultset.

write_results_pickle(results, path)

Write a resultset to a pickle file

Parameters:

results : ResultSet

The set of results

path : str

The path of the file to which write

read_results_pickle(path)

Reads a resultset from a pickle file.

Parameters:

path : str

The file path from which results are read

Returns:

results : ResultSet

The read result set

icarus.results.visualize module

Functions for visualizing results on graphs of topologies

draw_stack_deployment(topology, filename, plotdir)

Draw a topology with different node colors according to stack

Parameters:

topology : Topology

The topology to draw

plotdir : string

The directory onto which draw plots

filename : string

The name of the image file to save

draw_network_load(topology, result, filename, plotdir)

Draw topology with node colors according to stack and node size and link color according to server/cache hits and link loads.

Nodes are colored according to COLORMAP. Edge are colored on a blue-red scale where blue means min link load and red means max link load. Sources and caches have variable size proportional to their hit ratios.

Parameters:

topology : Topology

The topology to draw

result : Tree

The tree representing the specific experiment result from which metric are read

plotdir : string

The directory onto which draw plots

filename : string

The name of the image file to save

Module contents

This package contains the code in charge of processing experiment results.