Buffer operations

The <input> and <output> tags of every module on this page additionally accept the attributes common to all analysis modules.

append

This module appends all the values of the input buffers to a single output buffer. The order of the buffers will match the order in which their values appear in the output buffer. This module will return as many values as the sum of the input buffer sizes. A literal NaN given as a type="value" input is appended like any other value.

<append>
    <input as="in">BUFFER</input>
    <output as="out">BUFFER</output>
</append>

Inputs

as	Count	as required	Allowed types
in	at least one	no	buffer, value, empty

Outputs

as	Count	as required
out	exactly one	no

countadded in 1.2

Returns the number of values in the input buffer.

<count>
    <input as="buffer">BUFFER</input>
    <output as="count">BUFFER</output>
</count>

Inputs

as	Count	as required	Allowed types
buffer	exactly one	no	buffer

Outputs

as	Count	as required
count	exactly one	no

eventstreamadded in 1.18

This is a convenient and faster substitute for stopwatch implementations like the one used in the acoustic stopwatch. The idea is to detect events in a stream of data according to a given criterion; the index of each event within the input data stream is written to the output. The eventstream module also has multiple matching inputs and outputs to keep track of the status between multiple iterations of the analysis cycle.

The inputs that determine its behavior are data (the input data stream), threshold (with a slightly varying meaning according to the chosen mode) and distance (the minimum number of values before the next event may be detected).

Furthermore, it takes index, skip and last as inputs. These represent the index (nth sample) of the data within a stream, the number of values to be skipped before the first event (typically the remainder of the last distance from the previous block in the last analysis cycle) and the last value from the previous data block in case it is needed to determine the criterion (for example a difference between consecutive values). For most purposes it should be enough to assign a data container for each of index, skip and last and attach it to the matching inputs AND outputs.

The output is mainly events, which will hold the indices of detected events. Additionally, there are also index, skip and last as outputs, corresponding to the inputs.

A NaN threshold value participates in the comparisons like any number (no trigger ever fires); only an absent input or an empty buffer selects the default of 0. Absent index, skip and last inputs or empty buffers keep the documented start defaults (0, 0 and NaN); a present but non-finite distance, index or skip value is an error yielding empty outputs, which restarts the state loop from its defaults on the next run.

The criterion is set by the attribute "mode" determining whether raw values, derivatives or absolutes are used for triggering:

<eventstream mode="STRING">
    <input as="data">BUFFER</input>
    <input as="threshold">BUFFER</input>
    <input as="distance">BUFFER</input>
    <input as="index">BUFFER</input>
    <input as="skip">BUFFER</input>
    <input as="last">BUFFER</input>
    <output as="events">BUFFER</output>
    <output as="index">BUFFER</output>
    <output as="skip">BUFFER</output>
    <output as="last">BUFFER</output>
</eventstream>

Attributes

mode

Whether raw values, absolutes or derivatives are compared against the threshold, and in which direction.

above

Triggers if a raw value of the data stream is greater than the threshold.

below

Triggers if a raw value of the data stream is less than the threshold.

aboveAbsolute

Triggers if an absolute value of the data stream is greater than the threshold.

belowAbsolute

Triggers if an absolute value of the data stream is less than the threshold.

aboveDerivative

Triggers if the derivative (difference of current minus previous value) of the data stream is greater than the threshold.

belowDerivative

Triggers if the derivative (difference of current minus previous value) of the data stream is less than the threshold.

aboveDerivativeAbsolute

Triggers if the absolute of the derivative (difference of current minus previous value) of the data stream is greater than the threshold.

belowDerivativeAbsolute

Triggers if the absolute of the derivative (difference of current minus previous value) of the data stream is less than the threshold.

optional, one of above, below, aboveAbsolute, belowAbsolute, aboveDerivative, belowDerivative, aboveDerivativeAbsolute, belowDerivativeAbsolute, default: above

Inputs

as	Count	as required	Allowed types
data	exactly one	yes	buffer
threshold	optional, defaults to 0	yes	buffer, value
distance	optional, defaults to 0	yes	buffer, value
index	optional, defaults to 0	yes	buffer, value
skip	optional, defaults to 0	yes	buffer, value
last	optional, defaults to NaN	yes	buffer, value

Outputs

as	Count	as required
events	optional	yes
index	optional	yes
skip	optional	yes
last	optional	yes

first

Retrieves the first entry of each input buffer and appends it to the output buffer at the same position: output i receives exactly the first value of input i. An empty input skips only its own pair; outputs beyond the number of inputs stay empty.

<first>
    <input as="value">BUFFER</input>
    <output as="first">BUFFER</output>
