Better Organize & Document Analysis Operators

[aaronzedwick]

Proposed new feature or change:

Create an analysis operator notebook that showcases all our analysis operators. This will be added to as more operators are added. The goal is to have a notebook with very simple and short examples to let users know what analysis operators UXarray has and how to use them. Especially as @hongyuchen1030's work is getting merged, I think it is important to showcase and let users know what UXarray can offer in terms of operators.

@rajeeja We can tackle this together if you want.

Current List of Analysis Operators In UXarray for Notebook:

• Conservative Zonal Mean
• Add more here

[philipc2]

How would this be different from how we are currently using the user guide? We already develop user guide sections for each major operator, with a notebook for zonal averaging already part of the PR.

The API reference also serves a similar purpose.

I think it's important though to highlight analysis operators in scientific workflows as well. These would probably go under the Workflow Examples section similar to what we have already populated.

[aaronzedwick]

How would this be different from how we are currently using the user guide? We already develop user guide sections for each major operator, with a notebook for zonal averaging already part of the PR.

The API reference also serves a similar purpose.

I think it's important though to highlight analysis operators in scientific workflows as well. These would probably go under the Workflow Examples section similar to what we have already populated.

We were talking in the meeting today, it’s just a challenge I think for users to know what UXarray offers. And the user guides and API references are packed full of a lot of functions. Kinda hard to find stuff. This would be more a notebook that shows all the analysis operators (and only the operators) that are in UXarray and could link to any api references or notebooks needed. I just personally think having one spot that gives a list type showcase of all the operators would be nice. Just a line saying what it is and a line showing it being called. I think making a notebook for every single operator we make would create a lot of notebooks.

Those are just my thoughts. If you think this feature isn’t needed or useful though, I can close the issue.

[philipc2]

And the user guides and API references are packed full of a lot of functions. Kinda hard to find stuff.

May you elaborate why you think its hard to find things? We could consider reorganizing / improving existing sections if needed.

Just a line saying what it is and a line showing it being called

This is what the "Examples" section in our docstrings achieves. For example:

https://uxarray.readthedocs.io/en/latest/generated/uxarray.Grid.cross_section.constant_latitude.html#uxarray.Grid.cross_section.constant_latitude

I just personally think having one spot that gives a list type showcase of all the operators would be nice.

This can be achieved under our API reference if we want to, although we already have sections in the toc for each major set of functionality.

Let's hear some feedback from @erogluorhan and @rajeeja after the holidays. I think additions to our documentation are some of the most important contributions we can make, but I'd like to make sure we do not duplicate anything or spread everything into too many places.

[philipc2]

Regarding the API reference, we can also hyperlink to user-guide sections.

[aaronzedwick]

I think having hyper links to the API for the docs is definitely helpful. Maybe we could change the organization of the docs just a little, by adding a heading that we can group things under? So having an analysis operator heading and under that have cross sections, zonal mean, etc. We could do this for other functionality as well if other types of groups make sense. Would that possibly be a good solution?

My main worry is that as we get more functionality our docs will get bloated and things will be too scattered. If we have 10 different operators and each has a separate user guide and api reference, I think it would be simpler to find if we had somewhere to group that. Inside the api headings might be a better place than a notebook.

I think right now our docs are fine. But in the future, for a user of UXarray that doesn’t know what we have to offer I think it would useful for them to have a place that shows them we have analysis operators and here are the ones we have. I think since analysis operators are a really important feature for UXarray, this is especially helpful for that feature. Really I am trying to think how we can go about making the barrier to entry as low as possible. So someone can quickly look at our package and know whether it’s what they need or not.

[philipc2]

Maybe we could change the organization of the docs just a little, by adding a heading that we can group things under?

That sounds like a great idea. I was going to take a look at the API reference and clean it up a bit, so I can see if I can re-organize anything there. @aaronzedwick can we make the title of this issue a bit more general, maybe: "Better Organize & Document Analysis Operators" ?

