pad

UnitsAwareDataArray.pad(pad_width: Mapping[Any, int | tuple[int, int]] | None = None, mode: PadModeOptions = 'constant', stat_length: int | tuple[int, int] | Mapping[Any, tuple[int, int]] | None = None, constant_values: float | tuple[float, float] | Mapping[Any, tuple[float, float]] | None = None, end_values: int | tuple[int, int] | Mapping[Any, tuple[int, int]] | None = None, reflect_type: PadReflectOptions = None, keep_attrs: bool | None = None, **pad_width_kwargs: Any) Self

Pad this array along one or more dimensions.

Warning

This function is experimental and its behaviour is likely to change especially regarding padding of dimension coordinates (or IndexVariables).

When using one of the modes (“edge”, “reflect”, “symmetric”, “wrap”), coordinates will be padded with the same mode, otherwise coordinates are padded using the “constant” mode with fill_value dtypes.NA.

Parameters:
  • pad_width (mapping of Hashable to tuple of int) – Mapping with the form of {dim: (pad_before, pad_after)} describing the number of values padded along each dimension. {dim: pad} is a shortcut for pad_before = pad_after = pad

  • mode ({"constant", "edge", "linear_ramp", "maximum", "mean", "median", "minimum", "reflect", "symmetric", "wrap"}, default: "constant") –

    How to pad the DataArray (taken from numpy docs):

    • ”constant”: Pads with a constant value.

    • ”edge”: Pads with the edge values of array.

    • ”linear_ramp”: Pads with the linear ramp between end_value and the array edge value.

    • ”maximum”: Pads with the maximum value of all or part of the vector along each axis.

    • ”mean”: Pads with the mean value of all or part of the vector along each axis.

    • ”median”: Pads with the median value of all or part of the vector along each axis.

    • ”minimum”: Pads with the minimum value of all or part of the vector along each axis.

    • ”reflect”: Pads with the reflection of the vector mirrored on the first and last values of the vector along each axis.

    • ”symmetric”: Pads with the reflection of the vector mirrored along the edge of the array.

    • ”wrap”: Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning.

  • stat_length (int, tuple or mapping of Hashable to tuple, default: None) – Used in ‘maximum’, ‘mean’, ‘median’, and ‘minimum’. Number of values at edge of each axis used to calculate the statistic value. {dim_1: (before_1, after_1), … dim_N: (before_N, after_N)} unique statistic lengths along each dimension. ((before, after),) yields same before and after statistic lengths for each dimension. (stat_length,) or int is a shortcut for before = after = statistic length for all axes. Default is None, to use the entire axis.

  • constant_values (scalar, tuple or mapping of Hashable to tuple, default: 0) – Used in ‘constant’. The values to set the padded values for each axis. {dim_1: (before_1, after_1), ... dim_N: (before_N, after_N)} unique pad constants along each dimension. ((before, after),) yields same before and after constants for each dimension. (constant,) or constant is a shortcut for before = after = constant for all dimensions. Default is 0.

  • end_values (scalar, tuple or mapping of Hashable to tuple, default: 0) – Used in ‘linear_ramp’. The values used for the ending value of the linear_ramp and that will form the edge of the padded array. {dim_1: (before_1, after_1), ... dim_N: (before_N, after_N)} unique end values along each dimension. ((before, after),) yields same before and after end values for each axis. (constant,) or constant is a shortcut for before = after = constant for all axes. Default is 0.

  • reflect_type ({"even", "odd", None}, optional) – Used in “reflect”, and “symmetric”. The “even” style is the default with an unaltered reflection around the edge value. For the “odd” style, the extended part of the array is created by subtracting the reflected values from two times the edge value.

  • keep_attrs (bool or None, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False, the new object will be returned without attributes.

  • **pad_width_kwargs – The keyword arguments form of pad_width. One of pad_width or pad_width_kwargs must be provided.

Returns:

padded – DataArray with the padded coordinates and data.

Return type:

DataArray

See also

DataArray.shift, DataArray.roll, DataArray.bfill, DataArray.ffill, numpy.pad, dask.array.pad

Notes

For mode="constant" and constant_values=None, integer types will be promoted to float and padded with np.nan.

Padding coordinates will drop their corresponding index (if any) and will reset default indexes for dimension coordinates.

Examples

>>> arr = xr.DataArray([5, 6, 7], coords=[("x", [0, 1, 2])])
>>> arr.pad(x=(1, 2), constant_values=0)
<xarray.DataArray (x: 6)> Size: 48B
array([0, 5, 6, 7, 0, 0])
Coordinates:
  * x        (x) float64 48B nan 0.0 1.0 2.0 nan nan
>>> da = xr.DataArray(
...     [[0, 1, 2, 3], [10, 11, 12, 13]],
...     dims=["x", "y"],
...     coords={"x": [0, 1], "y": [10, 20, 30, 40], "z": ("x", [100, 200])},
... )
>>> da.pad(x=1)
<xarray.DataArray (x: 4, y: 4)> Size: 128B
array([[nan, nan, nan, nan],
       [ 0.,  1.,  2.,  3.],
       [10., 11., 12., 13.],
       [nan, nan, nan, nan]])
Coordinates:
  * x        (x) float64 32B nan 0.0 1.0 nan
  * y        (y) int64 32B 10 20 30 40
    z        (x) float64 32B nan 100.0 200.0 nan

Careful, constant_values are coerced to the data type of the array which may lead to a loss of precision:

>>> da.pad(x=1, constant_values=1.23456789)
<xarray.DataArray (x: 4, y: 4)> Size: 128B
array([[ 1,  1,  1,  1],
       [ 0,  1,  2,  3],
       [10, 11, 12, 13],
       [ 1,  1,  1,  1]])
Coordinates:
  * x        (x) float64 32B nan 0.0 1.0 nan
  * y        (y) int64 32B 10 20 30 40
    z        (x) float64 32B nan 100.0 200.0 nan