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 class

numpy: datetime64 and timedelta64

pandas: Timedelta, Timestamp, TimedeltaIndex, DatetimeIndex

pint.Quantity

strings representing a date ("2001-01-23 14:23:11") or a timedelta (23s)

The underlying implementation is based on the core pandas.TimedeltaIndex and pandas.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 as time parameter. In case time already contains absolute values and this parameter is set to None, 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 is False:

>>> 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 to Time as time 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 a Time 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 the length property or use len:

>>> 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

`all_close`	Return `True` if another object compares equal within a certain tolerance.
`as_data_array`	Return the time data as a `xarray.DataArray` coordinate.
`as_datetime`	Return the data as `pandas.DatetimeIndex`.
`as_pandas`	Return the underlying pandas time datatype.
`as_pandas_index`	Return a pandas index type regardless of length.
`as_quantity`	Return the data as `pint.Quantity`.
`as_timedelta`	Return the data as `pandas.TimedeltaIndex` or `pandas.Timedelta`.
`as_timedelta_index`	Return the data as `pandas.TimedeltaIndex`.
`as_timestamp`	Return a `pandas.Timestamp` if the object represents a timestamp.
`equals`	Test for matching `time` and `reference_time` between objects.
`resample`	Resample the covered duration.
`union`	Calculate the union of multiple time-like objects.

Attributes

`duration`	Get the covered time span.
`index`	Return a pandas index type regardless of length.
`is_absolute`	Return `True` if the class has a reference time and `False` otherwise.
`is_timestamp`	Return `True` if the data represents a timestamp and `False` otherwise.
`quantity`	Return the `pint.Quantity` representation scaled to seconds.
`reference_time`	Get the reference time.
`timedelta`	Return the timedelta values relative to the reference time (if it exists).