[Doc]: Consider updating the listed APIs for horizontal regridding

[tomvothecoder]

Describe your documentation update

After revisiting the horizontal regridding APIs we have listed in the API Reference page, I think listing all of these options can be confusing for the user.

1. Python classes
   • https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.regrid2.Regrid2Regridder.html
   • https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.xesmf.XESMFRegridder.html
2. General accessor method
   • https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal.html
3. Individual accessor method by tool
   • https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal_xesmf.html
   • https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal_regrid2.html

All of these methods achieve the same functions, but go about it in a slightly different way.
This is the callstack with xesmf: horizontal(...tool="xesmf") -> horizonal_xesmf() -> XESMFRegridder().

Solution

I propose we just keep "2. General accessor method" listed in our documentation. I foresee most people using that API since it is the most straightforward to use and most flexible (you can specify tool="regrid2" or tool="xesmf").

[tomvothecoder]

Any thoughts @xCDAT/core-developers?

[pochedls]

I haven't investigated this enough to weigh in on what is right, but I do find the regridder documentation a little confusing (as mentioned here). It seems like 2 has the correct documentation.

One note regarding these references:

Find options at xcdat.regridder.xesmf.XESMFRegridder()

I think this is probably the best way to note/refer to options specific to xESMF / regrid2, but if there was a way of putting it within the documentation here that could be helpful.

[jasonb5]

Describe your documentation update

After revisiting the horizontal regridding APIs we have listed in the API Reference page, I think listing all of these options can be confusing for the user.

1. Python classes
   
   * https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.regrid2.Regrid2Regridder.html
   * https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.xesmf.XESMFRegridder.html

These are purely there for documentation, that's the only way to make a link to reference the individual regridder options.

2. General accessor method
   
   * https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal.html

3. Individual accessor method by tool
   
   * https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal_xesmf.html
   * https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal_regrid2.html

All of these methods achieve the same functions, but go about it in a slightly different way. This is the callstack with xesmf: horizontal(...tool="xesmf") -> horizonal_xesmf() -> XESMFRegridder().

Solution

I propose we just keep "2. General accessor method" listed in our documentation. I foresee most people using that API since it is the most straightforward to use and most flexible (you can specify tool="regrid2" or tool="xesmf").

I'd be fine removing horizontal_xesmf and horizontal_regrid2, they really only save a single argument.

---

I haven't investigated this enough to weigh in on what is right, but I do find the regridder documentation a little confusing (as mentioned here). It seems like 2 has the correct documentation.

One note regarding these references:

Find options at xcdat.regridder.xesmf.XESMFRegridder()

I think this is probably the best way to note/refer to options specific to xESMF / regrid2, but if there was a way of putting it within the documentation here that could be helpful.

There's not really a good way to place the documentation here. I could try some regex magic and combine the regrid2 and xesmf docstring into a single one but it brings up another issue. If we ever add more regridders, we could end up with one very large docstring.

I'll also make another pass on the documentation with the insight from this issue.

[tomvothecoder]

These are purely there for documentation, that's the only way to make a link to reference the individual regridder options.

You're right, I forgot you need to list the accessor class to list its methods and attributes.

I'd be fine removing horizontal_xesmf and horizontal_regrid2, they really only save a single argument.

Yeah, I noticed people mostly using horizontal() in their code/notebooks. Those underlying APIs include xesmf or regrid2 in the name of the method, which almost as many characters tool='xesmf'.

[jasonb5]

After some more thought we could solve the documentation issue by getting rid of horizontal() and vertical() and just have regrid2(), xesmf(), and xgcm(). We could group them together under horizontal and vertical in the documentation since users will probably learn about them there.

[jasonb5]

After the last meeting, the plan is to deprecate the current regridding accessor functions and remove them in a few release cycles.

• horizontal()
• vertical()

The horizontal_xesmf() and horizontal_regrid2() will remain and vertical_xgcm() will be added. Retaining the horizontal and vertical prefix will allow the possibility for a regridder to implement both vertical and horizontal.

The documentation will be moved to these methods so there will no longer be a link from the accessor methods to class __init__ methods e.g. accessor method -> class init. Once this is done https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.regrid2.Regrid2Regridder.html and https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.xesmf.XESMFRegridder.html can be removed. This will drastically clean up the regridding documentation and make the individual regridders documentation easier to access.

I will also do a pass on all the regridding documentation to update anything requiring clarification.

[jasonb5]

Closing as we've decided to stick with generic horizontal and vertical methods. PR #535 addresses the documentation changes in this PR.