Agreegate all utilities.py functions

[ocefpaf]

As I am writing https://ioos.github.io/system-test/ I am collecting all the useful functions from the several utilities.py in a single file. We can package that later and provide to users that want to try the notebooks out.

[jbosch-noaa]

Do you have documentation for these functions? How do I learn to use them?

As you know, I am new to Python but proficient at Matlab. As an exercise to get comfortable with running my own python code I decided to walk through one of your system integration test scripts (test_iris_advanced_cartopy.ipynb).

I have run in to some trouble understanding what you are doing in your code. Particularly, I don't know what the functions in the utilities library do. Do you have documentation some where for functions like get_surface, get_nearest_water, make_tree, etc? They sound useful but I just don't know how or what they are useful for.

[ocefpaf]

@jenniferbosch these functions were developed by several authors (@birdage, @Bobfrat, @rsignell-usgs, @kwilcox, and many more). Virtually everybody that participated in the system-test exercise!

With that said: you might find functions with the same name that do different things, docs inside the notebook comments or reports, multiple versions of the same function, etc... In the original system-test notebooks each notebook has its one utilities.py file and that caused the fragmentation we are dealing with now.

Right now, your best option is to use some of the functions aggregated here. And for documentation we have only the docstrings, like this one.

I opened this issue to remind me to parse all the working versions of these functions, add docstrings to them, and then add them to the utilities module hoping to fix the fragmentation. Maybe we can even created a sphinx page with the docs.

PS: Remember that you can access the docsting from the notebook using either the ? or the <tab> completion.

[emiliom]

@ocefpaf, as you're (re)building the universal utilities module (which sounds like a big and tedious task!), I'd like to suggest that it be renamed to something less generic/opaque. If that module will have some use outside the system-test notebooks -- and it sounds like it would -- a more specific name would help. Say, ioosutil, ioos_sit_util, etc.

[birdage]

@emiliom i think that is quite a good idea, as it wont step on any other libraries then!

[jbosch-noaa]

As the person being dubbed the first "outside the system-test notebooks" user I completely agree with both of you. I am looking forward to documentation of the different functions. It seems like you all worked really hard to make functions useful to fellow IOOSians and I would love to learn how to use them.

[ocefpaf]

@ocefpaf, as you're (re)building the universal utilities module (which sounds like a big and tedious task!)

Indeed!

I'd like to suggest that it be renamed to something less generic/opaque. If that module will have some use outside the system-test notebooks -- and it sounds like it would -- a more specific name would help. Say, ioosutil, ioos_sit_util, etc.

Yes, the goal is to rename to something more meaningful. Like maybe this 😉

It will take some time until the dust settles and I am not 100% sure we should make a module out of those functions due to their transient nature. Several of those are already outdated due to libraries updates and/or changes in the services they try to access.

I believe that their true value is to be examples on how to roll your own solution. I am planning on "cracking" them open in the system-test blog.

[emiliom]

That all sounds great, @ocefpaf. I'm glad I tapped on a wider sentiment, too.