Add pixel_ratio option to .to_raster()

[zmoon]

Overview

As discussed in #1353, this PR introduces a pixel_ratio setting to the UxDataArray.to_raster() method, allowing you to easily control the resolution of the rasterization when using Matplotlib+Cartopy without HoloViz.

One issue is that the get-faces-containing-points gets pretty slow as you increase pixel ratio. So I also added an option to pass in a pre-computed mapping (pixel_mapping). Example use-cases could be if you are making a lot of plots of the same scene, or overlaying multiple fields in one plot, or tweaking things and want a faster iterate cycle. But I wasn't sure what would be the best way to expose creating the mapping to the user.

Also added an example and a few other docs tweaks.

Expected Usage

import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import uxarray as ux

grid_path = "/path/to/grid.nc"
data_path = "/path/to/data.nc"

uxds = ux.open_dataset(grid_path, data_path)

fig, ax = plt.subplots(
    subplot_kw={"projection": ccrs.Robinson()}, figsize=(8, 4), constrained_layout=True,
)

ax.set_extent([-125, -67, 24.5, 50], crs=ccrs.PlateCarree())
raster = uxds["dataVar"].to_raster(ax=ax, pixel_ratio=2.0)

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

PR Checklist

General

• An issue is linked created and linked
• Add appropriate labels
• Filled out Overview and Expected Usage (if applicable) sections

Testing

• Adequate tests are created if there is new functionality
• Tests cover all possible logical paths in your function
• Tests are not too basic (such as simply calling a function and nothing else)

Documentation

• Docstrings have been added to all new functions
• Docstrings have updated with any function changes
• Internal functions have a preceding underscore (_)
• User functions have been added to docs/user_api/index.rst

Examples

• Any new notebook examples added to docs/examples/ folder
• Clear the output of all cells before committing
• New notebook files added to docs/examples.rst toctree
• New notebook files added to new entry in docs/gallery.yml with appropriate thumbnail photo in docs/_static/thumbnails/

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[zmoon]

One issue is that the get-faces-containing-points gets pretty slow as you increase pixel ratio.

A little non-rigorous benchmark with the global QU 480 example to demonstrate.

Details

import time

import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import pandas as pd

import uxarray as ux
from uxarray.plot.matplotlib import _get_raster_pixel_to_face_mapping as get_pixel_mapping

base_path = "test/meshfiles/mpas/QU/480/"
grid_path = base_path + "grid.nc"
data_path = base_path + "data.nc"

uxds = ux.open_dataset(grid_path, data_path)

fig, ax = plt.subplots(
    subplot_kw={"projection": ccrs.Robinson()}, figsize=(8, 4), constrained_layout=True,
)

ax.set_global()

results = []
for pixel_ratio in [0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 1, 2, 3, 4, 6, 8]:
    for _ in range(5):
        tic = time.perf_counter_ns()
        _ = get_pixel_mapping(uxds, ax=ax, pixel_ratio=pixel_ratio)
        toc = time.perf_counter_ns()
        results.append((pixel_ratio, toc - tic))

df = pd.DataFrame(results, columns=["pixel_ratio", "time_ns"])
df.to_csv("bench.csv", index=False)

[philipc2]

One issue is that the get-faces-containing-points gets pretty slow as you increase pixel ratio.

A little non-rigorous benchmark with the global QU 480 example to demonstrate.

Do you have the system specs for the benchmark run here?

[zmoon]

Yeah, I think I'd slightly prefer the kwarg, keep to_raster() just returning raster by default. I will give it a go in this PR then unless you object.

[philipc2]

I like the idea of returning the pixel_mapping through a kwarg.

[erogluorhan]

Sounds like we have a plan; looking forward to your edits, @zmoon !

[erogluorhan]

This looks great! Docs looks really good! I only had a few inline comments.

[erogluorhan]

@zmoon could you please update this from UXarray's main branch. Once we see all test pass after that, I'll approve it

[philipc2]

Looks great! Thank you for this contribution.

[erogluorhan]

This looks great; thanks a lot for the contribution!

[zmoon]

Thanks @philipc2 and @erogluorhan , sorry that this ballooned a bit from the initial simple pixel_ratio idea.

[erogluorhan]

No worries at all! I really like how it evolved!