Add simple tide elevation and current scripts

[jerabaul29]

First, many thanks for bringing a really amazing package to the community!

I am not an expert on tides, and I had not used TMD packages before. When starting with pyTMD, I had a bit of difficulty to do / find documentation / find examples about how to do really simple things (like, given a lon, lat, and time, get tide elevation and currents).

I have written a couple of small notebook "scripts" for getting an "as simple as possible" example of how to use the package (i.e. having just some pyTMD, without the widget etc present in the more advanced notebooks available so far). To make sure I use pyTMD correctly, I also compare with observations for both tide and current.

This results in the two notebooks committed here. I think this may be useful for other users who want a "least complexity example" of how to use pyTMD in a python script, so submitting these to the upstream.

Let me know if you are interested in including this. If yes, could you have a quick look, to triple check I am doing things correctly? :)

[tsutterley]

hi @jerabaul29,
Looks like you're getting good results in comparison with your tide data. Awesome!

I like the idea of a simple demonstration that has set inputs and outputs. The CI tests actually do something similar to verify that everything is functioning as expected.

Generalizing paths for end users is a sticking point (which is one of the main reasons the current notebooks use widgets). Happy to take suggestions on better ways to handle this. Could just have a raw text input?

I've also thought about switching the documentation include compiled Jupyter notebooks for recipes and tutorials. A bigger change would be to switch to using a Jupyter Book format, which would be similar to CryoCloud's documentation. I go back and forth on if this is a good idea.

Do you want me to work on these notebooks for generalization or do you want to keep tinkering on them?

[jerabaul29]

Thanks :) .

I think (but just my 2 cents, and I may be "wrong", and that may be opinionated, so feel free to disagree with any points you think is wrong / can be improved of course :) ) that:

• it could be really useful to have a version of the notebooks and / or some additional file in the package providing modules and functions that include
  • a high level, n00b end user friendly function take simple inputs (i.e. i) path to the model folder, ii) something like args for lat, lon, time, each of the 3 either a single value or a np array, iii) a specification of what output is needed as a list of strings that is a "sub list" of ["eta", "u", "v"] or something like this), and spits out the corresponding results as an xarray dataset following CF conventions, so it can be used out of the box by many modern tools.
  • a simple example of how to use this function and comparison with some in-situ measurements like what I did in the notebooks, just to illustrate
  • making sure that all of the above use fully spelled out / commented code (like "tide_amplitude[type], tide_phase[type], model_bathymetry[type], tide_constituents[type]" instead of one-letter short names that can be obscure to most non expert readers, so that anybody can just look quickly in the function and understand what is what in it :) ).

I think this making such a function available could reduce a lot the barrier to entry to use the package (it took me actually a couple of afternoons to get to these notebooks working well - likely because I am a n00b on these aspects, but still :) ). Having a general high level though simple / convenient API through a single function like described above, would also mean that even if heavy updates happen in the future, you could make this invisible for the user by just providing the same "high level user API". Also providing a few high level functions that provide outputs as xarray datasets is maybe a bit constraining on the user, but makes the output self documented and so much easier to use right / harder to use wrong, and this is becoming a standard in the geophysics projects I see around me :) .

As far as I am concerned these notebooks I pushed do "what I want and need for now", and I do not want to push anything on you and your package, so I think for my personal use that I am happy with the current notebooks. But if you think it can be interesting to look into the directions discussed above, I would be happy to do my best to help (with the caveat that there is no guarantee for responsivity etc, since as everybody I am a bit overbooked :) ).

[jerabaul29]

To illustrate a bit what I meant: I put a "full example" here (only for my "model of interest", i.e. the Arc2km): https://github.com/jerabaul29/pyTMD/tree/feat/full-example/example . For my use, all I needed is a simple API that is easy to use:

https://github.com/jerabaul29/pyTMD/blob/7a0186b8996fbc185d059b7478f3c0418cf1b4e3/example/pytmd_get_tide_elevation_current.py#L10

So it can be used in the notebook easily: https://github.com/jerabaul29/pyTMD/blob/feat/full-example/example/pytmd_script_use_get_tide_elevation_current.ipynb

# compare with pytmd_script_get_tide_elevation_timeseries.ipynb

lat_to_predict = 79.029
lon_to_predict = 11.178

start_day_to_predict = datetime.datetime(2023, 7, 10, 0, 0, 0, tzinfo=datetime.timezone.utc)
number_of_hours_to_predict = 24*8
list_datetimes_to_predict = [start_day_to_predict + datetime.timedelta(hours=hr) for hr in range(number_of_hours_to_predict)]

dict_results = get_pytmd_tide_timeseries(list_datetimes_to_predict, lat_to_predict, lon_to_predict)

where dict_results has keys dict_keys(['list_datetimes', 'tide_meters', 'tide_current_u_cm_per_s', 'tide_current_v_cm_per_s']).

Of course, this is just my need / for a single model I am interested in, but I wonder if having some simple python wrappers / APIs a bit in this kind could make it even easier for the users :) .