TimeSeries

Description

obj = TimeSeries(name, nRows, nColumns, varargin);

TimeSeries inherits from the PARODIS class Figure (and thus also from the Matlab class handle). It is the only usable plotting class shipped with PARODIS so far. You can plot both history and status (prediction) values of all agents' states, inputs, disturbances, cost and evaluation functions. Note that parameters cannot be plotted directly. Instead, you can define an evaluation function which evaluates the parameter of your choice.
TimeSeries supports two types of plots:

1. LineSeries: "Regular" plot using the Matlab function stairs().
2. Heatmap: A heatmap plot using the Matlab surface function

Note: As usual in matlab classes derived from handle, all functions (other than the constructor) have the handle instance as first input argument in their definition. Since this argument is actually not given when called by the user, we omit its reference in the following.

Public Properties

Property	Description
lineSeries	Cell array with lines to plot. A line is defined as explained in addLine(..).
heatMaps	Cell array with heatmaps to plot. A heatmap is defined as explained in addHeatmap(..).
dependsOnAgents	Cell array with names of agents (as strings) on which the lineSeries or heatMaps depend on.
subplotDependsOnAgents	Cell array of cell arrays, i.e. one cell array for each subplot, which in turn has the names of agents on which any line or heatmap depend on. This is used to clear only subplots which depend on the calling agent.
doLinkAxes	Boolean value, if x-Axes of all subplots (of this figure) should be linked. Default: 1

Private Properties

Property	Description
subplotAxisPredictionTimesAndWidths	Cell array of 2-dimensional vectory, i.e. one entry for each subplot. show() uses this to temporarily save the limits for the gray box used to mark the prediction horizon.
subplotFixedXLimits	Cell array of 2-dimensional vectors, i.e. one entry for each subplot. If set (non-empty), x-limits of corresponding subplot are fixed. Can be set with set setFixedXLimits().
subplotFixedYLimitsLeft	Cell array of 2-dimensional vectors, i.e. one entry for each subplot. If set (non-empty), y-limits (left axis) of corresponding subplot are fixed. Can be set with set setFixedYLimits().
subplotFixedYLimitsRight	Cell array of 2-dimensional vectors, i.e. one entry for each subplot. If set (non-empty), y-limits (right axis) of corresponding subplot are fixed. Can be set with set setFixedYLimits().
subplotTempXLimits	Cell array of 2-dimensional vectory, i.e. one entry for each subplot. show() uses this to temporarily save the x-limits.
subplotHasRightY	Vector with nRows*nColumns boolean entries whether or not the subplot has a line which uses the right y-axis.
subplotHasLineSeries	Vector with nRows*nColumns boolean entries whether or not the subplot has a lineSerieselement.
subplotHasHeatMap	Vector with nRows*nColumns boolean entries whether or not the subplot has a heatMaps element.
subplotAxisPredictionBarAt	Cell array of 2-dimensional vectory, i.e. one entry for each subplot. show() uses this to temporarily save the -position of the "prediction bar" used to mark the beginning of the prediction horizon for heatmaps.
subplotHasLegend	Vector with nRows*nColumns boolean entries whether or not the subplot has a legend.
subplotLinesToDelete	Cell array of cell arrays, i.e. one cell array for each subplot, which show() uses to store all lines which need to be deleted manually. (This is because they have been created with 'HandleVisibility', 'off' to suppress a legend entry. Thus, they can't be deleted by cla(subplotAxisHandle).)

Methods to use

Function Call	Description
obj = TimeSeries(name, nRows, nColumns, varargin)	Constructor. It initializes (nearly) all class properties with the appropriate sizes and calls the constructor from Figure.
setDoLinkAxes(doLinkAxes)	Setter function for class property doLinkAxes.
setFixedXLimits(subplotIndex, xLimits)	Sets obj.subplotFixedXLimits{subplotIndex}=xLimits.
setFixedYLimits(subplotIndex, yLimits, [leftOrRight])	Sets y-limits of either left or right y-axis of subplot subplotIndex to yLimits. leftOrRight is optional with default value left.
addLine(agent, variable, variableIndex, subplotIndex, ... [legendName], [scenario], [optionsReal], [optionsPred], [leftOrRight])	Adding a lineSeries element. agent: handle to agent-instance from which variable shall be plotted. variable: Either x, u, d, cost, eval for regular values, or xVirt, uVirt, dVirt, costVirt, evalVirt for the virtual history or xDif, uDif, dDif, costDif, evalDif for the difference between regular and virtual history. variableIndex: For x, u, d a scalar index or an array of indices. For cost and eval it has to be a string with the name of the cost or eval function. subplotIndex: Index of subplot in which to plot. legendName: [Optional] Either string with legend entry or a cell array of strings in case of multiple entries in variableIndex. Default: {}. scenario: [Optional] Number of scenario for which values should be taken. Default: 1 optionsReal: [Optional] Cell array with alternating names and values of properties, which are used for the stairs()-call of the real (history) values. Default: {} optionsPred: [Optional] Cell array with alternating names and values of properties, which are used for the stairs()-call of the prediction (status) values. Default: {} leftOrRight: [Optional] String indicating which y-axis to use, either left or right. Default: left
addHeatmap(agent, variable, variableIndexArray, subplotIndex, ... [scenario], [optionsReal], [optionsPred])	Adding a colorMap element. agent: handle to agent-instance from which variable shall be plotted. variable: Either x, u, d, cost, eval for regular values, or xVirt, uVirt, dVirt, costVirt, evalVirt for the virtual history or xDif, uDif, dDif, costDif, evalDif for the difference between regular and virtual history variableIndex: For x, u, d a scalar index or an array of indices. For cost and eval it has to be a string with the name of the cost or eval function. subplotIndex: Index of subplot in which to plot. legendName: [Optional] Either string with legend entry or a cell array of strings in case of multiple entries in variableIndex. Default: {}. scenario: [Optional] Number of scenario for which values should be taken. Default: 1 optionsReal: [Optional] Cell array with alternating names and values of properties, which are used for the stairs()-call of the real (history) values. Default: {} optionsPred: [Optional] Cell array with alternating names and values of properties, which are used for the stairs()-call of the prediction (status) values. Default: {} leftOrRight: [Optional] String indicating which y-axis to use, either left or right. Default: left

Internal functions

Function Call	Description
show(callingAgent, isFinalUpdate)	"Main" function which is calles from simulation instance. It deletes (clears) all subplots which depend on the callingAgent and updates them by plotting every lineSeries and colorMap new. It handles the axes limits, legend entries etc. isFinalUpdate is a boolean value whether or not this is the final call after the regular simulation loop. If so, then x-limits are set to [0 T_sim], such that the prediction horizon is not visible anymore.
[plotTime, plotData] = readInDataToPlot(agent, variableName, ... variableIndex, scenario, historyOrStatus, lineOrColorMap)	Helper function called from show(...)to set appropriate time and data values to plot, which depends on whether variableNameis xor anything else, since xand xPred are always one step ahead from all other variables.
updateTempXLimits(subplotIndex, newLimits)	Helper function to handle x-limits. It checks whether newly set temporary x-limits (which happens with every line or heatmap which is added to the subplot) is bigger or not than current setting.