ENH: Added max_gap keyword for series.interpolate

doc/source/user_guide/missing_data.rst

@@ -339,6 +339,10 @@ Interpolation
 
   The ``limit_area`` keyword argument was added.
 
+.. versionadded:: 1.0.0
+
+  The ``max_gap`` keyword argument was added.
+
 Both Series and DataFrame objects have :meth:`~DataFrame.interpolate`
 that, by default, performs linear interpolation at missing data points.
 
@@ -481,8 +485,9 @@ filled since the last valid observation:
 
 .. ipython:: python
 
-   ser = pd.Series([np.nan, np.nan, 5, np.nan, np.nan,
-                    np.nan, 13, np.nan, np.nan])
+   ser = pd.Series([np.nan, np.nan, 2, np.nan, np.nan,
+                    3, np.nan, np.nan, np.nan,
+                    13, np.nan, np.nan])
    ser
 
    # fill all consecutive values in a forward direction
@@ -491,8 +496,24 @@ filled since the last valid observation:
    # fill one consecutive value in a forward direction
    ser.interpolate(limit=1)
 
+If an interpolation should only be carried out for consecutive ``NaN`` values
+of a certain maximum length, the ``max_gap`` keyword, introduced in v1.0.0,
+can be used. Any ``NaN`` gap longer than ``max_gap`` will not be modified.
+This can be useful, e.g. if an interpolation using the ``scipy`` methods
+should be restricted to short NaN-gaps because the expected variation over
+longer NaN-gaps forbids using interpolated values.
+
+.. ipython:: python
+
+   ser
+   # interpolate in forward direction but only NaN-gaps with a maximum 2 consecutive NaN values
+   ser.interpolate(max_gap=2)
+
 By default, ``NaN`` values are filled in a ``forward`` direction. Use
 ``limit_direction`` parameter to fill ``backward`` or from ``both`` directions.
+Note that for methods `pad`, `ffill`, `backfill` and `bfill` ``limit_direction``
+must not be set as these fill methods implicitly are meant to work only in one
+direction.
 
 .. ipython:: python
 

doc/source/whatsnew/v1.0.0.rst

@@ -125,6 +125,7 @@ Other enhancements
 - Roundtripping DataFrames with nullable integer or string data types to parquet
   (:meth:`~DataFrame.to_parquet` / :func:`read_parquet`) using the `'pyarrow'` engine
   now preserve those data types with pyarrow >= 1.0.0 (:issue:`20612`).
+- :meth:`Series.interpolate` added the ``max_gap`` keyword to limit interpolation to NaN-gaps of a certain length (:issue:`25141`)
 
 Build Changes
 ^^^^^^^^^^^^^
@@ -300,6 +301,7 @@ Performance improvements
 Bug fixes
 ~~~~~~~~~
 
+- ``limit_area`` and ``limit_direction`` now work in :meth:`Series.interpolate` if ``method`` is ``pad`` (:issue:`25141`)
 
 Categorical
 ^^^^^^^^^^^

pandas/core/generic.py

