Tutorial using all our packages for gravity processing

[leouieda]

This is a slightly updated version of our Transform 2021 tutorial. It uses our new curated datasets (downloading from Zenodo) and adds a few steps to the processing. Most notably, it now includes the conversion of "sea level" heights to ellipsoidal (geometric) heights using our geoid data, the topography grid is expanded to account for edge effects, density for the topographic correction needs to account for water and continental points below the ellipsoid, and the regional/residual separation is done with deep equivalent sources instead of a polynomial.

Reminders:

• [ ] Run make format and make check to make sure the code follows the style guide.
• [ ] Add tests for new features or tests that would have caught the bug that you're fixing.
• [ ] Add new public functions/methods/classes to doc/api/index.rst and the base __init__.py file for the package.
• [ ] Write detailed docstrings for all functions/classes/methods. It often helps to design better code if you write the docstrings first.
• [ ] If adding new functionality, add an example to the docstring, gallery, and/or tutorials.
• [ ] Add your full name, affiliation, and ORCID (optional) to the AUTHORS.md file (if you haven't already) in case you'd like to be listed as an author on the Zenodo archive of the next release.

[welcome[bot]]

💖 Thanks for opening your first pull request! 💖

Please make sure you read the following:

• Authorship Guidelines: Our rules for giving you credit for your contributions, including authorship on publications and Zenodo archives.
• Code of Conduct: How we expect people to interact in our projects.

A few things to keep in mind:

• Remember to run make format to make sure your code follows our style guide.
• If you need help writing tests, take a look at the existing ones for inspiration. If you don't know where to start, let us know and we'll walk you through it.
• All new features should be documented. It helps to write the docstrings for your functions/classes before writing the code. This will help you think about your code design and results in better code.
• No matter what, we are really grateful that you put in the effort to do this! ⭐

[leouieda]

@santisoler @andieie @aguspesce I started this yesterday and was playing around with our new data and trying to update this tutorial. Still need some polish in a few places but I'd appreciate any early feedback if you have some time. I added you all to the notebook and an AUTHORS.md file as authors (hope you don't mind).

Any ideas on how to better format this or use this repository are welcome as well!

[santisoler]

Thanks @leouieda for pushing this! I'm glad that the deep equivalent sources work like charm for removing the regional field.

Some thoughts:

• I would rename the trend object to deep_sources, regional_eqs or something like that so we detach ourselves from the idea that we are removing some polynomial trend, while are actually removing a harmonic regional field.
• Add more comments/Markdown text for the topographic correction, for the residual calculation and the gridding process. I suspect they are a work in progress, but I wanted to mention it.
• Maybe we could create a Jupyter Book out of this repo, so it's easier to read the notebooks without the need to download them and open them with JupyterLab. GitHub notebooks visualization is not that great either (Gitlab has much better support for visualizing and diffing notebooks: https://docs.gitlab.com/ee/user/project/repository/jupyter_notebooks/).

[andieie]

Looks great @leouieda . I agree with @santisoler points, especially the first one.

• I would elaborate a little on the Gravity Disturbance calculation.
• Also, maybe it's just me but I am not sure how to interpret the bottom of the prism model. Maybe some explanation could clear that up or a middle layer would be helpful.

This is a great notebook and I hope a lot of people can use it!

[leouieda]

Thanks for the feedback! I'll add a bit more text explaining things and rescue the nice figures from the Transform tutorial that I didn't include yet.

The topographic correction is particularly challenging (I had to draw it myself to be able to figure what to do). I'll see if I can include a figure about it to make the surfaces a bit clearer.

As for JupyterBook: we should definitely experiment with it. After this PR is done, we can try adding the required infrastructure here. It may even be possible to convert this notebook to Markdown and have Jupyter notebook generate the ipynb for us.

[santisoler]

The topographic correction is particularly challenging (I had to draw it myself to be able to figure what to do). I'll see if I can include a figure about it to make the surfaces a bit clearer.

I agree on this point, and I think the best way to picture it is through better visualization. I do think we need to start thinking about plotting the prism layer with pyvista. I know we don't want to have visualization wrapper functions inside Harmonica, but we should start talking about this (I think I'll add it to one of our Development Calls).

[leouieda]

You're right. And it would have to be something interactive it it's going to be 3D, which PyVista supports. I think for this we probably will need a custom function to get things from our xarray-based data structure into a format that PyVista expects. We can develop this in Harmonica and have a chat with the PyVista team to see what we can do going forward. But it always helps to have a prototype when approaching these talks.

[leouieda]

For now, I made this illustration (following the hand-drawn arrow style you were using for Transform, which I really liked):

This is what the correction is doing. The surface for the prism layer is set as the topography/bathymetry (referenced to the ellipsoid). The reference is the ellipsoid (0 height). The density is created to match the coloured patches. The stripped parts in the ocean are what I'm ignoring (I calculated it actually but it's a lot of work and was only 0.001 mGal).

[leouieda]

Alright, I added more text and some more figures. I also simplified the plots a bit and removed the top and bottom plots of the prism layer since they were probably more confusing than helpful.

I’m trying to see if I can implement cross-validation for the interpolation without adding too much complexity.

[LL-Geo]

There are some figures that I made several months ago. Haha, feel free to use it if that could be helpful. 😉 https://github.com/LL-Geo/PFToolbox/blob/master/Gravity%20disturbance.ipynb

[leouieda]

Thanks for sharing @LL-Geo! I love those figures ❤️ I think I'll stick to a simpler form here since it's mostly for topographic correction. But we should use your figures in a more general tutorial in Harmonica about this.

[leouieda]

Alright, gave up on cross-validation since it takes a bit too long to run for a tutorial. Maybe we can point people to another tutorial somewhere that covers this later on.

Could you all please take a final look to see if this OK to merge? Any comments or modification are more than welcome 🙂

[review-notebook-app[bot]]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[santisoler]

Thanks again @leouieda for improving our notebook! I left some minor corrections on ReviewNB. Let me know if you can see them. Besides that, feel free to merge!

[LL-Geo]

I made some comments as well. That's a really good tutorial! I really like that!!! @leouieda

[aguspesce]

@leouieda, sorry for the delay. The past weeks, I was with many things. I really like the notebook. I don't think I have something to change.

[leouieda]

Hi everyone, thanks for the comments and suggestions! I've incorporated them into the text. I'll merge this in now but please feel free to open PRs with changes or tweaks.

I added a note only about using Airy since the code turned out to be a bit too long for this tutorial. We kind of want this to be a quick thing (~20 min) so that it works as a video or demo. It would great to expand this in the Harmonica docs, though.

[welcome[bot]]

🎉 Congrats on merging your first pull request and welcome to the team! 🎉

If you would like to be added as a author on the Zenodo archive of the next release, add your full name, affiliation, and ORCID (optional) to the AUTHORS.md file of this repository. Feel free to do this in a new pull request if needed.

We hope that this was a good experience for you. Let us know if there is any way that the contributing process could be improved.