# Difference between revisions of "Analysis modules"

(→reduce) |
|||

Line 682: | Line 682: | ||

=== reduce === | === reduce === | ||

+ | |||

+ | '''Available since phyphox file format 1.7 (phyphox 1.1.0)''' | ||

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. | 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. |

## Revision as of 11:40, 7 October 2018

## Contents

## Basic math

### abs (absolute)

Calculates the absolute value of a single input element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

*value**input**as*not required- Number of inputs: Exactly one

*abs**output**as*not required

### add

Calculates the sum of all inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

*summand**input**as*not required- Number of inputs: At least one

*sum**output**as*not required

### divide

Calculates the quotient of multiple divisors from a single dividend element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

For this simple function you can leave out the *as* attribute. If you do so, the first input will be used as dividend and all subsequent values as divisors.

*dividend**input**as*not required, but order matters if left out- Number of inputs: Exactly one
*divisor**input**as*not required, but order matters if left out- Number of inputs: Arbitrary

*quotient**output**as*not required

### gcd (greatest common divisor)

Calculates the greatest common divisor of two inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

*value**input**as*not required- Number of inputs: Exactly two

*gcd**output**as*not required

### lcm (least common multiple)

Calculates the least common multiple of two inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

*value**input**as*not required- Number of inputs: Exactly two

*lcm**output**as*not required

### log

**Available since phyphox file format 1.5 (phyphox 1.0.7)**

Calculates the natural logarithm of a single input element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

*value**input**as*not required- Number of inputs: Exactly one

*log**output**as*not required

### multiply

Calculates the product of all inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

*factor**input**as*not required- Number of inputs: At least one

*product**output**as*not required

### power

Calculates the power of a base and an exponent element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

*base**input**as*required- Number of inputs: Exactly one
*exponent**input**as*required- Number of inputs: Exactly one

*power**output**as*not required

### round

**Available since phyphox file format 1.5 (phyphox 1.0.7)**

Round the values from the single input element-wise and writes the results to a single output buffer. This module will write as many values as there are values in the input buffer. By default it will round to the nearest integer. The attributes *ceil* and *floor* can change that to the nearest larger integer or the nearest smaller integer.

*floor**attribute**optional*, default: false

*ceil**attribute**optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*round**output**as*not required

### subtract

Calculates the difference of multiple subtrahends from a single minuend element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

For this simple function you can leave out the *as* attribute. If you do so, the first input will be used as minuend and all subsequent values as subtrahends.

*minuend**input**as*not required, but order matters if left out- Number of inputs: Exactly one
*subtrahend**input**as*not required, but order matters if left out- Number of inputs: Arbitrary

*difference**output**as*not required

## Trigonometric functions

### acos

Calculates the inverse cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*acos**output**as*not required

### asin

Calculates the inverse sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*asin**output**as*not required

### atan

Calculates the inverse tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*atan**output**as*not required

### atan2

Calculates the two-argument variant of the inverse tangens (corresponding to atan(y/x)) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*y**input**as*not required- Number of inputs: Exactly one

*x**input**as*not required- Number of inputs: Exactly one

*atan2**output**as*not required

### cos

Calculates the cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*cos**output**as*not required

### cosh

Calculates the hyperbolic cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

*value**input**as*not required- Number of inputs: Exactly one

*cosh**output**as*not required

### sin

Calculates the sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*sin**output**as*not required

### sinh

Calculates the hyperbolic sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

*value**input**as*not required- Number of inputs: Exactly one

*sinh**output**as*not required

### tan

Calculates the tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the *deg* attribute.

*deg**attribute*,**Available since phyphox file format 1.2 (phyphox 1.0.3)***optional*, default: false

*value**input**as*not required- Number of inputs: Exactly one

*tan**output**as*not required

### tanh

Calculates the hyperbolic tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

*value**input**as*not required- Number of inputs: Exactly one

*tanh**output**as*not required

## Statistics

### average

**Available since phyphox file format 1.2 (phyphox 1.0.3)**

This module calculates the average of all values in the input buffer. Optionally (i.e. if the output is connected), the standard deviation is calculated as well (Corrected sample standard deviation).

*buffer**input**as*not required- Number of inputs: Exactly one

*average**output**as*required*stddev**output**as*required

### binning

**Available since phyphox file format 1.2 (phyphox 1.0.3)**

The binning module distributes the values from its input *in* into ranges (bins) and outputs a mapping of these ranges and the number of values in each of them. The bins are set to x0..x0+dx..x0+2dx..x0+3dx etc. Therefore *x0* defines an offset of the bins and *dx* the size of each bin. *x0* defaults to zero and *dx* to 1, so without these, the module defaults to binning to integer intervals.

The output can directly be used to display a histogram. *binStarts* will receive the starting values of each range (bin) while the count is written to *binCounts*.

*in**input**as*not required- Number of inputs: Exactly one
*x0**input**as*required- Number of inputs: One or none
*dx**input**as*required- Number of inputs: One or none

*binStarts**output**as*not required*binCounts**output**as*not required

## Advanced math

### autocorrelation

