Time range offset (BTimeRangeOffsetBlock)

This block adjusts the time range, which the analytic trend request may have specified. The resulting time range is an absolute value of two fixed timestamps. This is important when you have additional time offsets in an algorithm. The Time Range Offset Block is often used in conjunction with a Timestamp Offset Block to perform period-over-period comparisons, such as month over month (MOM) or year over year (YOY).

Figure 147. Time Range Offset Block properties

To view these properties, double-click the block on the Wire Sheet or the block name in the Nav tree.

Property	Value	Description
Out	read-only value slot	Outputs the trend data with the time range offset based on the block’s configuration.
In	required value slot	Links from the output of other logic blocks or data sources to supply trend data to the current logic block.
Quantity	positive or negative number (defaults to -1)	Defines the numeric amount to offset. When `Quantity` is negative, the framework adjusts the time range further into the past. When `Quantity` is positive, the framework adjusts the time range further into the future.
Time Unit	drop-down list; defaults to `Years`	Defines the unit to use for the offset from `Years` to `Seconds`.
Time Range Part	drop-down list; defaults to `Both`	Defines which parts of the time range to adjust: only the `Start`, only the `End`, or `Both` the `Start` and `End` timestamps. You may need to set this property to `Start` when this block’s `Quantity` is negative and the Timestamp Offset Block’s `Quantity` is positive. You may need to set this property to `End` when both `Quantity`s, this block’s `Quantity` and the Timestamp Offset Block’s `Quantity`, are positive.

Examples

Sometimes a time lag occurs between cause and effect. Changing a setpoint for a process does not have an immediate effect on the actual process variable. For example, changing a zone temperature setpoint does not immediately change the actual zone temperature, rather it might take 15 to 30 minutes for the zone temperature to reach the new setpoint. To facilitate easier comparison in these situations, you can use a Timestamp Offset Block to shift the timestamps for either the setpoint history or process variable history by the expected lag.

Consider these data:

Figure 148. Timestamp data

The table shows a setpoint change from 80 to 73 at 8:00 am. The actual space temp lags by about 30 minutes to reach the new setpoint.

An Analytic Web Chart (hs:zoneAirTempSensor and hs:zoneAirTempEffectiveSp) shows the data with the lag.

Figure 149. Temperature data shown with a lag

This algorithm, which uses a Timestamp Offset Block, can shift the timestamps of the setpoint history forward by 30 minutes.

Figure 150. Timestamp Offset Block algorithm with a positive shift

An updated algorithm, alg:SetpointLag30Minutes uses the Timestamp Offset Block to shift the timestamps.

Figure 151. Timestamp Offset Block chart showing the timestamp positive shift

Compared to the previous Analytic Web Chart, the orange line records are now shifted forward by 30 minutes.

When using a Timestamp Offset Block in an algorithm and the quantity is positive, the timestamps are shifted forward in time. The algorithm has logic that filters any records from the result whose timestamp is after the end of the time range in the request. The Timestamp Offset Block does not adjust the start and end times of the time range in the request, so it may seem like there are fewer than expected or even no records in the result.

Consider a Numeric Point for Zone Temp with hs:zoneAirTempSensor and a:a marker tags. A bound table with an Analytic Table Binding using data = hs:zoneAirTempSensor and a time range to show data between 10 am and 11 am on a single day displays the expected four records.

Figure 152. Timestamp Offset Block result showing four records

Consider an algorithm with a data source of hs:zoneAirTempSensor that is linked to a Timestamp Offset Block with a positive 30 minute offset.

Figure 153. Timestamp Offset Block algorithm with a positive 30–minute offset

A Bound Table with an Analytic Table Binding using data = alg:PositiveTstampOffset and the same time range to show data between 10 am and 11 am on a single day only returns two records.

Figure 154. Timestamp Offset Block example showing only two records

The other two records have timestamps of 11:00 AM and 11:15 AM, which are after the end time (exclusive) of the requested time range.

Figure 155. Time Range configuration

If the Timestamp Offset Block was configured for positive 60 minutes, there would have been no records in the result. In this case you can add a Time Range Offset Block to the algorithm to adjust the end time of the requested time range in the future by the same amount of time that the Timestamp Offset block applies.

Figure 156. Timestamp Range Offset Block added to the algorithm

Using this updated alg:PositiveTstampOffset, the result displays all expected records with their adjusted timestamps.

Figure 157. Timestamp Offset Block example showing all expected records