Fill gaps limited 7665

doc/api.rst

@@ -167,6 +167,7 @@ Missing value handling
  Dataset.fillna
  Dataset.ffill
  Dataset.bfill
+ Dataset.fill_gaps
  Dataset.interpolate_na
  Dataset.where
  Dataset.isin
@@ -357,6 +358,7 @@ Missing value handling
  DataArray.fillna
  DataArray.ffill
  DataArray.bfill
+ DataArray.fill_gaps
  DataArray.interpolate_na
  DataArray.where
  DataArray.isin

xarray/core/dataarray.py

@@ -93,6 +93,7 @@
  from xarray.backends import ZarrStore
  from xarray.backends.api import T_NetcdfEngine, T_NetcdfTypes
  from xarray.core.groupby import DataArrayGroupBy
+ from xarray.core.missing import GapMask
  from xarray.core.resample import DataArrayResample
  from xarray.core.rolling import DataArrayCoarsen, DataArrayRolling
  from xarray.core.types import (
@@ -103,6 +104,8 @@
  ErrorOptions,
  ErrorOptionsWithWarn,
  InterpOptions,
+ LimitAreaOptions,
+ LimitDirectionOptions,
  PadModeOptions,
  PadReflectOptions,
  QuantileMethods,
@@ -113,6 +116,7 @@
  SideOptions,
  T_ChunkDimFreq,
  T_ChunksFreq,
+ T_GapLength,
  T_Xarray,
  )
  from xarray.core.weighted import DataArrayWeighted
@@ -3476,27 +3480,19 @@ def fillna(self, value: Any) -> Self:
 
  def interpolate_na(
  self,
- dim: Hashable | None = None,
+ dim: Hashable,
  method: InterpOptions = "linear",
  limit: int | None = None,
- use_coordinate: bool | str = True,
- max_gap: (
- None
- | int
- | float
- | str
- | pd.Timedelta
- | np.timedelta64
- | datetime.timedelta
- ) = None,
+ use_coordinate: bool | Hashable = True,
+ max_gap: T_GapLength | None = None,
  keep_attrs: bool | None = None,
  **kwargs: Any,
  ) -> Self:
  """Fill in NaNs by interpolating according to different methods.
 
  Parameters
  ----------
- dim : Hashable or None, optional
+ dim : Hashable
  Specifies the dimension along which to interpolate.
  method : {"linear", "nearest", "zero", "slinear", "quadratic", "cubic", "polynomial", \
  "barycentric", "krogh", "pchip", "spline", "akima"}, default: "linear"
@@ -3511,17 +3507,17 @@ def interpolate_na(
  - 'barycentric', 'krogh', 'pchip', 'spline', 'akima': use their
  respective :py:class:`scipy.interpolate` classes.
 
+ limit : int or None, default: None
+ Maximum number of consecutive NaNs to fill. Must be greater than 0
+ or None for no limit. This filling is done regardless of the size of
+ the gap in the data. To only interpolate over gaps less than a given length,
+ see ``max_gap``.
  use_coordinate : bool or str, default: True
  Specifies which index to use as the x values in the interpolation
  formulated as `y = f(x)`. If False, values are treated as if
  equally-spaced along ``dim``. If True, the IndexVariable `dim` is
  used. If ``use_coordinate`` is a string, it specifies the name of a
  coordinate variable to use as the index.
- limit : int or None, default: None
- Maximum number of consecutive NaNs to fill. Must be greater than 0
- or None for no limit. This filling is done regardless of the size of
- the gap in the data. To only interpolate over gaps less than a given length,
- see ``max_gap``.
  max_gap : int, float, str, pandas.Timedelta, numpy.timedelta64, datetime.timedelta, default: None
  Maximum size of gap, a continuous sequence of NaNs, that will be filled.
  Use None for no limit. When interpolating along a datetime64 dimension
@@ -3567,6 +3563,7 @@ def interpolate_na(
  >>> da = xr.DataArray(
  ... [np.nan, 2, 3, np.nan, 0], dims="x", coords={"x": [0, 1, 2, 3, 4]}
  ... )
+
  >>> da
  <xarray.DataArray (x: 5)> Size: 40B
  array([nan, 2., 3., nan, 0.])
@@ -3601,7 +3598,7 @@ def interpolate_na(
  def ffill(self, dim: Hashable, limit: int | None = None) -> Self:
  """Fill NaN values by propagating values forward
 
