search

CDAT / cdms

8 stars 10 forks source link

Document how the bounds are generated by setAutoBounds/getBounds #406

Closed jypeter closed 3 years ago

jypeter commented 3 years ago

As mentioned in https://github.com/CDAT/cdms/issues/320#issuecomment-669143303, I have found the documentation of setAutoBounds. Unfortunately, it does not elaborate on will automatically generate boundary information. The documentation (or at least this issue) could clarify this!

The documentation of getBounds mentions genGenericBounds, but genGenericBounds is not documented

I have found the source, but I don't want to spend too much time on trying to understand what is actually done. I guess the bounds are in the middle of 2 coordinates, with some special care for +/-90 for the latitudes, and the leftmost and rightmost bounds of the longitudes https://github.com/CDAT/cdms/blob/73a7572482c16d673508f182e3c648c64e41bfc6/Lib/axis.py#L1641

This is probably good enough for rectilinear grids where all the cells have the same width on the longitude axis (very often the case), and all cells have the same height on the latitude axis (not always the case). We need correct bounds in order to generate weights and use cdutil.averager !

Should getBounds print a warning when it has to compute the bounds, but the widths and/or heights are not all the same? Are the weights we get in that case good enough? I'm talking about the cases where a netcdf file does not provide lat_bounds and lon_bounds, and we don't have an explicit areacella variable either. Does @durack1 have some advice on this?

durack1 commented 3 years ago

@jypeter I have been advocating for an update of the bounds functionality, in particular for the spatial bounds and non-standard grids (i.e. most of the ocean grids). There does need to be some work to get this updated for CMIP5+ data.

@taylor13 may have a perspective to add here, he did some work on the ESMPy regrid code to ascertain what was going on with the CDMS implementation

jasonb5 commented 3 years ago

There's definitely a lack of documentation, i'll be making a pass and try to get alot updated.

durack1 commented 3 years ago

@jasonb5 this would be great!

Feel free to reach out to all of us @pochedls, @lee1043, @gleckler1, @chengzhuzhang and myself (amongst others) for examples and usage cases to augment the docs

jasonb5 commented 3 years ago

The setAutoBounds behavior/interaction is very confusing and it's not clear how it all works together.

I've added documentation to setAutoBounds, createVariable and createAxis that tries to link these interactions together, redirecting to setAutoBands.

As for bounds functionality and non-standard grids, this will be addressed in the next-gen CDMS. If you could put together a feature list regarding grids and bounds, this would be most helpful with improving the next version.

jypeter commented 3 years ago

Thanks @jasonb5 !