Support sampling face-centered data onto a GeoAxes

[philipc2]

Closes #1268, #366

Overview

• Adds a UxDataArray.to_raster() method, which is used to sample an unstructured grid onto a provided GeoAxes
• Enables Matplotlib plotting workflows that rely on raster data, such as imshow, contour and contourf
• Updated user guide section on Plotting with Matplotlib and Cartopy

Example

fig, ax = plt.subplots(
    subplot_kw={'projection': ccrs.Orthographic(central_longitude=-90, central_latitude=45)},
    constrained_layout=True,
    figsize=(10, 5),
)
scale = '110m'


ax.set_extent([-90, -80, 40, 50])  # great lakes 

var = uxds['lwupt'].isel(Time=0)

raster = var.to_raster(ax=ax)

my_plot = ax.imshow(raster, origin='lower', extent=ax.get_xlim() + ax.get_ylim())


ax.coastlines(resolution=scale, color='black', linewidth=1)
ax.add_feature(cfeature.BORDERS.with_scale(scale), linestyle=':', linewidth=0.8)
ax.add_feature(cfeature.STATES.with_scale(scale), linestyle=':', linewidth=0.8)
gl = ax.gridlines(
    draw_labels=True,
    linewidth=0.5,
    linestyle='--',
    color='gray',
    alpha=0.7,
)

lakes = NaturalEarthFeature(
    category='physical',
    name='lakes',
    scale='10m',
    edgecolor='black',
    facecolor='none',
    alpha=0.7,
)
ax.add_feature(lakes, linewidth=1, zorder=2)

gl.top_labels = False
gl.right_labels = False

ax.set_title(f"15km MPAS: {var.long_name}", pad=4, fontsize=10)

cbar = fig.colorbar(
    my_plot,
    ax=ax,
    orientation='vertical',
    shrink=0.6,
    pad=0.03,
)
label = rf"$\mathit{{{var.name}}}\ \left[\mathrm{{{var.units}}}\right]$"
cbar.set_label(label, labelpad=8, fontsize=12)

plt.show()

[philipc2]

@brianpm

Let me know if you have any feedback on this. I'm curious whether you think imshow() is an appropriate name here or if you have any other ideas.

[philipc2]

Rendering some data from the hackathon (HEALPix zoom=10) only takes about 5s on Derecho.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[kafitzgerald]

I'm a little worried that the API here might be confusing and not particularly intuitive for users familiar with conventions in the broader scientific Python ecosystem for a couple of reasons.

The first being that it deviates from other high level plotting APIs in the scientific Python ecosystem that use .plot() and .hvplot(). This is definitely beyond the scope of this PR, but adds some potential for confusion and complexity here.

And the second that imshow() here is pretty different from how it's used in Xarray and Matplotlib (e.g. there's a good bit going on with the resampling, Cartopy is used by default, etc.). Maybe a new name would be appropriate?

That said, I don't know that I have a great suggestion for what to do here. I suspect that something chained onto the .plot() accessor would be more intuitive, but that seems a bit complicated and potentially confusing given what's already present. Maybe implementing something under uxarray.plot.mpl.plot() for a high level Matplotlib plotting interface could work?

Edited to add: I should also say it's really exciting to see this and I think folks will very much appreciate having better support for Matplotlib and the performance improvements.

[philipc2]

Should be good for another set of reviews. I've made some reccomended changes after discussing with @erogluorhan , notably changing the signature to be to_raster().

Any feedback on the update notebook would be much appriciated, especially from @brianpm

[erogluorhan]

Thanks for putting this together! I like it overall; just see a few comments below please.

[philipc2]

@erogluorhan

I've added a "Conversion Methods" section in the API which can house our to_ methods and document the applications of them.

https://uxarray--1271.org.readthedocs.build/en/1271/api.html#conversion-methods

[erogluorhan]

@erogluorhan

I've added a "Conversion Methods" section in the API which can house our to_ methods and document the applications of them.

This sounds great and sure will help users find them much easier!

[erogluorhan]

Looks great; approving with a couple minor suggestions.

[kafitzgerald]

Looks good to me!