UXarray readme & docs should quickly clarify "spherical, 2D"

[Sevans711]

Proposed new feature or change:

UXarray fundamentally handles exactly 2 dimensions of "unstructured-ness", and always treats that 2D unstructured grid as being on the surface of a sphere. Restricting the domain of applicability like this has the benefit of enabling more development efforts and code space dedicated to methods specialized in Earth data analysis. However, these limitations not immediately obvious from the name, the README, nor the "Why UXarray?" docs page.

For example, people running fluid dynamics / plasma physics simulations on irregular 3D grids should be able to quickly understand that uxarray will not help them with their analysis. From quickly skimming the name, the README, and the "Why UXarray" docs page, I initially came away with the opposite impression; I figured "yes, this package does include many Earth-data-specific methods and functionality because that is the primary target audience, but fundamentally its goal is probably to support N-dimensional unstructured-ness, so it might help with 3D unstructured grids".

[erogluorhan]

Similar to #1615 , see this comment from that.

[erogluorhan]

Actually, the "... unstructured climate and global weather data analysis ..." phrase in the README/homepage is the key term to imply the "horizontally 2D meshes with vertical levels" assumption.

Additionally, the following part in Why UXarray? is helping with that understanding, too:

"Specifically, our core functionality is built around horizontally Unstructured Grids as defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain a mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured Grids may have structured vertical levels."

However, we can still improve docs as suggested here to be further helpful

[Sevans711]

Thank you for looking into this, @erogluorhan! Following up with a few thoughts:

Actually, the "... unstructured climate and global weather data analysis ..." phrase in the README/homepage is the key term to imply the "horizontally 2D meshes with vertical levels" assumption.

This makes sense to me now, but I remember being confused about it before starting to work with uxarray. Despite having some familiarity with nearby science (ionospheric physics), I did not initially realize that "unstructured climate and global weather data analysis" implies 2D horizontal meshes with vertical levels.

Part of my surprise may have also come uxarray's broad name ("unstructured grids + xarray") plus my understanding of xarray's purpose, as it is targeted for a broad audience of "anyone who needs N-dimensional labeled arrays in Python" despite "Originally, development was driven by the data analysis needs of physical scientists (especially geoscientists who already know and love netCDF)."

Additionally, the following part in Why UXarray? is helping with that understanding, too:

"Specifically, our core functionality is built around horizontally Unstructured Grids as defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain a mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured Grids may have structured vertical levels."

Ah, I missed this on my initial skimming of that page, when I was initially looking at uxarray to try to understand its purpose quickly. Maybe adding a .. note:: box on that page would have helped to more easily draw my eye towards it?

One more quick note: note that "spherical" still needs to be clarified.

I will get started on a PR that would clarify these things, while keeping your comments in mind and trying to remain as concise as possible!

[erogluorhan]

Maybe adding a .. note:: box on that page would have helped to more easily draw my eye towards it?

Yeah, that's a good idea! Admonitions almost always are helpful with this kind of more emphasis goals.

One more quick note: note that "spherical" still needs to be clarified.

I will get started on a PR that would clarify these things, while keeping your comments in mind and trying to remain as concise as possible!

Sure, sounds like a great plan! Thanks Sam!