expose coordinate padding options in .pad

[ircwaves]

Digging through the backlog with @jsignell, it seems the coord padding with NaN issue comes up every now and again. I've done enough windowed signal processing to know that changing this method's behavior will probably break things for someone, SO this change doesn't break the default type-promotion-and-fill-NaNs behavior. So, I thought I'd put up this PR that extends the change that @TomNicholas suggested as a first draft of what that might look like.

Notes

1. This keeps the behavior of using the non-coord parameter (end_values, constant_values, etc) values for the coord padding parameters in the case where it is inferred from the data padding mode parameter.
2. surfaces coord_ prefixed versions of the data padding parameters.

Example runs:

No args da.pad(x=(5,3)):

---------------- initial array ---------------
<xarray.DataArray (x: 3)> Size: 24B
array([0.5, 1.5, 2.5])
Coordinates:
  * x        (x) int64 24B -1 1 3
---------------- call pad ---------------
<xarray.DataArray (x: 11)> Size: 88B
array([nan, nan, nan, nan, nan, 0.5, 1.5, 2.5, nan, nan, nan])
Coordinates:
  * x        (x) float64 88B nan nan nan nan nan -1.0 1.0 3.0 nan nan nan

Or  use the new args for linear ramped coordinates (da.pad(x=(5, 3), constant_values=-1, coord_end_values=(-11,9), coord_mode="linear_ramp")):

---------------- initial array ---------------
<xarray.DataArray (x: 3)> Size: 24B
array([0.5, 1.5, 2.5])
Coordinates:
  * x        (x) int64 24B -1 1 3
---------------- call pad w/ linear_ramp on coodrs---------------
<xarray.DataArray (x: 11)> Size: 88B
array([-1. , -1. , -1. , -1. , -1. ,  0.5,  1.5,  2.5, -1. , -1. , -1. ])
Coordinates:
  * x        (x) int64 88B -11 -9 -7 -5 -3 -1 1 3 5 7 9

• Closes What should pad do about IndexVariables? #3868 Expose coord_mode in .pad() #6425
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

[ircwaves]

@jsignell -- I addressed your comments, and updated the docs.

[jsignell]

This looks like a straight improvement to me and it preserves backwards compatibility. But I don't have enough experience with this piece of the codebase to review. Maybe @dcherian or @benbovy?

[headtr1ck]

I didn't follow all the discussion before, but alternatively we could also allow a Mapping from variable/coordinate names to the pad options.
So you would specify the padding for coordinates in the same way as for a dataset.

This would even allow different pad modes for different coordinates etc.
Only downside I see is that for a DataArray with lots of coordinates you need to specify each coordinate in this mapping (but with inline stuff even that's easy in python).

[ircwaves]

@headtr1ck writes:

... we could also allow a Mapping from variable/coordinate names to the pad options. So you would specify the padding for coordinates in the same way as for a dataset.

Given that, other than mode and coord_pad_mode, all of the padding parameter do accept Mappings -- is your suggestion that mode and coord_pad_mode also accept Mappings? That might even get rid of coord_pad_mode, as it could be treated as just another variable.

With respect to the coordinate padding options, those only got made a separate set of parameters to handle the implicit functionality which selects a coord_pad_mode based on the mode variable, when coord_pad_mode is not provided.

This would even allow different pad modes for different coordinates etc. Only downside I see is that for a DataArray with lots of coordinates you need to specify each coordinate in this mapping (but with inline stuff even that's easy in python).

It feels like we could extend mode in a backwards compatible way by accepting:

    mode: PadModeOptions | Mapping[str, PadModeOptions] | None = None

I suppose the other bit this brings up is not having separate coord_ variables exposed, and just sourcing them from the Mappings, if they're provided. And if they're not provided, then revert to the current implicit behavior. I'll have to think on this a bit more. The implicit pad-mode selection might get ugly, but this might be doable.