Add function to swap dataset longitude axis orientation

[tomvothecoder]

Description

• Closes Add option to specify longitude axis system when opening up a dataset #135

This PR adds the ability to swap the axis orientation of longitude coordinates and bounds in the Dataset, either upon opening via xcdat.open_dataset/xcdat.open_mfdataset or as an independent function call. It also handles the prime meridian cell when converting from the 180 axis orientation to 360 by splitting it into east and west parts (reuses _align_lon_bounds_to_360() from the spatial averaging feature).

Summary of Changes

• Add swap_lon_axis() to axis.py
  • Supports axis orientations [-180, 180] and [0, 360]
  • Extendable to support subsets and wrapping beyond orientation min/max
• Add lon_orient kwarg to open_dataset() and open_mfdataset() for specifying orientation upon opening a Dataset
  • Default behavior is to sort values in ascending order
• Add _align_lon_to_360() to handle prime meridian cell for the entire Dataset
• Move _align_lon_bounds_to_360() from spatial_avg.py to axis.py
  • Extract helper function _get_prime_meridian_index() from _align_lon_bounds_to_360()
  • Update _get_longitude_weights() to use _get_prime_meridian_index()

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

If applicable:

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass with my changes (locally and CI/CD build)
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have noted that this is a breaking change for a major release (fix or feature that would cause existing functionality to not work as expected)

[tomvothecoder]

TODO @pochedls: add comments from meeting about covering some axis orientation edge cases and tag Jiwoo.

[codecov-commenter]

Codecov Report

Merging #145 (f97f4b1) into main (201a575) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##              main      #145    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            8         8            
  Lines          381       481   +100     
==========================================
+ Hits           381       481   +100     

Impacted Files	Coverage Δ
xcdat/__init__.py	100.00% <100.00%> (ø)
xcdat/axis.py	100.00% <100.00%> (ø)
xcdat/bounds.py	100.00% <100.00%> (ø)
xcdat/dataset.py	100.00% <100.00%> (ø)
xcdat/spatial_avg.py	100.00% <100.00%> (ø)
xcdat/xcdat.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 77ff299...f97f4b1. Read the comment docs.

[pochedls]

TODO @pochedls: add comments from meeting about covering some axis orientation edge cases and tag Jiwoo.

@tomvothecoder and @lee1043 - I've noted the CDAT behavior here. This has some advantages. If you purely convert the bounds to 0-360 units, then a bound that spans the prime meridian has a range that may be unexpected (e.g., [-1, 1] becomes [359, 1]). This has created headaches for spatial averaging (since the weight in each dimension scales as the difference between the bounds; 1 - -1 = 2, but 1 - 359 = -358).

[tomvothecoder]

If you purely convert the bounds to 0-360 units, then a bound that spans the prime meridian has a range that may be unexpected (e.g., [-1, 1] becomes [359, 1]). This has created headaches for spatial averaging (since the weight in each dimension scales as the difference between the bounds; 1 - -1 = 2, but 1 - 359 = -358).

We can pull some similar code from #152 to handle this edge case at the Dataset level

[chengzhuzhang]

We can pull some similar code from #152 to handle this edge case at the Dataset level

I was thinking the same, they are useful as general purpose functionality. :)

[pochedls]

This is functionality that I have not used, but I suspect that users would want one change: a reordering of the longitude axis after the longitude units are converted. I suspect that a lot of what you would want to do might be complicated if you go from [-180, -179, ..., -1, 0, 1, ..., 179] to [180, 181, ..., 359, 0, 1, ..., 179] (e.g., plotting). There would ideally be a third step that also reorders the longitude axis (and the corresponding dataarrays and bounds) to [0, 1, ..., 179, 180, 181, ..., 359].

Bounds are a special issue. The example above would have bounds of (notice the weird first bound):