This module will calculate the autocorrelation. It takes at least one input buffer *y*, but can take a second input *x* as well. If *x* is omitted, it will be filled with indices. Additionally, single value inputs *minX* and *maxX* can be set as well. These limit the x range over which the autocorrelation is calculated to improve performance. The module will return as many values as provided by the input buffer and fill the output buffer *y* with the normalized autocorrelation of the *y* input buffer. The *x* output buffer will be filled with the relative *x* of the autocorrelation based on the *x* input buffer.

*x**input**as*required- Number of inputs: One or none
*y**input**as*required- Number of inputs: Exactly one
*minX**input**as*required- Number of inputs: One or none
*maxX**input**as*required- Number of inputs: One or none

*y**output**as*required*x**output**as*required

### crosscorrelation

This module will calculate a crosscorrelation of two inputs. It will only calculate the part of the crosscorrelation for which the smaller buffer is entirely covered by the larger one. So with one input buffer of size n and one input of size m it will return exactly abs(m-n) values. If you need the crosscorrelation of two buffers of similar size, you will need to pad one of them with zeros first.

*in**input**as*not required- Number of inputs: Exactly two

*out**output**as*not required

### differentiate

Performs a simple differentiation of a single input by calculating the difference of consecutive elements. It will write the result to the output buffer with exactly one value less than there are values in the input buffer.

*in**input**as*not required- Number of inputs: Exactly one

*out**output**as*not required

### fft

This module will perform a fast fourier transform of a complex input and will write the complex result to the output buffers. For input and output the complex data is defined by two buffers *re* and *im* corresponding to the real and imaginary part. The *imaginary* buffer is optional and will be filled with zeros if omitted. This module will return as many values as provided by the input buffer.

*re**input**as*not required- Number of inputs: Exactly one
*im**input**as*required- Number of inputs: One or none

*re**output**as*not required*im**output**as*required

### gausssmooth

This module will smooth the data provided from the only input. The data of each point will be calculated from neighbouring points with a gaussian distribution. The width of this distribution can be controlled by the attribute *sigma* and is interpreted in terms of value indices. This module will output as many values as there are values in the input buffer.

*sigma**attribute**optional*, default: 3.0

*in**input**as*not required- Number of inputs: Exactly one

*out**output**as*not required

### integrate

Performs a simple integration of a single input by summing all elements and returning each step of the summation as a value. It will write as many values as there are values in the input buffer. So, if the input is a three-value array [v1, v2, v3], the output will be [v1, v1+v2, v1+v2+v3].

*in**input**as*not required- Number of inputs: Exactly one

*out**output**as*not required

### periodicity

Mathematically, this module is similar to the autocorrelation module, but is meant to analyse large amounts of data in small subsets. The output is the periodicity of each subset and the x location of this subset. The typical use is a time-based frequency analysis. You put in the recording of a (single frequency) musical melody and the output will be the frequencies as a function of time.

The *x* and *y* inputs take the data to be analyzed and you also need to define a step size *dx* in units of samples. This means, that the data will be split into subsets [0..dx-1], [dx..2dx-1], [2dx..3dx-1], etc. Optionally, you may define an *overlap*, describing the number of samples taken into the calculation from before and after the subset (hence, used in multiple subsets).

The algorithm expects the autocorrelation to be periodic. It looks for the first offset i0 at which it becomes negative and then searches for a maximum in the next positive period at 3*i0..5*i0. You may define an offset range (in samples) by setting *min* and/or *max*. If you do so, the algorithm will just search for a maximum between *min* and *max*. If you can set this range quite narrow, this will speed up the calculation vastly, but if min/max cover multiple periods, this will quite certainly be slower and give wrong results.

While all parameters are defined in samples, the resulting output *time* will be in units of the input *x*.

*x**input**as*required- Number of inputs: Exactly one
*y**input**as*required- Number of inputs: Exactly one
*dx**input**as*required- Number of inputs: Exactly one
*overlap**input**as*required- Number of inputs: One or none
*min**input**as*required- Number of inputs: One or none
*max**input**as*required- Number of inputs: One or none

*time**output**as*required*period**output**as*required

## Buffer operations

### 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 their values appear in the output buffer. This module will return as many value as the sum of the input buffer sizes.

*in**input**as*not required*type="empty"*allowed- Number of inputs: At least one

*out**output**as*not required

### count

**Available since phyphox file format 1.2 (phyphox 1.0.3)**

Returns the number of values in the input buffer

*buffer**input**as*not required- Number of inputs: Exactly one

*count**output**as*not required

### first

Retrieves the first entry of each buffer and appends it to each output buffer.

*value**input**as*not required- Number of inputs: At least one

*first**output**as*not required**Multiple may be defined!**

### match

This module takes multiple inputs and match valid values to the same number of outputs. The module will go through all inputs simultaneously and only return those value 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 as one of both inputs was infinite, not a number ("NaN") or just did not have any more values.

*in**input**as*not required- Number of inputs: At least one

*out**output**as*not required**Multiple may be defined!**

### 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 that are entirely above the threshold and return a maximum and position for each set.

