weldx.time.Time#
- class weldx.time.Time(time, time_ref=None)#
Provides a unified interface for time related operations.
The purpose of this class is to provide a unified interface for all operations related to time. This is important because time can have multiple representations. When working with time, some difficulties that might arise are the following:
we can have absolute times in form of dates and relative times in form of quantities
conversion factors between different time quantities differ. An hour consists of 60 minutes, but a day has only 24 hours
there are multiple time data types available in python like the ones provided by numpy or pandas. If you have to work with time classes from multiple libraries you might have to do a lot of conversions to perform simple tasks as calculating a time delta between two dates.
This class solves the mentioned problems for many cases. It can be created from many data types and offers methods to convert back to one of the supported types. Most of its methods also support the date types that can be used to create an instance of this class. Therefore, you do not need to perform any conversions yourself.
You can create the class from the following time representations:
other instances of the
Time
classnumpy:
datetime64
andtimedelta64
pandas:
Timedelta
,Timestamp
,TimedeltaIndex
,DatetimeIndex
strings representing a date (
"2001-01-23 14:23:11"
) or a timedelta (23s
)
The underlying implementation is based on the core
pandas.TimedeltaIndex
andpandas.DatetimeIndex
types, see the documentation for references.- Parameters:
time (
Union
[DatetimeIndex
,datetime64
,list
[str
],Time
,TimedeltaIndex
,Quantity
,timedelta64
,Timestamp
,str
,TimeDependent
]) – A supported class that represents either absolute or relative times. The data must be in ascending order. All classes derived from the abstract base class ‘TimeDependent’ are supported too.time_ref (
Union
[Timestamp
,str
,Time
,None
]) – An absolute reference point in time (timestamp). The return values of all accessors that return relative times will be calculated towards this reference time. This will turn the data of this class into absolute time values if relative times are passed astime
parameter. In casetime
already contains absolute values and this parameter is set toNone
, the first value of the data will be used as reference time.
- Raises:
ValueError – When time values passed are not sorted in monotonic increasing order.
Examples
Creation from a quantity:
>>> from weldx import Q_, Time >>> >>> quantity = Q_("10s") >>> t_rel = Time(quantity)
Since a quantity is not an absolute time like a date, the
is_absolute
property isFalse
:>>> t_rel.is_absolute False
To create an absolute value, just add a time stamp as
time_ref
parameter:>>> from pandas import Timestamp >>> >>> timestamp = Timestamp("2042-01-01 13:37") >>> t_abs = Time(quantity, timestamp) >>> t_abs.is_absolute True
Or use an absolute time type:
>>> t_abs = Time(timestamp) >>> t_abs.is_absolute True
>>> from pandas import DatetimeIndex >>> >>> dti = DatetimeIndex(["2001", "2002"]) >>> t_abs = Time(dti) >>> t_abs.is_absolute True
If you want to create a
Time
instance without importing anything else, just use strings:>>> # relative times >>> t_rel = Time("1h") >>> t_rel = Time(["3s","3h","3d"]) >>> >>> # absolute times >>> t_abs = Time(["1s","2s","3s"],"2010-10-05 12:00:00") >>> t_abs = Time("3h", "2010-08-11") >>> t_abs = Time("2014-07-23") >>> t_abs = Time(["2000","2001","2002"])
Types that are derived from the abstract base class
TimeDependent
can also be passed directly toTime
astime
parameter:>>> from weldx import LocalCoordinateSystem as LCS >>> lcs = LCS(coordinates=Q_([[0, 0, 0], [1, 1, 1]], "mm"), time=["1s", "2s"]) >>> t_from_lcs = Time(lcs) >>> >>> from weldx import TimeSeries >>> ts = TimeSeries(Q_([4, 5, 6], "m"), ["2000", "2001", "2002"]) >>> t_from_ts = Time(ts)
As long as one of the operands represents a timedelta, you can add two
Time
instances. If one of the instances is an array, the other one needs to be either a scalar or an array of same length. In the latter case, values are added per index:>>> t_res = Time(["1s", "2s"]) + Time("3s") >>> t_res = Time(["1s", "2s"]) + Time(["3s", "4s"]) >>> >>> t_res = Time(["1d", "2d"]) + Time("2000-01-01") >>> t_res = Time(["2001-01-01", "2001-01-02"]) + Time(["3d", "4d"])
Time
also accepts all other supported types on the right hand side of the+
operator:>>> t_res = Time(["1s", "2s"]) + Q_("10s") >>> t_res = Time(["1s", "2s"]) + DatetimeIndex(["2001", "2002"]) >>> t_res = Time(["1d", "2d"]) + "2000-01-01" >>> t_res = Time(["1s", "2s"]) + ["3s", "4s"]
Except for the numpy types and
pint.Quantity
other types are also supported on the left hand side:>>> t_res = DatetimeIndex(["2001", "2002"]) + Time(["1d", "2d"]) >>> t_res = "2000-01-01" + Time(["1d", "2d"]) >>> t_res = ["3s", "4s"] + Time(["1s", "2s"])
Subtraction is possible too, but there are some restrictions. It is not possible to subtract an absolute time from a time delta. Additionally, since the values of a
Time
instance must be monotonically increasing, any subtraction that produces a result that doesn’t fulfill this requirement will fail. This is always the case when subtracting arrays from scalars because either the array that is subtracted (it is internally cast to aTime
instance) or the resulting array violates this requirement. Apart from that, subtraction works pretty similar as the addition:>>> # absolute and time delta >>> t_res = Time("2002") - "1d" >>> t_res = Time(["2002", "2007", "2022"]) - "1d" >>> t_res = Time(["2002", "2007", "2022"]) - ["1d", "2d", "3d"] >>> >>> # both absolute >>> t_res = Time(["2002"]) - "2001" >>> t_res = Time(["2002", "2007", "2022"]) - "2001" >>> t_res = Time(["2002", "2007", "2022"]) - ["2001", "2002", "2003"] >>> >>> # both time delta >>> t_res = Time("2d") - "1d" >>> t_res = Time(["2d", "7d", "22d"]) - "1d" >>> t_res = Time(["2d", "7d", "22d"]) - ["1d", "2d", "3d"]
You can also compare two instances of
Time
:>>> Time(["1s"]) == Time(Q_("1s")) True
>>> Time("1s") == Time("2s") False
>>> Time("2000-01-01 17:00:00") == Time("2s") False
Note that any provided reference time is not taken into account when comparing two absolute time values. Only the values itself are compared:
>>> dti = DatetimeIndex(["2001", "2002", "2003"]) >>> all(Time(dti, "2000") == Time(dti, "2042")) True
If you want to include the reference times into the comparison, use the
equals
method.All supported types can also be used on the right hand side of the
==
operator:>>> all(Time(["2000", "2001"]) == DatetimeIndex(["2000", "2001"])) True
>>> all(Time(["1s", "2s"]) == Q_([1, 2],"s")) True
>>> Time("3s") == "20d" False
If you want to know how many entries are stored in a
Time
object, you can either use thelength
property or uselen
:>>> len(Time(["1s", "3s"])) 2
Direct access and iteration are also supported. The return types are fitting pandas types:
>>> t = Time(["1s", "2s", "3s"]) >>> t[1] Time: 0 days 00:00:02
>>> t = Time(["2000", "2001", "2002"]) >>> t[1] Time: 2001-01-01 00:00:00 reference time: 2000-01-01 00:00:00
>>> from pandas import Timedelta >>> >>> t = Time(["1s", "2s", "3s"]) >>> result = Timedelta(0, "s") >>> >>> for value in t: ... if not isinstance(value, Timedelta): ... raise TypeError("Unexpected type") ... result += value >>> >>> result Timedelta('0 days 00:00:06')
Methods
Return
True
if another object compares equal within a certain tolerance.Return the time data as a
xarray.DataArray
coordinate.Return the data as
pandas.DatetimeIndex
.Return the underlying pandas time datatype.
Return a pandas index type regardless of length.
Return the data as
pint.Quantity
.Return the data as
pandas.TimedeltaIndex
orpandas.Timedelta
.Return the data as
pandas.TimedeltaIndex
.Return a
pandas.Timestamp
if the object represents a timestamp.Test for matching
time
andreference_time
between objects.Resample the covered duration.
Calculate the union of multiple time-like objects.
Attributes
Get the covered time span.
Return a pandas index type regardless of length.
Return
True
if the class has a reference time andFalse
otherwise.Return
True
if the data represents a timestamp andFalse
otherwise.Return the
pint.Quantity
representation scaled to seconds.Get the reference time.
Return the timedelta values relative to the reference time (if it exists).