9. Formulas, Filters and Calculations¶
Answers to frequent questions about formula channels, formula tables, curve filters, interpolation, field functions and unit conversion.
9.1. Creating and managing formula channels¶
9.1.1. How do I remove a formula channel or an old formula that keeps being calculated?¶
Registered formulas (option Register Formula in the formula dialog) are stored as .ic files and re-evaluated independently of the channels in the data file. “Remove Channels” in the Data Editor does not remove them for good.
Open Tools > Formula List…. The window lists the loaded formulas. Select the formula and delete it.
In the Data Editor (Edit button of the Data Browser), right-click and choose Remove all Formula Channels to remove the formula channels already stored in the open file.
See also: Tools=>Formulalist, The Add/Edit Formula Channel Dialog Box.
9.1.2. Why does a saved multi-line formula fail, and do I need a semicolon at the end of each line?¶
Yes. In multi-line formulas every line must end with a semicolon (;). Without it some formulas still work, but many cause errors, for example when a saved formula is added again in the formula editor.
The formula editor adds only one formula per call (name = formula, then OK). To add several formulas at once, use Tools > Excel Formula Table > Import from Excel File…. All formulas known to UniPlot are listed in Tools > Formula List….
See also: The Add/Edit Formula Channel Dialog Box, Tools=>Excel Formula Table=>Import from Excel File.
9.1.3. How can I transfer my formulas to another computer?¶
Registered formulas are stored as .ic files in the Formula folder of the UniPlot home directory (see Tools > More Options > Paths and Files > User Home Directory).
Zip the
Formulafolder.Copy the files into the
Formulafolder of the home directory on the other computer.Restart UniPlot.
If the folder is configured differently, the search path is set in Tools > Formula Configuration… (Search Path for Formula Interpreter Functions; new formulas are added to the last specified directory). All formulas of the directory are also stored in one library file formula.icl9. Keep the formula directory on a local drive (see Formula channels are not recalculated and channels are not found when I exchange data after restarting UniPlot. What can cause this?).
See also: Tools=>Formula Configuration, Defining Formulas.
9.1.4. How can a formula replace a channel with the same name every time a file is imported?¶
By default, the result of a formula overwrites a channel with the same name in the data file. Formulas are calculated during import if Calculate Formulas during Import is set.
To keep the measured (imported) channel instead, set the option Do not overwrite imported channels with formula channels in Tools > Formula Configuration…. Then only formulas whose result channel does not exist in the file are calculated.
To modify channels during import with your own code, define the UniScript callback function OnImportUpdateNCFile(ssNetCDFName). If it is defined, UniPlot calls it for every imported data file:
Create an
.icfile containingdef OnImportUpdateNCFile(ssNetCDFName){ ... }and place it in theautoloadfolder of the user home directory.Inside the function, restrict the calculation to the files and channels you need.
After the calculation, set a new channel attribute (for example
calc = 1) and test it at the start, so that the channel is not calculated again when the file is reloaded. Otherwise an offset would be added repeatedly.
See also: Formula Interpreter 1 - Introduction.
9.1.5. How do I use the OnlyIf condition to apply a formula only to certain files?¶
An OnlyIf condition is defined by a UniScript function whose name starts with _fiis_ followed by the condition name in lowercase letters. The function returns TRUE or FALSE. It has access to the open NC file, so it can test global attributes or the file name:
def _fiis_mytest()
{
ncid = get_ncid();
if (ncid == -1) { error(); return FALSE; }
ssFileName = nc_filename(ncid);
svPath = SplitPath(ssFileName);
if (strmatch("*_MyTest_*", svPath[3])) { return TRUE; }
return FALSE;
}
Enter only the condition name (here mytest, without the prefix _fiis_) in the OnlyIf column of the formula table.
To choose between several calculations without a condition, you can also use alternative formulas (see How can I define a formula that uses channel1 if it exists and otherwise channel2?).
See also: Definition of a Condition, Formula Interpreter 3 - Creating Script Formulas.
9.2. Formula tables and Excel import¶
9.2.1. How do I import formulas from an Excel formula table so that the calculated channels appear?¶
Formula channels are only created after the formula table has been imported.
Save the formula table as an Excel file (cell A1 must contain
UniPlotFormulaTable, see What is the format of the UniPlot formula table?).Choose Tools > Excel Formula Table > Import from Excel File…, select the file and confirm. Set the file type filter to All files to select a macro-enabled
.xlsmfile.A message reports success or errors. Confirm with OK.
Check the imported formulas in Tools > Formula List….
The new formulas are not yet computed for the data file that is already loaded. Open the Data Browser edit mode with Edit and press F9 to recompute all formulas.
From then on, formula channels are created and updated automatically whenever a data file is imported, provided the channels required by the formulas exist in the file. If calculated channels are missing on one PC but present on a colleague’s PC with the same files, the formula table was probably not imported on the first PC.
See also: Tools=>Excel Formula Table=>Import from Excel File, Formula Import from an Excel Workbook, Tools=>Formulalist.
9.2.2. What is the format of the UniPlot formula table?¶
The formula table is an Excel sheet (or a text file) with one formula per row. It suits simple, short formulas.
Cell A1 must contain the string
UniPlotFormulaTable(orUniPlotFormelTabelle).The second row contains the column headers.
Blank rows and comment rows are allowed. A comment row has a first-column cell that starts with
#. Formulas can be commented out the same way.Every other row defines one formula.
The table has 9 columns: FunctionName, Description, Unit, Output, Formula, OnlyIf, Numberformat, Use SI-Units and Comment. The Use SI-Units column was added in R2013.11; before that the comment was in column 8, so an old table with 8 columns needs an additional (empty) column 8 in front of the Comment column. An example table is available in the samples folder of the installation.
To add the @ prefix to the Output entry (which disables missing-value handling for that formula), format the Output column in Excel as Text; otherwise Excel does not accept @ as first character.
See also: The Formula Table, Formula Interpreter 2 - Creating a formula table.
9.2.3. How can I define a formula that uses channel1 if it exists and otherwise channel2?¶
The formula editor only accepts formulas whose channels exist in the file (error “unknown channel name”), so an existence test is not possible there. Use alternative formulas instead: several formulas that all create the same result channel, defined in a formula table and imported with Tools > Excel Formula Table > Import from Excel File….
Example: the formulas Result_a, Result_b and Result_c all create the channel Result. UniPlot sorts the formula names alphabetically and tries Result_a first. If it can be evaluated, all other formulas creating the same channel are ignored. Otherwise Result_b is tried, and so on. Order the names so that the preferred formula comes first after sorting (you can test the order with sort(["Result_a", "Result_b"]) in the UniScript terminal).
If a formula result is unexpectedly missing, check that no constant has the same name as a formula channel. This makes formula generation fail. A constant cannot be used to fill in missing values of a formula.
9.3. Formula functions and recipes¶
9.3.1. The formula max(…) or min(…) with more than 5 channels gives warning F0007 “wrong number of parameters”. What can I do?¶
The formula functions max, min and mean accept at most 5 arguments. With more arguments, the formula check logs warning F0007 with the text “Error in no of parameters in function”.
For more channels, nest the calls, for example max(max(c1, c2, c3, c4, c5), max(c6, c7, c8)). You can also build the result in stages. For ten channels:
Alpha = max(c1, c2, c3, c4, c5)
Bravo = max(c6, c7, c8, c9, c10)
Charlie = max(Alpha, Bravo)
Do the same for min. For many channels (for example 100 or more) or for statistics per record across all channels, write a UniScript that loops over the channels.
See also: Functions in Formulas, mean.
9.3.2. How do I get a single value (for example the maximum of a channel) into a table cell?¶
The formula interpreter creates channels with one result per input value, so max(c) returns the maximum repeated for every sample. To show the scalar in a table cell, use a field function in the text of the cell instead, for example @f{xystatvalue(Data1, ymax)} for the maximum of the dataset Data1 (see Field Functions).
See also: Field Functions, Formula and Latex Text.
9.3.3. How can I calculate the process capability index Cpk and show it in a diagram?¶
UniPlot has no dedicated Cpk function. Calculate Cpk with formula channels based on the formula functions mean() and std().
Example for a channel x with the lower limit LSL = 10 and the upper limit USL = 20:
x_mean = mean(x)
x_std = std(x)
Cpu = (20 - x_mean) / (3 * x_std)
Cpl = (x_mean - 10) / (3 * x_std)
Cpk = min(Cpu, Cpl)
Each result channel contains the same value for every sample. To show Cpk as a number in a text box or table cell, use a field function:
@f{ncvaluefromdata(Data1, Cpk, 1, %.2f)}reads the first value of the channelCpk.Data1must be a dataset of the same data file.Alternatively, plot the
Cpkchannel and use@f{xystatvalue(...)}on that dataset.
See also: Functions in Formulas, @f{ncvaluefromdata}, How do I get a single value (for example the maximum of a channel) into a table cell?.
9.3.4. How can I compute the average of the first N points of a channel, or a running average from the first point?¶
Divide the cumulative sum by the point counter:
Running average from the first point:
cumsum(Temperature)/counter()Average of the first 400 points (a single value):
get_val_at(cumsum(Temperature)/counter(), 400)
get_val_at(c, i) returns one value of the channel (a negative index counts from the end).
A formula such as mean(Temperature1, ..., Temperature400) does not work. The arguments of mean are channels, not data points, and at most 5 arguments are allowed (see The formula max(…) or min(…) with more than 5 channels gives warning F0007 “wrong number of parameters”. What can I do?).
See also: cumsum, Functions in Formulas, The formula max(…) or min(…) with more than 5 channels gives warning F0007 “wrong number of parameters”. What can I do?.
9.3.5. How does smooth_time work, and what TimeWindow do I need for a 4 second running average?¶
smooth_time(c, TimeChannel, TimeWindow) computes a centred running average. TimeWindow is the full width of the window, in the unit of the time channel. For a 4 s running average use TimeWindow = 4: each value is averaged from x-2 s to x+2 s.
UniPlot converts the time window into a number of points. It uses the sampling interval at the start of the time channel, so the channel should be sampled evenly. On each side of a value the window is limited to 5 % of the points of the channel (and to 5000 points). For channels with few points, large windows therefore all give the same result. Use a smaller window.
Example: Ratio_s = smooth_time(Ratio, time, 1)
See also: Functions in Formulas.
9.3.6. How can I shift a channel in time or by a number of points (for example a gas transport time correction)?¶
By a number of points (fixed sample rate):
shift_points(c, nPoints, rsMissing)shifts the channel (positive values to the right, negative values to the left). The vacated points are set torsMissing.By a time (non-uniform sample rate): use the add-in Gas Response Time Correction (Tools > Gas Response Time Configuration…), which shifts signals by a delay time during the data import.
Offset set in a diagram: an X offset applied to a signal in a diagram only changes the plotted XY dataset, not the channel in the NC file, so formula channels based on it are not recalculated. Put
shift_pointsinto the formula so that the shift is part of the file.
Example for a jump over ten points: jump = CHANNEL - shift_points(CHANNEL, -10, 0)
See also: Gas Response Time Correction, Functions in Formulas.
9.3.7. How do I split a signal into a positive-only and a negative-only curve?¶
Create two formula channels:
Channel1_negative_data = if_then_else(compare_less(Channel1, 0), Channel1, 0)
Channel1_positive_data = if_then_else(compare_greater(Channel1, 0), Channel1, 0)
Alternatively, apply a filter on the dataset that removes the unwanted values.
See also: Functions in Formulas.
9.3.8. How can I detect a threshold crossing (for example a voltage drop) automatically?¶
Create a formula channel with crossings(rvData, rsThreshold). It returns 1 where the signal crosses the horizontal threshold (rising or falling) and 0 elsewhere, for example crossing_v1 = crossings(volt_cell_1, 4). Plot the channel together with the signal and set the cursors on the crossing events. A relative criterion (for example a 25 percent drop or a rate of 0.1 V/s) needs an additional formula, for example based on the derivative.
See also: crossings(rvData, rsThreshold).
9.3.9. How can I number charge and discharge cycles and compute the duration of each cycle?¶
Create a cycle counter channel that increments at each phase change, then integrate the time with a reset at each new cycle:
cycle = cumsum((abs(diff(current))-diff(current))/2/max(current))
cycle_duration_integral = integral_withreset(time, diff(time), cycle, 0)
Plot current, cycle and cycle_duration_integral. Right-click the cycle_duration_integral curve and choose New Dataset > Find Peaks… (also available in Data > More Data Functions…). Select the type Maximum (Peaks) and keep Label Points switched on: the labels show the duration of each cycle. Filling text boxes or a table automatically with one value per cycle is not available.
See also: integral_withreset(x, y, rsYResetThreshold or idx_vector, bEndValueOnly), integral_withreset2(x, y, bool_channel_01, bEndValueOnly).
9.3.10. How do I integrate a signal and reset the integral when it exceeds a threshold?¶
Use the formula function integral_withreset_thd(x, y, Threshold), which resets the integral to 0 when the integral of Y over X goes above the threshold (available since R2022.2). To reset the integral when the y value crosses a threshold from below, use integral_withreset(x, y, rsYResetThreshold, bEndValueOnly). If you get only step values per section instead of an integration curve, check that bEndValueOnly is 0.
See also: integral_withreset_thd(x, y, Threshold), integral_withreset(x, y, rsYResetThreshold or idx_vector, bEndValueOnly).
9.3.11. How do I calculate a running (cumulative) maximum of a channel?¶
There is no built-in running-maximum formula function. Define your own function as a script formula in UniScript and place it in the autoload folder of the user home directory (the path is returned by GetUserDirectory()). After a restart the function appears in the formula calculator drop-down.
If the function is not found, check that:
the
autoloadfolder is inside the user directory,the folder is not on a network share,
UniPlot was not started with
/NoAutoLoad.
See also: Formula Interpreter 3 - Creating Script Formulas, User Defined Functions.
9.3.12. The functions asin() and acos() give “unknown function” in the formula editor. How can I use them?¶
The inverse trigonometric functions asin(c) and acos(c) are available in current releases; older releases do not offer them. Update UniPlot.
See also: Functions in Formulas.
9.3.13. In R2026.1 get_ncid() is reported as “function not found” when formulas are loaded during import. What should I use?¶
In R2026.1 the formula function get_ncid() was renamed to _FE_get_ncid() to stress that it returns the ncid of the file currently under formula evaluation. From R2026.2 on, get_ncid() works again and _FE_get_ncid() is kept, so both names compile. With R2026.1, use _FE_get_ncid() or update.
9.3.14. How do I convert AVL Concerto formulas to UniPlot formulas?¶
UniPlot formulas work on whole channels and have no create, reduce, new or for-loop constructs, so a direct translation is not possible. Typical equivalents:
Yvalory[-1]:get_val_at(channel, -1)count:len()Conditions:
if_then_else(bool, a, b)with comparison functions such ascompare_greaterequalnew: right-click a channel > Add Channelround: set the number of decimals in the formula editorjump:jump = CHANNEL - shift_points(CHANNEL, -1, 0)(use-10for ten points)
See also: Functions in Formulas.
9.3.15. Can I use if/else logic in a formula, and how do I combine channels of different sizes?¶
Use if_then_else(bool, a, b) in the formula channel dialog. Channels used in one formula normally must have the same number of points (see How can I apply a formula to channels with different numbers of points or sampling rates?). To mix a channel with a scalar, take a single value with get_val_at first:
BT_Battery_bool_1 = get_val_at(BT_Battery_bool, 1);
BT_BatteryVoltage_cst_1 = get_val_at(BT_BatteryVoltage_cst, 1);
BatVoltage = if_then_else(BT_Battery_bool_1, BT_BatteryVoltage, BT_BatteryVoltage_cst_1);
BT_BatteryVoltage_2 = 2 * BatVoltage
In UniScript read the data into vectors and implement the condition with vector operations or a loop.
See also: Functions in Formulas.
9.4. Missing values, sampling rates and recalculation¶
9.4.1. How can I apply a formula to channels with different numbers of points or sampling rates?¶
For MDF, BLF, Famos and ASAM-ODS data, the formula interpreter interpolates all channels used in a formula to the time base of the channel with the most points. For all other file types, all channels of a formula must have the same number of points.
For files with several sampling rates this works correctly only if the file defines channel groups (as MDF/MF4 files do). To create groups manually, set the global attribute _nc_hasgroups to 1 and a channel attribute _nc_group per channel (for example 1Hz, 10Hz). It is currently not possible to choose the sampling rate or time vector of a formula channel. As a workaround, resample the whole file: click Edit in the Data Browser, right-click and choose More Functions > Channel Interpolation….
Formulas between channels of different files are not possible. Bring the data into one file or calculate in a UniScript, where ch() gives access to other channels of the same NC file. For findfirst the X axis must be monotonic.
See also: Formula Interpreter 1 - Introduction, Browser=>Interpolation.
9.4.2. How can a formula be calculated when some input channels are missing or contain invalid values?¶
Formulas with missing input channels are ignored. To provide a default, create a formula channel with the same name as the missing channel and a constant value (for example T2 = 100). To keep a measured channel with the same name, set the option Do not overwrite imported channels with formula channels in Tools > Formula Configuration….
For channels that are present but contain “Missing Values”, use replace_missings(c1, value) (clear the option Handle Missing Values in the formula dialog first):
T_Average = mean(replace_missings(T1,100), replace_missings(T2,100), replace_missings(T3,100))
See also: Channels with Missing Values, The Add/Edit Formula Channel Dialog Box.
9.4.3. A calculated channel based on a channel created with “replace values” still contains missing values. Why?¶
Update UniPlot. Releases before R2021.1 did not handle missing values correctly in the formula function min() (fixed in R2021.1), and cumsum did not handle missing values correctly before R2020.2. If the formula min(A*C) returns a missing value although the same calculation in separate steps works, this is the cause.
See also: Channels with Missing Values.
9.4.4. Formula channels are not recalculated and channels are not found when I exchange data after restarting UniPlot. What can cause this?¶
A typical cause is a formula folder (formula library) on a network drive, even one that is available offline. UniPlot may then not be able to use the formulas reliably. Copy the formula files to a local drive and assign the local folder as the formula directory in Tools > Formula Configuration…. In general keep resources such as formulas, templates and scripts on local drives.
See also: Tools=>Formula Configuration.
9.4.5. Formula channels are not recalculated after a data exchange with NC2 files. How can I recalculate?¶
For non-NC sources, a data exchange with re-import recalculates the formulas. For NC2 data files the formulas are calculated before the data exchange is executed since R2020.1. If formula channels are still outdated after a data exchange (for example in older releases), recalculate them:
Load the NC2 file into the Data Browser (File > Import Data…, or right-click the dataset in the diagram > Open Datafile).
Open it with the Edit button.
Press F9 once. All formula channels are recalculated and updated.
See also: The Data Editor, The Data Browser Window.
9.4.6. Why does a formula channel ignore the offset and scale attributes of an input channel?¶
Formulas use the raw data of channels, not the offset and scale attributes. This is not changed by default because it would alter existing formulas. Add the offset and scale to the formula explicitly, for example (Channel * scale) + offset.
See also: The Add/Edit Formula Channel Dialog Box.
9.5. Formula error messages¶
9.5.1. “The formula could not be evaluated properly” when adding a formula channel¶
The message means that a channel used in the formula could not be found or read, or that the formula could not be evaluated for the data. Things to check:
Start UniPlot without user scripts (
uniplot.exe /NoAutoLoad). If the error disappears, a script in theautoloadfolder is the cause. A typical case is a global variable kept in a custom script that is not reset when the next file is processed, so the second file opened in a session fails.Channel names and import settings in Tools > More Options > Data Import and Data Browser: “Unicode Data Files”, “Allow Special chars in channel names”, “Trim blank characters from channel names (Text, Excel)” and “Trim blank characters from channel names (UTX)”. Names starting with special characters such as
$may cause problems.Very large files: a long file path (try a local copy) and the UniPlot log.
The formula syntax (message
Syntax error at pos:): check the formula and the filter parameters.
See also: The Add/Edit Formula Channel Dialog Box, Debug Formula.
9.5.2. When I edit a formula channel repeatedly, the channel name is inserted into the formula text. Is this a known bug?¶
In older releases (reported for R2018.13) every edit and save duplicated the assigned channel name in the formula text and produced broken entries in the formula list. This is fixed in current releases. Update UniPlot, then delete the broken formulas in Tools > Formula List….
See also: Tools=>Formulalist.
9.5.3. 2D interpolation or a 2D difference plot gives wrong results or errors in R2020.2 to R2020.4. Is this a known bug?¶
Yes. Bugs in R2020.2 to R2020.4 affected the 2D interpolation and the functions xygetdata and xycreate used for computed datasets (difference plots, “Update dependencies”). They are fixed in R2020.5. Update UniPlot.
See also: Data=>Interpolation.
9.5.4. What does the error “x is not monotonically ascending” mean when averaging or interpolating several curves?¶
The interpolation and averaging of several curves requires strictly ascending X values for every curve. If a curve has repeated or decreasing X values (for example a time channel that resets or contains duplicates), the message appears. Sort or clean the X channel first.
Averaging several curves also requires that the curves share the same X values. Apply a filter that interpolates the curves onto a common X grid, then compute the mean value.
See also: Browser=>Interpolation, Filter Functions for XY datasets.
9.6. Filters, interpolation and statistics¶
9.6.1. Where is the Data Filter function?¶
Import the file, then click Edit for the channel in the Data Browser. A tab opens. Enable the Filter check box on the right side. Another tab opens in which you define and apply the filter.
See also: Edit Filter Functions, Dialog Box=>Data Filter.
9.6.2. How can I calculate an FFT amplitude spectrum for a selected time section of a signal?¶
Use curve filters on the diagram:
Select the curve and choose Data > 1D- and 2D-Dataset…, tick Filter and click Edit Filter.
Select the filters
extractandfft_spectrumand add each with the => button. Both appear in the right list and can be edited with edit.In
extractset the X range (for example 0.3 s to 0.5 s). Infft_spectrumthe parameters areWindowandSegment_Points. The defaults (0 and 0) gave the most accurate results. A largeSegment_Pointsvalue that does not fit the data length (for example 4096) causes an error.The X axis of the result is the frequency. Change the axis label from “time” manually and use autoscale to adapt the axes.
Apply the extract filter first and the FFT second. Do not apply an FFT to a curve that already shows an FFT. If the channel has more points than the data reduction limit (10 million points per channel by default, see What does Delayed Channel Import do, and how can I speed up the import of very large MF4/MDF files?), UniPlot reduces the points used for display and filtering and the FFT result can be wrong. A UniScript function fft also exists.
See also: Filter Functions for XY datasets, fft.
9.6.3. After an FFT the amplitude in the spectrum is much lower than the peak value of the signal. Is this correct?¶
Yes. The first diagram shows the signal over time, x(t). The second shows the amplitude spectrum |X(f)| over frequency, that is, which sine and cosine components the signal consists of. Its peak therefore has no direct relation to the peak of the time signal (a 750 kPa peak does not give a 750 kPa spectral peak). The values depend on the transform scaling and on how the energy is spread over frequencies: narrow peaks give high values, broad ones low values.
See also: fft.
9.6.4. Does UniPlot support FFT, and how can I create a frequency / speed / amplitude plot?¶
Yes. The curve filter fft_spectrum and the UniScript functions such as fft provide the transform. For a frequency-over-speed map, compute the amplitude spectrum per speed section with a small UniScript and plot the result as a 3D dataset with X = frequency, Y = speed and Z = FFT amplitude. Some coding is needed for the plot. UniPlot is not the best-suited tool for very large NVH analyses because of the data volume.
See also: How can I calculate an FFT amplitude spectrum for a selected time section of a signal?.
9.6.5. How do I do a linear regression?¶
Use p = polyfit(x, y, N), which returns the coefficients of a polynomial of degree N. With N = 1 you get the best-fit straight line. The same fit is available as the filter polyfit for XY datasets.
See also: polyfit, polyfit - Polynomfit.
9.6.6. How can I draw a hyperbola-shaped trend line through a few points?¶
Two approaches:
Use the UniScript function nonlin with a hyperbola function as fit function.
Compute points on the hyperbola (for example in Excel), import them and connect them with the filter spline. More points give a smoother curve, but it is not an exact hyperbola.
See also: nonlin.
9.6.7. How can I convert a measured sensor voltage to a physical value using a calibration curve?¶
Use interpol with the characteristic curve:
Import the data.
Create a simple formula channel. Its content does not matter at first.
Open the generated formula
.icfile. Edit it so that the vectorsrsX(sensor voltage) andrsY(physical value) contain the characteristic curve.Apply
interpolto the measured voltage channel. The result is the physical value per sample.
For a curve filter on a dataset, the filter characteristic_curve (Scaling-Y) does the same without scripting.
See also: interpol, characteristic_curve - Scaling-Y (Characteristic curve).
9.6.8. How can I multiply a signal by a correction factor that depends on the signal value?¶
If the factor is available as a channel, create a formula channel (Data Browser > Edit > right-click > Add/Edit Formula Channel), for example Corrected = Signal * Factor.
If the correction is a characteristic curve with support points, use the 1D/2D filter correction_factor(x, y) (available since R2022.2). It corrects the y coordinate with a variable correction factor that depends on the operating point, for example to correct a sensor signal that is known to deviate at some operating points. The parameters are described in correction_factor - Scaling-Y (Correction Factor).
See also: correction_factor - Scaling-Y (Correction Factor), characteristic_curve - Scaling-Y (Characteristic curve).
9.6.9. How can I reduce or increase the sampling rate of a vector?¶
To reduce the rate, build an index and select only those points. Every second point (for example 1 Hz to 0.5 Hz):
idx = [1:2:len(DATA)];
DATA_half = DATA[idx];
If the raster is not 1 s, compute the number of points that corresponds to the desired step. To increase the rate or to resample, use the interpolation function interpol.
See also: interpol, Browser=>Interpolation.
9.6.10. How can I plot the difference between two datasets in a 2D XY diagram?¶
Two ways:
Use the 2D interpolation function to interpolate both datasets onto a common X axis and subtract them.
Create a formula channel that calculates the difference between the channels of the two datasets.
See also: Data=>Interpolation, The Add/Edit Formula Channel Dialog Box.
9.6.11. How can I get a single median value per bin instead of many points when plotting 2D or 3D data?¶
The option “Enable Data Filter for 3D datasets” (Tools > More Options > 2D and 3D Datasets) only speeds up plotting. It has nothing to do with the median.
2D x/y: select the curve, open the “1D and 2D Dataset” dialog, check Filter, open Edit Filter and add the filter median to the selected filters.
3D x/y/z, option 1: in Data Browser > Edit…, right-click the channel sheet > Add/Edit Formula Channel and use quantile(c,q), for example MedianTorque = quantile(Channel, 0.5). Then load the 3D x/y/z dataset with that channel as Z.
3D x/y/z, option 2: activate the add-in 3D Classification of XYZ Data in Tools > Add-In Manager (restart UniPlot). Then choose File > More File Functions…, select “3D Classification of XYZ Data”, select the data file and in the dialog box select Plot Median in the group Output.
The function reduce3d does essentially the same as the 3D classification; it requires scripting and returns the indices of the extracted points without creating a graph.
See also: 3D Classification of a XYZ-Dataset, quantile, reduce3d.
9.6.12. How do I compute an averaged cycle (mean trace over many working cycles)?¶
Use the Data Editor function Create Mean Cycle NC file…. It averages the cycles point by point and saves the mean cycle (and, if you want, the minimum and maximum cycle) in a new NC file.
Import the data file and click Edit in the Data Browser.
Right-click the data grid and choose More Functions > Create Mean Cycle NC file….
Select the Independent Channel (Time, CA).
Enter the X Coordinate of Cycle Start. This value must exist in the data.
Enter the Cycle Length, for example
720for a four-stroke cycle in degrees crank angle.In Cycle Selection enter
Allor a list of cycles, for example3,6,10-15.Enable Mean and, if needed, Minimum and Maximum.
Select the channels to average and confirm.
The result is a new file <name>_mean.nc with one averaged cycle.
Requirements:
The independent channel must increase monotonically over all cycles and must not contain missing values. A crank angle that restarts at -360 deg in every cycle must first be converted to a continuous angle.
All cycles must have the same number of points.
A formula such as MeanChannel = mean(Channel) does not help here. It returns one constant value for the whole channel (for example the mean pressure), not a mean per crank angle.
Display tips:
For a fixed cycle length, use the plot type 2D: x/y Cycle, which shows each cycle as a separate curve. Plot the mean separately with 1D: y/t or 2D: x/y, change the line colour via Line style… and copy it into the cycle diagram.
To use Data > More Data Functions… on several curves, first select all datasets of the diagram: hold Ctrl+Shift and click each curve, then right-click > More Data Functions.
In UniScript use NC_CreateMeanCycleFile.
See also: Browser=>Mean Cycle, NC_CreateMeanCycleFile.
9.6.13. Linear and non-linear interpolation in the dataset list configuration appear swapped, or different interpolation types give the same result in a script¶
In some R2018 releases the strings for linear and non-linear interpolation in the Configuration dialog of the dataset list were reversed. Selecting non-linear applied linear interpolation and vice versa. This is fixed in current releases.
Extrapolation with the interpolation function is only reliable with linear interpolation. With non-linear interpolation, add boundary points manually. To extrapolate maps (3D datasets), see How can I extrapolate a map (3D dataset) beyond the measured points?.
See also: What is the difference between the interpolation methods in UniPlot ?, How can I extrapolate a map (3D dataset) beyond the measured points?.
9.6.14. How can I extrapolate a map (3D dataset) beyond the measured points?¶
Use the Thin-Plate-Spline interpolation, make the interpolation range large enough and switch off the hull:
Select the map and choose Data > Interpolation.
Select the type Thin-Plate-Spline. It is the recommended method for plotting beyond the data hull.
Make sure that the interpolation range covers the area to extrapolate. Switch off Interpolation at Grid lines and enter the range, or extend the axis range.
Choose Data > 3D-Dataset > Hull and select No Hull. Otherwise the isolines are clipped at the data hull and no extrapolated area is visible. For a 3D surface, select Extrapolate outside Hull.
If you calculate values with the Map Calculator, do not select No Extrapolation.
Extrapolated values far away from the measured points are not reliable. Check them for plausibility, for example against the physics of the engine.
See also: Data=>Interpolation, Data=>3D-Dataset=>Hull, Map Calculator.
9.6.15. Why does the axis unit not change after applying a filter such as derivative or integral?¶
UniPlot does not update axis titles or units when filter functions are added, because a diagram can contain datasets of different types and units (for example mg/s and g) and a correct automatic title is hard to determine. Change the unit manually, for example from mg/s to mg after an integration.
The unit of the result of Data > Integral or the area function is the product of the X axis unit and the Y axis unit. UniPlot does not attach a unit to the result.
See also: Data=>Integral, Filter Functions for XY datasets.
9.6.16. fround() gives identical results for the rounding methods “up” and “down”. Is that a bug?¶
Yes, in versions before R2022.2. fround(0.12345, 4, 0, "up") and fround(0.12345, 4, 0, "down") must give 0.1235 and 0.1234. Numbers are stored as binary floating point values, so 0.12345 is not exactly representable, which affects rounding at the digit 5. The problem is fixed in R2022.2. Update UniPlot.
See also: fround.
9.7. Field functions in text boxes and tables¶
9.7.1. The field function @f{xyinterpol(Data4, x=90, %.2lf)} does not return a value. How do I fix it?¶
The syntax is @f{xyinterpol(Dataset, x=value, format)} in a text box (double-click the box to open the text object properties). Before R2022.4 the function did not return a value for requests of type x= when the x axis is not a time axis, and for requests of type y=. Update to a current release. Press F9 (or choose Edit > Update Fields) to force a field update.
Since R2025.2 a field function can be used as a parameter of xyinterpol; for example @f{xyinterpol(Data3, x=xystatvalue(Data1, ymaxpos))} returns the Y value of Data3 at the X position of the maximum of Data1.
See also: Overview Field Functions, Edit=>Update Fields.
9.7.2. How can I show the channel name and unit in a text box with xyvalue / xystatvalue?¶
Use the full form @f{xyvalue(Data1, y.name.unit, 1)} (or y.name for the name only). The third parameter is the data point index (negative counts from the end); an optional format such as %.2lf can follow. Likewise use @f{xystatvalue(Data1, ymean.name.unit)}. Releases before R2021.4 did not show the types name and unit in some cases; this was fixed in R2021.4. The legend of the dataset can alternatively be edited to show only the name and unit in brackets.
See also: Overview Field Functions, Field Functions.
9.7.3. xystatvalue reports “ylast” unknown, or xyvalue with ymax moves the table. What should I use?¶
Use @f{xystatvalue(Data1, yend)} for the last Y value and ystart for the first one (not yfirst or ylast). For the maximum use @f{xystatvalue(Data1, ymax, %.2f)}. The function xyvalue also returns the position and moves the table when it is edited.
If xyvalue or xystatvalue (for example yend) returns nothing for calculated channels because the last values are missing, the measurement probably contains channels with several different time bases (for example INCA measurements). Resampling all channels to a common time base solves the problem.
If xyvalue with a negative index such as -10 gives an error or the field is not updated, press F9 to force a field update.
See also: Overview Field Functions.
9.7.4. The field function ncvaluefromdata ignores my data filter. How can I show a value from filtered data?¶
@f{ncvaluefromdata(...)} reads the raw data of a channel. It does not apply the data filter that is active for a diagram. Use @f{xyvalue(...)} instead: it works on the dataset of the diagram and therefore takes the filtered data into account. The script of the field function is script/field/ff_ncvaluefromdata.ic in the UniPlot installation folder. Copy it to the autoload folder of the user home directory and modify the copy, not the original.
See also: Overview Field Functions.
9.8. Units and unit conversion¶
9.8.1. How can I change the unit of a channel after import, or convert units such as hPa to kPa?¶
Single channel: change the unit in the channel properties in the Data Browser. UniPlot converts compatible units (see the unit converter article for the supported unit names). A filter such as
scale(0.1, 0)applies a fixed factor.All channels: in the Data Editor (Edit button of the Data Browser) right-click and choose More Functions > Convert Channel Units…. It converts to SI or preferred units based on the units table (
units.xlsxin thetemplatefolder of the installation). Copy the file, edit it and select it in Tools > Formula Configuration… (Units Table). The conversion is lost on a data exchange with a raw file.Automatically on import: a UniScript in the
autoloadfolder of the user home directory callsnc_convert_units(ssNetCDFName, 0)after import (0 = SI units, 1 = preferred units). Use a units file that contains only the units to convert. The autoload folder in Program Files may need administrator rights, so use the user home directory.
See also: Unit Converter, nc_convert_units, Browser=>Convert Units.
9.8.2. UniPlot reports that the units table (units.xlsx) cannot be read after an update. What could be the cause?¶
A units table maintained in Excel can become unreadable because of an encoding incompatibility, for example when the file was edited on a computer with a different language or regional setting. Re-save the units file with UTF-8 encoding and re-import it.
See also: Units Sheet, Unit Converter.
9.8.3. Unit conversion fails for channels with a measuring point placeholder such as <ii> in the name (R2018.13)¶
Since support for 3-digit measuring point placeholders was added, unit table entries where a numeric placeholder meets a numeric constant (for example foo<ii>1 or bar2<ii>) are interpreted ambiguously. Review the unit table (Tools > Formula Configuration…, Units Table) and remove or rename such entries.
See also: Channel Sheet, Unit Converter.
id-423168