This module will return exactly one value per call if multiple is deactivated (default).

*x**input**as*required- Number of inputs: One or none
*y**input**as*required- Number of inputs: Exactly one
*threshold**input**as*required- Number of inputs: One or none

*max**output**as*required*position**output**as*required

### 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 that are entirely above the threshold and return a minimum and position for each set.

This module will return exactly one value per call if multiple is deactivated (default).

*x**input**as*required- Number of inputs: One or none
*y**input**as*required- Number of inputs: Exactly one
*threshold**input**as*required- Number of inputs: One or none

*min**output**as*required*position**output**as*required

### rangefilter

This module takes multiple inputs and allows to set min and max limits for each of them. The module will go through all inputs simultaneously and only return those value 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.

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 and 42, in2 will not trigger the filter at all (but if in1 or in3 trigger the filter only 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>

*in**input**as*not required- Number of inputs: At least one
*min**input**as*required- Number of inputs: One or none per
*in*input. This always refers to the previously defined*in*buffer. *max**input**as*required- Number of inputs: One or none per
*in*input. This always refers to the previously defined*in*buffer.

*out**output**as*not required**Multiple may be defined!**

### reduce

**Available since phyphox file format 1.7 (phyphox 1.1.0)**

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>

*averageX**attribute**optional*, x values will be averaged to produce x output values, default: false*averageY**attribute**optional*, y values will be averaged to produce y output values, default: false*sumY**attribute**optional*, the y output values will be the sum of the original y value, default: false

*factor**input**as*required- Number of inputs: Exactly one.
*x**input**as*required- Number of inputs: Exactly one.
*y**input**as*required- Number of inputs: One or none.

*x**output**as*required- Number of inputs: Exactly one.
*y**output**as*required- Number of inputs: One or none.

### 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>

*from**input**as*required- Number of inputs: One or none. Defaults to 0

*to**input**as*required- Number of inputs: One or none. Defaults to length of input

*length**input**as*required- Number of inputs: One or none. Defaults to length of input, supersedes
*to*

*in**input**as*not required- Number of inputs: At least one

*out**output**as*not required**Multiple may be defined!**

### threshold

This module takes at least one input *y* and looks for 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.

*falling**attribute**optional*, default: false

*x**input**as*required- Number of inputs: One or none
*y**input**as*required- Number of inputs: Exactly one
*threshold**input**as*required- Number of inputs: One or none (defaults to 0.0)

*position**output**as*not required

## Data genreation

### const

This module will initialize a buffer to a constant value. Both inputs are optional and without any inputs it will fill the entire buffer with zero. If *value* is set, the buffer gets filled with this value and if *length* is set, only 'length* values will be initialized. (This is usefull in combination with the *append* module to zero-pad a buffer.)*

*value**input**as*required- Number of inputs: One or none
*length**input**as*required- Number of inputs: One or none

*out**output**as*not required

### ramp

This module will create a ramp of values, i.e. a linear range of values. This is very usefull to create time bases for example for audio recordings. The module takes as inputs *start*, *stop* and the optional *length*. It will make that the first value is exactly *start* and the last value is *stop*. It will return *length* values or if *length* is not provided as many values as the size of the output buffer.

*start**input**as*required- Number of inputs: Exactly one
*stop**input**as*required- Number of inputs: Exactly one
*length**input**as*required- Number of inputs: One or none

*out**output**as*not required

### timer

Simple module which just outputs the (fractional) seconds that have past since the first analysis run started and the current analysis run began.

*out**output**as*not required

## Logic

### if

**Available since phyphox file format 1.3 (phyphox 1.0.4)**

The if module is the phyphox equivalent to the if-statement of a programming language. It takes two inputs a and b and will behave differently depending on the relation of the last values found there. By changing the attributes *less*, *equal* or *greater*, you can decide whether you are looking for a < b, a = b or a > b, respectively. If the relation is true, the if-module will write the data from the input *true* to the output, otherwise it will write the data from the input *false*. If you enable multiple attributes, the input *true* is used if any of them is fulfilled, so if you enable *less* and *equal*, a <= b will write the *true* input to the output, while a > b writes the *false* input.

Since version 1.4 (phyphox 1.0.6) you may set an input to be of the type *empty*. Effectively, this does not change the output as nothing is written, but can make sense in combination with setting the output to *clear*. In this case, the if module behaves somewhat special as it only clears its output if a matching input is connected. For example if you set the true input to *empty*, do not connect the false input and set the output to *clear*, it will only clear the output if the condition is true, but leaves it alone otherwise. This can be used as a reset condition. Note, that since the visual editor does not support reusing buffers, you probably cannot do this there in a reasonable way...

*less**attribute**optional*, default: false*equal**attribute**optional*, default: false*greater**attribute**optional*, default: false

*a**input**as*not required- Number of inputs: Exactly one
*b**input**as*not required- Number of inputs: Exactly one
*true**input**as*not required*type="empty"*allowed- Number of inputs: Exactly one
*false**input**as*not required*type="empty"*allowed- Number of inputs: Exactly one

*out**output**as*not required