From 0c31e0b8619b5d5abf017fc82d7d25de20af9935 Mon Sep 17 00:00:00 2001
From: leufen1 <l.leufen@fz-juelich.de>
Date: Thu, 12 Nov 2020 19:10:07 +0100
Subject: [PATCH] expanded input date range for mixed sampling data handler
(will not expand target date range and therefore sampling date range, but
reduced data loss)
---
docs/_source/_plots/separation_of_scales.png | Bin 0 -> 31085 bytes
mlair/data_handler/data_handler_kz_filter.py | 6 +-
.../data_handler_mixed_sampling.py | 56 +++++++++++++--
.../data_handler_single_station.py | 14 ++--
test/test_data_handler/test_data_handler.py | 67 ++++++++++++++++++
5 files changed, 126 insertions(+), 17 deletions(-)
create mode 100755 docs/_source/_plots/separation_of_scales.png
create mode 100644 test/test_data_handler/test_data_handler.py
diff --git a/docs/_source/_plots/separation_of_scales.png b/docs/_source/_plots/separation_of_scales.png
new file mode 100755
index 0000000000000000000000000000000000000000..d2bbc625a5d50051d8ec2babe976f88d7446e39e
GIT binary patch
literal 31085
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
literal 0
HcmV?d00001
diff --git a/mlair/data_handler/data_handler_kz_filter.py b/mlair/data_handler/data_handler_kz_filter.py
index de1cb071..6b960e79 100644
--- a/mlair/data_handler/data_handler_kz_filter.py
+++ b/mlair/data_handler/data_handler_kz_filter.py
@@ -25,11 +25,9 @@ class DataHandlerKzFilterSingleStation(DataHandlerSingleStation):
def __init__(self, *args, kz_filter_length, kz_filter_iter, **kwargs):
self._check_sampling(**kwargs)
- kz_filter_length = to_list(kz_filter_length)
- kz_filter_iter = to_list(kz_filter_iter)
# self.original_data = None # ToDo: implement here something to store unfiltered data
- self.kz_filter_length = kz_filter_length
- self.kz_filter_iter = kz_filter_iter
+ self.kz_filter_length = to_list(kz_filter_length)
+ self.kz_filter_iter = to_list(kz_filter_iter)
self.cutoff_period = None
self.cutoff_period_days = None
super().__init__(*args, **kwargs)
diff --git a/mlair/data_handler/data_handler_mixed_sampling.py b/mlair/data_handler/data_handler_mixed_sampling.py
index 0aae0ad6..1aec30b8 100644
--- a/mlair/data_handler/data_handler_mixed_sampling.py
+++ b/mlair/data_handler/data_handler_mixed_sampling.py
@@ -4,15 +4,13 @@ __date__ = '2020-11-05'
from mlair.data_handler.data_handler_single_station import DataHandlerSingleStation
from mlair.data_handler.data_handler_kz_filter import DataHandlerKzFilterSingleStation
from mlair.data_handler import DefaultDataHandler
-from mlair.configuration import path_config
from mlair import helpers
from mlair.helpers import remove_items
from mlair.configuration.defaults import DEFAULT_SAMPLING
-import logging
-import os
import inspect
from typing import Callable
+import datetime as dt
import numpy as np
import pandas as pd
@@ -39,7 +37,7 @@ class DataHandlerMixedSamplingSingleStation(DataHandlerSingleStation):
def load_and_interpolate(self, ind) -> [xr.DataArray, pd.DataFrame]:
data, self.meta = self.load_data(self.path[ind], self.station, self.statistics_per_var, self.sampling[ind],
- self.station_type, self.network, self.store_data_locally)
+ self.station_type, self.network, self.store_data_locally, start, end)
data = self.interpolate(data, dim=self.time_dim, method=self.interpolation_method,
limit=self.interpolation_limit)
return data
@@ -90,6 +88,33 @@ class DataHandlerMixedSamplingWithFilterSingleStation(DataHandlerMixedSamplingSi
self.call_transform()
self.make_samples()
+ def estimate_filter_width(self):
+ """
+ f = 0.5 / (len * sqrt(itr)) -> T = 1 / f
+ :return:
+ """
+ return int(self.kz_filter_length[0] * np.sqrt(self.kz_filter_iter[0]) * 2)
+
+ @staticmethod
+ def _add_time_delta(date, delta):
+ new_date = dt.datetime.strptime(date, "%Y-%m-%d") + dt.timedelta(hours=delta)
+ return new_date.strftime("%Y-%m-%d")
+
+ def load_and_interpolate(self, ind) -> [xr.DataArray, pd.DataFrame]:
+
+ if ind == 0: # for inputs
+ estimated_filter_width = self.estimate_filter_width()
+ start = self._add_time_delta(self.start, -estimated_filter_width)
+ end = self._add_time_delta(self.end, estimated_filter_width)
+ else: # target
+ start, end = self.start, self.end
+
+ data, self.meta = self.load_data(self.path[ind], self.station, self.statistics_per_var, self.sampling[ind],
+ self.station_type, self.network, self.store_data_locally, start, end)
+ data = self.interpolate(data, dim=self.time_dim, method=self.interpolation_method,
+ limit=self.interpolation_limit)
+ return data
+
class DataHandlerMixedSamplingWithFilter(DefaultDataHandler):
"""Data handler using mixed sampling for input and target. Inputs are temporal filtered."""
@@ -100,6 +125,15 @@ class DataHandlerMixedSamplingWithFilter(DefaultDataHandler):
class DataHandlerMixedSamplingSeparationOfScalesSingleStation(DataHandlerMixedSamplingWithFilterSingleStation):
+ """
+ Data handler using mixed sampling for input and target. Inputs are temporal filtered and depending on the
+ separation frequency of a filtered time series the time step delta for input data is adjusted (see image below).
+
+ ..image::../../../../../ _source / _plots / monthly_summary_box_plot.png
+ :width: 400
+
+ """
+
_requirements = DataHandlerMixedSamplingWithFilterSingleStation.requirements()
def __init__(self, *args, time_delta=np.sqrt, **kwargs):
@@ -147,11 +181,21 @@ class DataHandlerMixedSamplingSeparationOfScalesSingleStation(DataHandlerMixedSa
res = xr.concat(res, dim="filter").chunk()
return res
+ def estimate_filter_width(self):
+ """
+ Attention: this method returns the maximum value of
+ * either estimated filter width f = 0.5 / (len * sqrt(itr)) -> T = 1 / f or
+ * time delta method applied on the estimated filter width mupliplied by window_history_size
+ to provide a sufficiently wide filter width.
+ """
+ est = self.kz_filter_length[0] * np.sqrt(self.kz_filter_iter[0]) * 2
+ return int(max([self.time_delta(est) * self.window_history_size, est]))
+
class DataHandlerMixedSamplingSeparationOfScales(DefaultDataHandler):
"""Data handler using mixed sampling for input and target. Inputs are temporal filtered and different time step
sizes are applied in relation to frequencies."""
- data_handler = DataHandlerMixedSamplingWithFilterSingleStation
- data_handler_transformation = DataHandlerMixedSamplingWithFilterSingleStation
+ data_handler = DataHandlerMixedSamplingSeparationOfScalesSingleStation
+ data_handler_transformation = DataHandlerMixedSamplingSeparationOfScalesSingleStation
_requirements = data_handler.requirements()
diff --git a/mlair/data_handler/data_handler_single_station.py b/mlair/data_handler/data_handler_single_station.py
index cd922e75..4c274f91 100644
--- a/mlair/data_handler/data_handler_single_station.py
+++ b/mlair/data_handler/data_handler_single_station.py
@@ -142,7 +142,7 @@ class DataHandlerSingleStation(AbstractDataHandler):
Setup samples. This method prepares and creates samples X, and labels Y.
"""
data, self.meta = self.load_data(self.path, self.station, self.statistics_per_var, self.sampling,
- self.station_type, self.network, self.store_data_locally)
+ self.station_type, self.network, self.store_data_locally, self.start, self.end)
self._data = self.interpolate(data, dim=self.time_dim, method=self.interpolation_method,
limit=self.interpolation_limit)
self.set_inputs_and_targets()
@@ -163,7 +163,7 @@ class DataHandlerSingleStation(AbstractDataHandler):
self.remove_nan(self.time_dim)
def load_data(self, path, station, statistics_per_var, sampling, station_type=None, network=None,
- store_data_locally=False):
+ store_data_locally=False, start=None, end=None):
"""
Load data and meta data either from local disk (preferred) or download new data by using a custom download method.
@@ -199,7 +199,7 @@ class DataHandlerSingleStation(AbstractDataHandler):
store_data_locally=store_data_locally)
logging.debug("loading finished")
# create slices and check for negative concentration.
- data = self._slice_prep(data)
+ data = self._slice_prep(data, start=start, end=end)
data = self.check_for_negative_concentrations(data)
return data, meta
@@ -442,7 +442,7 @@ class DataHandlerSingleStation(AbstractDataHandler):
self.label = self.label.sel({dim: intersect})
self.observation = self.observation.sel({dim: intersect})
- def _slice_prep(self, data: xr.DataArray, coord: str = 'datetime') -> xr.DataArray:
+ def _slice_prep(self, data: xr.DataArray, start=None, end=None) -> xr.DataArray:
"""
Set start and end date for slicing and execute self._slice().
@@ -451,9 +451,9 @@ class DataHandlerSingleStation(AbstractDataHandler):
:return: sliced data
"""
- start = self.start if self.start is not None else data.coords[coord][0].values
- end = self.end if self.end is not None else data.coords[coord][-1].values
- return self._slice(data, start, end, coord)
+ start = start if start is not None else data.coords[self.time_dim][0].values
+ end = end if end is not None else data.coords[self.time_dim][-1].values
+ return self._slice(data, start, end, self.time_dim)
@staticmethod
def _slice(data: xr.DataArray, start: Union[date, str], end: Union[date, str], coord: str) -> xr.DataArray:
diff --git a/test/test_data_handler/test_data_handler.py b/test/test_data_handler/test_data_handler.py
new file mode 100644
index 00000000..418c7946
--- /dev/null
+++ b/test/test_data_handler/test_data_handler.py
@@ -0,0 +1,67 @@
+import pytest
+import inspect
+
+from mlair.data_handler.abstract_data_handler import AbstractDataHandler
+
+
+class TestDefaultDataHandler:
+
+ def test_required_attributes(self):
+ dh = AbstractDataHandler
+ assert hasattr(dh, "_requirements")
+ assert hasattr(dh, "__init__")
+ assert hasattr(dh, "build")
+ assert hasattr(dh, "requirements")
+ assert hasattr(dh, "own_args")
+ assert hasattr(dh, "transformation")
+ assert hasattr(dh, "get_X")
+ assert hasattr(dh, "get_Y")
+ assert hasattr(dh, "get_data")
+ assert hasattr(dh, "get_coordinates")
+
+ def test_init(self):
+ assert isinstance(AbstractDataHandler(), AbstractDataHandler)
+
+ def test_build(self):
+ assert isinstance(AbstractDataHandler.build(), AbstractDataHandler)
+
+ def test_requirements(self):
+ dh = AbstractDataHandler()
+ assert isinstance(dh._requirements, list)
+ assert len(dh._requirements) == 0
+ assert isinstance(dh.requirements(), list)
+ assert len(dh.requirements()) == 0
+
+ def test_own_args(self):
+ dh = AbstractDataHandler()
+ assert isinstance(dh.own_args(), list)
+ assert len(dh.own_args()) == 0
+ assert "self" not in dh.own_args()
+
+ def test_transformation(self):
+ assert AbstractDataHandler.transformation() is None
+
+ def test_get_X(self):
+ dh = AbstractDataHandler()
+ with pytest.raises(NotImplementedError):
+ dh.get_X()
+ assert sorted(["self", "upsampling", "as_numpy"]) == sorted(inspect.getfullargspec(dh.get_X).args)
+ assert (False, False) == inspect.getfullargspec(dh.get_X).defaults
+
+ def test_get_Y(self):
+ dh = AbstractDataHandler()
+ with pytest.raises(NotImplementedError):
+ dh.get_Y()
+ assert sorted(["self", "upsampling", "as_numpy"]) == sorted(inspect.getfullargspec(dh.get_Y).args)
+ assert (False, False) == inspect.getfullargspec(dh.get_Y).defaults
+
+ def test_get_data(self):
+ dh = AbstractDataHandler()
+ with pytest.raises(NotImplementedError):
+ dh.get_data()
+ assert sorted(["self", "upsampling", "as_numpy"]) == sorted(inspect.getfullargspec(dh.get_data).args)
+ assert (False, False) == inspect.getfullargspec(dh.get_data).defaults
+
+ def test_get_coordinates(self):
+ dh = AbstractDataHandler()
+ assert dh.get_coordinates() is None
--
GitLab