Plot/Graph Action Blocks

Aus expecco Wiki (Version 2.x)
Zur Navigation springen Zur Suche springen

Introduction[Bearbeiten]

With expecco18.1, a new block type named "Plot/Graph Actions" is introduced. These behave similar to other script action blocks, in that they are defined by a script (in this case: gnuplot scripting language) and are placed into the test sequence flow just like any other block.

However, when executed, these actions generate a graphic document (jpeg, png or postscript), which is then either added to the activity log, or added as attachment. It will therefore be available in the generated "elf" execution log file, or shown in the generated "pdf" report file. Of course, you can do anything you like with the generated graphic file, by feeding the name of the generated file to another action for further processing.

Notice: if you prefer other graphic packages or other programming languages, you may of course use R language scripts or Python scripts (with matplotlib and/or seaboarn) to generate graphics in a similar way.

Creating Plot/Graph Action Blocks[Bearbeiten]

Plot/graph action blocks are created via the "Actions - More - Plot/Graph" menu item.

Plot Graph Actions in Menu.png

Select the "Plot/Graph" item, to create a new gnuplot action. An initial set of input pins and an initial (demo-) script is generated for you.

For details on the scripting language, please refer to the public gnuplot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".

Any input pin named "<pinName>" is available in the script as "%(pinName)". Thus, the script can be parametrized in arbitrary ways. A number of pins are already created for you; these are:

  • "outputFile"
    both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.
  • "outputFormat"
    specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report.
    On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.
  • "title"
    A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)
  • "data"
    If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "%(data)". Theis will be the raw data, to be processed by the script.
  • "dataSize"
    There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.
  • "attachToLog"
    if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.

You can add additional input pins and refer to the corresponding pin value in the script with the "%(...)" notation.

A Simple Graph Script[Bearbeiten]

A typical gnuplot script looks like:

# The code below is sent to gnuplot and the generated output
# will be stored in a file named %%(outputFile) 
# (unless explicitly specified, a temporary file is created)
#
set output "%(outputFile)"
 
# 
set term %(outputFormat)

# All input pin values can be used here as %%(nameOfPin).
# so the next line controls the title via the "title" pin
#
set title "%(title)"

# You can add more pins.
# For example, add pins named "min" and "max" with type Number,
# and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range.
set key left box
plot [1:%(dataSize)] [-10:10] "%(data)" title "My Data" with impulses

to plot a simple impulse graph of the data values, as presented at the input pin, assuming that the pins get the following values:

  • "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
  • "outputFormat" - freeze as "png"
  • "title" - any title - such as "Measurement #1"
  • "data" - a vector of numbers

Of course, this is actually the simplest possible script to render such data. Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc. A few examples are provided in the "Plot_Graph Library.ets", but much more is found on the gnuplot website and gnuplot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".

Short List of Useful Script Commands[Bearbeiten]

For a full list, please take a look at the gnu plot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf". The following list is only presenting the most common plot commands:

  • plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses
    You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot.
    Replace "nameOfDataFile" by "%(data)" if the data comes via an input pin and is not already in a file.
  • plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"
    Without the "impulses" parameter, a regular graph is drawn (straight lines between points)
  • plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines
    The same as above (straight lines between points)
  • plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots
    Draws dots
  • plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks
    the data file should contain multiple colums per line. Select the colums with a "using..." parameter.
  • set key left box
    defines the position (left) and type (boxed) of the graph-title (the string comes from the title "graph title" argument in the plot command)
  • set title "someTitle"
    defines a headline title
  • set term %(outputFormat)
    defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "png", "jpg", etc. here

A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".

Accessing Data from Attachments[Bearbeiten]

You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "foo.dat", use ... data "foo.dat" ... inside the script. Notice that the attchment's filename is to be used - not its name in the tree.

Plotting Multiple Graphs into a Single Picture[Bearbeiten]

To do this, generate multiple datasets (as ascii files, with one textline per row). Add data<i> input pins and feed them the filenames. Add multiple plot commands, each with its own "%(data<i>)" argument, and possibly with its own graph-title.

Changing the Size of the Generated Image[Bearbeiten]

By default, the generated image's size is 640 x 400 pixels. For a fix size, change the script's "set term" statement to:

