✨ add fill_value option to gap handlers (#218)

* ✨ add fill_value option to gap handlers

* 💨 update basic example

* 🖊️ review code

---------

Co-authored-by: Jeroen Van Der Donckt <[email protected]>

Author: jonasvdd

examples/README.md

@@ -22,7 +22,9 @@ Additionally, this notebook also shows some more advanced functionalities, such
 * How to add (shaded) confidence bounds to your time series
 * The flexibility of configuring different aggregation-algorithms and number of shown samples per trace
 * How plotly-resampler can be used for logarithmic x-axes and an implementation of a logarithmic aggregation algorithm, i.e., [LogLTTB](example_utils/loglttb.py)
+* Using different `fill_value` for gap handling of filled area plots.
 
+**Note**: the basic example notebook requires `plotly-resampler>=0.9.0rc3`.
 
 ### 1.2 Figurewidget example
 

examples/basic_example.ipynb

@@ -11,6 +11,19 @@
 
 
 class AbstractGapHandler(ABC):
+    def __init__(self, fill_value: Optional[float] = None):
+        """Constructor of AbstractGapHandler.
+
+        Parameters
+        ----------
+        fill_value: float, optional
+            The value to fill the gaps with, by default None.
+            Note that setting this value to 0 for filled area plots is particularly
+            useful.
+
+        """
+        self.fill_value = fill_value
+
     @abstractmethod
     def _get_gap_mask(self, x_agg: np.ndarray) -> Optional[np.ndarray]:
         """Get a boolean mask indicating the indices where there are gaps.
@@ -32,13 +45,13 @@ def _get_gap_mask(self, x_agg: np.ndarray) -> Optional[np.ndarray]:
         """
         pass
 
-    def insert_none_between_gaps(
+    def insert_fill_value_between_gaps(
         self,
         x_agg: np.ndarray,
         y_agg: np.ndarray,
         idxs: np.ndarray,
     ) -> Tuple[np.ndarray, np.ndarray]:
-        """Insert None values in the y_agg array when there are gaps.
+        """Insert the fill_value in the y_agg array where there are gaps.
 
         Gaps are determined by the x_agg array. The `_get_gap_mask` method is used to
         determine a boolean mask indicating the indices where there are gaps.
@@ -48,7 +61,7 @@ def insert_none_between_gaps(
         x_agg: np.ndarray
             The x array. This is used to determine the gaps.
         y_agg: np.ndarray
-            The y array. A copy of this array will be expanded with None values where
+            The y array. A copy of this array will be expanded with fill_values where
             there are gaps.
         idxs: np.ndarray
             The index array. This is relevant aggregators that perform data point
@@ -83,6 +96,8 @@ def insert_none_between_gaps(
         # Set the NaN values
         # We add the gap index offset (via the np.arange) to the indices to account for
         # the repeats (i.e., expanded y_agg array).
-        y_agg_exp_nan[np.where(gap_mask)[0] + np.arange(gap_mask.sum())] = None
+        y_agg_exp_nan[
+            np.where(gap_mask)[0] + np.arange(gap_mask.sum())
+        ] = self.fill_value
 
         return y_agg_exp_nan, idx_exp_nan

plotly_resampler/aggregation/gap_handler_interface.py

@@ -183,7 +183,7 @@ def aggregate(
         if np.issubdtype(xdt, np.timedelta64) or np.issubdtype(xdt, np.datetime64):
             agg_x_parsed = agg_x_parsed.view("int64")
 
-        agg_y, indices = gap_handler.insert_none_between_gaps(
+        agg_y, indices = gap_handler.insert_fill_value_between_gaps(
             agg_x_parsed, agg_y, indices
         )
         if isinstance(downsampler, DataPointSelector):

plotly_resampler/aggregation/plotly_aggregator_parser.py

@@ -174,6 +174,41 @@ def test_wrap_aggregate_x_gaps(downsampler, series):
     assert pd.Series(y_agg).isna().sum() == 3
 
 
+@pytest.mark.parametrize(
+    "downsampler",
+    [EveryNthPoint, LTTB, MinMaxAggregator, MinMaxLTTB, MinMaxOverlapAggregator],
+)
+@pytest.mark.parametrize("series", [lf("float_series")])
+def test_wrap_aggregate_x_gaps_float_fill_value(downsampler, series):
+    idx = np.arange(len(series))
+    idx[1000:] += 1000
+    idx[2000:] += 1500
+    idx[8000:] += 2500
+    series.index = idx
+    # 1. test with the default fill value (i.e., None)
+    x_agg, y_agg, indices = wrap_aggregate(
+        hf_x=series.index,
+        # add a constant to the series to ensure that the fill value is not used
+        hf_y=series.values + 1000,
+        downsampler=downsampler(),
+        gap_handler=MedDiffGapHandler(),
+        n_out=100,
+    )
+    assert len(x_agg) == len(y_agg) == len(indices)
+    assert pd.Series(y_agg).isnull().sum() == 3
+    # 2. test with a custom default fill value (i.e., 0)
+    x_agg, y_agg, indices = wrap_aggregate(
+        hf_x=series.index,
+        # add a constant to the series to ensure that the fill value is not used
+        hf_y=series.values + 1000,
+        downsampler=downsampler(),
+        gap_handler=MedDiffGapHandler(fill_value=0),
+        n_out=100,
+    )
+    assert len(x_agg) == len(y_agg) == len(indices)
+    assert pd.Series(y_agg == 0).sum() == 3
+
+
 @pytest.mark.parametrize(
     "downsampler", [EveryNthPoint, LTTB, MinMaxLTTB, MinMaxOverlapAggregator]
 )