- *Requires bottleneck.*
+ *Requires numbagg or bottleneck.*
 
  Parameters
  ----------
@@ -3685,7 +3682,7 @@ def ffill(self, dim: Hashable, limit: int | None = None) -> Self:
  def bfill(self, dim: Hashable, limit: int | None = None) -> Self:
  """Fill NaN values by propagating values backward
 
- *Requires bottleneck.*
+ *Requires numbagg or bottleneck.*
 
  Parameters
  ----------
@@ -3766,6 +3763,151 @@ def bfill(self, dim: Hashable, limit: int | None = None) -> Self:
 
  return bfill(self, dim, limit=limit)
 
+ def fill_gaps(
+ self,
+ dim: Hashable,
+ *,
+ use_coordinate: bool | Hashable = True,
+ limit: T_GapLength | None = None,
+ limit_direction: LimitDirectionOptions = "both",
+ limit_area: LimitAreaOptions | None = None,
+ max_gap: T_GapLength | None = None,
+ ) -> GapMask[DataArray]:
+ """Fill in gaps (consecutive missing values) in the data using one of several filling methods.
+ Allows for fine control on how far to extend the valid data into the gaps and the maximum size of the gaps to fill.
+
+ *Requires numbagg or bottleneck.*
+
+ Parameters
+ ----------
+ dim : Hashable
+ Specifies the dimension along which to calculate gap sizes.
+ use_coordinate : bool or Hashable, default: True
+ Specifies which index to use when calculating gap sizes.
+
+ - False: a consecutive integer index is created along ``dim`` (0, 1, 2, ...).
+ - True: the IndexVariable `dim` is used.
+ - String: specifies the name of a coordinate variable to use as the index.
+
+ limit : int, float, str, pandas.Timedelta, numpy.timedelta64, datetime.timedelta, default: None
+ Maximum number or distance of consecutive NaNs to fill.
+ Use None for no limit. When interpolating along a datetime64 dimension
+ and ``use_coordinate=True``, ``limit`` can be one of the following:
+
+ - a string that is valid input for pandas.to_timedelta
+ - a :py:class:`numpy.timedelta64` object
+ - a :py:class:`pandas.Timedelta` object
+ - a :py:class:`datetime.timedelta` object
+
+ Otherwise, ``limit`` must be an int or a float.
+ If ``use_coordinates=True``, for ``limit_direction=forward`` distance is defined
+ as the difference between the coordinate at a NaN value and the coordinate of the next valid value
+ to the left (right for ``limit_direction=backward``).
+ For example, consider::
+
+ <xarray.DataArray (x: 9)>
+ array([nan, nan, nan, 1., nan, nan, 4., nan, nan])
+ Coordinates:
+ * x (x) int64 0 1 2 3 4 5 6 7 8
+
+ For ``limit_direction=forward``, distances are ``[nan, nan, nan, 0, 1, 2, 0, 1, 2]``.
+ To only fill gaps less than a given length,
+ see ``max_gap``.
+ limit_direction: {"forward", "backward", "both"}, default: "forward"
+ Consecutive NaNs will be filled in this direction.
+ limit_area: {"inside", "outside"} or None: default: None
+ Consecutive NaNs will be filled with this restriction.
+
+ - None: No fill restriction.
+ - "inside": Only fill NaNs surrounded by valid values
+ - "outside": Only fill NaNs outside valid values (extrapolate).
+ max_gap : int, float, str, pandas.Timedelta, numpy.timedelta64, datetime.timedelta, default: None
+ Maximum size of gap, a continuous sequence of NaNs, that will be filled.
+ Use None for no limit. When calculated along a datetime64 dimension
+ and ``use_coordinate=True``, ``max_gap`` can be one of the following:
+
+ - a string that is valid input for pandas.to_timedelta
+ - a :py:class:`numpy.timedelta64` object
+ - a :py:class:`pandas.Timedelta` object
+ - a :py:class:`datetime.timedelta` object
+
+ Otherwise, ``max_gap`` must be an int or a float. If ``use_coordinate=False``, a linear integer
+ index is created. Gap length is defined as the difference
+ between coordinate values at the first data point after a gap and the last valid value
+ before a gap. For gaps at the beginning (end), gap length is defined as the difference
+ between coordinate values at the first (last) valid data point and the first (last) NaN.
+ For example, consider::
+
+ <xarray.DataArray (x: 9)>
+ array([nan, nan, nan, 1., nan, nan, 4., nan, nan])
+ Coordinates:
+ * x (x) int64 0 1 2 3 4 5 6 7 8
+
+ The gap lengths are 3-0 = 3; 6-3 = 3; and 8-6 = 2 respectively
+
+ Returns
+ -------
+ Gap Mask: GapMask
+ An object where all remaining gaps are masked. Unmasked values can be filled by calling any of the provided methods.
+
+ See Also
+ --------
+ DataArray.fillna
+ DataArray.ffill
+ DataArray.bfill
+ DataArray.interpolate_na
+ pandas.DataFrame.interpolate
+
+ Notes
+ -----
+ ``Limit`` and ``max_gap`` have different effects on gaps: If ``limit`` is set, *some* values in a gap will be filled (up to the given distance from the boundaries). ``max_gap`` will prevent *any* filling for gaps larger than the given distance.
+
+ Examples
+ --------
+ >>> da = xr.DataArray(
+ ... [np.nan, 2, np.nan, np.nan, 5, np.nan, 0],
+ ... dims="x",
+ ... coords={"x": [0, 1, 2, 3, 4, 5, 6]},
+ ... )
+
+ >>> da
+ <xarray.DataArray (x: 7)> Size: 56B
+ array([nan, 2., nan, nan, 5., nan, 0.])
+ Coordinates:
+ * x (x) int64 56B 0 1 2 3 4 5 6
+
+ >>> da.fill_gaps(dim="x", limit=1, limit_direction="forward").interpolate_na(
+ ... dim="x"
+ ... )
+ <xarray.DataArray (x: 7)> Size: 56B
+ array([nan, 2. , 3. , nan, 5. , 2.5, 0. ])
+ Coordinates:
+ * x (x) int64 56B 0 1 2 3 4 5 6
+
+ >>> da.fill_gaps(dim="x", max_gap=2, limit_direction="forward").ffill(dim="x")
+ <xarray.DataArray (x: 7)> Size: 56B
+ array([nan, 2., nan, nan, 5., 5., 0.])
+ Coordinates:
+ * x (x) int64 56B 0 1 2 3 4 5 6
+
+ >>> da.fill_gaps(dim="x", limit_area="inside").fillna(9)
+ <xarray.DataArray (x: 7)> Size: 56B
+ array([nan, 2., 9., 9., 5., 9., 0.])
+ Coordinates:
+ * x (x) int64 56B 0 1 2 3 4 5 6
+ """
+ from xarray.core.missing import mask_gaps
+
+ return mask_gaps(
+ self,
+ dim,
+ use_coordinate=use_coordinate,
+ limit=limit,
+ limit_direction=limit_direction,
+ limit_area=limit_area,
+ max_gap=max_gap,
+ )
+
  def combine_first(self, other: Self) -> Self:
  """Combine two DataArray objects, with union of coordinates.