From 994dc4959fb12e9d2365bab904d43176ba80c60d Mon Sep 17 00:00:00 2001
From: Peter Luenenschloss <peter.luenenschloss@ufz.de>
Date: Fri, 6 Dec 2019 15:23:43 +0100
Subject: [PATCH] Update FunctionDescriptions.md
---
docs/FunctionDescriptions.md | 42 ++++++++++++++++++++++++++++++++++--
1 file changed, 40 insertions(+), 2 deletions(-)
diff --git a/docs/FunctionDescriptions.md b/docs/FunctionDescriptions.md
index 3e77e97cb..b6dad5a13 100644
--- a/docs/FunctionDescriptions.md
+++ b/docs/FunctionDescriptions.md
@@ -710,19 +710,57 @@ Key word overview:
if there is one available in the succeeding sampling interval. If not, BAD - flag gets assigned.
* `"nearest_shift"`: every grid point gets assigned the flag in its range. ( range = +/- `freq`/2 ).
* Extra flag fields like "comment", just get shifted along with the flag.
- Only inserted flags for empty intervals will signified by the set flag routine of the current flagger..
+ Only inserted flags for empty intervals will get signified by the set flag routine of the current flagger.
Set `set_shift_comment` to `True`, to apply setFlags signification to all flags.
2. Aggregations:
- * `"fagg"`: all falgs in a sampling interval get aggregated with the function passed to `agg_method`
+ * `"fagg"`: all flags in a sampling interval get aggregated with the function passed to `agg_method`
, and the result gets assigned to the last grid point.
* `"bagg"`: all flags in a sampling interval get aggregated with the function passed to `agg_method`
, and the result gets assigned to the next grid point.
* `"nearest_agg"`: all flags in the range (+/- freq/2) of a grid point get
aggregated with the function passed to agg_method and assigned to it.
+## `deharmonize`
+### Signature
+```
+deharmonize(co_flagging)
+```
+### Parameters
+| parameter | data type | default value | description |
+| --------- | --------- | ------------- | ----------- |
+| co_flagging | boolean | | |
+### Description
+
+After having calculated flags on an equidistant frequency grid, generated by
+a call to a harmonization function, you may want to project
+that new flags on to the original data index, or just restore the
+original data shape. Then a call to `deharmonize` will do exactly that.
+
+`deharmonize` will check for harmonization information for the variable it is
+applied on (automatically generated by any call to a harmonization function of that variable)
+and than:
+
+1. Overwrite the harmonized data series with the original dataseries and its timestamps.
+2. Project the calculated flags onto the original index, by inverting the
+ flag projection method used for harmonization, meaning, that:
+ * if the flags got shifted or aggregated forward, either the flag associated with the ultimatly preceeding
+ original timestamp, to the harmonized flag (`co_flagging`=`False`),
+ or all the flags, coverd by the harmonized flags preceeding sampling intervall (`co_flagging`=`True`)
+ get overwritten with the harmonized flag - if they are "better" than this harmonized flag.
+ (According to the flagging order of the current flagger.)
+ * if the flags got shifted or aggregated backwards, either the flag associated with the first succeeding
+ original timestamp, to the harmonized flag (`co_flagging`=`False`),
+ or all the flags, coverd by the harmonized flags succeeding sampling intervall (`co_flagging`=`True`)
+ get overwritten with the harmonized flag - if they are "better" than this harmonized flag.
+ (According to the flagging order of the current flagger.)
+ * if the flags got shifted or aggregated to the nearest harmonic index,
+ either the flag associated with the flag, nearest, to the harmonized flag (`co_flagging`=`False`),
+ or all the flags, covered by the harmonized flags range (`co_flagging`=`True`)
+ get overwritten with the harmonized flag - if they are "better" than this harmonized flag.
+ (According to the flagging order of the current flagger.)
--
GitLab