</first>

Inputs

as	Count	as required	Allowed types
value	at least one	no	buffer

Outputs

as	Count	as required
first	at least one	no

match

This module takes multiple inputs and matches valid values to the same number of outputs. The module will go through all inputs simultaneously and only return those values for which all inputs have a finite value.

If for example input1 provides [1, 2, NaN, 4, 5] and input2 provides [11, +Inf, 13, 14], the result will be [1, 4] for output1 and [11, 14] for output2. The other value pairs (more than two inputs are allowed though) were filtered because one of the inputs was infinite, not a number ("NaN") or just did not have any more values. Outputs beyond the number of inputs are left empty.

<match>
    <input as="in">BUFFER</input>
    <output as="out">BUFFER</output>
</match>

Inputs

as	Count	as required	Allowed types
in	at least one	no	buffer

Outputs

as	Count	as required
out	at least one	no

mapadded in 1.7

This module takes three buffers representing x, y and z data. The data may be scattered randomly and may be unordered. This module will be given ranges as well as a desired number of values along x and y and then rearrange the x, y, z data into a grid that is suitable to be displayed in a color map plot.

<map zMode="average">
    <input as="mapWidth" type="value">100</input>
    <input as="minX" type="value">0</input>
    <input as="maxX" type="value">10</input>
    <input as="mapHeight" type="value">100</input>
    <input as="minY" type="value">1</input>
    <input as="maxY" type="value">2</input>
    <input as="x">xData</input>
    <input as="y">yData</input>
    <input as="z">zData</input>
    <output as="x">xMapOut</output>
    <output as="y">yMapOut</output>
    <output as="z">zMapOut</output>
</map>

The example above takes xData, yData and zData and creates a grid of 100 by 100 data points covering x values from 0 to 10 and y values from 1 to 2.

Points with a non-finite x, y or z value are skipped. Degenerate ranges (such as minX equal to maxX) yield clamped bin indices instead of failing. A missing z input with zMode "sum" or "average" rejects the file at load, since that is a permanent configuration error rather than an intermediate state.

<map zMode="STRING">
    <input as="mapWidth">BUFFER</input>
    <input as="minX">BUFFER</input>
    <input as="maxX">BUFFER</input>
    <input as="mapHeight">BUFFER</input>
    <input as="minY">BUFFER</input>
    <input as="maxY">BUFFER</input>
    <input as="x">BUFFER</input>
    <input as="y">BUFFER</input>
    <input as="z">BUFFER</input>
    <output as="x">BUFFER</output>
    <output as="y">BUFFER</output>
    <output as="z">BUFFER</output>
</map>

Attributes

zMode

Determines how the z data is produced from the input points.

average

Averages all z values falling into a grid point.

count

Counts the number of values for each grid point. No z data has to be provided in this mode.

sum

Adds up all z values of a grid point.

optional, one of average, count, sum, default: average

Inputs

as	Count	as required	Allowed types
mapWidth	exactly one	yes	buffer, value
minX	exactly one	yes	buffer, value
maxX	exactly one	yes	buffer, value
mapHeight	exactly one	yes	buffer, value
minY	exactly one	yes	buffer, value
maxY	exactly one	yes	buffer, value
x	exactly one	yes	buffer, value
y	exactly one	yes	buffer, value
z	optional	yes	buffer, value

Outputs

as	Count	as required
x	exactly one	yes
y	exactly one	yes
z	exactly one	yes

max

Returns the maximum and its position. This module takes at least one input y and looks for the maximum of this buffer, but may also take a second input x. If x is defined, it will return the position of this maximum in terms of the associated x value. If x is not defined, position will be the index of the maximum.

If you want to find multiple local maxima, you can set the attribute "multiple" to true. In this case a third input may be used, which provides a threshold. The algorithm will split the data into sets of consecutive values at or above the threshold and return a maximum and position for each set. The final set is emitted even when the data ends inside it.

This module will return exactly one value per call if multiple is deactivated (default): an empty input or an input without any valid value then yields NaN on each connected output (in multiple mode it yields empty outputs). An x buffer shorter than y truncates processing to the common length; only an omitted x input generates indices automatically. In multiple mode, an absent threshold input or an empty threshold buffer selects the default of 0, while a NaN threshold value participates like any number — no comparison with it is ever true, so the whole input forms one set.

<max multiple="BOOLEAN">
    <input as="x">BUFFER</input>
    <input as="y">BUFFER</input>
    <input as="threshold">BUFFER</input>
    <output as="max">BUFFER</output>
    <output as="position">BUFFER</output>
</max>

Attributes

multiple

See the module description.

