From a29c7d40fcafa82e63015b51fdb1731970a6f521 Mon Sep 17 00:00:00 2001
From: Mario Fink <knif.oiram@gmail.com>
Date: Tue, 19 Jan 2021 14:11:03 +0100
Subject: [PATCH] update README.md with docu

---
 README.md          | 45 +++++++++++++++++++++++++++++++++++++++++++--
 lib/tdm_reaper.hpp |  9 ++++-----
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e861e41..cba2d0b 100644
--- a/README.md
+++ b/README.md
@@ -61,8 +61,8 @@ looks basically like this:
 ```
 
 and is comprised of _four_ main XML elements: `usi:documentation`, `usi:model`,
-`usi:include` and `usi:data`. The element `usi:include` reveals one of _two_
-possible orderings of the mass data (.tdx):
+`usi:include` and `usi:data`. The element `usi:include` references the data file
+`example.tdx` and reveals one of _two_ possible orderings of the mass data (.tdx):
 
 1. either _channel wise_ (`<block>`) - all values of a specific channel follow subsequently -
 1. or _block wise_ (`<block_bm>`) - all values of a specific measurement time follow subsequently -
@@ -80,6 +80,47 @@ ordering. The supported _numerical data types_ are
 | eFloat64Usi | DT_DOUBLE        | 7       | double_sequence | 8byte | 64 Bit double           |
 | eStringUsi  | DT_STRING        | 1       | string_sequence |       | text                    |
 
+The XML element `<usi:data>` is basically comprised of _five_ different types of
+elements that are `<tdm_root>`, `<tdm_channelgroup>`, `<tdm_channel>`, `<localcolumn>`
+and `<submatrix>`. The root element `<tdm_root>` describes the general properties
+of the dataset and lists the _id's_ of all channel groups that belong to
+the dataset. The element `<tdm_channelgroup>` divides the _channels_ into groups
+and has a unique _id_ that is referenced by its root element. The `<channels>`
+element in `<tdm_channelgroup>` lists the unique ids of all channels that belong
+to that group. Finally, the element `<tdm_channel>` describes a single column of
+actual data including its datatype. The remaining element types are
+`<localcolumn>`
+
+```xml
+<localcolumn id="usiXY">
+  <name>Untitled</name>
+  <measurement_quantity>#xpointer(id("usiAB"))</measurement_quantity>
+  <submatrix>#xpointer(id("usiMN"))</submatrix>
+  <global_flag>15</global_flag>
+  <independent>0</independent>
+  <sequence_representation> ... </sequence_representation>
+  <values>#xpointer(id("usiZ"))</values>
+</localcolumn>
+```
+
+with a unique id, the `<measurement_quantity>` refering to one specific channel,
+the `<submatrix>` and its id respectively, the type of representation in
+`<sequence_representation>` - being one of _explicit_, _implicit linear_ or
+_rawlinear_ - and the `<values>` element, which refers to one _value sequence_,
+and the element `<submatrix>`
+
+```xml
+<submatrix id="usiXX">
+  <name>Untitled</name>
+  <measurement>#xpointer(id("usiUV"))</measurement>
+  <number_of_rows>N</number_of_rows>
+  <local_columns>#xpointer(id("usiMN"))</local_columns>
+</submatrix>
+```
+
+that references the channel group in `<measurement>` it belongs to and provides
+the _number of rows_ in the channels listed in `<local_columns>`.
+
 ## Installation
 
 The library can be used both as a _CLI_ based tool and as a _Python_ module.
diff --git a/lib/tdm_reaper.hpp b/lib/tdm_reaper.hpp
index e56a101..83b34f8 100644
--- a/lib/tdm_reaper.hpp
+++ b/lib/tdm_reaper.hpp
@@ -152,8 +152,8 @@ struct tdm_channel {
 // https://zone.ni.com/reference/de-XX/help/370858P-0113/tdmdatamodel/tdmdatamodel/tdm_tdxdata_submatrix/
 struct tdm_submatrix {
   std::string name_;
-  unsigned long int number_of_rows_;
-  unsigned long int measurement_id_;
+  unsigned long int number_of_rows_;  // -> number of values in channels
+  unsigned long int measurement_id_;  // -> channelgroup
   unsigned long int local_column_id_;
 };
 
@@ -171,9 +171,9 @@ struct localcolumn {
   double minimum_, maximum_;
   representation sequence_representation_;
   std::vector<double> generation_parameters_; // { offset, factor }
-  unsigned long int measurement_quantity_id_;
+  unsigned long int measurement_quantity_id_; // -> references single channel
   unsigned long int submatrix_id_;
-  unsigned long int values_id_;
+  unsigned long int values_id_;               // -> refers to usi:data -> _sequence
 };
 
 // -------------------------------------------------------------------------- //
@@ -183,7 +183,6 @@ class tdm_ripper
   // .tdm and .tdx paths/filenames
   std::string tdmfile_;
   std::string tdxfile_;
-  bool suppress_status_;
 
   // set of .csv files
   std::vector<std::string> csvfile_;