Concept

Filtering is a mechanism to further process raw time series data. It is used by typing in the keywords defined in the filter syntax. The syntax and keywords are described in the following article.

The syntax consists of a filter selection part and the time period part. For example "AVG10MIN" calculates and shows the averages over ten minute time spans. Several filters can also be applied on top of each other. They are separated with pipe '|', for example "AVG1MIN|MAX1H" produces the hourly maximum values from the one minute average values.

In case aggregated histories are collected for the used raw time series data, filters are able to automatically use it to optimize the calculation In case optimization is not wanted to happen, it can be set off by starting with an empty filter, that is pipe '|'. For example: "AVG1MIN" is optimized while "|AVG1MIN" is not optimized.

Filters can be used from <<glossary:Engineering UI>> trend or from any program using Vtrinlib API. As well OData and ODBC provides filters as is. OPC UA and HDA Servers implement HA Aggregates which are close relatives to filters only difference being the fact that aggregations can't be stacked on top of each other.

Please find further information on how to use filters with graphs under Time Series > Aggregates and filters.

Supported filters

Filter name	Description
AAVG	Arithmetic Average
AAVGRAW	Arithmetic Average including invalid values
ADEV	Arithmetic Deviation
ADEVP	Arithmetic Deviation of Entire Population
AMAX	Arithmetic Maximum of valid values. (version info: 5.3_24.12)
AMEDIAN	Arithmetic Median
AMIN	Arithmetic Minimum of valid values (version info: 5.3_24.12)
AMODE	Arithmetic Mode
AVARIANCE	Arithmetic Variance
AVARIANCEP	Arithmetic Variance of Entire Population
AVG	Time Weighted Average
AVGRAW	Raw Time Weighted Average - ignoring the invalidity of values
CALC	User Defined Calculation. E.g. CALC(y*2) returns values doubled and CALC(y > 0 ? 10:20) returns 10 if y > 0, otherwise return 20. See the chapter below for supported constants and functions.
CALCI	Works like the CALC except in cases where there is change between zero and non-zero value, where it interpolates a new point to position where the value changes from zero to non-zero or vice versa. This is especially useful with WHEN filter, where it makes possible to use linear variables as the WHEN criteria.
COUNT	Count of Samples Within Period
COUNTG	Count of Good Samples Within Period
COUNTI	Count of Invalid Samples Within Period
COUNTQ	Count of Questionable Samples Within Period
COUNTS	Count of Substituted Samples Within Period
CONVERT	Converts Values to User Specified Unit. E.g. CONVERT(hp) can be used to get horse powers out of kilowatts
CUMSUM	Cumulative Sum
CUMSUMTODOUBLE	Cumulative Sum to Double Value
DELTA	Last Sample In Period minus First Sample In Period
DEV	Time Weighted Deviation
DUR	Duration = Period Length (changes only upon daylight savings or with month periods)
DURG	Good Duration as a TimeSpan Within Period
DURI	Invalid Duration as a TimeSpan Within Period
FIRST	First Value of a Period
FFT	Fast Fourier Transform of input data
HISTOGRAM	Histogram of input data
INTSEC	Time Integral in Seconds
INTMIN	Time Integral in Minutes
INTHOUR	Time Integral in Hours
LAST	Last Value of a Period
MAX	Maximum Value of a Period, TimeStamp is the Value Time
MAXPT	Maximum Value of a Period, TimeStamp is the Period Time
MIN	Minimum Value of a Period, TimeStamp is the Value Time
MINPT	Minimum Value of a Period, TimeStamp is the Period Time
OK	Changes invalid values to valid
OPTIME	Operating Time. Requires a parameter, e.g. OPTIME10MIN(>5) calculates the time the value has been greater than 5.
PERG	Percent of Good Samples (0-1)
PERI	Percent of Invalid Samples (0-1)
RANGE	Maximum Value Within a Period minus Minimum Value Within
SKIP	Skip and select period values SKIP(initial_skip, value_skip) initial_skip – period to start, e.g. 3 skips 3 periods value_skip – how many periods to skip between the selected ones, e.g. 2 skips 2 periods and selects every third SKIP can only be used after some other periodical filter, not with raw value query, e.g. AVG1HOUR\|SKIP(0, 3) selects every 4th hour average value
STABILITY	Stability Graph - Fetches all the values in the time range, sorts them in descending order, and makes X-axis show the cumulative timespan based on how long each value was active.
STARTUP	Startup Count - requires a parameter. E.g. STARTUP5MIN(>5) calculates the number of occurrences the value has increased from less than or equal to five to greater than five
SUM	Sum of Values Within a Period
SUMRAW	Raw Sum - Ignoring the Invalidity of Values
SUMTODOUBLE	Sum of Values Within a Period Calculated to Double - Use If There is a Risk of Overflow
VARIANCE	Time Weighted Variance
WHEN	Conditional fetch of values. Returns requested values when given conditions are greater than zero. Syntax: WHEN(Class=...;Property1=...;Property2=...; ...etc... PropertyN=...; xProperty=...;yProperty=...;Filter=...) See chapter Using the WHEN Filter for more detailed information.

