7. TimeSeries
Tutorial#
7.1. imports#
import numpy as np
import pandas as pd
from weldx import Q_, MathematicalExpression, TimeSeries
7.2. about the TimeSeries
class#
The TimeSeries
class is a general way to describe the behavior of a scalar or multidimensional quantity over time.
In principle, two different approaches can be taken to define this behavior:
use a symbolic mathematical expression to exactly define the time dependent relationship
provide discrete values with associated times and define how to interpolate the time dependent behavior between timesteps
After creating a TimeSeries
we can query the values at any point in time using the TimeSeries.interp_time()
method.
7.3. about unit support when using TimeSeries
#
TimeSeries
only works with Quantity
objects to enforce consistency in handling unit conversions, that means that all values have to be associated with a unit. When working with dimensionless data, this has to be explicitly stated by providing a dimensionless unit ""
.
The preferred way to create quantity data is to use the weldx-Q_
constructor.
7.4. About time formats#
Currently the time representation only supports relative
Timedelta
-like time values and no absoluteTimestamp
information.To describe time values, either
pandas.TimedeltaIndex
orpint.Quantity
describing time values are supported as we will show below.
7.5. Discrete Values Examples#
7.5.1. simple constant examples#
7.5.1.1. scalar constants#
We start by creating the simplest TimeSeries
object possible: a simple constant (scalar) value.
Since constant values are inherently independent of time we only have to provide the value to the TimeSeries
. Keep in mind to use Quantities here as well.
Lets create a simple TimeSeries representing a constant frequency of 5 Hz.
ts_constant = TimeSeries(Q_(5, "Hz"))
print(ts_constant)
<TimeSeries>
Constant value:
5
Units:
Hz
Let’s evaluate our constant timeseries at each second over a span of 10 seconds. To do this, we first create a pandas.TimedeltaIndex
that represents our desired timespan.
t = pd.timedelta_range(start="0s", end="10s", freq="s")
t
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq='S')
We can now use these timestamps to evaluate our constant timeseries.
ts_constant.interp_time(time=t)
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[5. 5. 5. 5. 5. 5. 5. 5. 5. 5. 5.]
Interpolation:
step
Units:
Hz
It is important to note, that TimeSeries.interp_time()
will always return its results as an xarray object with the following structure:
a single named
time
dimension with the evaluated timestamps as coordinate valuesthe data consisting of our constant value as a
Quantity
We can also create a simple plot, using the TimeSeries.plot
function:
ts_constant.plot(time=t, marker="o")
<Axes: xlabel='t in s', ylabel='values in Hz'>

7.5.1.2. multi-dimensional constant example#
We can also create multi-dimensional constant values. For this to work, we have to wrap our value into another dimension of length 1 to indicate a constant time axis.
For example, lets represent a single constant cartesian vector with our TimeSeries
:
ts_constant_vector = TimeSeries(Q_([[0, 2, 10]], "cm"))
print(ts_constant_vector)
<TimeSeries>
Constant value:
[ 0 2 10]
Units:
cm
Interpolation still works as expected:
ts = ts_constant_vector.interp_time(time=t)
print(ts)
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]
[ 0. 2. 10.]]
Interpolation:
step
Units:
cm
7.5.2. Interpolation examples#
The main idea of TimeSeries
is to reflect time dependent data. For values that change over time, we can define discrete values at specific points in time and pass the interpolation method on to the TimeSeries
.
Let’s say we want a value representing a velocity that starts at 10 cm/min, jumps to 15 cm/min between 2 and 6 seconds of our experiment and stays at 8 cm/min afterwards.
To represent this behavior we can use the step
interpolation method.
ts_step = TimeSeries(
data=Q_([10, 15, 8], "cm/min"),
time=pd.TimedeltaIndex(data=[0, 2, 6], unit="s"),
interpolation="step",
)
ts_step
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:02', '0 days 00:00:06'], dtype='timedelta64[ns]', freq=None)
Values:
[10 15 8]
Interpolation:
step
Units:
cm / min
lets interpolate this to our previous timeline and see the results
ts = ts_step.interp_time(t)
print(ts)
ts.plot(marker="o")
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[10 10 15 15 15 15 8 8 8 8 8]
Interpolation:
step
Units:
cm / min
<Axes: xlabel='t in s', ylabel='values in cm / min'>

The second supported interpolation style is linear
. Let’s use this to create a timeseries that increases from 100 A to 200 A between 3 seconds and 7 seconds of the experiment.
ts_linear = TimeSeries(
data=Q_([100, 200], "A"),
time=pd.TimedeltaIndex(data=[3, 7], unit="s"),
interpolation="linear",
)
ts_linear
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:03', '0 days 00:00:07'], dtype='timedelta64[ns]', freq=None)
Values:
[100 200]
Interpolation:
linear
Units:
A
ts = ts_linear.interp_time(t)
print(ts)
ts.plot(marker="o")
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[100. 100. 100. 100. 125. 150. 175. 200. 200. 200. 200.]
Interpolation:
linear
Units:
A
<Axes: xlabel='t in s', ylabel='values in A'>

One important note about TimeSeries.interp_time()
that can be seen from the plot above:
Even though we only defined the TimeSeries
discrete values at timesteps 3s and 7s, the interpolation gives back results outside of that timerange as well. This is the current intended behavior of all timeseries interpolations. The last defined values will be propagated as constant values outside of the initial time range. The initial and final values are preserved even when not included in the interpolation time.
ts = ts_linear.interp_time(t + pd.Timedelta(0.5, "s"))
print(ts)
ts.plot(marker="o")
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00.500000', '0 days 00:00:01.500000',
'0 days 00:00:02.500000', '0 days 00:00:03.500000',
'0 days 00:00:04.500000', '0 days 00:00:05.500000',
'0 days 00:00:06.500000', '0 days 00:00:07.500000',
'0 days 00:00:08.500000', '0 days 00:00:09.500000',
'0 days 00:00:10.500000'],
dtype='timedelta64[ns]', freq=None)
Values:
[100. 100. 100. 112.5 137.5 162.5 187.5 200. 200. 200. 200. ]
Interpolation:
linear
Units:
A
<Axes: xlabel='t in s', ylabel='values in A'>

