Source Functions

Reference documentation for supported source functions

Source functions are defined inside the func namespace, and must be explicitly qualified using func.. Any node that uses one or more of these functions will be recalculated at regular intervals according to its configured sample rate.

active_alarms_count(group)

Returns the number of currently active alarms for the given group.

Arguments

• group: a reference to a group. This is given by either a string (i.e. '/group1'), or a regular node reference followed by .ref (i.e. {/group1}.ref).

Example usage

A group reference with string:

func.active_alarms_count('/site1')

A group reference with .ref method:

func.active_alarms_count({/site1}.ref)

active_alarms_duration(group, unacked_only)

Returns the average duration of currently active alarms in the given group (time elapsed since alarm start).

Arguments

• group: a reference to a group. This is given by either a string (i.e. '/group1'), or a regular node reference followed by .ref (i.e. {/group1}.ref).

• unacked_only (default: false): an optional argument. If true, the function will calculate the alarm duration for acknowledged alarms as the time period between alarm start and alarm acknowledge.

Example usage

Average duration for currently active alarms:

func.active_alarms_duration('/site1')

Average duration for unacknowledged alarms:

func.active_alarms_duration({/site1}.ref, true)

alarm_history_avg_duration(group, period)

Calculates the average duration of alarms occurring in the given period for the given group. The duration is calculated as the time elapsed between alarm start and alarm end.

Arguments

• group: a reference to a group. This is given by either a string (i.e. '/group1'), or a regular node reference followed by .ref (i.e. {/group1}.ref).

• period: an optional argument denoting the time period in seconds, going back from the present moment. By default, the period consulted is the last 24 hours (86400 seconds).

Example usage

Average duration of alarms occurring in the last 3 days:

func.alarm_history_avg_duration('/site1', 86400 * 3)

alarm_history_count(group, period)

Calculates the number of alarms occurring in the given period for the given group.

Arguments

• group: a reference to a group. This is given by either a string (i.e. '/group1'), or a regular node reference followed by .ref (i.e. {/group1}.ref).

• period: an optional argument denoting the time period in seconds, going back from the present moment. By default, the period consulted is the last 24 hours (86400 seconds).

Example usage

Number of alarms in the last week:

func.alarm_history_count('/site1', 86400 * 7)

avg(expr, period)

Calculates a running average on the given expression over the given period.

Arguments

• expr: an expression evaluating to a number.- period: the time period for the running average in seconds.

Example usage

Calculate a running average over one hour:

func.avg({/site1/registers/r1504}, 3600)

(Note: the running average will be updated according to the target node's sample rate).

integrate(ref, period:, units:, mode:)

Calculates time-based integral of given reference over the given period, either for the current period, or for the previous period. This function can be used to calculate e.g. total flow based on flow rate.

Arguments

• ref: a reference to a point node. This is given by either a string (i.e. '/group1/registers/r1504'), or a regular node reference followed by .ref (i.e. {/group1/registers/r1504}.ref).

• period (default :day): the period over which to integrate the value, either :month, :week, :week_sunday, :day, :hour, :minute, :second or a number indicating time period in seconds (60 for one minute, 3600 for one hour, etc). Weekly periods start on monday. For weekly periods starting on sunday use :week_sunday.

• units (default :hour): the units to use for the integral, either :day, :hour, :minute, :second or a number indicating time period in seconds (60 for one minute, 3600 for one hour, etc).

• mode (default :previous): one of the following:

  • :previous - calculate integral for previous rounded time period. Note that in this mode the result of the function will be updated once per time period. For example, for an hour-based integral, the result of the function will signify the integral for the previous hour.

  • :current - calculate integral for current rounded time period (projected up to the end of the current time period).

  • :realtime - calculate integral for current rounded time period up until present moment.

Example usage

Calculate total flow in flow/hour units for yesterday:

func.integrate('/r1442', period: :day, units: :hour, mode: :previous)

Calculate total flow in flow/minute units for today up until now:

func.integrate('/r1442', period: :day, units: :minute, mode: :realtime)

prev_period_value(ref, period:, mode:)

Calculates historical value for the previous time period given node reference according to given period and mode.

Arguments

• ref: a reference to a point node. This is given by either a string (i.e. '/group1/registers/r1504'), or a regular node reference followed by .ref (i.e. {/group1/registers/r1504}.ref).

• period: symbol indicating period (:day, :hour, :minute, :second) or a number indicating time period in seconds (60 for one minute, 3600 for one hour, etc).

• mode: one of the following:

  • :first: first value for the previous time period

  • :last: last value for the previous time period

  • :delay: value at period seconds ago

  • :avg: weighed average for the previous time period

  • :diff: difference between first value and last value over the previous time period

Example usage

Calculate weighed average for the previous day:

func.prev_period_value('/r1442', period: :day, mode: :avg)

Calculate first value for the previous hour:

func.prev_period_value('/r1442', period: 3600, mode: :first)

pulse_count(ref, period:, mode:)

Calculates total pulses (transitions from 0 to 1) of given reference over the given period, either for the current period, or for the previous period.

Arguments

• ref: a reference to a point node. This is given by either a string (i.e. '/group1/io/b12'), or a regular node reference followed by .ref (i.e. {/group1/io/b12}.ref).

• period (default :day): the period over which to count pulses, either :day, :week, :month, :minute or a number indicating time period in seconds (60 for one minute, 3600 for one hour, etc).

• mode (default :previous): one of the following:

  • :previous: calculate pulse count for previous rounded time period. Note that in this mode the result of the function will be updated once per time period. For example, for an hour-based pulse count, the result of the function will signify the pulse count for the previous hour.

  • :current: calculate pulse count for current rounded time period.

Example usage

Calculate pulse count for yesterday:

func.pulse_count('/b12', period: :day, mode: :previous)

Calculate pulse count for current rounded hour:

func.pulse_count('/b12', period: :hour, mode: :current)

rate_of_change(expr, period:)

Calculates the rate of change of the given expression over the given time period.

Arguments

• expr: a numeric expression.

• period (default :hour): the period over which to count pulses, either :month, :week, :day, :hour, :minute or a number indicating time period in seconds (60 for one minute, 3600 for one hour, etc).

Example usage

Calculate rate of change per hour

func.rate_of_change({/r1032}, period: :hour)

Calculate rate of change per minute

func.rate_of_change({/r1032}, period: 60)

runtime(ref, period: , units:, mode:)

Counts running time based on boolean given expression.

Arguments

• ref: a reference to a point node. This is given by either a string (i.e. '/group1/io/b12'), or a regular node reference followed by .ref (i.e. {/group1/io/b12}.ref).

• period: time period for resetting running time, one of: :daily, :hourly (default is :daily).

• units: unit for expressing time, one of: :day, :hour, :minute, :second (default is :hour).

• mode (default :previous): one of the following:

  • :previous: calculate pulse count for previous rounded time period. Note that in this mode the result of the function will be updated once per time period. For example, for an hour-based pulse count, the result of the function will signify the pulse count for the previous hour.

  • :current: calculate pulse count for current rounded time period.

Example usage

By default `func.runtime` measures running time in hours and resets the running time daily (at midnight):

func.runtime('/site1/bits/b33')

To change the default behaviour add more arguments:

func.runtime({/site1/bits/b33}.ref, period: :hour, units: :second, mode: :current)