lon_bnds = [[359.5, 0.5],
            [0.5, 1.5],
            ...,
            [178.5, 179.5],
            [179.5, 180.5],
            [180.5, 190.5], 
            ...,
            [358.5, 359.5]]

CDAT breaks this first bound up making the longitude axis go from length 360 to 361 (see added/modified values marked with asterisks): [0, 1, ..., 179, 180, 181, ..., 359, *360*] and

lon_bnds = [*[0, 0.5]*,
            [0.5, 1.5],
            ...,
            [178.5, 179.5],
            [179.5, 180.5],
            [180.5, 190.5], 
            ...,
            [358.5, 359.5], 
            *[359.5, 360.5]*]

This is what is done in #152.

The corresponding data array (e.g., tas) would simply repeat the values for the first and last longitude. I think CDAT might actually modify the first and last longitude coordinate value, too (e.g., [*0.5*, 1, ..., 179, 180, 181, ..., 359, *359.5*]).

@lee1043 - could you comment here on this PR (and let me know if you agree with this comment).

[tomvothecoder]

Hey @pochedls this PR is ready for review. @lee1043 and @chengzhuzhang, if you want to test out this feature that'd be nice too.

After checking out the branch, there are two ways to test it:

1. Using xcdat.open_dataset()/xcdat.open_mfdataset() with kwarg lon_orient set to 180 or 360

   import xcdat
   
   ds = xcdat.open_dataset("path/to/file.nc", lon_orient=360)
   

2. Open dataset (can use xcdat or xarray) and pass object to xcdat.swap_lon_axis()

   import xcdat
   
   ds = xcdat.open_dataset("path/to/file.nc")
   # `sort_ascending` is optional
   ds = xcdat.swap_lon_axis(ds, to=360, sort_ascending=True)
   

[lee1043]

Hey @pochedls this PR is ready for review. @lee1043 and @chengzhuzhang, if you want to test out this feature that'd be nice too.

After checking out the branch, there are two ways to test it:

1. Using `xcdat.open_dataset()`/`xcdat.open_mfdataset()` with kwarg `lon_orient` set to 180 or 360
   ```
   import xcdat
   
   ds = xcdat.open_dataset("path/to/file.nc", lon_orient=360)
   ```

2. Open dataset (can use xcdat or xarray) and pass object to `xcdat.swap_lon_axis()`
   ```
   import xcdat
   
   ds = xcdat.open_dataset("path/to/file.nc")
   # `sort_ascending` is optional
   ds = xcdat.swap_lon_axis(ds, to=360, sort_ascending=True)
   ```

@tomvothecoder it is great that this capability has been added, thanks! I like that there are 2 ways of using it. I have mostly used above way 1 in PMP, but have noticed that in some case I needed above way 2 to consider different areas with one open file (e.g., one area 60 to 120, another -30 to 30).

Is there any chance that parameters for lon_orient or to of xcdat.swap_lon_axis() to be more articulated? I am thinking of [0, 360] or [-180, 180], instead of 360 or 180, but open to any suggestion.

[pochedls]

I haven't reviewed this code yet, but the syntax looks fine for my use cases.

@lee1043 is suggesting we should do a bit more to orient and subset in the same function call. An even more advanced version of this was suggested here - it was noted we should even be able to "tile" the grid (e.g., -180 to 360 which would repeat part of the grid).

@tomvothecoder - should this all be lumped together or should the subsetting be a future feature?

[lee1043]

@lee1043 is suggesting we should do a bit more to orient and subset in the same function call. An even more advanced version of this was suggested here - it was noted we should even be able to "tile" the grid (e.g., -180 to 360 which would repeat part of the grid).

@pochedls thanks for your comment. I was not thinking that to parameter should be more flexible like [-180, 360] or any number e.g., [20, 270] or something. I was simply thinking 180 to [-180, 180] and 360 to [0, 360] so it is more straightforward. Although I like the idea of the flexibility, I think I am okay with having it for future feature.

[jasonb5]

LGTM