renamed the translation methods

CHANGELOG.md

@@ -10,7 +10,9 @@ SPDX-License-Identifier: GPL-3.0-or-later
 [List of commits](https://git.ufz.de/rdm-software/saqc/-/compare/v2.2.1...develop)
 ### Added
 ### Changed
-- The default flagging scheme `FloatTranslator` now accepts non-integer values
+- Remove all flag value restrictions from the default flagging scheme `FloatTranslator` 
+- Renamed `TranslationScheme.forward` to `TranslationScheme.toInternal` 
+- Renamed `TranslationScheme.backward` to `TranslationScheme.toExternal` 
 ### Removed
 ### Fixed
 

saqc/core/core.py

@@ -110,7 +110,7 @@ class SaQC(FunctionsMixin):
 
     @property
     def flags(self) -> MutableMapping:
-        flags = self._scheme.backward(self._flags, attrs=self._attrs)
+        flags = self._scheme.toExternal(self._flags, attrs=self._attrs)
         flags.attrs = self._attrs.copy()
         return flags
 

saqc/core/translation/basescheme.py

@@ -34,11 +34,11 @@ class TranslationScheme:  # pragma: no cover
         pass
 
     @abstractmethod
-    def forward(self, flags: pd.DataFrame | DictOfSeries) -> Flags:
+    def toInternal(self, flags: pd.DataFrame | DictOfSeries) -> Flags:
         pass
 
     @abstractmethod
-    def backward(self, flags: Flags, attrs: dict | None = None) -> DictOfSeries:
+    def toExternal(self, flags: Flags, attrs: dict | None = None) -> DictOfSeries:
         pass
 
 
@@ -150,7 +150,7 @@ class MappingScheme(TranslationScheme):
             return float(flag)
         return float(self._forward[flag])
 
-    def forward(self, flags: pd.DataFrame | DictOfSeries | pd.Series) -> Flags:
+    def toInternal(self, flags: pd.DataFrame | DictOfSeries | pd.Series) -> Flags:
         """
         Translate from 'external flags' to 'internal flags'
 
@@ -165,7 +165,7 @@ class MappingScheme(TranslationScheme):
         """
         return Flags(self._translate(flags, self._forward))
 
-    def backward(
+    def toExternal(
         self,
         flags: Flags,
         attrs: dict | None = None,
@@ -206,7 +206,7 @@ class FloatScheme(TranslationScheme):
         except (TypeError, ValueError, OverflowError):
             raise ValueError(f"invalid flag, expected a numerical value, got: {flag}")
 
-    def forward(self, flags: pd.DataFrame | DictOfSeries) -> Flags:
+    def toInternal(self, flags: pd.DataFrame | DictOfSeries) -> Flags:
         try:
             return Flags(flags.astype(float))
         except (TypeError, ValueError, OverflowError):
@@ -214,7 +214,7 @@ class FloatScheme(TranslationScheme):
                 f"invalid flag(s), expected a collection of numerical values, got: {flags}"
             )
 
-    def backward(self, flags: Flags, attrs: dict | None = None) -> DictOfSeries:
+    def toExternal(self, flags: Flags, attrs: dict | None = None) -> DictOfSeries:
         out = flags.toDios()
         out.attrs = attrs or {}
         return out

saqc/core/translation/dmpscheme.py

@@ -91,7 +91,7 @@ class DmpScheme(MappingScheme):
             field_history.append(histcol, meta=meta)
         return field_history
 
-    def forward(self, df: pd.DataFrame) -> Flags:
+    def toInternal(self, df: pd.DataFrame) -> Flags:
         """
         Translate from 'external flags' to 'internal flags'
 
@@ -114,7 +114,7 @@ class DmpScheme(MappingScheme):
 
         return Flags(data)
 
-    def backward(
+    def toExternal(
         self, flags: Flags, attrs: dict | None = None, **kwargs
     ) -> pd.DataFrame:
         """
@@ -131,7 +131,7 @@ class DmpScheme(MappingScheme):
         -------
         translated flags
         """
-        tflags = super().backward(flags, attrs=attrs)
+        tflags = super().toExternal(flags, attrs=attrs)
 
         out = pd.DataFrame(
             index=reduce(lambda x, y: x.union(y), tflags.indexes).sort_values(),

saqc/core/translation/positionalscheme.py

@@ -43,7 +43,7 @@ class PositionalScheme(MappingScheme):
     def __init__(self):
         super().__init__(forward=self._FORWARD, backward=self._BACKWARD)
 
-    def forward(self, flags: pd.DataFrame) -> Flags:
+    def toInternal(self, flags: pd.DataFrame) -> Flags:
         """
         Translate from 'external flags' to 'internal flags'
 
@@ -75,7 +75,7 @@ class PositionalScheme(MappingScheme):
 
         return Flags(data)
 
-    def backward(self, flags: Flags, **kwargs) -> pd.DataFrame:
+    def toExternal(self, flags: Flags, **kwargs) -> pd.DataFrame:
         """
         Translate from 'internal flags' to 'external flags'
 

tests/core/test_translator.py

@@ -60,7 +60,7 @@ def test_backwardTranslation():
     for _, scheme in _genTranslators():
         keys = tuple(scheme._backward.keys())
         flags = _genFlags({field: np.array(keys)})
-        translated = scheme.backward(flags)
+        translated = scheme.toExternal(flags)
         expected = set(scheme._backward.values())
         assert not (set(translated[field]) - expected)
 
@@ -72,7 +72,7 @@ def test_backwardTranslationFail():
         # add an scheme invalid value to the flags
         flags = _genFlags({field: np.array(keys + (max(keys) + 1,))})
         with pytest.raises(ValueError):
-            scheme.backward(flags)
+            scheme.toExternal(flags)
 
 
 def test_dmpTranslator():
@@ -94,7 +94,7 @@ def test_dmpTranslator():
         {"func": "flagFoo", "kwargs": {"cause": "BELOW_OR_ABOVE_MIN_MAX"}}
     )
 
-    tflags = scheme.backward(flags)
+    tflags = scheme.toExternal(flags)
 
     assert set(tflags.columns.get_level_values(1)) == {
         "quality_flag",
@@ -137,7 +137,7 @@ def test_positionalTranslator():
     flags[1::3, "var1"] = DOUBTFUL
     flags[2::3, "var1"] = BAD
 
-    tflags = scheme.backward(flags)
+    tflags = scheme.toExternal(flags)
     assert (tflags["var2"].replace(-9999, np.nan).dropna() == 90).all(axis=None)
     assert (tflags["var1"].iloc[1::3] == 90210).all(axis=None)
     assert (tflags["var1"].iloc[2::3] == 90002).all(axis=None)
@@ -156,7 +156,7 @@ def test_positionalTranslatorIntegration():
     for field in flags.columns:
         assert flags[field].astype(str).str.match("^9[012]*$").all()
 
-    round_trip = scheme.backward(scheme.forward(flags))
+    round_trip = scheme.toExternal(scheme.toInternal(flags))
 
     assert (flags.values == round_trip.values).all()
     assert (flags.index == round_trip.index).all()
@@ -183,7 +183,7 @@ def test_dmpTranslatorIntegration():
     assert qfunc.isin({"", "flagMissing", "flagRange"}).all(axis=None)
     assert (qcause[qflags[col] == "BAD"] == "OTHER").all(axis=None)
 
-    round_trip = scheme.backward(scheme.forward(flags))
+    round_trip = scheme.toExternal(scheme.toInternal(flags))
 
     assert round_trip.xs("quality_flag", axis="columns", level=1).equals(qflags)
 
@@ -276,8 +276,8 @@ def test_positionalMulitcallsPreserveState():
     scheme = PositionalScheme()
     flags1 = saqc1._flags
     flags2 = saqc2._flags
-    tflags1 = scheme.backward(flags1).astype(str)
-    tflags2 = scheme.backward(flags2).astype(str)
+    tflags1 = scheme.toExternal(flags1).astype(str)
+    tflags2 = scheme.toExternal(flags2).astype(str)
 
     for k in flags2.columns:
         expected = tflags1[k].str.slice(start=1) * 2