optional, boolean, default: false

Inputs

as	Count	as required	Allowed types
x	optional	yes	buffer
y	exactly one	yes	buffer
threshold	optional, defaults to 0	yes	buffer, value

Outputs

as	Count	as required
max	optional	yes
position	optional	yes

min

Returns the minimum and its position. This module takes at least one input y and looks for the minimum of this buffer, but may also take a second input x. If x is defined, it will return the position of this minimum in terms of the associated x value. If x is not defined, position will be the index of the minimum.

If you want to find multiple local minima, you can set the attribute "multiple" to true. In this case a third input may be used, which provides a threshold. The algorithm will split the data into sets of consecutive values at or below the threshold and return a minimum and position for each set. The final set is emitted even when the data ends inside it.

This module will return exactly one value per call if multiple is deactivated (default): an empty input or an input without any valid value then yields NaN on each connected output (in multiple mode it yields empty outputs). An x buffer shorter than y truncates processing to the common length; only an omitted x input generates indices automatically. In multiple mode, an absent threshold input or an empty threshold buffer selects the default of 0, while a NaN threshold value participates like any number — no comparison with it is ever true, so the whole input forms one set.

<min multiple="BOOLEAN">
    <input as="x">BUFFER</input>
    <input as="y">BUFFER</input>
    <input as="threshold">BUFFER</input>
    <output as="min">BUFFER</output>
    <output as="position">BUFFER</output>
</min>

Attributes

multiple

See the module description.

optional, boolean, default: false

Inputs

as	Count	as required	Allowed types
x	optional	yes	buffer
y	exactly one	yes	buffer
threshold	optional, defaults to 0	yes	buffer, value

Outputs

as	Count	as required
min	optional	yes
position	optional	yes

rangefilter

This module takes multiple inputs and makes it possible to set min and max limits for each of them. The module will go through all inputs simultaneously and only return those values for which all inputs fall within their set min and max range. If one input is shorter than the others, its values are set to NaN and will not trigger the filter. Non-finite values are compared like any number: infinities can be filtered, while NaN never triggers the filter.

Min and max have to be defined immediately after the corresponding input and are treated as a single value (last value for buffers). The outputs correspond to the order of the inputs. Here multiple outputs can be defined with the same name!

In the following example, in1 will trigger the filter if not in the range of 0 to 42, in2 will not trigger the filter at all (but if in1 or in3 trigger the filter, only the corresponding elements will be returned) and in3 will trigger the filter if the value is larger than the value in the buffer "limit". The results will be written to the buffers "out1", "out2" and "out3".

<rangefilter>
    <input>in1</input>
    <input as="min" type="value">0</input>
    <input as="max" type="value">42</input>
    <input>in2</input>
    <input>in3</input>
    <input as="max">limit</input>
    <output>out1</output>
    <output>out2</output>
    <output>out3</output>
</rangefilter>

<rangefilter>
    <input as="in">BUFFER</input>
    <input as="min">BUFFER</input>
    <input as="max">BUFFER</input>
    <output as="out">BUFFER</output>
</rangefilter>

Inputs

as	Count	as required	Allowed types
in	at least one	no	buffer
min	any number	yes	buffer, value
max	any number	yes	buffer, value

The slots min, max form a repeating group: a further set of tags in the same order adds another one.

Outputs

as	Count	as required
out	at least one	no

reduceadded in 1.7

This module takes a buffer with multiple values and reduces the number of items by a given (integer) factor. It distinguishes between x and y values and allows for different strategies like summing or averaging values which fall into a single value. A factor smaller than 1 can be used to inflate the size, but in this case the module will simply duplicate each item, so each item occurs round(1/factor) times.

<reduce averageX="false" averageY="false" sumY="false">
    <input as="factor" type="value">2</input>
    <input as="x">xBuffer</input>
    <input as="y">yBuffer</input>
    <output as="x">out1</output>
    <output as="y">out2</output>
</reduce>

Processing truncates to the shortest present buffer; only an absent y input keeps processing all of x (with 0 as the y contribution). With averaging enabled, an incomplete final chunk is averaged over the number of values it actually contains, not the nominal factor. A non-finite factor is an error yielding empty outputs. The x output is required — a file without it is rejected at load.

<reduce averageX="BOOLEAN" averageY="BOOLEAN" sumY="BOOLEAN">
    <input as="factor">BUFFER</input>
    <input as="x">BUFFER</input>
    <input as="y">BUFFER</input>
    <output as="x">BUFFER</output>
    <output as="y">BUFFER</output>
</reduce>

Attributes

averageX

x values will be averaged to produce x output values.

optional, boolean, default: false

