Update and standardize documentation plots

[mdtanker]

I've gone through all the documentation and fixed some errors, standardized the plots, and switched all remaining matplotlib plots to use PyGMT.

Maybe it's personal preferences, but I've switched all diverging color scales to use balance instead of vik (or polar). Based on this site balance is more perceptually uniform, and I think it also just looks better.

I fixed some plots that used divering colorscales but either weren't centered on 0 or didn't have equal amplitude max and min limits.

I've updated the colorscale limits to use actual quantiles of the data , instead of just scaling the max and min values by a factor.

I've tried to standardize titles, the position and labels of colorbars, and removed some erroneous extra quotations in the titles and labels.

If anyone doesn't like some of these changes, I'm happy to revert them!

Relevant issues/PRs:

Fixes #591

[santisoler]

Thanks @mdtanker! I'll check these plots out! I'm updating this branch to bring in the changes in #601 here, so we can see the built documentation by downloading from the uploaded artifact.

[mdtanker]

Oh that's a nice way to check out the build, thanks!

[santisoler]

Thanks @mdtanker for opening this PR!

I couldn't find the statement about the balanced colormap being more perceptually uniform in the website you shared. But nonetheless, my eyes see more contrast in those plots, and therefore I found it easier to see (specially for colors close from the white center).

I saw you replaced some matplotlib plots for pygmt plots in the grid transformation page (and in a few other pages). My reasoning was to plot plain coordinates grids with matplotlib and geographic coordinates grids with pygmt. For plain coordinates the two should produce the same plot, and most users are probably more familiar with matplotlib than with pygmt. Do you think we should make the move to all pygmt plots?

I left two minor comments below, let me know what do you think!

[mdtanker]

I couldn't find the statement about the balanced colormap being more perceptually uniform in the website you shared. But nonetheless, my eyes see more contrast in those plots, and therefore I found it easier to see (specially for colors close from the white center).

Just comparing the Perceptual lightness charts for balance and vik. Probably a small difference but I agree it's easy to pick out differences.

I saw you replaced some matplotlib plots for pygmt plots in the grid transformation page (and in a few other pages). My reasoning was to plot plain coordinates grids with matplotlib and geographic coordinates grids with pygmt. For plain coordinates the two should produce the same plot, and most users are probably more familiar with matplotlib than with pygmt. Do you think we should make the move to all pygmt plots?

Oh I assumed they just hadn't been switched over to pygmt yet! I saw for example, in the prism forward modeling user guide there was already a mix of pygmt and matplotlib.

I'm happy to revert to matplotlib, but then we would probably switch those pygmt plots to matplotlib as well.

One thing I like about using pygmt is it shows users how to go from separate coords / data to an xarray dataarray with vd.make_xaray_grid. What are your thoughts?

[santisoler]

I'm happy to revert to matplotlib, but then we would probably switch those pygmt plots to matplotlib as well.

I don't have strong opinions on having matplotlib or pygmt plots. Actually, I find myself going back to the Harmonica's pygmt plots when I don't remember how to do certain thing in pygmt. My point is that it's not necessary to switch all to matplotlib or all to pygmt. I do prefer pygmt for data we already have in geographical coordinates, though. And I think it's nice to have some matplotlib plots in the user guide, so readers that are already familiar with matplotlib only need to get used to one single new thing (Harmonica), rather than learning Harmonica and how to use pygmt.

One thing I like about using pygmt is it shows users how to go from separate coords / data to an xarray dataarray with vd.make_xaray_grid. What are your thoughts?

We can use that function in the matplotlib plots too. We can define the dataarray and plot it directly through the DataArray.plot.pcolormesh method. We can use the function and comment that we can optionally convert the grid to a DataArray and then plot it (using either matplotlib or pygmt).

[mdtanker]

Ok yeah you're right it's probably best to have both. Maybe we keep the gallery examples as PyGMT, but I'll revert some of the user guides back to matplotlib, and maybe switch one to use pcolormesh. How does that sounds?

[santisoler]

Sounds good, @mdtanker!