{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# `TimeSeries` Tutorial\n",
    "## imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "from weldx import Q_, MathematicalExpression, TimeSeries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## about the `TimeSeries` class\n",
    "The `TimeSeries` class is a general way to describe the behavior of a scalar or multidimensional quantity over time.\n",
    "\n",
    "In principle, two different approaches can be taken to define this behavior:\n",
    "\n",
    "1. use a symbolic mathematical expression to exactly define the time dependent relationship\n",
    "2. provide discrete values with associated times and define how to interpolate the time dependent behavior between timesteps\n",
    "\n",
    "After creating a `TimeSeries` we can query the values at any point in time using the `TimeSeries.interp_time()` method.\n",
    "\n",
    "## about unit support when using `TimeSeries`\n",
    "`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 `\"\"`.\n",
    "The preferred way to create quantity data is to use the weldx-`Q_` constructor.\n",
    "\n",
    "## About time formats\n",
    "  - Currently the time representation only supports relative `Timedelta`-like time values and no absolute `Timestamp` information.\n",
    "  - To describe time values, either `pandas.TimedeltaIndex` or `pint.Quantity` describing time values are supported as we will show below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Discrete Values Examples\n",
    "### simple constant examples\n",
    "#### scalar constants\n",
    "We start by creating the simplest `TimeSeries` object possible: a simple constant (scalar) value.\n",
    "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.\n",
    "\n",
    "Lets create a simple TimeSeries representing a constant frequency of 5 Hz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_constant = TimeSeries(Q_(5, \"Hz\"))\n",
    "print(ts_constant)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "t = pd.timedelta_range(start=\"0s\", end=\"10s\", freq=\"s\")\n",
    "t"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now use these timestamps to evaluate our constant timeseries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_constant.interp_time(time=t)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is important to note, that `TimeSeries.interp_time()` will always return its results as an xarray object with the following structure:\n",
    "\n",
    "- a single named `time` dimension with the evaluated timestamps as coordinate values\n",
    "- the data consisting of our constant value as a `Quantity`\n",
    "\n",
    "We can also create a simple plot, using the `TimeSeries.plot` function: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_constant.plot(time=t, marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### multi-dimensional constant example\n",
    "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.\n",
    "For example, lets represent a single constant cartesian vector with our `TimeSeries`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_constant_vector = TimeSeries(Q_([[0, 2, 10]], \"cm\"))\n",
    "print(ts_constant_vector)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Interpolation still works as expected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts = ts_constant_vector.interp_time(time=t)\n",
    "print(ts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interpolation examples\n",
    "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`.\n",
    "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.\n",
    "To represent this behavior we can use the `step` interpolation method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_step = TimeSeries(\n",
    "    data=Q_([10, 15, 8], \"cm/min\"),\n",
    "    time=pd.TimedeltaIndex(data=[0, 2, 6], unit=\"s\"),\n",
    "    interpolation=\"step\",\n",
    ")\n",
    "ts_step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "lets interpolate this to our previous timeline and see the results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts = ts_step.interp_time(t)\n",
    "print(ts)\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts_linear = TimeSeries(\n",
    "    data=Q_([100, 200], \"A\"),\n",
    "    time=pd.TimedeltaIndex(data=[3, 7], unit=\"s\"),\n",
    "    interpolation=\"linear\",\n",
    ")\n",
    "ts_linear"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts = ts_linear.interp_time(t)\n",
    "print(ts)\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One important note about `TimeSeries.interp_time()` that can be seen from the plot above:\n",
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts = ts_linear.interp_time(t + pd.Timedelta(0.5, \"s\"))\n",
    "print(ts)\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mathematical expression examples\n",
    "The second method to describe our `TimeSeries` object is by providing a `MathematicalExpression` that can be evaluated against time parameters.\n",
    "\n",
    "### linear equation example\n",
    "Let's create a linear ramp function as an example: $f(t) = a*t + b$.\n",
    "\n",
    "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`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_string = \"a*t+b\"\n",
    "parameters = {\"a\": Q_(\"120 m/min\"), \"b\": Q_(\"-10 m\")}\n",
    "expr = MathematicalExpression(expression=expr_string, parameters=parameters)\n",
    "\n",
    "ts_expr = TimeSeries(data=expr)\n",
    "\n",
    "ts = ts_expr.interp_time(t)\n",
    "print(ts)\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use `Quantites` with the appropriate dimension as Inputs for our interpolation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "t2 = Q_(np.arange(101) * 100, \"ms\")\n",
    "ts = ts_expr.interp_time(t2)\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### sine example\n",
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_string = \"a*sin(o*t)+b\"\n",
    "parameters = {\"a\": Q_(\"1 m\"), \"b\": Q_(\"1 m\"), \"o\": Q_(\"36 deg/s\")}\n",
    "expr = MathematicalExpression(expression=expr_string, parameters=parameters)\n",
    "\n",
    "ts_sine = TimeSeries(data=expr)\n",
    "\n",
    "ts = ts_sine.interp_time(pd.timedelta_range(start=\"0s\", end=\"10s\", freq=\"100ms\"))\n",
    "ts.plot(marker=\"o\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### vector example\n",
    "With careful syntax it is also possible to create multidimensional `TimeSeries` objects from math expressions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_string = \"a*sin(o*t)+b*t\"\n",
    "parameters = {\n",
    "    \"a\": Q_(np.asarray([1, 0, 0]), \"m\"),\n",
    "    \"b\": Q_([0, 1, 0], \"m/s\"),\n",
    "    \"o\": Q_(\"36 deg/s\"),\n",
    "}\n",
    "expr = MathematicalExpression(expression=expr_string, parameters=parameters)\n",
    "\n",
    "ts_vector = TimeSeries(data=expr)\n",
    "\n",
    "ts = ts_vector.interp_time(pd.timedelta_range(start=\"0s\", end=\"10s\", freq=\"500ms\"))\n",
    "print(ts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is a plot showing the x,y,z coordinates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts.plot(marker=\"o\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "",
   "language": "python",
   "name": ""
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}