Appendix: Python API for Chart Scripts¶

This chapter describes the API of the Python modules available for chart scripts. These modules are available in the Analysis Tool in the IDE, in opp_charttool, and may also be used in standalone Python scripts.

Some conventional import aliases appear in code fragments throughout this chapter, such as np for NumPy and pd for Pandas.

Modules¶

Module omnetpp.scave.results¶

Provides access to simulation results loaded from OMNeT++ result files (.sca, .vec). The results are returned as Pandas DataFrame’s of various formats.

The module can be used in several ways, depending on the environment it is run in, and on whether the set of result files to query are specified in a stateful or a stateless way:

1. Inside a chart script in the Analysis Tool in the Simulation IDE. In that mode, the set of result files to take as input are defined on the “Inputs” page of the editor. The get_results(), get_scalars() and similar methods are invoked with a filter string as first argument to select the appropriate subset of results from the result files. Note that this mode of operation is stateful: The state is set up appropriately by the IDE before the chart script is run.

   A similar thing happens when charts in an analysis (.anf) file are run from within opp_charttool: the tool sets up the module state before running the chart script, so that the getter methods invoked with a filter string will return result from the set of result files saved as “inputs” in the anf file.

2. Standalone stateful mode. In order to use get_results(), get_scalars() and similar methods with a filter string, the module needs to be configured via the set_inputs()/add_inputs() functions to tell it the set of result files to use as input for the queries. (Doing so is analogous to filling in the “Inputs” page in the IDE).

3. Stateless mode. It is possible to load the result files (in whole or a subset of results in them) into memory as a “raw” DataFrame using read_result_files(), and then use get_scalars(), get_vectors() and other getter functions with the dataframe as their first argument to produce DataFrame’s of other formats. Note that when going this route, a filter string can be specified to read_result_files() but not to the getter methods. However, Pandas already provides several ways for filtering the rows of a dataframe, for example by indexing with logical operators on columns, or using the df.query(), df.pipe() or df.apply() methods.

Filter expressions

The filter_or_dataframe parameters in all functions must contain either a filter string, or a “raw” dataframe produced by read_result_files(). When it contains a filter string, the function operates on the set of result files configured earlier (see stateful mode above).

Filter strings of all functions have the same syntax. It is always evaluated independently on every loaded result item or metadata entry, and its value determines whether the given item or piece of metadata is included in the returned DataFrame.

A filter expression is composed of terms that can be combined with the AND, OR, NOT operators, and parentheses. A term filters for the value of some property of the item, and has the form <property> =~<pattern>, or simply <pattern>. The latter is equivalent to name =~<pattern>.

The following properties are available:

• name: Name of the result or item.

• module: Full path of the result’s module.

• type: Type of the item. Value is one of: scalar, vector, parameter, histogram, statistics.

• isfield: true is the item is a synthetic scalar that represents a field of statistic or a vector, false if not.

• file: File name of the result or item.

• run: Unique run ID of the run that contains the result or item.

• runattr:<name>: Run attribute of the run that contains the result or item. Example: runattr:measurement.

• attr:<name>: Attribute of the result. Example: attr:unit.

• itervar:<name>: Iteration variable of the run that contains the result or item. Example: itervar:numHosts.

• config:<key>: Configuration key of the run that contains the result or item. Example: config:sim-time-limit, config:**.sendIaTime.

Patterns may contain the following wildcards:

• ? matches any character except ’.’

• * matches zero or more characters except ’.’

• ** matches zero or more characters (any character)

• {a-z} matches a character in range a-z

• {^a-z} matches a character not in range a-z

• {32..255} any number (i.e. sequence of digits) in range 32..255 (e.g. 99)

• [32..255] any number in square brackets in range 32..255 (e.g. [99])

• \ takes away the special meaning of the subsequent character

Patterns only need to be surrounded with quotes if they contain whitespace or other characters that would cause ambiguity in parsing the expression.

Example: module =~"**.host*" AND (name =~"pkSent*" OR name =~"pkRecvd*")

The “raw” dataframe format

This dataframe format is a central one, because the content of “raw” dataframes correspond exactly to the content result files, i.e. it is possible to convert between result files and the “raw” dataframe format without data loss. The “raw” dataframe format also corresponds in a one-to-one manner to the “CSV-R” export format of the Simulation IDE and opp_scavetool.

The outputs of the get_results() and read_result_files() functions are in this format, and the dataframes that can be passed as input into certain query functions (get_scalars(), get_vectors(), get_runs(), etc.) are also expected in the same format.

Columns of the DataFrame:

• runID (string): Identifies the simulation run

• type (string): Row type, one of the following: scalar, vector, statistics, histogram, runattr, itervar, param, attr

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): Name of the result item (scalar, statistic, histogram or vector)

• attrname (string): Name of the run attribute or result item attribute (in the latter case, the module and name columns identify the result item the attribute belongs to)

• attrvalue (string): Value of run and result item attributes, iteration variables, saved ini param settings (runattr, attr, itervar, param)

• value (double or string): Output scalar or parameter value

• count, sumweights, mean, min, max, stddev (double): Fields of the statistics or histogram

• binedges, binvalues (np.array): Histogram bin edges and bin values. len(binedges)==len(binvalues)+1

• underflows, overflows (double): Sum of weights (or counts) of underflown and overflown samples of histograms

• vectime, vecvalue (np.array): Output vector time and value arrays

Requesting metadata columns

Several query functions have the include_attrs, include_runattrs, include_itervars, include_param_assignments, and include_config_entries boolean options. When such an option is turned on, it will add extra columns into the returned DataFrame, one for each result attribute, run attribute, iteration variable, etc. When there is a name clash among items of different types, the column name for the second one will be modified by adding its type after an underscore (_runattr, _itervar, _config, _param).

• include_attrs: Adds the attributes of the result in question

• include_runattrs: Adds the run attributes of the (result’s) run

• include_itervars: Adds the iteration variables of the (result’s) run

• include_config_entries: Adds all configuration entries of the (result’s) run, including parameter parameter assignments and per-object configuration options. If this option is turned on, include_param_assignments has no effect.

• include_param_assignments: Adds the configuration entries that set module or channel parameters. This is a subset of the entries added by include_config_entries.

Note that values in metadata columns are generally strings (with missing values represented as None or nan). The Pandas to_numeric() function or utils.to_numeric() can be used to convert values to float or int where needed.

convert_to_base_unit_func()¶

Converts results with units in the passed DataFrame to their base units in-place. The DataFrame needs to have a “unit” column - which is updated to the base unit. By default, the following columns are converted: “value”, “min”, “max”, “mean”, “stddev”, “vecvalue”, “binedges” Every converted column must contain either all numbers or all np.ndarray instances.

This works for example on the DataFrames returned by get_scalars, get_vectors, get_statistics, and get_histograms in omnetpp.scave, but NOT on those returned by get_results.

Class ResultQueryError¶

get_serial()¶

Returns an integer that is incremented every time the set of loaded results changes, typically as a result of the IDE loading, reloading or unloading a scalar or vector result file. The serial can be used for invalidating cached intermediate results when their input changes.

set_inputs()¶

Specifies the set of simulation result files (.vec, .sca) to use as input for the query functions. The argument may be a single string or a list of strings. Each string is interpreted as a file or directory path and may also contain wildcards. In addition to ? and *, ** (which is able to match several directory levels) is also accepted as a wildcard. If a path corresponds to a directory, it is interpreted as [ "<dir>/**/*.sca", "<dir>/**/*.vec" ], that is, all result files will be loaded from that directory and recursively all its subdirectories.

