Keep seam faces in polygon plots

docs/user-guide/mpl.ipynb

@@ -384,7 +384,7 @@
    "metadata": {},
    "source": [
     "```{important}\n",
-    "By default, `periodic_elements` is set to `\"exclude\"`. \n",
+    "`to_polycollection()` defaults to `periodic_elements=\"exclude\"`; use `\"split\"` to preserve antimeridian faces. \n",
     "```\n",
     "\n",
     "To reduce the number of polygons in the collection, you can [subset](./subset) before converting."

docs/user-guide/plotting.ipynb

@@ -260,8 +260,8 @@
     "* ``periodic_elements='split'``: Periodic polygons are split along the antimeridian\n",
     "* ``periodic_elements='ignore'``: Periodic polygons are left uncorrected.\n",
     "\n",
-    "```{warning}\n",
-    "It is suggested to keep ``periodic_elements='exclude'`` (default value) when working with moderatly large datasets, as there is a significant overhead needed correct the antimeridian faces.\n",
+    "```{note}\n",
+    "Shaded polygon plots default to ``periodic_elements='split'`` so seam-crossing faces are preserved. For very large grids, ``periodic_elements='exclude'`` can be faster if dropping antimeridian faces is acceptable.\n",
     "```\n"
    ]
   },
@@ -294,10 +294,8 @@
    "source": [
     "(\n",
     "    uxds_mpas[\"bottomDepth\"]\n",
-    "    .plot(\n",
-    "        cmap=\"Blues\",\n",
-    "    )\n",
-    "    .opts(width=700, height=350, title=\"Default Plot (Excluding Periodic Elements)\")\n",
+    "    .plot(periodic_elements=\"exclude\", cmap=\"Blues\", width=700, height=350)\n",
+    "    .opts(title=\"Exclude Periodic Elements\")\n",
     "    + uxds_mpas[\"bottomDepth\"]\n",
     "    .plot(periodic_elements=\"split\", cmap=\"Blues\", width=700, height=350)\n",
     "    .opts(title=\"Include Periodic Elements (Split)\")\n",

test/core/test_dataarray.py

@@ -77,6 +77,18 @@ def test_to_polycollection(gridpath, datasetpath):
     assert len(pc_geoflow_grid._paths) == uxds_geoflow.uxgrid.n_face
 
 
+def test_plot_polygons_preserves_antimeridian_faces(gridpath, datasetpath):
+    uxds = ux.open_dataset(
+        gridpath("scrip", "ne30pg2", "grid.nc"),
+        datasetpath("scrip", "ne30pg2", "data.nc"),
+    )
+
+    gdf = uxds["RELHUM"].isel(lev=0).to_geodataframe(periodic_elements="split")
+
+    assert gdf.shape == (uxds.uxgrid.n_face, 2)
+    assert len(uxds.uxgrid.antimeridian_face_indices) == 120
+
+
 def test_geodataframe_caching(gridpath, datasetpath):
     uxds = ux.open_dataset(
         gridpath("ugrid", "outCSne30", "outCSne30.ug"),

uxarray/plot/accessor.py

@@ -368,7 +368,7 @@ def __getattr__(self, name: str) -> Any:
 
     def polygons(
         self,
-        periodic_elements: str | None = "exclude",
+        periodic_elements: str | None = "split",
         backend: str | None = None,
         engine: str | None = "spatialpandas",
         rasterize: bool | None = True,
@@ -388,11 +388,11 @@ def polygons(
 
         Parameters
         ----------
-        periodic_elements : str, optional, default="exclude"
-            Specifies whether to include or exclude periodic elements in the grid.
+        periodic_elements : str, optional, default="split"
+            Specifies whether to split, include, or exclude periodic elements in the grid.
             Options are:
-            - "exclude": Exclude periodic elements,
             - "split": Split periodic elements.
+            - "exclude": Exclude periodic elements,
             - "ignore": Include periodic elements without any corrections
         backend : str or None, optional
             Plotting backend to use. One of ['matplotlib', 'bokeh']. Equivalent to running holoviews.extension(backend)