TimeAxis
The chapter What is a time series? outlined that a sequence of time points can be interpreted as
a list of non-overlapping time periods. This is represented by a TimeAxis
object which is able
to deal with fixed period time series as well as irregularly spaced time periods.
As the TimeAxis
object is fundamental to a TimeSeries object, it needs to be
created before the actual TimeSeries can be created. Its usage requires understanding
Calendar and time.
There are several ways to create a TimeAxis
and the right approach depends on the faced problem
and available data.
Create a TimeAxis object
Fixed interval time axis
The simplest time axis is defined by a start time, a delta time value and the number of periods.
This is also the most efficient one.
To create the time axis we need a starting point t0
, length of periods dt
and how
many periods n
.
The code below will create a time axis from the 01.01.2020 UTC until 08.01.2020 UTC with 24 hour
periods.
from shyft.time_series import Calendar, TimeAxis, deltahours
# Create a utc-based calendar.
utc = Calendar()
t0 = utc.time(2020, 1, 1)
dt = deltahours(24) # alternatively: dt = Calendar.DAY
n = 7
ta = TimeAxis(start=t0, delta_t=dt, n=n)
# TimeAxis('2020-01-01T00:00:00Z', 86400s, 7)
Ireggular interval time axis
A time axis with irregularly spaced time periods can be created with the list of defined time
points. The input time points are the starting point of each period, and we must add a last
argument t_end
to declare the end of the last period.
osl = sts.Calendar('Europe/Oslo')
t0 = osl.time(2021, 3, 1)
dt = sts.Calendar.MONTH
n = 5
ta_osl = sts.TimeAxis(calendar=osl, start=t0, delta_t=dt, n=n)
Note
If the t_end
is not supplied the time axis will assume that the last point in the list
is the end of the last period.
Calendar time axis
The third option when creating a time axis is a calendar time axis, this will make the time axis aware of what a month is in a calendar setting, as well as daylight savings time.
ta_fixed = sts.TimeAxis(t0, dt, n)
# TimeAxis('2021-03-28T20:00:00Z', 3600s, 5)
for t_osl, t_fix in zip(ta_osl.time_points, ta_fixed.time_points):
print(f'{osl.to_string(int(t_osl))} | {osl.to_string(int(t_fix))}')
And we can compare this with a fixed time axis
# 2021-05-01T00:00:00+02 | 2021-04-30T01:00:00+02
# 2021-06-01T00:00:00+02 | 2021-05-30T01:00:00+02
# 2021-07-01T00:00:00+02 | 2021-06-29T01:00:00+02
# 2021-08-01T00:00:00+02 | 2021-07-29T01:00:00+02
total_period = osl_ta.total_period()
# [2021-02-28T23:00:00Z,2021-07-31T22:00:00Z>
time_points = osl_ta.time_points
# array([1614553200, 1617228000, 1619820000, 1622498400, 1625090400,
# 1627768800])
Here we see that the calendar time axis (first column) always start the first of every calendar
month at the start of the day, while in the fixed time axis it naively goes 2592000 seconds
(Calendar.MONTH
) forward.
A few helpful functions
A few helpful functions that helps us explore a given time axis.
total_period()
returns a UtcPeriod
that spans the total period of the time axis.
total_period = osl_ta.total_period()
# [2021-02-28T23:00:00Z,2021-07-31T22:00:00Z>
time_points
returns an numpy.array
with each starting point per period
as well as the end of the last period.
time_points = osl_ta.time_points
# array([1614553200, 1617228000, 1619820000, 1622498400, 1625090400,
# 1627768800])
Note
time_points
returns time points in second resolution, as of now we need to use
time_points_double
to get sub-second resolution
size()
returns the number of periods in the time axis.
size_ta = osl_ta.size()
# 5