Timestamp offset (BTimestampOffsetBlock)

This block adjusts the timestamp of a history record as it is processed by the algorithm. It is often used in conjunction with a Time Range Offset block to perform period-over-period comparisons, such as month over month (MOM) or year over year (YOY).

Figure 158. Timestamp Offset 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 value from `In` with the timestamp 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	number (defaults to 1)	Defines the numeric amount to offset. Use negative numbers to go back in time. In an algorithm, if `Quantity` is positive, this block shifts the timestamps forward in time and filters out any records from the algorithm’s result whose timestamp is after the end of the time range in the request. This block does not adjust the start or end times of the time range in the request; therefore, it is possible to exclude the forward shifted records from the result. When using this block with a positive `Quantity`, it may be necessary to use a Time Range Offset block to offset only the `End` timestamp by the same `Quantity` and `Time Unit`, or to offset the `Start` timestamp by the negative quantity and same `Time Unit`.
Time Unit	drop-down list (defaults to `Years`)	Defines the unit to use for the offset from `Years` to `Seconds`.

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 159. 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 160. 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 161. Timestamp Offset Block algorithm with a positive shift

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

Figure 162. 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 (the forward shifted records may be excluded from the result).

When using the Timestamp Offset Block with a positive Quantity it may be necessary to use a Time Range Offset Block to offset only the End timestamp by the same Quantity and Time Unit, or to offset the Start timestamp by the negative quantity and same Time Unit.

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 163. 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 164. 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 165. 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 166. 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 167. Timestamp Range Offset Block added to the algorithm

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

Figure 168. Timestamp Offset Block example showing all expected records