Update `to_polycollection()`, `to_linecollection` and create Matplotlib Visualization Guide

[philipc2]

Closes #430, #839

[review-notebook-app[bot]]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[github-actions[bot]]

ASV Benchmarking

Benchmark Comparison Results

Benchmarks that have improved: | Change | Before [b986ef35] | After [94c14710] | Ratio | Benchmark (Parameter) | |----------|----------------------|---------------------|---------|--------------------------------------------------------------------------------------| | - | 388M | 347M | 0.9 | mpas_ocean.Integrate.peakmem_integrate('480km') | | - | 11.5±0.02s | 349±1ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'exclude') | | - | 11.4±0.07s | 347±1ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'include') | | - | 11.5±0.02s | 353±7ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'split') | | - | 737±6ms | 21.8±0.2ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'exclude') | | - | 729±4ms | 22.1±0.2ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'include') | | - | 730±4ms | 22.1±0.3ms | 0.03 | mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'split') | Benchmarks that have stayed the same: | Change | Before [b986ef35] | After [94c14710] | Ratio | Benchmark (Parameter) | |----------|----------------------|---------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------| | | 242M | 242M | 1 | face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc')) | | | 303M | 303M | 1 | face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc')) | | | 321M | 308M | 0.96 | face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc')) | | | 318M | 304M | 0.95 | face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc')) | | | 14.1±0.05s | 13.9±0.03s | 0.99 | face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc')) | | | 2.06±0s | 2.08±0.01s | 1.01 | face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc')) | | | 19.6±0.1s | 19.6±0.1s | 1 | face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc')) | | | 74.0±0.8ms | 73.3±0.8ms | 0.99 | face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc')) | | | 1.64±0.01s | 1.67±0.03s | 1.02 | import.Imports.timeraw_import_uxarray | | | 373M | 393M | 1.05 | mpas_ocean.GeoDataFrame.peakmem_to_geodataframe('120km', False) | | | 352M | 382M | 1.09 | mpas_ocean.GeoDataFrame.peakmem_to_geodataframe('120km', True) | | | 323M | 355M | 1.1 | mpas_ocean.GeoDataFrame.peakmem_to_geodataframe('480km', False) | | | 322M | 354M | 1.1 | mpas_ocean.GeoDataFrame.peakmem_to_geodataframe('480km', True) | | | 1.18±0s | 1.21±0s | 1.03 | mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', False) | | | 56.0±0.8ms | 56.7±0.3ms | 1.01 | mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', True) | | | 95.5±1ms | 94.4±0.3ms | 0.99 | mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', False) | | | 5.32±0.09ms | 5.31±0.1ms | 1 | mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', True) | | | 258M | 259M | 1 | mpas_ocean.Gradient.peakmem_gradient('120km') | | | 236M | 236M | 1 | mpas_ocean.Gradient.peakmem_gradient('480km') | | | 2.71±0.03ms | 2.67±0.02ms | 0.99 | mpas_ocean.Gradient.time_gradient('120km') | | | 286±3μs | 284±2μs | 0.99 | mpas_ocean.Gradient.time_gradient('480km') | | | 175±0.8ms | 177±2ms | 1.01 | mpas_ocean.Integrate.time_integrate('120km') | | | 11.9±0.08ms | 12.0±0.05ms | 1.01 | mpas_ocean.Integrate.time_integrate('480km') | | | 234M | 232M | 0.99 | quad_hexagon.QuadHexagon.peakmem_open_dataset | | | 231M | 231M | 1 | quad_hexagon.QuadHexagon.peakmem_open_grid | | | 6.64±0.06ms | 6.73±0.1ms | 1.01 | quad_hexagon.QuadHexagon.time_open_dataset | | | 5.63±0.02ms | 5.68±0.03ms | 1.01 | quad_hexagon.QuadHexagon.time_open_grid | Benchmarks that have got worse: | Change | Before [b986ef35] | After [94c14710] | Ratio | Benchmark (Parameter) | |----------|----------------------|---------------------|---------|--------------------------------------------------------------------| | + | 5.85±0.08μs | 1.73±0.02ms | 295.81 | mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('120km') | | + | 5.38±0.05μs | 497±10μs | 92.32 | mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('480km') | | + | 323M | 364M | 1.13 | mpas_ocean.Integrate.peakmem_integrate('120km') |