averageY

y values will be averaged to produce y output values.

optional, boolean, default: false

sumY

The y output values will be the sum of the original y values.

optional, boolean, default: false

Inputs

as	Count	as required	Allowed types
factor	exactly one	yes	buffer, value
x	exactly one	yes	buffer
y	optional	yes	buffer

Outputs

as	Count	as required
x	exactly one	yes
y	optional	yes

sort

This module takes at least one input and sorts it. Values in additional inputs will follow the sorting of the first input buffer. By default, the values in the first buffer will be sorted in ascending order. This can be reversed with the attribute descending.

The number of values returned matches the number of values in the shortest buffer. NaN sorts as the largest value.

<sort descending="BOOLEAN">
    <input as="in">BUFFER</input>
    <output as="out">BUFFER</output>
</sort>

Attributes

descending

See the module description.

optional, boolean

Inputs

as	Count	as required	Allowed types
in	at least one	no	buffer

Outputs

as	Count	as required
out	at least one	no

splitadded in 1.18

Takes data as input and splits it into two buffers at the given index. A third parameter overlap makes it possible to set a number of elements from before the split index that will also end up in the second buffer. index defaults to the length of the input data if not given, i.e. the entire input is returned as the first output without any splitting, which only makes sense in combination with an overlap, for example to take all data from a buffer associated with the input from a sensor and set "overlap" such that a certain number of values is retained as a starting point for the next iteration.

Negative and out-of-range positive values for index are clamped into range, as is overlap. A present but non-finite index or overlap value is an error yielding empty outputs; absent inputs or empty buffers keep the defaults (index = input length, overlap = 0).

<split>
    <input as="data">BUFFER</input>
    <input as="index">BUFFER</input>
    <input as="overlap">BUFFER</input>
    <output as="out1">BUFFER</output>
    <output as="out2">BUFFER</output>
</split>

Inputs

as	Count	as required	Allowed types
data	exactly one	yes	buffer
index	optional, defaults to the number of values in the data buffer	yes	buffer, value
overlap	optional, defaults to 0	yes	buffer, value

Outputs

as	Count	as required
out1	optional	no
out2	optional	no

subrange

This module takes multiple inputs and returns all values within a given index range. This is much faster than using the rangefilter module for this purpose. The range is set using the inputs from (inclusive) and to (exclusive). Optionally, instead of setting to, you can set length, defining the total number of values returned after from.

<subrange>
    <input as="from" type="value">0</input>
    <input as="to">countBuffer</input>
    <input>in1</input>
    <input>in2</input>
    <output>out1</output>
    <output>out2</output>
</subrange>

A present but non-finite from, to or length value is an error yielding empty outputs; only an absent input or an empty parameter buffer keeps the defaults (the full range).

<subrange>
    <input as="from">BUFFER</input>
    <input as="to">BUFFER</input>
    <input as="length">BUFFER</input>
    <input as="in">BUFFER</input>
    <output as="out">BUFFER</output>
</subrange>

Inputs

as	Count	as required	Allowed types
from	optional, defaults to 0	yes	buffer, value
to	optional, defaults to the length of the input	yes	buffer, value
length	optional, defaults to unused; if given, it supersedes to	yes	buffer, value
in	at least one	no	buffer

Outputs

as	Count	as required
out	at least one	no

threshold

This module takes at least one input y and looks for the position at which the values cross a given threshold. The input threshold is interpreted as a single value (last added element). This module may also take a third input x. If x is defined, it will return the position of the crossing in terms of the associated x value. If x is not defined, position will be the index of the crossing.

You can also define the attribute falling as true to search for a crossing from larger to smaller values.

This module will return exactly one value per call. The threshold has to be crossed: any value not on the trigger side arms the trigger, and the next value on the trigger side fires it — a value exactly equal to the threshold never triggers. NaN values never lie on the trigger side, so they arm the trigger but never fire it. When no crossing is found, the output is NaN. An absent threshold input or an empty threshold buffer selects the default of 0, while a present NaN threshold value participates like any number: no comparison with it is ever true, so no crossing is found.

<threshold falling="BOOLEAN">
    <input as="x">BUFFER</input>
    <input as="y">BUFFER</input>
    <input as="threshold">BUFFER</input>
    <output as="position">BUFFER</output>
</threshold>

Attributes

falling

Search for a crossing from larger to smaller values instead of the other way round.

optional, boolean, default: false

Inputs

as	Count	as required	Allowed types
x	optional	yes	buffer
y	exactly one	yes	buffer
threshold	optional, defaults to 0.0	yes	buffer, value

Outputs

as	Count	as required
position	exactly one	no