Discussion about renaming interpolate() to regrid() in the upcoming 0.5 release

[sandorkertesz]

The upcoming release (0.5.0) will introduce some significant changes:

• adds access to MIR
• adds interpolation backends (the default being "mir")

Part of the changes is that the main method interpolate() will be deprecated and replaced by the new method regrid(). See the planned release notes (not yet finalised) at: https://earthkit-regrid.readthedocs.io/en/develop/release_notes/version_0.5_updates.html

The main goal of this discussion to figure out if this renaming is acceptable or would confuse users.

[sandorkertesz]

Some of the reasons for using regrid():

• the package name is earthkit-regrid so using regrid() seems to be a more logical choice

• the method does interpolation, cropping etc. so interpolate() may be too restrictive

• the default return type changed when the input is an array. The reason behind this is as follows:

  • interpolate() always returns a single object, e.g. an array for an arrray input.

   data = np.random.rand(5248)
   interpolated_data = interpolate(data, in_grid={"grid": "O32"}, out_grid={"grid": [5, 5]})

  • however, when using MIR the out_grid can be altered/adjusted by MIR . So it was decided that a tuple of (array, altered_out_grid) should be returned by default when the input is an array. It seemed easier to introduce this fundamental change with a new method instead of altering the behaviour of interpolate().

  data = np.random.rand(5248)
  interpolated_data, res_grid = regrid(
      data,
      in_grid={"grid": "O32"},
      out_grid={"grid": [5, 5]},
  )

  • please note that the return type in regrid() can be controlled by the output kwarg (see: https://earthkit-regrid.readthedocs.io/en/develop/guide/mir/regrid.html#mir-regrid)
  • please also note that output is only used when the input data is an array. For other data types (e.g. fieldlist) always the same type of data is returned as the input. The reason for this is that the (potentially) altered out_grid is already encoded into the returned data so the user does not need it. While for the array input/output the out_grid is needed to correctly interpret the returned array.