Add MeasurementChain introduction for new tutorial series

CHANGELOG.rst

@@ -10,6 +10,7 @@ added
 =====
 
 - New tutorial that demonstrates the usage of the CSM in conjunction with an existing WelDX file [:pull:`793`]
+- New tutorial about the ``MeasurementChain`` class using an existing WelDX file [:pull:`796`]
 
 changes
 =======

doc/tutorials.rst

@@ -20,6 +20,7 @@ data processing and visualization.
    tutorials/01_02_time_dependent_data
    tutorials/01_03_geometry
    tutorials/01_04_coordinate_systems
+   tutorials/01_05_measurement_chains
 
 ******************
  Welding Examples

tutorials/01_05_measurement_chains.ipynb

@@ -0,0 +1,280 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6ac1a1a6",
+   "metadata": {},
+   "source": [
+    "# Measurement chains \n",
+    "\n",
+    "[<< PREVIOUS TUTORIAL](01_04_coordinate_systems.ipynb)\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "**This tutorial covers:**\n",
+    "\n",
+    "The `MeasurementChain` class that describes in detail how the experimental date was acquired\n",
+    "\n",
+    "**Requirements:**\n",
+    "\n",
+    "- Opening and navigating through WelDX files ([tutorial](01_01_introduction.ipynb))\n",
+    "- Dealing with time-dependent data ([tutorial](01_02_time_dependent_data.ipynb))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14844f2e-0e45-42f9-8df5-da5f258cc640",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# download the example file for this tutorial\n",
+    "\n",
+    "from util import download_tutorial_input_file\n",
+    "\n",
+    "download_tutorial_input_file(print_status=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1804362d",
+   "metadata": {},
+   "source": [
+    "## Plotting the measurement chain\n",
+    "\n",
+    "When working with experimental data we sometimes need more information than just the pure data itself.\n",
+    "For example, we might want to know how large the measurement error can be or if the data has already been preprocessed before it was written to the file.\n",
+    "Getting this information might be challenging because the person who conducted the experiment might be not available to you or the information is simply lost because nobody remembers and it hasn't been documented.\n",
+    "\n",
+    "WelDX solves this problem by enforcing that the experimental setup is actually documented and stored during the creation of a file.\n",
+    "Therefore, it uses a dedicated data structure called the `Measurement`.\n",
+    "Let's get it out of our example file and explore the information it provides.\n",
+    "\n",
+    "As always, we get us a quick overview of the file content to find out how to access the data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bf7e1936",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from weldx import WeldxFile\n",
+    "\n",
+    "wxfile = WeldxFile(\"single_pass_weld.wx\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "92a600db",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "wxfile.info()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5b010094",
+   "metadata": {},
+   "source": [
+    "From the file content we see, that there actually multiple `Measurement` objects stored under the key `\"measurements\"`.\n",
+    "Let's extract the list and print the names of all measurements by using the `name` attribute of the `Measurement` class:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9b812e97",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "measurements = wxfile[\"measurements\"]\n",
+    "for measurement in measurements:\n",
+    "    print(measurement.name)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "19af52ee",
+   "metadata": {},
+   "source": [
+    "From the output we learn that there are a current, voltage and two temperature measurements.\n",
+    "We will pick the current measurement for further discussion:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e0b5405",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_measurement = measurements[0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "989547dc",
+   "metadata": {},
+   "source": [
+    "The `Measurement` class is just a data container that stores the name of a measurement, the data that belongs to it, and a special class called `MeasurementChain`.\n",
+    "The `MeasurementChain` documents the setup of a measurement and provides a complete overview of the different involved processing steps.\n",
+    "Let's extract it from the `Measurement` class:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dfce377b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_measurement_chain = current_measurement.measurement_chain"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f91db18c-8322-494f-bc19-af4386d1660c",
+   "metadata": {},
+   "source": [
+    "The easiest way to get an overview of the `MeasurementChain` is to call the `plot` function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cd66684c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_measurement_chain.plot();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3b04b5db-ac56-4efc-9430-24d991111154",
+   "metadata": {},
+   "source": [
+    "As you can see in the flow chart, we had an initial analog signal that was converted to a digital one by an AD converter.\n",
+    "By applying the calibration, we finally got a digital signal that corresponds to the welding current.\n",
+    "We only stored values after the last transformation step as measurement data.\n",
+    "\n",
+    "The plot also shows us the formulas of the transformation step.\n",
+    "Furthermore, the error percentage of the AD-conversion is shown.\n",
+    "\n",
+    "## Extracting the data\n",
+    "\n",
+    "With the `get_signal_data` function, we can extract the data from the `MeasurementChain`.\n",
+    "But this requires us to provide the name of the signal that was recorded.\n",
+    "The signal name is equal to the preceding transformation or source name.\n",
+    "We could deduce this from the plot, but another way is to use the `transformation_names` and `source_name` functions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14436e53-9a71-4d37-a04c-b8afa275fa04",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_measurement_chain.transformation_names"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "595b60c9-a085-4909-a27b-d9159f5f7049",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_measurement_chain.source_name"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30c2ca1b-933f-456c-836e-ed644f2de08f",
+   "metadata": {},
+   "source": [
+    "Because only the data after the calibration step was stored, we use `\"current_calibration\"` as input to `get_signal_data`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1a1803c8-b959-4344-bde1-10edc2d4ee22",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_data = current_measurement_chain.get_signal_data(\"current calibration\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4abe6057-4e47-45a3-9f83-6a08693677b0",
+   "metadata": {},
+   "source": [
+    "The returned data is a `TimeSeries` that was [introduced in an earlier tutorial](01_02_time_dependent_data.ipynb).\n",
+    "We can simply call its `plot` function to take a look at the data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "01c66e92-f590-4bb7-a467-9fa3899afcbe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "current_data.plot();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4bdc57d9-e61c-44dc-8b94-65cba6bcb46a",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "This tutorial demonstrated that WelDX provides a class called `MeasurementChain` that captures not only the measurement data itself but also important meta data about how it was gathered.\n",
+    "It has a useful visualization method that provides a quick overview over the experimental setup.\n",
+    "\n",
+    "## Further readings\n",
+    "\n",
+    "- [`MeasurementChain` - full tutorial](measurement_chain.ipynb)\n",
+    "\n",
+    "[<< PREVIOUS TUTORIAL](01_04_coordinate_systems.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d5e2d5a1-63ce-41e1-981a-b8fc83cf2f2e",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "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.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}