Time Zones
As already outlined in the understanding timestamps in TIM section, correctly handling time zones is crucial - incorrectly specified time zone can lead to unexpected results. In the date and time formatting section we explained how the TIM Platform complies to the ISO 8601 standard which includes the possibility to send time zone-specific timestamps in datasets and as parameters in requests to TIM. We also explained the meaning of transactional and dataset timestamps and the difference between them.
Handling time zones in transactional timestamps should be clear from the previous sections. On the input, you can indicate time zone by appending UTC offset designator to timestamp. On the output, everything is in UTC. This section is focused on dataset timestamps and the possibility to set time zone globally during dataset upload (timeZoneName parameter - Swagger REST API documentation -> Schemas -> Configuration -> timeZoneName).
Overview
There are multiple options how to specify time zone of a dataset during dataset upload. You can upload a dataset that optionally contains UTC offset designators on the level of individual timestamps. You can also set the gobal timeZoneName parameter which is, by default, set to UTC. Each option implies different dataset upload behavior and different consequences when working with the dataset. The table below clarifies this:
| Scenario | UTC offset designator on timestamp level | timeZoneName parameter | TIM DB | Dataset manipulation (timescale, model building, ...) | Rendering (e.g. TIM Studio) |
|---|---|---|---|---|---|
| A | not provided (e.g. 2023-01-01 12:00:00) | default (UTC) | Dataset stored as is. (2023-01-01 12:00:00.000Z) | Dataset shifted to timeZoneName before manipulation. | Dataset shifted to timeZoneName. (2023-01-01 12:00:00) |
| B | provided (2023-01-01 12:00:00+04:00) | default (UTC) | Each timestamp shifted to UTC according to its UTC offset designator. (2023-01-01 08:00:00.000Z) | 〃 | 〃 (2023-01-01 08:00:00) |
| C | not provided (2023-01-01 12:00:00) | other than default (Europe/Bratislava) | Dataset shifted from timeZoneName to UTC (dataset is assumed to be sampled in timeZoneName). (2023-01-01 11:00:00.000Z) | 〃 | 〃 (2023-01-01 12:00:00) |
| D | provided (2023-01-01 12:00:00+04:00) | other than default (Europe/Bratislava) | Each timestamp shifted to UTC according to its UTC offset designator; timeZoneName is ignored. (2023-01-01 08:00:00.000Z) | 〃 | 〃 (2023-01-01 09:00:00) |
Notes:
Zstands for the Zulu/UTC time (the same as +00:00)- 〃 is a ditto mark
- In winter, time in Europe/Bratislava time zone is one hour ahead of UTC
In summary, by providing UTC offset designators on timestamp level you control how TIM DB shifts the timestamps to UTC, nothing more is affected. The timeZoneName parameter is much more powerful - it is basically saying to TIM which time zone you want to work with the dataset in. Below we provide couple of examples to better understand these concepts.
Examples
The examples that make up the rest of this section illustrate the implications of incorrectly working with time zones and serve as a guideline of how TIM operates with time zones.
Dataset upload
Let's compare the dataset upload following the scenarios defined in the table above and with concrete values from the following table.
| Scenario | UTC offset designator on the timestamp level | timeZoneName | Last timestamp in the uploaded dataset |
|---|---|---|---|
| A | not provided | not provided (UTC) | 2010-07-14 23:00:00 |
| B | -05:00 | not provided (UTC) | 2010-07-14 23:00:00-05:00 |
| C | not provided | Asia/Tokyo | 2010-07-14 23:00:00 |
| D | -05:00 | Asia/Tokyo | 2010-07-14 23:00:00-05:00 |
By uploading such datasets we get the results below.
In scenario A, no time zone information was provided, so the dataset is stored as if it was collected in UTC. As expected, the last timestamp on the image matches the last timestamp of the uploaded dataset (2010-07-14 23:00:00).
In scenario B, timestamps are shifted back by 5 hours against UTC. This information is utilized by TIM DB when shifting the dataset to UTC - each timestamp is shifted 5 hours ahead. Since the timeZoneName is not provided, the dataset is rendered in UTC, so the last timestamp on the image (2010-07-15 04:00:00) is five hours ahead of the last timestamp of the uploaded dataset (2010-07-14 23:00:00).
In scenario C, the timeZoneName parameter is set to Asia/Tokyo (+9 hours shift against UTC). In this case TIM assumes the dataset is sampled in Asia/Tokyo time zone and the user also wants to work with the dataset in this time zone. Hence, the dataset is shifted 9 hours back to UTC for storing but then, before rendering, shifted back to Asia/Tokyo. That is the reason why the last timestamp on the image matches the last timestamp of the uploaded dataset (2010-07-14 23:00:00).
In scenario D, the timeZoneName parameter is set to Asia/Tokyo (+9 hours shift against UTC) and the dataset also contains UTC offset designators (-05:00) next to each timestamp. The dataset upload behaves the same as in scenario B - each timestamp is shifted 5 hours ahead when saving to TIM DB. However, user wants to work with the dataset in Asia/Tokyo time zone and therefore the last timestamp on the image (2010-07-15 13:00:00) is shifted 14 hours (5 + 9) ahead of the last timestamp of the uploaded dataset (2010-07-14 23:00:00).
Forecast
Now, let's see what happens if we try to build a forecasting model and create a day-ahead forecast on the four datasets from the dataset upload example. We will do this by setting the prediction from and prediction to parameters set to {"baseUnit": "Day", "value": 1} during job registration.
We can clearly see that the way how we upload the dataset has impact on where the forecast is created. The day-ahead forecast means that the forecast is created the next day after the day where the target variable ends. As the end of the target variable varies across the four datasets (as shown in the dataset upload example) so does the day-ahead forecast change.
Of course, the model will be different as well since the offsets of target variable are available from -1, -20, -1, and -11 hours in scenario A, B, C, and D respectively.
Timescale
Similarly as in the forecast example, also timescaling is influenced by time zone information specified during dataset upload. We apply one day timescale to the four datasets created in the dataset upload example. The results are depicted below.
Clearly, the dataset rescaled to one day sampling rate looks differently across the four scenarios. In scenario A and C the last data point is from 2010-07-14 00:00:00 while in scenario B and D the last data point is from 2010-07-15 00:00:00.