set term %(outputFormat) size <width>,<height>

where <width> and <height> define the size in pixels.

Alternatively, add two pins named "width" and "height", and change the statement to:

set term %(outputFormat) size %(width),%(height)

and provide the desired size (as integers) at the input pins.

Caveats[Bearbeiten]

Do not place pause statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.

Complete Example 1: Gathering Response Times of MQTT Protocol Messages[Bearbeiten]

This example demonstrates, how a test suite can gather response times of a remote system, when sending MQTT messages to it.

Step 1: Define the Test Sequence[Bearbeiten]

this is a very simple publish-response setup, in that a topic is published to an MQTT broker, and the time measured, until the notification arrives (in order to run this on your machine, the expecco MQTT plugin needs to be installed):

Outside (Schema) view of the measuring action:

Schema Measuring MQTT.png

which is implemented as:

Net Measuring MQTT.png

The yellow area does the MQTT setup. First, an MQTT client connection is created, and the client handle forwarded to the Subscribe action, which registers expecco to react to the "expeccoTesting/test" topic.

The green area does the actual publish operation, publishing the "Hello from Expecco" string on this topic.

In parallel, the blue area waits for the next incoming event, (and generates a printed detail info on the received packet for the activity log).

The red area contains a stopWatch action block, which gets started with when the publish is done, and stops when the event arrives.

The measurement action is prametrized with the broker's host and port, and generates the measured timeDuration as output.

Step 2: Test Run[Bearbeiten]

Assuming that you have an MQTT client running on the local host, the test sequence can be immediately tried via the Test/Demo page:

Test Measuring MQTT.png

A good strategy is to package the MQTT broker into a docker file. Here is the MQTT client's output of the above run:

$ sh rundocker.sh 
1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting
1522084243: Using default config.
1522084243: Opening ipv4 listen socket on port 1883.
1522084243: Opening ipv6 listen socket on port 1883.
1522084272: New connection from 172.17.0.1 on port 1883.
1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0).
1522084272: Client expeccoMQTT disconnected.

and here the activitylog in expecco:

Log1 Measuring MQTT.png

with the event info detail:

Log2 Measuring MQTT.png

Step 3: Running that Sequence Multiple Times[Bearbeiten]

Now that we have verified, that the communication with the MQTT broker works correctly, we create another action bock, which runs the above action multiple times and collects all the execution times:

Multiple Measuring MQTT.png

[ explanation: first, a new empty colletion is created, then, the timing values of the multi-triggered measure-step are all added to this collection. When done (no step active), the collection is forwarded (now filled) to the output pin]

Here is the activity log after 10 runs:

Log1 Multiple Measuring MQTT.png

Step 4: Adding the Graph[Bearbeiten]

The last step is the easiest: select the "New Plot/Graph" action block from the menu, name it "Time Measurement Graph" and change its autogenerated gnuplot script to:

set output "%(outputFile)"
set term %(outputFormat)
set title "%(title)"
set key left box
plot [1:%(dataSize)] [0:100] "%(data)" title "%(lineTitle)" with impulses

then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input of the "Measurement-Graph" step:

Multiple Measuring plus Graph MQTT.png

Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):

Multiple Measuring MQTT Report img.png

Datei:Multiple Measuring MQTT Report.pdf

Example 1 Simplified: Using Probes to Gather the Data[Bearbeiten]

The above data collection may look a bit complicated, due to the need for start/stop synchronization. A much nicer and easier to use solution is in using a probe to gather the data. For this, we need a probe which does no range checks, but instead only collects the incoming values:

Measuring MQTT with Probe.png

Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item), and specified to "collect incoming data without check":

Measuring MQTT with ProbeMenu.png

Now that we have a probe at the roundtrip time, the outer measurement looks much simpler:

  • reset the probe (to clear any previously gathered data)
  • prime the probe enable data collecting)
  • run the roundtrip-test n-times
  • unprime the probe (disable further data collecting)
  • fetch the probe's values and pass them to the gnuplot action

Measuring MQTT with Probe2.png

See Also[Bearbeiten]

Gnuplot Manual
Collection of Examples

"R Action Blocks" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.
"Octave/Matlab Actions" another framework for mathematical computations and/or to generate graphs/plots.



Copyright © 2014-2024 eXept Software AG