Equation Syntax
DataView uses the muParser library developed by Ingo Berg for solving user-defined equations. Full details of this are available on the developer's web page, but essentially, you write mathematical equations in natural order, using the pre-defined functions and operators listed below (the listing is taken from the library's home page, with a few DataView-specific additions).
Some example equations are given here.
Changes in expression syntax introduced in v11.17.1 are given below.
Parser Syntax
DataView-specific
Variables
| xt | Represent the current sample time. |
| x1 - x128 | Represent the data values of traces 1 - 128 at the current sample time. |
Functions
| rndu() | Return a random number drawn from a uniform distribution (0 <= x < 1). |
| rndn() | Return a random number drawn from a normal distribution (mean 0, standard deviation 1). To convert this to a number from a distribution with mean m and standard deviation s, simply enter (m+s*rndn()) where m and s are replaced by the desired actual numbers. If written as successive samples in a trace, this generates white noise (where all frequencies have equal power). |
| rndp() | Return a random number drawn from a pink noise distribution with an approximate mean of 0 and standard deviation of 1. If written as successive samples in a trace, pink noise (1/f noise) has power at each frequency that is inversely proportional to the frequency. This means that pink noise has more low frequency components than white noise. |
| rndo(t) | Return a random number generated from an Ornstein-Uhlenbeck stochastic process with a time constant t. This effectively generates exponentially-filtered white noise (Linaro et al., 2011), so there is auto-correlation in which successive samples depend to a greater or lesser extent on the value of the previous sample, with the extent determined by the time constant. |
| fmod(x,y) | Return the floating-point remainder of x / y. [If y = 0 the calculation continues but returns not-a-number, leading to indeterminate result.] |
| erf(x) | Return the Gaussian error function of x. |
Built-in functions
The following table gives an overview of the functions supported by the default muParser implementation. It lists the function names, the number of arguments and a brief description.
| Name | Argc. | Explanation |
| sin | 1 | sine function |
| cos | 1 | cosine function |
| tan | 1 | tangent function |
| asin | 1 | arcus sine function |
| acos | 1 | arcus cosine function |
| atan | 1 | arcus tangent function |
| sinh | 1 | hyperbolic sine function |
| cosh | 1 | hyperbolic cosine |
| tanh | 1 | hyperbolic tangent function |
| asinh | 1 | hyperbolic arcus sine function |
| acosh | 1 | hyperbolic arcus tangent function |
| atanh | 1 | hyperbolic arcur tangent function |
| log2 | 1 | logarithm to the base 2 |
| log10 | 1 | logarithm to the base 10 |
| log | 1 | logarithm to base e (2.71828...) |
| ln | 1 | logarithm to base e (2.71828...) |
| exp | 1 | e raised to the power of x |
| sqrt | 1 | square root of a value |
| sign | 1 | sign function -1 if x<0; 1 if x>0 |
| rint | 1 | round to nearest integer |
| abs | 1 | absolute value |
| min | var. | min of all arguments |
| max | var. | max of all arguments |
| sum | var. | sum of all arguments |
| avg | var. | mean value of all arguments |
Built-in constants
| _pi | pi: 3.14159265358979 |
| _e | e: 2.71828182845905 |
Built-in operators
Binary
The following table lists the default binary operators supported by the parser.
| Operator | Description | Priority |
| = | assignment | -1 |
| && | logical and | 1 |
| || | logical or | 2 |
| <= | less or equal | 4 |
| >= | greater or equal | 4 |
| != | not equal | 4 |
| == | equal | 4 |
| > | greater than | 4 |
| < | less than | 4 |
| + | addition | 5 |
| - | subtraction | 5 |
| * | multiplication | 6 |
| / | division | 6 |
| ^ | raise x to the power of y | 7 |
Ternary
muParser supports the if then else operator ? :. It uses lazy evaluation to make sure only the necessary branch of the expression is evaluated.
| Operator | Description | Remarks |
| ? : | if-then-else operator | C++ style syntax. The syntax is: logical_expression ? value_if_true : value_if_false |
Examples
- Generate a waveform containing random numbers drawn from a normal (Gaussian) distribution with a mean of 3.5 and a standard deviation of 1.7:
3.5 + 1.7 * rndn()
- Generate a waveform that is the point-by-point sum of the values in pre-existing traces 1, 3 and 5:
x1 + x3 + x5
or
sum(x1, x3, x5) - Generate a waveform that is largest of the point-by-point values in pre-existing traces 1, 3 and 5:
max(x1, x3, x5)
- Generate a waveform that has a standard normal distribution between 200 and 600 time units, and has the value of pre-existing trace 1 at all other times:
xt < 200 || xt > 600 ? x1: rndn()
- The expression sin(f * 2 * _pi *xt / 1000) will generate a sine wave with the frequency f, if you substitute the actual value of f into the expression.
Generate a 50 Hz sine waveform:sin(50 * 2 * _pi * xt / 1000)
- Generate a sawtooth waveform, with a period of 100 ms and a peak amplitude of 0.5:
0.5 * fmod(xt, 100) / 100
- Generate a ramp waveform that starts at 500 and lasts for 1000 ms. The stimulus has an initial value of 0 and a final value of -0.04:
xt <= 500 ? 0 : xt > 1500 ? -0.04 : -0.04 * (xt - 500) / 1000
- Generate a triangle waveform with a maximum value of 2, starting after 200 ms, with on and off ramps 500 ms in duration:
xt <= 200 || xt > 1200 ? 0 : xt < 700 ? 2 * (xt - 200) / 500 : 2 - 2 * (xt - 700) / 500
Breaking changes from pre v11.17
- The constant value pi is now written as _pi (i.e. with a preceding underscore).
- The random variables rndu, rndn and rndp are now written as functions rndu(), rndn() and rndp() and require the inclusion of brackets.
Parser License
The muParser library has the following license. Note that this applies to the parser library software, not to DataView as a whole.
Copyright (c) 2016 Ingo Berg
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.