Supported time periods


No period length	The whole period between start time and end time is used. E.g. AVG return the average value for the whole period.
TICKS, HUNDREDNANOSECONDS	Hundred nanoseconds
MICROSECOND, MICROSECONDS	Microseconds
MS, MSEC, MILLISECOND, MILLISECONDS	Milliseconds
S, SECOND, SECONDS	Seconds
MIN, MINUTE, MINUTES	Minutes
H, HOUR, HOURS	Hours, local time
H_UTC, HOUR_UTC,HOURS_UTC	Hours, UTC time
D, DAY, DAYS	Days, local time
D_UTC, DAY_UTC,DAYS_UTC	Days, UTC time
MON, MONTH, MONTHS	Months, local time
MON_UTC, MONTH_UTC, MONTHS_UTC	Months, UTC time
Y, YEAR, YEARS	Years, local time
Y_UTC, YEAR_UTC, YEARS_UTC	Years, UTC time
PL, PLEN, PERIODLENGTH	Source data period lengths. E.g. if source data is AVG5MIN, AVG2PLEN produces data that has been averaged over 10 minutes. (AVG5MIN \| AVG2PLEN equals AVG10MIN)

Supported constants and functions in the CALC Filter


y	Current y value
x	Current x value, in case of CALCI x may be the iterated or interpolated value
PI	pi
e	natural logarithmic base
nextx	next x value, at the end of the period it is the last x
nexty	next y value, at the end of the period it is the last y
prevy	previous y value, for the first value in result set this is the same as y
prevyz	previous y value, for the first value in result set this is zero
prevx	previous x value, for the first value in result set this is the same as x
prevcy	previous calculated y value (result of the calculation of previous values)
periodlength	period length in 100 nanosecond units
goodtime	time the value has not been invalid (representativeness affects too)
meantime	x-prevx
querystarx	(5.3 Dec-2025 and newer) query start x value (eg. start time if x axis is time)
queryendx	(5.3 Dec-2025 and newer) query end x value (eg. end time if x axis is time)

When filter

The WHEN Filter can be used for conditional fetch of values. The filter returns the requested values when conditions given as arguments are greater than zero. Syntax of the WHEN filter is below.

WHEN(Class=...;Property1=...;Property2=...; ...etc... PropertyN=...;xProperty=...;yProperty=...;
Filter=...)

No argument is compulsory. There can be 0-N properties of the given class used as conditions. Default value for "Class" is "ProcessHistory", which is used, if the "Class" argument is left empty. Available classes are the same as the sources for a trend. Properties are the same as the properties for the trend sources. E.g. a first property can be "Variable" and a second property can be "History" for the "ProcessHistory" class. From 5.3 Dec-2025 and up you can also specify "xshift", to alter the x range the condition is fetched (eg. fetching from previous hour). Filter can be any valid filter operation.

In Example 1 clause returns the "CPU Total time" variable's values when the value is greater than 20.

WHEN(Class=ProcessHistory;Variable=SYS_CPU_TotalTime;XProperty=Time;YProperty=Value;xshift=00:00:00;Filter=
CALC(y>20))

In Example 2 clause returns the same values as in Example 1, as the only difference is the lack of default values.

WHEN(Variable=SYS_CPU_TotalTime;Filter=CALC(y>20))

In Example 3 clause returns time periods where Variable "BleacherState" has been 1 reduced with 20 seconds from both ends. The purpose of this example is to select "steady state" of the process, i.e. removing transition period at the start and end of the production period.

WHEN(Variable=BleacherState;Filter=CALCI(y==1 && (x-prevx)>seconds(20) && (nextx>x?(nextx-x)>seconds(20):1)))

In Example 4 clause returns the values of "float0" equipment property under the path "Plant1.Area1.Motor102" when the value is greater than 3.

WHEN(Class=EquipmentHistory;Path=Plant1.Area1.Motor102;Property=float0;Filter=CALC(y>3))