Advanced math¶
The <input> and <output> tags of every module on this page additionally accept the attributes common to all analysis modules.
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 restrict the output to the given x range. Without them the module returns as many values as provided by the input buffer; with them only the lags within the range are returned. The output buffer y is filled with the autocorrelation of the y input buffer, each lag divided by the number of samples that overlap at that lag - so the value at lag zero is the mean square of the input, not 1. The x output buffer is optional; if connected, it will be filled with the relative x of the autocorrelation based on the x input buffer.
<autocorrelation>
<input as="x">BUFFER</input>
<input as="y">BUFFER</input>
<input as="minX">BUFFER</input>
<input as="maxX">BUFFER</input>
<output as="y">BUFFER</output>
<output as="x">BUFFER</output>
</autocorrelation>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
x |
optional | yes | buffer |
y |
exactly one | yes | buffer |
minX |
optional, defaults to no lower bound | yes | buffer, value |
maxX |
optional, defaults to no upper bound | yes | buffer, value |
Outputs
as |
Count | as required |
|---|---|---|
y |
optional | yes |
x |
optional | yes |
butterworth¶added in 1.20
This module represents the transfer function of a Butterworth filter. It takes the order n and (upper) cutoff frequency as inputs and acts as a low pass. Optionally, you can also provide a positive lower cutoff frequency as cutoffLow, in which case it acts as a bandpass (a cutoffLow of zero keeps it a low pass). The x input needs to provide frequencies for each data point of the y input. Frequencies are taken as absolute values for the filter. The module multiplies the y values by the magnitude of the filter's transfer function at their frequencies, so you want to use it together with the fft module.
<butterworth>
<input as="y">BUFFER</input>
<input as="x">BUFFER</input>
<input as="n">BUFFER</input>
<input as="cutoff">BUFFER</input>
<input as="cutoffLow">BUFFER</input>
<output as="filtered">BUFFER</output>
</butterworth>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
y |
exactly one | yes | buffer |
x |
exactly one | yes | buffer |
n |
exactly one | yes | buffer, value |
cutoff |
exactly one | yes | buffer, value |
cutoffLow |
optional | yes | buffer, value |
Outputs
as |
Count | as required |
|---|---|---|
filtered |
exactly one | no |
crosscorrelation¶
This module will calculate a crosscorrelation of two inputs. It will only calculate offsets at which the smaller buffer is entirely covered by the larger one, leaving out the last such offset. 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.
The output values are the raw correlation sums without any normalization, matching the default of numpy.correlate, scipy.signal.correlate and MATLAB xcorr. Any empty input yields an empty output.
<crosscorrelation>
<input as="in">BUFFER</input>
<output as="out">BUFFER</output>
</crosscorrelation>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
in |
exactly 2 | no | buffer |
Outputs
as |
Count | as required |
|---|---|---|
out |
exactly one | no |
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 fewer than there are values in the input buffer.
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
in |
exactly one | no | buffer |
Outputs
as |
Count | as required |
|---|---|---|
out |
exactly one | no |
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 (the full complex spectrum is returned either way, not a shortened real-input half). A provided im input, in contrast, truncates the transform to the shorter of re and im.
Provide a power-of-two number of input samples: only then is the output guaranteed to be identical on both platforms. This lets the module use the fastest transform each platform offers. For other input lengths the result is implementation-defined and differs between platforms; a separate general-purpose dft module (slower, exact input length) is planned for those cases.
The platforms differ here by design: FFT output for input lengths that are not a power of two
A non-power-of-two number of input samples yields a different output length and different values on the two platforms; a power-of-two input gives identical results on both.
The contract: fft uses the fastest transform each platform offers, so only a power-of-two number of input samples is guaranteed to give identical results on both platforms - an experiment that needs a portable FFT must provide that. Any other length is implementation-defined. For exact transforms of arbitrary length a separate, slower dft module is planned; until it exists, non-power-of-two input is simply outside the guaranteed contract.
This difference is permanent and documented - account for it when writing portable experiments.
| Implementation | Current behaviour |
|---|---|
| Android | FFTW transforms the input length directly, and the Java fallback zero-pads internally but truncates back, so the output length always equals the input length (analysis.cpp fftw3complex, Analysis.java fftAM). |
| iOS | vDSP_DFT only accepts lengths of the form f*2^n with f in {1, 3, 5, 15}, so other inputs are zero-padded to the next supported length and the padded, longer spectrum is returned (FFTAnalysis.swift, nextFFTSize). |
<fft>
<input as="re">BUFFER</input>
<input as="im">BUFFER</input>
<output as="re">BUFFER</output>
<output as="im">BUFFER</output>
</fft>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
re |
exactly one | no | buffer |
im |
optional | yes | buffer |
Outputs
as |
Count | as required |
|---|---|---|
re |
optional | no |
im |
optional | yes |
gausssmooth¶
This module will smooth the data provided from the only input. The data of each point will be calculated from neighboring 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. An omitted or empty sigma attribute selects the default of 3; a present value must be greater than zero. This module will output as many values as there are values in the input buffer.
<gausssmooth sigma="FLOAT">
<input as="in">BUFFER</input>
<output as="out">BUFFER</output>
</gausssmooth>
Attributes
- sigma
- Width of the Gaussian distribution used to smooth the data, in terms of value indices.
- optional, float, default:
3.0
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
in |
exactly one | no | buffer |
Outputs
as |
Count | as required |
|---|---|---|
out |
exactly one | no |
interpolate¶
Interpolates input data. It takes x and y values from the source data and a buffer with x values at which to interpolate the y input data. The attribute method determines the method for interpolation, which can be previous (the y value corresponding to the x value immediately preceding the x value at which the data is to be interpolated), next (the y value corresponding to the x value immediately succeeding the x value at which the data is to be interpolated), nearest (the y value corresponding to the nearest x value to the x value at which the data is to be interpolated) and linear (the y value is interpolated linearly). In all cases, the first or the last y value is simply reused if the evaluated x value is entirely outside the range of the input x values.
Note that both x and xi need to be monotonic (i.e. ordered).
<interpolate method="STRING">
<input as="x">BUFFER</input>
<input as="y">BUFFER</input>
<input as="xi">BUFFER</input>
<output as="out">BUFFER</output>
</interpolate>
Attributes
- method
- See the module description.
- optional, one of
nearest,previous,next,linear, default:linear
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
x |
exactly one | yes | buffer |
y |
exactly one | yes | buffer |
xi |
exactly one | yes | buffer, value |
Outputs
as |
Count | as required |
|---|---|---|
out |
exactly one | no |
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].
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
in |
exactly one | no | buffer |
Outputs
as |
Count | as required |
|---|---|---|
out |
exactly one | no |
loess¶
Smooths data using locally estimated scatterplot smoothing (LOESS) aka local regression. It takes x and y data as well as a list of x values at which to generate smoothed y values. Additionally, you have to set the width of the windowing function (tri-cubic window). Smoothed data can be generated at the same x positions as the source data or anywhere as long as it is near the source data, so that it contributes within the window width. Both the x data and the xi values need to be monotonically increasing.
Optionally, you can use three outputs to directly get the local fit parameters yi0, yi1 and yi2 to the function y(x) = yi0 + yi1 * x + yi2 * x². In this formula, the axis for x is shifted such that x=0 is in place of the evaluated position xi. If the input is position data versus time, these parameters are great estimates for a (smoothed) position, the momentary velocity and the momentary acceleration. Note that if you describe the location as a function of time from an initial location, velocity and acceleration, you would have the formula y(t) = y0 + v*t + 1/2 a*t², so if you want to extract location y0, velocity v and acceleration a from the fit parameters, you need to multiply yi2 by two as yi2 = a/2.
The window width d is read as a single value (last added element of its buffer); a non-positive or non-finite d is an error yielding empty outputs.
<loess>
<input as="x">BUFFER</input>
<input as="y">BUFFER</input>
<input as="d">BUFFER</input>
<input as="xi">BUFFER</input>
<output as="yi0">BUFFER</output>
<output as="yi1">BUFFER</output>
<output as="yi2">BUFFER</output>
</loess>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
x |
exactly one | yes | buffer |
y |
exactly one | yes | buffer |
d |
exactly one | yes | buffer, value |
xi |
exactly one | yes | buffer, value |
Outputs
as |
Count | as required |
|---|---|---|
yi0 |
exactly one | no |
yi1 |
optional | yes |
yi2 |
optional | yes |
periodicity¶
Mathematically, this module is similar to the autocorrelation module, but is meant to analyze 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. A non-positive, non-finite or empty dx yields empty outputs. Fractional bounds are treated conservatively: min is rounded down and max is rounded up, so periods on the boundary are included in the search.
<periodicity>
<input as="x">BUFFER</input>
<input as="y">BUFFER</input>
<input as="dx">BUFFER</input>
<input as="overlap">BUFFER</input>
<input as="min">BUFFER</input>
<input as="max">BUFFER</input>
<output as="time">BUFFER</output>
<output as="period">BUFFER</output>
</periodicity>
Inputs
as |
Count | as required |
Allowed types |
|---|---|---|---|
x |
exactly one | yes | buffer |
y |
exactly one | yes | buffer |
dx |
exactly one | yes | buffer, value |
overlap |
optional | yes | buffer, value |
min |
optional | yes | buffer, value |
max |
optional | yes | buffer, value |
Outputs
as |
Count | as required |
|---|---|---|
time |
optional | yes |
period |
optional | yes |