@@ -6894,7 +6894,9 @@ def replace(
             Update the data in place if possible.
         limit_direction : {'forward', 'backward', 'both'}, default 'forward'
             If limit is specified, consecutive NaNs will be filled in this
-            direction.
+            direction. If the methods 'pad' or 'ffill' are used it must be
+            None or 'forward'. If 'backfill' or 'bfill' are use it must be
+            None or 'backwards'.
         limit_area : {`None`, 'inside', 'outside'}, default None
             If limit is specified, consecutive NaNs will be filled with this
             restriction.
@@ -6906,6 +6908,13 @@ def replace(
 
             .. versionadded:: 0.23.0
 
+        max_gap : int, optional
+            Maximum number of consecutive NaN values up to which a NaN-gap
+            will be interpolated. All longer NaN-gaps will be left unchanged.
+            Must be greater than 0.
+
+            .. versionadded:: 1.0.0
+
         downcast : optional, 'infer' or None, defaults to None
             Downcast dtypes if possible.
         **kwargs
@@ -6990,6 +6999,36 @@ def replace(
         8             4.71
         dtype: object
 
+        Similar to the examples above. Filling in ``NaN`` in a Series
+        by padding, but here filling only NaN-gaps smaller than a specific
+        gap width using the kwarg `max_gap`.
+
+        >>> s = pd.Series([np.nan, "single_one", np.nan,
+        ...                "fill_two_more", np.nan, np.nan, np.nan,
+        ...                4.71, np.nan])
+        >>> s
+        0              NaN
+        1       single_one
+        2              NaN
+        3    fill_two_more
+        4              NaN
+        5              NaN
+        6              NaN
+        7             4.71
+        8              NaN
+        dtype: object
+        >>> s.interpolate(method='pad', max_gap=2)
+        0              NaN
+        1       single_one
+        2       single_one
+        3    fill_two_more
+        4              NaN
+        5              NaN
+        6              NaN
+        7             4.71
+        8             4.71
+        dtype: object
+
         Filling in ``NaN`` in a Series via polynomial interpolation or splines:
         Both 'polynomial' and 'spline' methods require that you also specify
         an ``order`` (int).
@@ -7045,8 +7084,9 @@ def interpolate(
         axis=0,
         limit=None,
         inplace=False,
-        limit_direction="forward",
+        limit_direction=None,
         limit_area=None,
+        max_gap=None,
         downcast=None,
         **kwargs,
     ):
@@ -7085,6 +7125,28 @@ def interpolate(
                 "column to a numeric dtype."
             )
 
+        # Set `limit_direction` depending on `method`
+        if (method == "pad") or (method == "ffill"):
+            if (limit_direction == "backward") or (limit_direction == "both"):
+                raise ValueError(
+                    "`limit_direction` must not be `%s` for method `%s`"
+                    % (limit_direction, method)
+                )
+            else:
+                limit_direction = "forward"
+        elif (method == "backfill") or (method == "bfill"):
+            if (limit_direction == "forward") or (limit_direction == "both"):
+                raise ValueError(
+                    "`limit_direction` must not be `%s` for method `%s`"
+                    % (limit_direction, method)
+                )
+            else:
+                limit_direction = "backward"
+        else:
+            # Set default
+            if limit_direction is None:
+                limit_direction = "forward"
+
         # create/use the index
         if method == "linear":
             # prior default
@@ -7120,6 +7182,7 @@ def interpolate(
             limit=limit,
             limit_direction=limit_direction,
             limit_area=limit_area,
+            max_gap=max_gap,
             inplace=inplace,
             downcast=downcast,
             **kwargs,

pandas/core/internals/blocks.py

@@ -1083,6 +1083,7 @@ def interpolate(
         values=None,
         inplace=False,
         limit=None,
+        max_gap=None,
         limit_direction="forward",
         limit_area=None,
         fill_value=None,
@@ -1117,6 +1118,8 @@ def check_int_bool(self, inplace):
                 axis=axis,
                 inplace=inplace,
                 limit=limit,
+                max_gap=max_gap,
+                limit_area=limit_area,
                 fill_value=fill_value,
                 coerce=coerce,
                 downcast=downcast,
@@ -1133,6 +1136,7 @@ def check_int_bool(self, inplace):
             values=values,
             axis=axis,
             limit=limit,
+            max_gap=max_gap,
             limit_direction=limit_direction,
             limit_area=limit_area,
             fill_value=fill_value,
@@ -1147,6 +1151,8 @@ def _interpolate_with_fill(
         axis=0,
         inplace=False,
         limit=None,
+        max_gap=None,
+        limit_area=None,
         fill_value=None,
         coerce=False,
         downcast=None,
@@ -1169,16 +1175,38 @@ def _interpolate_with_fill(
         # We only get here for non-ExtensionBlock
         fill_value = convert_scalar(self.values, fill_value)
 
-        values = missing.interpolate_2d(
-            values,
-            method=method,
-            axis=axis,
-            limit=limit,
-            fill_value=fill_value,
-            dtype=self.dtype,
-        )
+        # We have to distinguish two cases:
+        # 1. When kwargs `max_gap` or `limit_area` are used: They are not
+        #    supported by `missing.interpolate_2d()`. Using these kwargs only
+        #    works by applying the fill along a certain axis.
+        # 2. All other cases: Then, `missing.interpolate_2d()` can be used.
+        if (max_gap is not None) or (limit_area is not None):
+
+            def func(x):
+                return missing.interpolate_1d_fill(
+                    x,
+                    method=method,
+                    axis=axis,
+                    limit=limit,
+                    max_gap=max_gap,
+                    limit_area=limit_area,
+                    fill_value=fill_value,
+                    dtype=self.dtype,
+                )
+
+            interp_values = np.apply_along_axis(func, axis, values)
+
+        else:
+            interp_values = missing.interpolate_2d(
+                values,
+                method=method,
+                axis=axis,
+                limit=limit,
+                fill_value=fill_value,
+                dtype=self.dtype,
+            )
 
-        blocks = [self.make_block_same_class(values, ndim=self.ndim)]
+        blocks = [self.make_block_same_class(interp_values, ndim=self.ndim)]
         return self._maybe_downcast(blocks, downcast)
 
     def _interpolate(
@@ -1189,6 +1217,7 @@ def _interpolate(
         fill_value=None,
         axis=0,
         limit=None,
+        max_gap=None,
         limit_direction="forward",
         limit_area=None,
         inplace=False,
@@ -1227,6 +1256,7 @@ def func(x):
                 x,
                 method=method,
                 limit=limit,
+                max_gap=max_gap,
                 limit_direction=limit_direction,
                 limit_area=limit_area,
                 fill_value=fill_value,