- Generated by
1.8.10
|
OpenCurves
0.9
|
Expressions allow plots to be compared against each other using simple expressions. For example, consider a file containing columns for "X" and "X_corrected". An expression comparing the error between the two can be graphed by defining:
X - X_corrected
The expressions UI is used to add, remove and edit expressions.
Expressions are calculated after loading all pending data files and generally relate plots from within the same data file. Expressions support the following syntax and features:
An expression plot will only be visible for files that contain columns matching all expression items.
The domain of an expression is calculated as the union of the domain of expressions parts. In effect, the expression domain is solely derived from the domains of the curves referenced by and bound to the expression. This is because only curves have a well defined domain.
The domain of a curve is determined by the time value of the minimum and maximum time samples for that curve; [tmin, tmax]. This normally corresponds to the time for the first and last samples in the curve. The time is either the zero based index of the sample - [0, N-1] where N is the number of samples - or the corresponding entry in the time column - [tmin, tmax] (see Time and Scaling).
For example, consider the curve S={ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 } and the time column T={ 0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0, 2.25, 2.5 }. The domain of this curve, with time column enabled is [0.25, 2.5].
By contrast, a constant has no fixed, independent domain, and can be evaluated for any time.
Note that some expressions will define a strict time domain, while others may be modified by the time column, time base and time scale. Slicing expressions in particular must define a strict time domain and must be recalculated if the time column, base or scale for the referenced curve changes.
Plot references are matched by name, with optional single or double quotes surrounding the plot name. Quotes are only required if the plot name contains spaces (see Supported Formats) or if the name includes quotes. Below are some examples:
Regular expressions are also supported and perform exhaustive matching. Regular expressions require single or double quotes and are prefixed by an upper or lower case an 'r' (or 'R'). Below are some examples:
Literal or constant values support any valid numeric string. This includes negative numbers and scientific notation in the form '1.534e-3'.
Functions are special operations which may be used in an expression to perform special calculations. Functions accept a number of parameters and accept any valid expression to generate the arguments. Functions are evaluated for each value in the current time series.
For example, the max(x) function returns the maximum value of x so far in the time series. Consider the curve S={ -1, 0, 2, 5, 4, 6, 3, 1, 0 }, then the expression max('S') yeilds { -1, 0, 2, 5, 5, 6, 6, 6, 6 }.
Some expressions, such as maxof(x...) accept a variable number of parameters and may be used to compare the results of other expressions. maxof returns the current maximum sample of any number of expressions. From the previous example, we use S and add a new set U={ 5, 4, 2, 0, -1, 8, 6, 2, 2 } and the expression maxof(S, U, 3). The result is the maximum sample of S and U and the constant 3 at each sample time: { 5, 4, 3, 5, 4, 8, 6, 3, 3 }.
Plot references also support the following advanced features:
Plot references may be indexed using the following syntax:
plot_name[time]
The time may be an expression and uses the value of the 'time' expression to reference a sample in 'plot_name' at the matching time. Returns zero for out of range references.
Slicing syntax may be used to display a smaller portion of the original plot. Slicing syntax is:
plot_name[start:end]
This draws the parts of 'plot_name' between the start and end times (inclusive). Specifying both start and end is optional allowing only a start or end to be specified. The other is assumed to be from first sample, or to the end sample respectively. Examples:
Note that the end slice value is included in the sampling domain. This differs from common slicing notation used in languages such as Python. This is because the slice values represent times rather than indexes.
Also note that a slice expression must be regenerated if the referenced curve changes it's time domain. This occurs when the time column, time base or time scale are changed (consult Time and Scaling for more information).
A plot reference may specify matching only a specific plot file using the following syntax:
plot_file|plot_name
This matches 'plot_name', but only when loaded from 'plot_file'. Note that the 'plot_file' string matches the string which appears in the "Files" list in the Open Curves UI. The file name and plot name are quoted separately. The following quoting patterns are acceptable:
The following quoting pattern is not a file specific reference and will instead look for a column matching the entire string:
Using file specific references, it is possible to generate plots which compare results between different files. For example, consider the expression:
file1|column1 - file2|column1
This will plot the difference between column1 in file1 and file2. The file specification may optionally be quoted usign either single or double quotes. The abs() function can be used to plot only the magnitude of the result:
abs(file1|column1 - file2|column1)
File specific references also support regular expressions. It is possible to compare column1 between all loaded files using the expression:
r'.*'|column1 - r'.*'|column1
Note: since regular expression matching is exhaustive, this will result in mirrored graphs, comparing file1 to file2 and file2 to file1.
Advanced expressions may cause some issues with determining the expression domain. Normally, curves from the same file all have the same domain, thus the domain of any expression referencing multiple curves from the same file is the same as the domain of any expression referencing only one such curve. Advanced curve references may have a different domain. Slicing expressions narrow the domain of the original curve, while file specific references allow files with independent domains to be combined.
This issue is resolved by setting the domain of any expression as the union of the domains of all parts of that expression. Consider the sequence S={ -1, 0, 2, 5, 4, 6, 3, 1, 0 } with time column T={ 1, 2, 3, 4, 5, 6, 7, 9, 10 } and the expression S[:5] - S[7:]. The domain of S is [1, 10], but the domains of S[:5] and S[7:] are [1, 4] and [7, 10] respectively. Note that in practice this is a meaningless expression, however, the expression evaluation proceeds as follows:
S[:5] and S[7:][1, 10]The second step here results in both expressions S[:5] and S[7:] being sampled outside of their domains. This is resolved by simply returning a zero value for such out of range references.
The resulting curve is: S[:5] - S[7:] = { -1, 0, 2, 5, 0, 0, -3, -1, 0 }.
1.8.10