Adding target_dim as parameter to .transform()

[NoraLoose]

Still WIP

• Closes [DOC] Depth to depth xgcm.Grid.transform onto terrain-following depth levels #614 and closes [BUG] broken cells in transform page of docs  #573
• Documentation added
• Tests added
• Passes pre-commit run --all-files
• User visible changes (including notable bug fixes) are documented in whats-new.rst

I added a section to the existing doc/transform.ipynb notebook to document the new capability. While working on this notebook, I also fixed pre-existing issues with this notebook including:

• Insert autoparse_metadata=False into Grid() to avoid error messages
• Correct dictionary keys for pangeo cloud data library
• Remove non-existing xc coordinate from Grid object to avoid existing ValueError
• Insert a .squeeze() for plotting AMOC to avoid error

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[NoraLoose]

The changes made in this PR are not the reason for the failing checks above. The same checks fail in #641. I opened issues #643 and #644.

[NoraLoose]

Just realized that there is overlap between this PR and PR #627

[jbusecke]

Hey @NoraLoose, thank you so much for working on this and sorry for the delay. I think I got the CI issues #644 and #648 under control now. Once #649 is merged can you try to rebase this one?

Just realized that there is overlap between this PR and PR #627

Feel free to absorb and close this if needed.

[jbusecke]

Also I have restructured the linting and setup in #650, please let me know if it is ok to merge this ahead of time. I think this should not cause too big of a conflict?

[NoraLoose]

Also I have restructured the linting and setup in #650, please let me know if it is ok to merge this ahead of time. I think this should not cause too big of a conflict?

Yep, feel free to merge #650!

[NoraLoose]

Transforming onto a spatially varying vertical coordinate (e.g., terrain-following) works with the linear interpolation method, see newly added tests and the example in the documentation.

I tested this also for the conservative interpolation method by adding the following test case to the cases dictionary in xgcm/test/test_transform.py:

    "conservative_depth_depth_multidim_target": {
        "source_coord": ("z", [5, 25, 60]),
        "source_bounds_coord": ("zc", [0, 10, 50, 75]),
        "source_data": ("data", [1, 4, 0]),
        "source_additional_data_coord": (
            "zc",
            [0, 10, 50, 75],
        ),
        "source_additional_data": ("zc", [0, 10, 50, 75]),
        # 2D target
        "target_dims": ("eta_rho", "s_w"),  # eta_rho: horizontal dimension; s_w: vertical dimension
        "target_coord": ("interface_depth_rho", np.array([[0, 1, 10, 50, 80], [0, 5, 20, 30, 100]])),
        "target_data": ("interface_depth_rho", np.array([[0, 1, 10, 50, 80], [0, 5, 20, 30, 100]])),
        "expected_dims": ("eta_rho", "s_w"),
        "expected_coord": ("interface_depth_rho", np.array([[0.5, 5.5, 30, 65], [2.5, 12.5, 25, 65]])),
        "expected_data": (
            "data",
            np.array([[0.1, 0.9, 4.0, 0.0], [0.5, 1.5, 1.0, 2.0]])
        ),
        "grid_kwargs": {
            "coords": {"Z": {"center": "z", "outer": "zc"}},
            "autoparse_metadata": False,
        },
        "transform_kwargs": {"method": "conservative", "target_data": "zc", "target_dim": "s_w"},
    }

However, it fails because of this line:

xgcm/xgcm/transform.py

Line 160 in 2de04bf

assert target_theta_bins.ndim == 1

[NoraLoose]

@jbusecke I'm not sure when I have time to look into generalizing the conservative method to multiple dimensions. We could merge this PR, and open a feature request issue? If we do this, should we include more warnings (where?) to clarify that the conservative method is not yet supported for multi-dimensional vertical target coordinates?

[jbusecke]

Thank you so much @NoraLoose! This is awesome. I am pretty busy today, but will try to take some time next week to review and maybe also enable conservative interpolation.