Examples: set_inputs("results/"), set_inputs("results/**.sca"), set_inputs(["config1/*.sca", *config2/*.sca"]).

add_inputs()¶

Appends to the set of simulation result files (.vec, .sca) to use as input for the query functions. The argument may be a single string or a list of strings. Each string is interpreted as a file or directory path and may also contain wildcards (?, *, **). See set_inputs() for more details.

read_result_files()¶

Loads the simulation result files specified in the first argument filenames and returns the filtered set of results and metadata as a Pandas DataFrame.

The filenames argument specifies the set of simulation result files (.vec, .sca) to load. The argument may be a single string or a list of strings. Each string is interpreted as a file or directory path and may also contain wildcards (?, *, **). See set_inputs() for more details on this format.

It is possible to limit the set of results to return by specifying a filter expression and vector start/end times.

Parameters:

• filenames (string or list of strings): Specifies the result files to load.

• filter_expression (string): The filter expression to select the desired items to load. Example: module =~"*host*" AND name =~"numPacket*"

• include_fields_as_scalars (bool): Optional. If True, the fields of statistics and histograms (:min, :mean, etc.) are also returned as synthetic scalars.

• vector_start_time, vector_end_time (double): Optional time limits to trim the data of vector type results. The unit is seconds, the interval is left-closed, right-open.

Returns: a DataFrame in the “raw” format (see the corresponding section of the module documentation for details).

get_results()¶

Returns a filtered set of results and metadata in a Pandas DataFrame. The items can be any type, even mixed together in a single DataFrame. They are selected from the complete set of data referenced by the analysis file (.anf), including only those for which the given filter_or_dataframe evaluates to True.

Parameters:

• filter_or_dataframe (string or dataframe): The filter expression to select the desired items from the inputs, or a dataframe in the “raw” format. Example: module =~"*host*" AND name =~"numPacket*"

• row_types: Optional. When given, filters the returned rows by type. Should be a unique list, containing any number of these strings: "runattr", "itervar", "config", "scalar", "vector", "statistic", "histogram", "param", "attr"

• omit_unused_columns (bool): Optional. If True, all columns that would only contain None are removed from the returned DataFrame

• include_fields_as_scalars (bool): Optional. If True, the fields of statistics and histograms (:min, :mean, etc.) are also returned as synthetic scalars.

• start_time, end_time (double): Optional time limits to trim the data of vector type results. The unit is seconds, the interval is left-closed, right-open.

Returns: a DataFrame in the “raw” format (see the corresponding section of the module documentation for details).

get_runs()¶

Returns a filtered list of runs, identified by their run ID.

Parameters:

• filter_or_dataframe (string or dataframe): The filter expression to select the desired run from the inputs, or a dataframe in the “raw” format (e.g. one returned by read_result_files()). Example: runattr:network =~"Aloha" AND config:Aloha.slotTime =~0

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the result, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• Additional metadata items (run attributes, iteration variables, etc.), as requested

get_runattrs()¶

Returns a filtered list of run attributes.

The set of run attributes is fixed: configname, datetime, experiment, inifile, iterationvars, iterationvarsf, measurement, network, processid, repetition, replication, resultdir, runnumber, seedset.

Parameters:

• filter_or_dataframe (string or dataframe): The filter expression to select the desired run attributes from the inputs, or a dataframe in the “raw” format. Example: name =~*date* AND config:Aloha.slotTime =~0

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the result, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• name (string): The name of the run attribute

• value (string): The value of the run attribute

• Additional metadata items (run attributes, iteration variables, etc.)

get_itervars()¶

Returns a filtered list of iteration variables.

Parameters:

• filter_or_dataframe (string or dataframe): The filter expression to select the desired iteration variables from the inputs, or a dataframe in the “raw” format. Example: name =~iaMean AND config:Aloha.slotTime =~0

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the result, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• name (string): The name of the iteration variable

• value (string): The value of the iteration variable.

• Additional metadata items (run attributes, iteration variables, etc.), as requested

get_scalars()¶

Returns a filtered list of scalar results.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired scalars, or a dataframe in the “raw” format. Example: name =~"channelUtilization*" AND runattr:replication =~"#0"

• include_attrs (bool): Optional. When set to True, result attributes (like unit for example) are appended to the DataFrame, pivoted into columns.

• include_fields (bool): Optional. If True, the fields of statistics and histograms (:min, :mean, etc.) are also returned as synthetic scalars.

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the DataFrame, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

• convert_to_base_unit (bool): Optional. If True, the values of the scalars are converted to their base unit (e.g. ms to s, mW to W, etc.)

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): The name of the scalar

• value (double): The value of the scalar

• Additional metadata items (result attributes, run attributes, iteration variables, etc.), as requested

get_parameters()¶

Returns a filtered list of parameters - actually computed values of individual cPar instances in the fully built network.

Parameters are considered “pseudo-results”, similar to scalars - except their values are strings. Even though they act mostly as input to the actual simulation run, the actually assigned value of individual cPar instances is valuable information, as it is the result of the network setup process. For example, even if a parameter is set up as an expression like normal(3, 0.4) from omnetpp.ini, the returned DataFrame will contain the single concrete value picked for every instance of the parameter.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired parameters, or a dataframe in the “raw” format. Example: name =~"x" AND module =~Aloha.server

• include_attrs (bool): Optional. When set to True, result attributes (like unit) are appended to the DataFrame, pivoted into columns.

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the DataFrame, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): The name of the parameter

• value (string): The value of the parameter.

• Additional metadata items (result attributes, run attributes, iteration variables, etc.), as requested

get_vectors()¶

Returns a filtered list of vector results.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired vectors, or a dataframe in the “raw” format. Example: name =~"radioState*" AND runattr:replication =~"#0"

• include_attrs (bool): Optional. When set to True, result attributes (like unit or source) are appended to the DataFrame, pivoted into columns.

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the DataFrame, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

• start_time, end_time (double): Optional time limits to trim the data of vector type results. The unit is seconds, both the vectime and vecvalue arrays will be affected, the interval is left-closed, right-open.

• convert_to_base_unit (bool): Optional. If True, the values in the vectors are converted to their base unit (e.g. ms to s, mW to W, etc.)

• omit_empty_vectors (bool): Optional. If True, empty vectors are discarded from the output.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): The name of the vector

• vectime, vecvalue (np.array): The simulation times and the corresponding values in the vector

• Additional metadata items (result attributes, run attributes, iteration variables, etc.), as requested

get_statistics()¶

Returns a filtered list of statistics results.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired statistics, or a dataframe in the “raw” format. Example: name =~"collisionLength:stat" AND itervar:iaMean =~"5"

• include_attrs (bool): Optional. When set to True, result attributes (like unit or source) are appended to the DataFrame, pivoted into columns.

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the DataFrame, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

• convert_to_base_unit (bool): Optional. If True, some fields of the statistics (in the min, max, mean, and stddev columns) are converted to their base unit (e.g. ms to s, mW to W, etc.)

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): The name of the statistic

• count, sumweights, mean, stddev, min, max (double): The characteristic mathematical properties of the statistics result

• Additional metadata items (result attributes, run attributes, iteration variables, etc.), as requested

get_histograms()¶

Returns a filtered list of histogram results.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired histograms, or a dataframe in the “raw” format. Example: name =~"collisionMultiplicity:histogram" AND itervar:iaMean =~"2"

• include_attrs (bool): Optional. When set to True, result attributes (like unit or source for example) are appended to the DataFrame, pivoted into columns.

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the DataFrame, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

• convert_to_base_unit (bool): Optional. If True, some fields of the histograms (in the min, max, mean, stddev, and binedges columns) are converted to their base unit (e.g. ms to s, mW to W, etc.)

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• module (string): Hierarchical name (a.k.a. full path) of the module that recorded the result item

• name (string): The name of the vector

• count, sumweights, mean, stddev, min, max (double): The characteristic mathematical properties of the histogram

• binedges, binvalues (np.array): The histogram edge locations and the weighted sum of the collected samples in each bin. len(binedges) == len(binvalues) + 1

• underflows, overflows (double): The weighted sum of the samples that fell outside of the histogram bin range in the two directions

• Additional metadata items (result attributes, run attributes, iteration variables, etc.), as requested

get_config_entries()¶

Returns a filtered list of config entries. That is: parameter assignment patterns; and global and per-object config options.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired config entries, or a dataframe in the “raw” format. Example: name =~sim-time-limit AND itervar:numHosts =~10

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the result, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• name (string): The name of the config entry

• value (string): The value of the config entry

• Additional metadata items (run attributes, iteration variables, etc.), as requested

get_param_assignments()¶

Returns a filtered list of parameter assignment patterns. The result is a subset of what get_config_entries would return with the same arguments.

Parameters:

• filter_or_dataframe (string): The filter expression to select the desired parameter assignments, or a dataframe in the “raw” format. Example: name =~**.flowID AND itervar:numHosts =~10

• include_runattrs, include_itervars, include_param_assignments, include_config_entries (bool): Optional. When set to True, additional pieces of metadata about the run is appended to the result, pivoted into columns. See the “Metadata columns” section of the module documentation for details.

Columns of the returned DataFrame:

• runID (string): Identifies the simulation run

• name (string): The parameter assignment pattern

• value (string): The assigned value

• Additional metadata items (run attributes, iteration variables, etc.), as requested

Module omnetpp.scave.chart¶

Provides access to the properties of the current chart for the chart script.

Note that this module is stateful. It is set up appropriately by the OMNeT++ IDE or opp_charttool before the chart script is run.

Class ChartScriptError¶

Raised by chart scripts when they encounter an error. A message parameter can be passed to the constructor, which will be displayed on the plot area in the IDE.

get_properties()¶

Returns the currently set properties of the chart as a dict whose keys and values are both strings.

get_property()¶

Returns the value of a single property of the chart, or None if there is no property with the given name (key) set on the chart.

get_name()¶

Returns the name of the chart as a string.

get_chart_type()¶

Returns the chart type, which is one of the strings “BAR”, “LINE”, “HISTOGRAM”, and “MATPLOTLIB”.

is_native_chart()¶

Returns True if this chart uses the IDE’s built-in plotting widgets.

set_suggested_chart_name()¶

Sets a proposed name for the chart. The IDE may offer this name to the user when saving the chart.

set_observed_column_names()¶

Sets the DataFrame column names observed during the chart script. The IDE may use them for content assist when the user edits the legend format string.

Module omnetpp.scave.ideplot¶

This module is the interface for displaying plots using the IDE’s native (non-Matplotlib) plotting widgets from chart scripts. The API is intentionally very close to matplotlib.pyplot: most functions and the parameters they accept are a subset of pyplot’s interface. If one restricts themselves to a subset of Matplotlib’s functionality, switching between omnetpp.scave.ideplot and matplotlib.pyplot in a chart script may be as simple as much as editing the import statement.

When the API is used outside the context of a native plotting widget (such as during the run of opp_charttool, or in IDE during image export), the functions are emulated with Matplotlib.

Note that this module is stateful. It is set up appropriately by the OMNeT++ IDE or opp_charttool before the chart script is run.

is_native_plot()¶

Returns True if the script is running in the context of a native plotting widget, and False otherwise.

plot()¶

Plot ys versus xs as lines and/or markers. Call plot multiple times to plot multiple sets of data.

Parameters:

• xs, ys (array-like or scalar): The horizontal / vertical coordinates of the data points.

• key (string): Identifies the series in the native plot widget.

• label (string): Series label for the legend

• drawstyle (string): Matplotlib draw style (’default’, ’steps’, ’steps-pre’, ’steps-mid’, ’steps-post’)

• linestyle (string): Matplotlib line style (’-’, ’–’, ’-.’, ’:’, etc)

• linewidth (float): Line width in pixels

• color (string): Matplotlib color name or abbreviation (’b’ for blue, ’g’ for green, etc.)

• marker (string): Matplotlib marker name (’.’, ’,’, ’o’, ’x’, ’+’, etc.)

• markersize (float): Size of markers in pixels.

hist()¶

Make a histogram plot. This function adds one histogram to the bar plot; make multiple calls to add multiple histograms.

Parameters:

• x (array-like): Input values.

• bins (array-like): Bin edges, including the left edge of the first bin and the right edge of the last bin.

• key (string): Identifies the series in the native plot widget.

• density (bool): See mpl.hist().

• weights (array-like): Weights.

• cumulative (bool): See mpl.hist().

• bottom (float): Location of the bottom baseline for bins.

• histtype (string): Whether to fill the area under the plot. Accepted values are ’step’ and ’stepfilled’.

• color (string): Matplotlib color name or abbreviation (’b’ for blue, ’g’ for green, etc.)

• label (string): Series label for the legend

• linewidth (float): Line width in pixels

• underflows, overflows: Number of values / sum of weights outside the histogram bins in both directions.

• minvalue, maxvalue: The minimum and maximum value, or nan if unknown.

Restrictions:

1. Overflow bin data (minvalue, maxvalue, underflows, and overflows) is not accepted by pyplot.hist().

2. The native plot widget only accepts a precomputed histogram (using the trick documented for pyplot.hist())

bar()¶

Make a bar plot. This function adds one series to the bar plot; make multiple calls to add multiple series.

The bars are positioned at x with the given alignment. Their dimensions are given by width and height. The vertical baseline is bottom (default 0).

Each of x, height, width, and bottom may either be a scalar applying to all bars, or it may be a sequence of length N providing a separate value for each bar.

Parameters:

• x (sequence of scalars): The x coordinates of the bars.

• height (scalar or sequence of scalars): The height(s) of the bars.

• width (scalar or array-like): The width(s) of the bars.

• key (string): Identifies the series in the native plot widget.

• label (string): The label of the series the bars represent.

• color (string): The fill color of the bars.

• edgecolor (string): The edge color of the bars.

The native plot implementation has the following restrictions:

• widths are automatic (the parameter is ignored)

• x coordinates are automatic (values are ignored)

• height must be a sequence (cannot be a scalar)

• in multiple calls to bar(), the lengths of the height sequence must be equal (i.e. all series must have the same number of values)

• the default color is grey (Matplotlib assigns a different color to each series)

set_property()¶

Sets one property of the native plot widget to the given value. When invoked outside the context of a native plot widget, the function does nothing.

Parameters:

• key (string): Name of the property.

• value (string): The value to set. If any other type other than a string is passed in, it will be converted to a string.

set_properties()¶

Sets several properties of the native plot widget. It is functionally equivalent to repeatedly calling set_property with the entries of the props dictionary. When invoked outside the context of a native plot widget (TODO?), the function does nothing.

Parameters:

• props (dict): The properties to set.

get_supported_property_keys()¶

Returns the list of property names that the native plot widget supports, such as ’Plot.Title’, ’X.Axis.Max’, and ’Legend.Display’, among many others.

Note: This method has no equivalent in pyplot. When the script runs outside the IDE (TODO?), the method returns an empty list.

set_warning()¶

Displays the given warning text in the plot.

title()¶

Sets the plot title to the given string.

xlabel()¶

Sets the label of the X-axis to the given string.

ylabel()¶

Sets the label of the Y-axis to the given string.

xlim()¶

Sets the limits of the X-axis.

Parameters:

• left (float): The left xlim in data coordinates. Passing None leaves the limit unchanged.

• right (float): The right xlim in data coordinates. Passing None leaves the limit unchanged.

ylim()¶

Sets the limits of the Y-axis.

Parameters:

• bottom (float): The bottom ylim in data coordinates. Passing None leaves the limit unchanged.

• top (float): The top ylim in data coordinates. Passing None leaves the limit unchanged.

xscale()¶

Sets the scale of the X-axis. Possible values are ’linear’ and ’log’.

yscale()¶

Sets the scale of the Y-axis.

xticks()¶

Sets the current tick locations and labels of the x-axis.

Parameters:

• ticks (array_like): A list of positions at which ticks should be placed. You can pass an empty list to disable xticks.

• labels (array_like): A list of explicit labels to place at the given locs.

• rotation (float): Label rotation in degrees.

grid()¶

Configure the grid lines.

Parameters:

• b (bool or ``None``): Whether to show the grid lines.

• which (’major’, ’minor’, or ’both’): The grid lines to apply the changes to.

legend()¶

Place a legend on the axes.

Parameters:

• show (bool or ``None``): Whether to show the legend. TODO does pyplot have this?

• frameon (bool or ``None``): Control whether the legend should be drawn on a patch (frame). Default is None, which will take the value from the resource file.

• loc (string or ``None``): The location of the legend. Possible values are ’best’, ’upper right’, ’upper left’, ’lower left’, ’lower right’, ’right’, ’center left’, ’center right’, ’lower center’, ’upper center’, ’center’ (these are the values supported by Matplotlib), plus additionally ’outside top left’, ’outside top center’, ’outside top right’, ’outside bottom left’, ’outside bottom center’, ’outside bottom right’, ’outside left top’, ’outside left center’, ’outside left bottom’, ’outside right top’, ’outside right center’, ’outside right bottom’.

Module omnetpp.scave.utils¶

A collection of utility function for data manipulation and plotting, built on top of Pandas data frames and the chart and ideplot packages from omnetpp.scave. Functions in this module have been written largely to the needs of the chart templates that ship with the IDE.

There are some functions which are (almost) mandatory elements in a chart script. These are the following.

If you want style settings in the chart dialog to take effect:

• preconfigure_plot()

• postconfigure_plot()

If you want image/data export to work:

• export_image_if_needed()

• export_data_if_needed()

set_verbose_export()¶

Sets the verbose_export flag, which controls whether the export_image_if_needed() and export_data_if_needed() functions will print an “Exported <filename>” message after the export. The default setting is False.

convert_to_base_unit()¶

Converts results with units in the passed DataFrame to their base units in-place. The DataFrame needs to have a “unit” column - which is updated to the base unit. By default, the following columns are converted: “value”, “min”, “max”, “mean”, “stddev”, “vecvalue”, “binedges” Every converted column must contain either all numbers or all np.ndarray instances.

This works for example on the DataFrames returned by get_scalars, get_vectors, get_statistics, and get_histograms in omnetpp.scave, but NOT on those returned by get_results.

make_legend_label()¶

Produces a reasonably good label text (to be used in a chart legend) for a result row from a DataFrame. The legend label is produced as follows.

First, a base version of the legend label is produced:

1. If the DataFrame contains a legend column, its content is used.

2. Otherwise, if there is a legend_format property, it is used as a format string for producing the legend label. The format string may contain references to other columns of the DataFrame in the “$name” or “${name}” form.

3. Otherwise, the legend label is concatenated from the columns listed in legend_cols, a list whose contents are usually produced using the extract_label_columns() function.

Second, if there is a legend_replacements property, it defines a series of replacements to be done on the legend labels. legend_replacements is expected to be a multi-line string, where each line contains a replacement. A replacement line can be a plain substring replacement in the findstring --> replacement syntax, or a regex replacement in the sed-style /findregex/replacement/ syntax. With the latter, “findregex” should be a valid regular expression, and “replacement” a string that may contain match group references (”\1”, “\2”, etc.). If “/” is unsuitable as separator, other characters may also be used; common choices are “|” and “!”. Similar to the legend_format property, “findstring”, “findregex” and “replacement” may contain column references in the “$name” or “${name}” form. Use “$$” to mean a single “$” sign. Also note that “findregex” may still end in “$” to match the end of the string; it won’t collide with column references.

Parameters:

• row (named tuple): The row from the dataframe.

• props (dict): The properties that control how the legend is produced.

• legend_cols (list of strings): The names of columns chosen for the legend.

Properties that affect the generated legend label:

• legend_automatic (string): If true, do not use the legend format string even if present.

• legend_format (string): A format string to produce the label from columns.

• legend_replacements (string): A multi-line string of regex find/replace operations to modify the label.

Possible errors:

• References to nonexistent columns in legend_format or legend_replacements (KeyError)

• Malformed regex in the “findstring” parts of legend_replacements (re.error)

• Invalid group reference in the “replacement” parts of legend_replacements (re.error)

add_legend_labels()¶

Adds a legend column to the dataframe. In the dataframe, each row is expected to represent an item to be plotted. The legend label will be computed for each item individually by the make_legend_label() function.

Parameters:

• df: The dataframe.

• props (dict): The properties.

Notable properties that affect the legend generation: See the documentation of make_legend_label().

sort_rows_by_legend()¶

Sorts the rows of the dataframe, where each row represents an item to be plotted. The dataframe is expected to have a legend column, which will serve as the basis for ordering.

Ordering is based on two lists of regexes, one for primary ordering and another one for secondary ordering. Each item’s rank will be determined by the index of the first regex the item’s legend matches. After sorting, items matching the first regex will appear at the top, those matching the second regex will be placed below, and so forth. Case-sensitive substring match is used.

Parameters:

• df: The dataframe.

• props (dict): The properties.

Notable properties that affect the ordering:

• ordering_regex_list: Regex list for primary ordering, as multi-line string (one regex per line).

• secondary_ordering_regex_list: Regex list for secondary ordering, as multi-line string (one regex per line).

• sorting: Boolean to determine if sorting should be applied

plot_bars()¶

Creates a bar plot from the dataframe, with styling and additional input coming from the properties. Each row in the dataframe defines a series.

Group names (displayed on the x axis) are taken from the column index.

Error bars can be drawn by providing an extra dataframe of identical dimensions as the main one. Error bars will protrude by the values in the errors dataframe both up and down (i.e. range is 2x error).

To make the legend labels customizable, an extra dataframe can be provided, which contains any columns of metadata for each series.

Colors are assigned automatically. The cycle_seed property allows you to select other combinations if the default one is not suitable.

Parameters:

• df: The dataframe.

• errors_df: Dataframe with the errors (in y axis units).

• meta_df: Dataframe with the metadata about each series.

• props (dict): The properties.

• sort (bool): Whether to sort the values by the column and row indices (which are the labels of the bar series and groups).

Notable properties that affect the plot:

• baseline: The y value at which the x axis is drawn.

• bar_placement: Selects the arrangement of bars: aligned, overlap, stacked, etc.

• xlabel_rotation: Amount of counter-clockwise rotation of x axis labels a.k.a. group names, in degrees.

• title: Plot title (autocomputed if missing).

• cycle_seed: Alters the sequence in which colors are assigned to series.

• unit: If present, it is required to be the same for all series, and it will be used in the automatic y axis label.

plot_vectors()¶

Creates a line plot from the dataframe, with styling and additional input coming from the properties. Each row in the dataframe defines a series.

Colors and markers are assigned automatically. The cycle_seed property allows you to select other combinations if the default one is not suitable.

A function to produce the legend labels can be passed in. By default, make_legend_label() is used, which offers many ways to influence the legend via dataframe columns and chart properties. In the absence of more specified settings, the legend is normally computed from columns which best differentiate among the vectors.

Parameters:

• df: The dataframe.

• props (dict): The properties.

• legend_func (function): The function to produce custom legend labels. See utils.make_legend_label() for prototype and semantics.

• sort (bool): Whether to sort the vectors by the columns used for the legend (before applying legend_func, for backwards bug-compatibility).

Columns of the dataframe:

• vectime, vecvalue (Numpy ``ndarray``’s of matching sizes): the x and y coordinates for the plot

• interpolationmode (str, optional): this column normally comes from a result attribute, and determines how the points will be connected

• legend (optional): legend label for the series; if missing, legend labels are derived from other columns

• name, title, module, etc. (optional): provide input for the legend

Notable properties that affect the plot:

• title: plot title (autocomputed if missing)

• drawstyle: Matplotlib draw style; if present, it overrides the draw style derived from interpolationmode.

• linestyle, linecolor, linewidth, marker, markersize: styling

• cycle_seed: Alters the sequence in which colors and markers are assigned to series.

• unit: If present, it is required to be the same for all series, and it will be used in the automatic y axis label.

plot_vectors_separate()¶

This is very similar to plot_vectors, with identical usage. The only difference is in the end result, where each vector will be plotted in its own separate set of axes (coordinate system), arranged vertically, with a shared X axis during navigation.

plot_histograms()¶

Creates a histogram plot from the dataframe, with styling and additional input coming from the properties. Each row in the dataframe defines a histogram.

Colors are assigned automatically. The cycle_seed property allows you to select other combinations if the default one is not suitable.

A function to produce the legend labels can be passed in. By default, make_legend_label() is used, which offers many ways to influence the legend via dataframe columns and chart properties. In the absence of more specified settings, the legend is normally computed from columns that best differentiate among the histograms.

Parameters:

• df: The dataframe.

• props (dict): The properties.

• legend_func (function): The function to produce custom legend labels. See utils.make_legend_label() for the prototype and semantics.

• sort (bool): Whether to sort the histograms by the columns used for the legend (before applying legend_func, for backward bug-compatibility).

Columns of the dataframe:

• binedges, binvalues (array-like, ``len(binedges)==len(binvalues)+1``): The bin edges and the bin values (count or sum of weights) for the histogram.

• min, max, underflows, overflows (float, optional): The minimum/maximum values, and the bin values for the underflow/overflow bins. These four columns must either be all present or all absent from the dataframe.

• legend (string, optional): Legend label for the series. If missing, legend labels are derived from other columns.

• name, title, module, etc. (optional): Provide input for the legend.

• unit (string, optional): The unit for the X-axis values. If present, it is required to be the same for all series.

Notable properties that affect the plot:

• normalize (bool): If true, normalize the sum of the bin values to 1. If normalize is true (and cumulative is false), the probability density function (PDF) will be displayed.

• cumulative (bool): If true, show each bin as the sum of the previous bin values plus itself. If both normalize and cumulative are true, that results in the cumulative density function (CDF) being displayed.

• show_overflows (bool): If true, show the underflow/overflow bins.

• title: Plot title (autocomputed if missing).

• drawstyle: Selects whether to fill the area below the histogram line.

• linestyle, linecolor, linewidth: Styling.

• cycle_seed: Alters the sequence in which colors and markers are assigned to series.

• xaxis_unit: If present, specifies the unit for the X-axis. If empty string, automatically selects the best unit.

• yaxis_unit: If present, specifies the unit for the Y-axis. If empty string, automatically selects the best unit.

plot_lines()¶

Creates a line plot from the dataframe, with styling and additional input coming from the properties. Each row in the dataframe defines a line.

Colors are assigned automatically. The cycle_seed property allows you to select other combinations if the default one is not suitable.

A function to produce the legend labels can be passed in. By default, make_legend_label() is used, which offers many ways to influence the legend via dataframe columns and chart properties. In the absence of more specified settings, the legend is normally computed from columns that best differentiate among the lines.

Parameters:

• df: The dataframe.

• props (dict): The properties.

• legend_func (function): The function to produce custom legend labels. See utils.make_legend_label() for the prototype and semantics.

• sort (bool): Whether to sort the series by the columns used for the legend (before applying legend_func, for backward bug-compatibility).

Columns of the dataframe:

• x, y (array-like, ``len(x)==len(y)``): The X and Y coordinates of the points.

• error (array-like, ``len(x)==len(y)``, optional): The half lengths of the error bars for each point.

• legend (string, optional): Legend label for the series. If missing, legend labels are derived from other columns.

• name, title, module, etc. (optional): Provide input for the legend.

Notable properties that affect the plot:

• title: Plot title (autocomputed if missing).

• linewidth: Line width.

• marker: Marker style.

• linestyle, linecolor, linewidth: Styling.

• error_style: If error is present, controls how the error is shown. Accepted values: “Error bars”, “Error band”

• cycle_seed: Alters the sequence in which colors and markers are assigned to series.

• unit: If present, it is required to be the same for all series and will be used in the automatic y-axis label.

plot_boxwhiskers()¶

Creates a box and whiskers plot from the dataframe, with styling and additional input coming from the properties. Each row in the dataframe defines one set of a box and two whiskers.

Colors are assigned automatically. The cycle_seed property allows you to select other combinations if the default one is not suitable.

A function to produce the legend labels can be passed in. By default, make_legend_label() is used, which offers many ways to influence the legend via dataframe columns and chart properties. In the absence of more specified settings, the legend is normally computed from columns that best differentiate among the boxes.

Parameters:

• df: The dataframe.

• props (dict): The properties.

• legend_func (function): The function to produce custom legend labels. See utils.make_legend_label() for the prototype and semantics.

• sort (bool): Whether to sort the series by the columns used for the legend (before applying legend_func, for backward bug-compatibility).

Columns of the dataframe:

• min, max, mean, stddev, count (float): The minimum/maximum values, mean, standard deviation, and sample count of the data.

• legend (string, optional): Legend label for the series. If missing, legend labels are derived from other columns.

• name, title, module, etc. (optional): Provide input for the legend.

Notable properties that affect the plot:

• title: Plot title (autocomputed if missing).

• cycle_seed: Alters the sequence in which colors and markers are assigned to series.

• unit: If present, it is required to be the same for all series and will be used in the automatic y-axis label.

customized_box_plot()¶

Generates a customized box-and-whiskers plot based on explicitly specified percentile values. This method is necessary because pyplot.boxplot() insists on computing the stats from the raw data (which we often don’t have) itself.

The data is in the percentiles argument, which should be a list of tuples. One box will be drawn for each tuple. Each tuple contains 6 elements (or 5, because the last one is optional):

(q1_start, q2_start, q3_start, q4_start, q4_end, fliers)

The first five elements have the following meaning:

• q1_start: y coord of bottom whisker cap

• q2_start: y coord of bottom of the box

• q3_start: y coord of median mark

• q4_start: y coord of top of the box

• q4_end: y coord of top whisker cap

The last element, fliers, is a list containing the values of the outlier points.

x coords of the box-and-whiskers plots are automatic.

Parameters:

• percentiles: The list of tuples.

• labels: If provided, the legend labels for the boxes.

• axes: The axes object of the plot.

• redraw: If False, redraw is deferred.

• args, kwargs: Passed to axes.boxplot().

preconfigure_plot()¶

Configures the plot according to the given properties, which normally get their values from settings in the “Configure Chart” dialog. Calling this function before plotting is performed should be a standard part of chart scripts.

A partial list of properties taken into account for native plots:

• property keys understood by the plot widget, see ideplot.get_supported_property_keys()

And for Matplotlib plots:

• plt.style

• properties listed in the matplotlibrc property

• properties prefixed with matplotlibrc.

Parameters:

• props (dict): the properties

postconfigure_plot()¶

Configures the plot according to the given properties, which normally get their values from settings in the “Configure Chart” dialog. Calling this function after plotting is performed should be a standard part of chart scripts.

A partial list of properties taken into account:

• yaxis_title, yaxis_title, xaxis_min, xaxis_max, yaxis_min, yaxis_max, xaxis_log, yaxis_log, legend_show, legend_border, legend_placement, grid_show, grid_density

• properties listed in the plot.properties property

Parameters:

• props (dict): the properties

export_image_if_needed()¶

If a certain property is set, save the plot in the selected image format. Calling this function should be a standard part of chart scripts, as it is what makes the “Export image” functionality of the IDE and opp_charttool work.

Note that for export, even IDE-native charts are rendered using Matplotlib.

The properties that are taken into account:

• export_image (boolean): Controls whether to perform the exporting. This is normally false, and only set to true by the IDE or opp_charttool when image export is requested.

• image_export_format: The default is SVG. Accepted formats (and their names) are the ones supported by Matplotlib.

• image_export_folder: The folder in which the image file is to be created.

• image_export_filename: The output file name. If it has no extension, one will be added based on the format. If missing or empty, a sanitized version of the chart name is used.

• image_export_width: Image width in inches (default: 6”)

• image_export_height: Image height in inches (default: 4”)

• image_export_dpi: DPI setting, default 300. For raster image formats, the image dimensions are produced as width (or height) times dpi.

Note that these properties come from two sources to allow meaningful batch export. export_image, image_export_format, image_export_folder and image_export_dpi come from the export dialog because they are common to all charts, while image_export_filename, image_export_width and image_export_height come from the chart properties because they are specific to each chart. Note that image_export_dpi is used for controlling the resolution (for raster image formats) while letting charts maintain their own aspect ratio and relative sizes.

Parameters:

• props (dict): the properties

get_image_export_filepath()¶

Returns the file path for the image to export based on the image_export_format, image_export_folder and image_export_filename properties given in props. If a relative filename is returned, it is relative to the working directory when the image export takes place.

export_data_if_needed()¶

If a certain property is set, save the dataframe in CSV format. Calling this function should be a standard part of chart scripts, as it is what makes the “Export data” functionality of the IDE and opp_charttool work.

The properties that are taken into account:

• export_data (boolean): Controls whether to perform the exporting. This is normally false, and only set to true by the IDE or opp_charttool when data export is requested.

• data_export_folder: The folder in which the CSV file is to be created.

• data_export_filename: The output file name. If missing or empty, a sanitized version of the chart name is used.

Note that these properties come from two sources to allow meaningful batch export. export_data and image_export_folder come from the export dialog because they are common to all charts, and image_export_filename comes from the chart properties because it is specific to each chart.

Parameters:

• df: the dataframe to save

• props (dict): the properties

get_data_export_filepath()¶

Returns the file path for the data to export based on the data_export_format, data_export_folder and data_export_filename properties given in props. If a relative filename is returned, it is relative to the working directory when the data export takes place.

histogram_bin_edges_from_props()¶

Calculates histogram bin edges based on chart dialog properties. This is a convenience wrapper around histogram_bin_edges(). See that function for detailed documentation of the binning algorithm and parameters.

Parameters:

• values: Input data array

• unit: Measurement unit of the input data

• props (dict): Properties from the chart configuration dialog, containing settings like “use_manual”, “manual_edges”, “num_bins”, “bin_width”, “range_min”, “range_max”, “round_bin_widths”, “method”.

Returns:

• bin_edges: Array of bin edges

histogram_bin_edges()¶

Enhanced histogram bin edge calculator with flexible parameter combinations and smart defaults. Automatically returns integer-aligned edges for integer data and uses rounded “nice” bin widths for improved readability.

Parameters:

• values: Input data array

• num_bins: Number of bins to use. If round_bin_widths is True, this will be treated as a hint.

• bin_width: Fixed width for each bin

• range_min: Lower endpoint of histogram range

• range_max: Upper endpoint of histogram range

• round_bin_widths: Choose “nice” bin widths such as 1, 2, 5 * 10^k.

• method: Binning method (used if num_bins is None, default: ’auto’ if None)

When parameters are provided (not None), they are respected. If parameters are overconstrained, an exception will be thrown.

Returns:

• bin_edges: Array of bin edges

Raises:

• ValueError: If parameters are overconstrained or incompatible

confidence_interval()¶

Returns the half-length of the confidence interval of the mean of data, assuming normal distribution, for the given confidence level alpha.

Parameters:

• alpha (float): Confidence level, must be in the [0..1] range.

• data (array-like): An array containing the values.

pivot_for_barchart()¶

Turns a DataFrame containing scalar results (in the format returned by results.get_scalars()) into a 3-tuple of a value, an error, and a metadata DataFrame, which can then be passed to utils.plot_bars(). The error dataframe is None if no confidence level is given.

Parameters:

• df (pandas.DataFrame): The dataframe to pivot.

• groups (list): A list of column names, the values in which will be used as names for the bar groups.

• series (list): A list of column names, the values in which will be used as names for the bar series.

• confidence_level (float, optional): The confidence level to use when computing the sizes of the error bars.

• sort (bool): Whether to sort the values by the columns in groups and series before pivoting.

Returns:

• A triplet of DataFrames containing the pivoted data: (values, errors, metadata)

pivot_for_scatterchart()¶

Turns a DataFrame containing scalar results (in the format returned by results.get_scalars()) into a DataFrame which can then be passed to utils.plot_lines().

Parameters:

• df (pandas.DataFrame): The dataframe to pivot.

• xaxis_itervar (string): The name of the iteration variable whose values are to be used as X coordinates.

• group_by (list): A list of column names, the values in which will be used to group the scalars into lines.

• confidence_level (float, optional): The confidence level to use when computing the sizes of the error bars.

Returns:

• A DataFrame containing the pivoted data, with these columns: name, x, y, and optionally error - if confidence_level is given.

get_confidence_level()¶

Returns the confidence level from the confidence_level property, converted to a float. Also accepts “none” (returns None in this case), and percentage values (e.g. “95%”).

perform_vector_ops()¶

Performs the given vector operations on the dataframe, and returns the resulting dataframe. Vector operations primarily affect the vectime and vecvalue columns of the dataframe, which are expected to contain ndarray’s of matching lengths.

operations is a multiline string where each line denotes an operation; they are applied in sequence. The syntax of one operation is:

opname [ ( arglist ) ] [ # comment ]

Blank lines and lines only containing a comment are also accepted.

opname is the name of the function, optionally qualified with its package name. If the package name is omitted, omnetpp.scave.vectorops is assumed.

compute and apply specify whether the newly computed vectors will replace the input row in the DataFrame (apply) or added as extra lines (compute). The default is apply.

See the contents of the omnetpp.scave.vectorops package for more information.

set_plot_title()¶

Sets the plot title. It also sets the suggested chart name (the name that the IDE offers when adding a temporary chart to the Analysis file.)

fill_missing_titles()¶

Utility function to fill missing values in the title and moduledisplaypath columns from the name and module columns. (Note that title and moduledisplaypath normally come from result attributes of the same name.)

extract_label_columns()¶

Utility function to make a reasonable guess as to which column of the given DataFrame is most suitable to act as a chart title and which ones can be used as legend labels.

Ideally a “title column” should be one in which all lines have the same value, and can be reasonably used as a title. This is often the title or name column.

Label columns should be a minimal set of columns whose corresponding value tuples uniquely identify every line in the DataFrame. These will primarily be iteration variables and run attributes.

Returns:

A pair of a string and a list; the first value is the name of the “title” column, and the second one is a list of pairs, each containing the index and the name of a “label” column.

Example: (’title’, [(8, ’numHosts’), (7, ’iaMean’)])

make_chart_title()¶

Produces a reasonably good chart title text from a result DataFrame, given a selected list of “title” columns.

select_best_partitioning_column_pair()¶

Choose two columns from the dataframe which best partitions the rows of the dataframe, and returns their names as a pair. Returns (None, None) if no such pair was found. This method is useful for creating e.g. a bar plot.

select_groups_series()¶

Extracts the column names to be used for groups and series from the df DataFrame, for pivoting. The columns whose names are to be used as group names are given in the “groups” property in props, as a comma-separated list. The names for the series are selected similarly, based on the “series” property. There should be no overlap between these two lists.

If both “groups” and “series” are given (non-empty), they are simply returned as lists after some sanity checks. If both of them are empty, a reasonable guess is made for which columns should be used, and ([“module”], [“name”]) is used as a fallback.

The data in df should be in the format as returned by result.get_scalars(), and the result can be used directly by utils.pivot_for_barchart().

Returns: - (group_names, series_names): A pair of lists of strings containing the selected names for the groups and the series, respectively.

select_xaxis_and_groupby()¶

Extracts an iteration variable name and the column names to be used for grouping from the df DataFrame, for pivoting. The columns whose names are to be used as group names are given in the “group_by” property in props, as a comma-separated list. The name of the iteration variable is selected similarly, from the “xaxis_itervar” property. The “group_by” list should not contain the given “xaxis_itervar” name.

If both “xaxis_itervar” and “group_by” are given (non-empty), they are simply returned after some sanity checks, with “group_by” split into a list. If both of them are empty, a reasonable guess is made for which columns should be used.

The data in df should be in the format as returned by result.get_scalars(), and the result can be used directly by utils.pivot_for_scatterchart().

Returns: - (xaxis_itervar, group_by): An iteration variable name, and a list of strings containing the selected column names to be used as groups.

assert_columns_exist()¶

Ensures that the dataframe contains the given columns. If any of them are missing, the function raises an error with the given message.

Parameters:

• df (DataFrame): The DataFrame to operate on

• cols (list of strings): The list of column names to check.

to_numeric()¶

Convenience function. Runs pandas.to_numeric on the given (or all) columns of df. If any of the given columns doesn’t exist, throws an error.

Parameters:

• df (DataFrame): The DataFrame to operate on

• columns (string or list of strings): The column name or list of column names to convert. If not given, all columns will be converted.

parse_rcparams()¶

Accepts a multiline string that contains rc file content in Matplotlib’s RcParams syntax, and returns its contents as a dictionary. Parse errors and duplicate keys are reported via exceptions.

make_fancy_xticklabels()¶

Only useful for Matplotlib plots. It causes the x tick labels to be rotated by the minimum amount necessary so that they don’t overlap. Note that the necessary amount of rotation typically depends on the horizontal zoom level.

split()¶

Split a string with the given separator (by default with comma), trim the surrounding whitespace from the items, and return the result as a list. Returns an empty list for an empty or all-whitespace input string. (Note that in contrast, s.split(’,’) will return an empty array, even for s=’’.)

Module omnetpp.scave.vectorops¶

Contains operations that can be applied to vectors.

In the IDE, operations can be applied to vectors on a vector chart by means of the plot’s context menu and by editing the Vector Operations field in the chart configuration dialog.

Every vector operation is implemented as a function. The notation used in the documentation of the individual functions is:

• y[k]: The kth value in the input

• t[k]: The kth timestamp in the input

• yout[k]: The kth value in the output

• tout[k]: The kth timestamp in the output

A vector operation function accepts a DataFrame row as the first positional argument, and optionally additional arguments specific to its operation. When the function is invoked, the row will contain a vectime and a vecvalue column (both containing NumPy ndarray’s) that are the input of the operation. The function should return a similar row, with updated vectime and a vecvalue columns.

Additionally, the operation may update the name and title columns (provided they exist) to reflect the processing in the name. For example, an operation that computes mean may return mean(%s) as name and Mean of %s as title (where %s indicates the original name/title).

The aggregate() and merge() functions are special. They receive a DataFrame instead of a row in the first argument, and return new DataFrame with the result.

Vector operations can be applied to a DataFrame using utils.perform_vector_ops(df,ops). ops is a multiline string where each line denotes an operation; they are applied in sequence. The syntax of one operation is:

opname [ ( arglist ) ] [ # comment ]

opname is the name of the function, optionally qualified with its package name. If the package name is omitted, omnetpp.scave.vectorops is assumed.

compute and apply specify whether the newly computed vectors will replace the input row in the DataFrame (apply) or added as extra lines (compute). The default is apply.

To register a new vector operation, define a function that fulfills the above interface (e.g. in the chart script, or an external .py file, that the chart script imports), with the omnetpp.scave.vectorops.vector_operation decorator on it.

Make sure that the registered function does not modify the data of the NumPy array instances in the rows, because it would have an unwanted effect when used in compute (as opposed to apply) mode.

Example:

from omnetpp.scave import vectorops

@vectorops.vector\_operation("Fooize", "foo(42)")
def foo(r, arg1, arg2=5):
    \# r.vectime = r.vectime * 2    \# <- this is okay
    \# r.vectime *= 2               \# <- this is NOT okay!

    r.vectime = r.vectime * arg1 + arg2
    if "title" in r:
        r.title = r.title + ", but fooized" \# this is also okay
    return r

perform_vector_ops()¶

See: utils.perform_vector_ops

vector_operation()¶

Returns, or acts as, a decorator; to be used on methods you wish to register as vector operations. Parameters:

• label: will be shown on the GUI for the user

• example: should be string, containing a valid invocation of the function Alternatively, this can also be used directly as decorator (without calling it first).

lookup_operation()¶

Returns a function from the registered vector operations by name, and optionally module. module and name are both strings. module can also be None, in which case it is ignored.

aggregate()¶

Aggregates several vectors into a single one, aggregating the y values at the same time coordinate with the specified function. Possible values: ’sum’, ’average’, ’count’, ’maximum’, ’minimum’

merge()¶

Merges several series into a single one, maintaining increasing time order in the output.

mean()¶

Computes mean on (0,t): yout[k] = sum(y[i], i=0..k) / (k+1).

sum()¶

Sums up values: yout[k] = sum(y[i], i=0..k)

add()¶

Adds a constant to all values in the input: yout[k] = y[k] + c

compare()¶

Compares value against a threshold, and optionally replaces it with a constant. yout[k] = if y[k] < threshold and less != None then less; else if y[k] == threshold and equal != None then equal; else if y[k] > threshold and greater != None then greater; else y[k] The last three parameters are all independently optional.

crop()¶

Discards values outside the [t1, t2] interval. The time values are in seconds.

difference()¶

Subtracts the previous value from every value: yout[k] = y[k] - y[k-1]

diffquot()¶

Calculates the difference quotient of every value and the subsequent one: yout[k] = (y[k+1]-y[k]) / (t[k+1]-t[k])

divide_by()¶

Divides every value in the input by a constant: yout[k] = y[k] / a

divtime()¶

Divides every value in the input by the corresponding time: yout[k] = y[k] / t[k]

expression()¶

Replaces the value with the result of evaluating the Python arithmetic expression given as a string: yout[k] = eval(expression). The expression may use the following variables: t, y, tprev, yprev, tnext, ynext, k, n which stand for t[k], y[k], t[k-1], y[k-1], t[k+1] and y[k+1], k, and the size of vector, respectively.

If as_time is True, the result will be assigned to the time variable instead of the value variable.

Note that for efficiency, the expression will be evaluated only once, with the variables being np.ndarray instances instead of scalar float values. Thus, the result is computed using vector operations instead of looping through all vector indices in Python. Expression syntax remains the usual. Most Numpy mathematical functions can be used without module prefix; other Numpy functions can be used by prefixing them with np..

Examples: 2*y+0.5, abs(floor(y)), (y-yprev)/(t-tprev), fmin(yprev,ynext), cumsum(y), nan_to_num(y)

integrate()¶

Integrates the input as a step function (“sample-hold” or “backward-sample-hold”) or with linear (“linear”) interpolation.

lineartrend()¶

Adds a linear component with the given steepness to the input series: yout[k] = y[k] + a * t[k]

modulo()¶

Computes floating point reminder (modulo) of the input values with a constant: yout[k] = y[k] % m

movingavg()¶

Applies the exponentially weighted moving average filter with the given smoothing coefficient in range (0.0, 1.0]: yout[k] = yout[k-1] + alpha * (y[k]-yout[k-1])

multiply_by()¶

Multiplies every value in the input by a constant: yout[k] = a * y[k]

removerepeats()¶

Removes repeated (consecutive) y values

slidingwinavg()¶

Replaces every value with the mean of values in the window: yout[k] = sum(y[i], i=(k-winsize+1)..k) / winsize If min_samples is also given, allows each window to have only that many valid (not missing [at the ends], and not NaN) samples in each window.

subtractfirstval()¶

Subtract the first value from every subsequent value: yout[k] = y[k] - y[0]

timeavg()¶

Average over time (integral divided by time), possible parameter values: ’sample-hold’, ’backward-sample-hold’, ’linear’

timediff()¶

Sets each value to the elapsed time (delta) since the previous value: tout[k] = t[k] - t[k-1]

timeshift()¶

Shifts the input series in time by a constant (in seconds): tout[k] = t[k] + dt

timedilation()¶

Dilates the input series in time by a constant factor: tout[k] = t[k] * c

timetoserial()¶

Replaces time values with their index: tout[k] = k

timewinavg()¶

Calculates time average: Replaces the input values with one every ’window_size’ interval (in seconds), that is the mean of the original values in that interval. tout[k] = k * winSize, yout[k] = average of y values in the [(k-1) * winSize, k * winSize) interval

timewinthruput()¶

Calculates time windowed throughput: tout[k] = k * winSize, yout[k] = sum of y values in the [(k-1) * winSize, k * winSize) interval divided by window_size

winavg()¶

Calculates batched average: replaces every ’winsize’ input values with their mean. Time is the time of the first value in the batch.

Module omnetpp.scave.analysis¶

This module allows reading, writing, creating and editing OMNeT++ Analysis (.anf) files, querying their contents, and running the charts scripts they contain. The main user of this module is opp_charttool.

Class ExpatError¶

Class DialogPage¶

Represents a dialog page in a Chart. Dialog pages have an ID, a label (which the IDE displays on the page’s tab in the Chart Properties dialog), and XSWT content (which describes the UI controls on the page).

Class Chart¶

Represents a chart in an Analysis. Charts have an ID, a name, a chart script (a Python script that mainly uses Pandas and the omnetpp.scave.* modules), dialog pages (which make up the contents of the Chart Properties dialog in the IDE), and properties (which are what the Chart Properties dialog in the IDE edits).

Class Folder¶

Represents a folder in an Analysis. Folders may contain charts and further folders.

Class Workspace¶

This is an abstraction of an IDE workspace, and makes it possible to map workspace paths to filesystem paths. This is necessary because the inputs in the Analysis are workspace paths. The class tolerates if workspace metadata (the .metadata subdirectory) is missing; then it looks for projects in directories adjacent to other known projects.

Accepts the workspace location, plus a dict that contains the (absolute, or workspace-location-relative) location of projects by name. The latter is useful for projects that are NOT at the <workspace_dir>/<projectname> location.

Find the project name searching from the given directory (or the current dir if not given) upwards. Project directories of the Eclipse-based IDE can be recognized by having a .project file in them.

Utility function: Find the project directory searching from the given directory (or the current dir if not given) upwards. Project directories of the Eclipse-based IDE can be recognized by having a .project file in them.

Utility function: Find the IDE workspace directory searching from the given directory (or the current dir if not given) upwards. The workspace directory of the Eclipse-based IDE can be recognized by having a .metadata subdir. If the workspace is not found, None is returned.

Returns a list of projects that are referenced by the given project, even transitively.

Returns the location of the given workspace project in the filesystem path.

Returns the “real” name of the project from the .project (project description) file in the given project directory.

Returns a list of projects that are referenced by the given project.

Translate workspace paths to filesystem path.

Class Analysis¶

Represents an OMNeT++ Analysis, i.e. the contents of an anf file. Methods allow reading/writing anf files, and running the charts in them for interactive display, image/data export or other side effects.

Collects and returns a list of all charts in the specified folder, or in this Analysis if no folder is given.

Runs a chart script for data export. This method just calls run_chart() with extra properties that instruct the chart script to perform data export. (It is assumed that the chart script invokes utils.export_data_if_needed() or implements equivalent functionality).

Runs a chart script for image export. This method just calls run_chart() with extra properties that instruct the chart script to perform image export. (It is assumed that the chart script invokes utils.export_image_if_needed() or implements equivalent functionality).

Reads the given anf file and returns its content as an Analysis object.

Returns the path of the item (Chart or Folder) within the Analysis as list of path segments (Folder items). The returned list includes both the root folder of the Analysis and the item itself. If the item is not part of the Analysis, None is returned.

Returns the path of the item (Chart or Folder) within the Analysis as a string. Segments are joined with the given separator. The returned string includes the item name itself, but not the root folder (i.e. for items in the root folder, the path string equals to the item name). If the item is not part of the Analysis, None is returned.

Runs a chart script with the given working directory, workspace, and extra properties in addition to the chart’s properties. If show=True, it calls plt.show() if it was not already called by the script.

Saves the analysis to the given .anf file.

load_anf_file()¶

Reads the given anf file and returns its content as an Analysis object. This is synonym for Analysis.from_anf_file().

Module omnetpp.scave.charttemplate¶

Loading and instantiating chart templates.

Class ChartTemplate¶

Represents a chart template.

Creates a chart template from the given data elements.

Parameters:

• id (string): A short string that uniquely identifies the chart template.

• name (string): Name of the chart template.

• type (string): Chart type, one of: “bar”/”histogram”/”line”/”matplotlib”.

• icon (string): Name of the icon to be used for charts of this type.

• script (string): The Python chart script.

• dialog_pages (list of ``DialogPage``): Pages of the “Configure Chart” dialog.

• properties (string->string dictionary): Initial values for chart properties.

Creates and returns a chart object (org.omnetpp.scave.Chart) from this chart template. Chart properties will be set to the default values defined by the chart template. If a props argument is present, property values in it will overwrite the defaults.

Parameters:

• id (string): A numeric string that identifies the chart within the Analysis. Auto-assigned if missing.

• name (string): Name for the chart. If missing, the chart template name will be used.

• props (string->string dictionary): Chart properties to set. It may not introduce new properties, i.e. the keys must be subset of the property keys defined in the chart template.

get_chart_template_locations()¶

Returns a list of locations (directories) where the chart templates that come with the IDE can be found.

load_chart_templates()¶

Loads chart templates from the given list of directories, and returns them in a dictionary. Chart templates are loaded from files with the .properties extension.

Parameters:

• dirs (string list): A short string that uniquely identifies the chart template.

• add_default_locations (bool): Whether the directories returned by get_chart_template_locations() should also be searched in addition to the specified directory list.

Returns:

• A string->ChartTemplate dictionary, with chart template IDs used as keys.

load_chart_template()¶

Loads the chart template from the specified .properties file, and returns it as a ChartTemplate object.