My main worry is that as we get more functionality our docs will get bloated and things will be too scattered. If we have 10 different operators and each has a separate user guide and api reference, I think it would be simpler to find if we had somewhere to group that.

This is a valid concern, though as packages progress and more functionality is added, the API reference will inevitably become very long, which is a good thing (as long as it is organized correctly).

But in the future, for a user of UXarray that doesn’t know what we have to offer I think it would useful for them to have a place that shows them we have analysis operators and here are the ones we have.

This sounds more like something that belongs in the package description in our README. We already have the following in our README.

Really I am trying to think how we can go about making the barrier to entry as low as possible. So someone can quickly look at our package and know whether it’s what they need or not.

I think this reinforces the importance of a well-formatted README then, since that is the first thing people will see when searching for the package on PyPi or on Github.

[philipc2]

@aaronzedwick

We could update our "Why UXarray?" section from the Getting Started Guide to include a brief discussion of what "Core Functionality" we have, that could be a good starting point.

We could list out the functionality we have similar to the README and add hyperlinks to the API. What do you think?

[aaronzedwick]

@aaronzedwick

We could update our "Why UXarray?" section from the Getting Started Guide to include a brief discussion of what "Core Functionality" we have, that could be a good starting point.

We could list out the functionality we have similar to the README and add hyperlinks to the API. What do you think?

That sounds great Philip, thanks for the discussion on this! I’ll change the issue name.

[erogluorhan]

Maybe we could change the organization of the docs just a little, by adding a heading that we can group things under?

I like this!

Also, regarding the API reference, while I think it could serve for the purpose of this issue, I also agree with its current format making things a bit hard to read. it'd be great if there was a way to provide a way of filtering for those headings throughout the reStructuredText in the very beginning of the doc, so the reader could filter the whole reference for, say "Mathematical Operators".

Throwing all of the analysis operators into a single notebook may not cater a meaningful story to the reader even though I see the value with the purpose mentioned.

[philipc2]

it'd be great if there was a way to provide a way of filtering for those headings throughout the reStructuredText in the very beginning of the doc, so the reader could filter the whole reference for, say "Mathematical Operators".

Other than the TOC I assume?

Something like what HoloViews does?

https://holoviews.org/reference_manual/index.html

[aaronzedwick]

it'd be great if there was a way to provide a way of filtering for those headings throughout the reStructuredText in the very beginning of the doc, so the reader could filter the whole reference for, say "Mathematical Operators".

Other than the TOC I assume?

Something like what HoloViews does?

https://holoviews.org/reference_manual/index.html

Yeah, I think sub headings would be great, would just make it easier to navigate. I click geometry operators and a list of all the geometry operators drops down. Maybe something like that?

[aaronzedwick]

it'd be great if there was a way to provide a way of filtering for those headings throughout the reStructuredText in the very beginning of the doc, so the reader could filter the whole reference for, say "Mathematical Operators".

Other than the TOC I assume?

Something like what HoloViews does?
https://holoviews.org/reference_manual/index.html

Yeah, I think sub headings would be great, would just make it easier to navigate. I click geometry operators and a list of all the geometry operators drops down. Maybe something like that?

Since we already basically do this for other things like remapping, just do the same thing for things such as the analytical operators.

[aaronzedwick]

I think updating the readme “Why UXarray” section is really where the focus should be personally though as @philipc2 mentioned. It’s one of the first things new users will read so it should be the most up to date and best reflection of what UXarray can do.

[philipc2]

I think updating the readme “Why UXarray” section is really where the focus should be personally though as @philipc2 mentioned. It’s one of the first things new users will read so it should be the most up to date and best reflection of what UXarray can do.

This would be a great start. Do you want to tackle this?

[aaronzedwick]

I think updating the readme “Why UXarray” section is really where the focus should be personally though as @philipc2 mentioned. It’s one of the first things new users will read so it should be the most up to date and best reflection of what UXarray can do.

This would be a great start. Do you want to tackle this?

Sure!

[erogluorhan]

Yeah, subheadings would work for what I was looking for.