7.6. Mathematical expression examples#
The second method to describe our TimeSeries
object is by providing a MathematicalExpression
that can be evaluated against time parameters.
7.6.1. linear equation example#
Let’s create a linear ramp function as an example: $f(t) = a*t + b$.
Note that all parameters must be defined as Quantities
in a way that the expression correctly evaluates all dimensions when provided with a time-dimension input (in our case for parameter t
)
expr_string = "a*t+b"
parameters = {"a": Q_("120 m/min"), "b": Q_("-10 m")}
expr = MathematicalExpression(expression=expr_string, parameters=parameters)
ts_expr = TimeSeries(data=expr)
ts = ts_expr.interp_time(t)
print(ts)
ts.plot(marker="o")
<TimeSeries>
Time:
Time:
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
'0 days 00:00:03', '0 days 00:00:04', '0 days 00:00:05',
'0 days 00:00:06', '0 days 00:00:07', '0 days 00:00:08',
'0 days 00:00:09', '0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[-600. -480. -360. -240. -120. 0. 120. 240. 360. 480. 600.]
Interpolation:
step
Units:
m * s / min
<Axes: xlabel='t in s', ylabel='values in m * s / min'>

We can also use Quantites
with the appropriate dimension as Inputs for our interpolation:
t2 = Q_(np.arange(101) * 100, "ms")
ts = ts_expr.interp_time(t2)
ts.plot(marker="o")
<Axes: xlabel='t in s', ylabel='values in m * s / min'>

7.6.2. sine example#
Of course we can also have more complex examples. Lets create a sine wave function that oscillates around 1 m at a frequency of 36 deg/s.
expr_string = "a*sin(o*t)+b"
parameters = {"a": Q_("1 m"), "b": Q_("1 m"), "o": Q_("36 deg/s")}
expr = MathematicalExpression(expression=expr_string, parameters=parameters)
ts_sine = TimeSeries(data=expr)
ts = ts_sine.interp_time(pd.timedelta_range(start="0s", end="10s", freq="100ms"))
ts.plot(marker="o")
<Axes: xlabel='t in s', ylabel='values in m'>

7.6.3. vector example#
With careful syntax it is also possible to create multidimensional TimeSeries
objects from math expressions.
expr_string = "a*sin(o*t)+b*t"
parameters = {
"a": Q_(np.asarray([1, 0, 0]), "m"),
"b": Q_([0, 1, 0], "m/s"),
"o": Q_("36 deg/s"),
}
expr = MathematicalExpression(expression=expr_string, parameters=parameters)
ts_vector = TimeSeries(data=expr)
ts = ts_vector.interp_time(pd.timedelta_range(start="0s", end="10s", freq="500ms"))
print(ts)
<TimeSeries>
Time:
Time:
TimedeltaIndex([ '0 days 00:00:00', '0 days 00:00:00.500000',
'0 days 00:00:01', '0 days 00:00:01.500000',
'0 days 00:00:02', '0 days 00:00:02.500000',
'0 days 00:00:03', '0 days 00:00:03.500000',
'0 days 00:00:04', '0 days 00:00:04.500000',
'0 days 00:00:05', '0 days 00:00:05.500000',
'0 days 00:00:06', '0 days 00:00:06.500000',
'0 days 00:00:07', '0 days 00:00:07.500000',
'0 days 00:00:08', '0 days 00:00:08.500000',
'0 days 00:00:09', '0 days 00:00:09.500000',
'0 days 00:00:10'],
dtype='timedelta64[ns]', freq=None)
Values:
[[ 0.00000000e+00 0.00000000e+00 0.00000000e+00]
[ 3.09016994e-01 5.00000000e-01 0.00000000e+00]
[ 5.87785252e-01 1.00000000e+00 0.00000000e+00]
[ 8.09016994e-01 1.50000000e+00 0.00000000e+00]
[ 9.51056516e-01 2.00000000e+00 0.00000000e+00]
[ 1.00000000e+00 2.50000000e+00 0.00000000e+00]
[ 9.51056516e-01 3.00000000e+00 0.00000000e+00]
[ 8.09016994e-01 3.50000000e+00 0.00000000e+00]
[ 5.87785252e-01 4.00000000e+00 0.00000000e+00]
[ 3.09016994e-01 4.50000000e+00 0.00000000e+00]
[ 1.22464680e-16 5.00000000e+00 0.00000000e+00]
[-3.09016994e-01 5.50000000e+00 0.00000000e+00]
[-5.87785252e-01 6.00000000e+00 0.00000000e+00]
[-8.09016994e-01 6.50000000e+00 0.00000000e+00]
[-9.51056516e-01 7.00000000e+00 0.00000000e+00]
[-1.00000000e+00 7.50000000e+00 0.00000000e+00]
[-9.51056516e-01 8.00000000e+00 0.00000000e+00]
[-8.09016994e-01 8.50000000e+00 0.00000000e+00]
[-5.87785252e-01 9.00000000e+00 0.00000000e+00]
[-3.09016994e-01 9.50000000e+00 0.00000000e+00]
[-2.44929360e-16 1.00000000e+01 0.00000000e+00]]
Interpolation:
step
Units:
m
Here is a plot showing the x,y,z coordinates:
ts.plot(marker="o")
<Axes: xlabel='t in s', ylabel='values in m'>
