Add Z axis support for spatial averaging

[tomvothecoder]

Discussed in #591

^{Originally posted by tomvothecoder January 29, 2024}

Is your feature request related to a problem?

I'm running into a case where I need to average over the Z axis. The CDAT code being used is cdutil.averager(tvar, axis="z"), which I need to replace.

xCDAT's spatial averager, which is based on cdutil.averager(), only supports rectilinear grids ("X" and "Y"). However, we do mention that the get_weights() method can be extended to support other axes:

xcdat/xcdat/spatial.py

Lines 246 to 252 in fbf1db6

	Notes
	-----
	This method was developed for rectilinear grids only. ``get_weights()``
	recognizes and operate on latitude and longitude, but could be extended
	to work with other standard geophysical dimensions (e.g., time, depth,
	and pressure).
	"""

Are there are any possible answers you came across?

No response

Describe alternatives you've considered

No response

Additional context

For the short-term, I might be able to use xarray.DataArray.weighted directly. However, I still need to generate the weights xr.DataArray beforehand.

datarray.weighted(weights).mean("height")

[pochedls]

@tomvothecoder - FYI - I thought this might only be a couple lines and took a look. It ended up being a little more than I thought, but I committed a working prototype because I thought it might be helpful (needs validation, review to make sure the docs are updated correctly, and unit tests). It could be possible to combine some of the _get_XYZ_weights functionality, but maybe it is fine as-is. We can delete the branch if you have something in progress already. Or I can open a PR.

[tomvothecoder]

@pochedls Thanks for taking a stab at this so quickly! You can open a PR and tag me for review.

As a temporary workaround in e3sm_diags, I created a _get_z_weights() function that is based on xCDAT logic. I am planning on replacing it whenever xCDAT supports generating weights for the Z axis, which now seems sooner rather than later.