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:

[(compute|apply) : ] 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

Functions¶

Module Contents¶

perform_vector_ops(df, operations: str)[source]¶

See: utils.perform_vector_ops

vector_operation(label: str = None, example: str = None)[source]¶

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(module, name)[source]¶

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(df, function='average')[source]¶

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(df)[source]¶

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

mean(r)[source]¶

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

sum(r)[source]¶

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

add(r, c)[source]¶

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

compare(r, threshold, less=None, equal=None, greater=None)[source]¶

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(r, t1, t2)[source]¶

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

difference(r)[source]¶

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

diffquot(r)[source]¶

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(r, a)[source]¶

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

divtime(r)[source]¶

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

expression(r, expression, as_time=False)[source]¶

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(r, interpolation='sample-hold')[source]¶

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

lineartrend(r, a)[source]¶

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

modulo(r, m)[source]¶

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

movingavg(r, alpha)[source]¶

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(r, a)[source]¶

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

removerepeats(r)[source]¶

Removes repeated (consecutive) y values

slidingwinavg(r, window_size, min_samples=None)[source]¶

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(r)[source]¶

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

timeavg(r, interpolation)[source]¶

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

timediff(r)[source]¶

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

timeshift(r, dt)[source]¶

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

timedilation(r, c)[source]¶

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

timetoserial(r)[source]¶

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

timewinavg(r, window_size=1)[source]¶

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(r, window_size=1)[source]¶

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(r, window_size=10)[source]¶

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