deploy: c90df0d

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d6e862a27f70b9e0db6b688d41908016
+config: c53fb8e28eea5da8ab38c84a0a2bedc3
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/714f83d87afaca41fed5d7f2c5f887d4/vector_conversion.py

@@ -14,6 +14,7 @@
 
 import geopandas as gpd
 import matplotlib.pyplot as plt
+import pandas as pd
 
 import xugrid as xu
 
@@ -73,14 +74,27 @@
 # cells that are covered or touched by a polygon.
 #
 # In this example, we mark the faces that are covered by a certain province.
+#
+# We start by re-projecting the provinces dataset to the coordinate reference
+# system (CRS), from WGS84 (EPSG:4326) to the Dutch National coordinate system
+# (RD New, EPSG: 28992). Then, we give each province a unique id, which we
+# burn into the grid.
 
 provinces = xu.data.provinces_nl().to_crs(28992)
-provinces["value"] = range(len(provinces))
-burned = xu.burn_vector_geometry(provinces, uda, column="value")
+provinces["id"] = range(len(provinces))
+burned = xu.burn_vector_geometry(provinces, uda, column="id")
 burned.ugrid.plot()
 
 # %%
-# This is a convenient way to create masks and such:
+# This makes it very easy to classify and group data. Let's say
+# we want to compute the average surface elevation per province:
+
+burned = xu.burn_vector_geometry(provinces, uda, column="id")
+uda.groupby(burned).mean()
+
+
+# %%
+# This is a convenient way to create masks for specific regions:
 
 utrecht = provinces[provinces["name"] == "Utrecht"]
 burned = xu.burn_vector_geometry(utrecht, uda)
@@ -107,15 +121,21 @@
 ax.set_xlim(xmin, xmax)
 ax.set_ylim(ymin, ymax)
 
+# %%
+# We can also use such "masks" to e.g. modify specific parts of the grid data:
+
+modified = (uda + 50.0).where(burned == 1, other=uda)
+modified.ugrid.plot(vmin=-20, vmax=90, cmap="terrain")
+
 # %%
 # Note that ``all_touched=True`` is less suitable when differently valued
 # polygons are present that share borders. While the centroid of a face is
 # contained by only a single polygon, the area of the polygon may be located
 # in more than one polygon. In this case, the results of each polygon will
 # overwrite each other.
 
-by_centroid = xu.burn_vector_geometry(provinces, uda, column="value")
-by_touch = xu.burn_vector_geometry(provinces, uda, column="value", all_touched=True)
+by_centroid = xu.burn_vector_geometry(provinces, uda, column="id")
+by_touch = xu.burn_vector_geometry(provinces, uda, column="id", all_touched=True)
 
 fig, axes = plt.subplots(ncols=2, figsize=(10, 5))
 by_centroid.ugrid.plot(ax=axes[0], add_colorbar=False)
@@ -145,6 +165,24 @@
 ax.set_xlim(xmin, xmax)
 ax.set_ylim(ymin, ymax)
 
+# %%
+# We can also burn points.
+
+province_centroids = gpd.GeoDataFrame(geometry=provinces.centroid)
+burned = xu.burn_vector_geometry(province_centroids, uda)
+
+fig, ax = plt.subplots()
+burned.ugrid.plot(ax=ax)
+provinces.plot(ax=ax, edgecolor="red", facecolor="none")
+
+# %%
+# Finally, it's also possible to combine multiple geometry types in a single
+# burn operation.
+
+combined = pd.concat([lines, province_centroids])
+burned = xu.burn_vector_geometry(combined, uda)
+burned.ugrid.plot()
+
 # %%
 # Polygonizing
 # ------------

_downloads/be05b5a234b2a85e0ca223679f6e137e/vector_conversion.ipynb

@@ -15,7 +15,7 @@
       },
       "outputs": [],
       "source": [
-        "import geopandas as gpd\nimport matplotlib.pyplot as plt\n\nimport xugrid as xu"
+        "import geopandas as gpd\nimport matplotlib.pyplot as plt\nimport pandas as pd\n\nimport xugrid as xu"
       ]
     },
     {
@@ -76,7 +76,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "<div class=\"alert alert-info\"><h4>Note</h4><p>Not every GeoDataFrame can be converted to a ``xugrid`` representation!\n  While an unstructured grid topology is generally always a valid collection\n  of polygon geometries, not every collection of polygon geometries is a\n  valid grid: polygons should be convex and non-overlapping to create a valid\n  unstructured grid.\n\n  Secondly, each polygon fully owns its vertices (nodes), while the face of a\n  UGRID topology shares its nodes with its neighbors. All the vertices of the\n  polygons must therefore be exactly snapped together to form a connected\n  mesh.\n\n  Hence, the ``.from_geodataframe()`` is primarily meant to create ``xugrid``\n  objects from data that were originally created as triangulation or\n  unstructured grid, but that were converted to vector geometry form.</p></div>\n\n## \"Rasterizing\", or \"burning\" vector geometries\n\nRasterizing is a common operation when working with raster and vector data.\nWhile we cannot name the operation \"rasterizing\" when we're dealing with\nunstructured grids, there is a clearly equivalent operation where we mark\ncells that are covered or touched by a polygon.\n\nIn this example, we mark the faces that are covered by a certain province.\n\n"
+        "<div class=\"alert alert-info\"><h4>Note</h4><p>Not every GeoDataFrame can be converted to a ``xugrid`` representation!\n  While an unstructured grid topology is generally always a valid collection\n  of polygon geometries, not every collection of polygon geometries is a\n  valid grid: polygons should be convex and non-overlapping to create a valid\n  unstructured grid.\n\n  Secondly, each polygon fully owns its vertices (nodes), while the face of a\n  UGRID topology shares its nodes with its neighbors. All the vertices of the\n  polygons must therefore be exactly snapped together to form a connected\n  mesh.\n\n  Hence, the ``.from_geodataframe()`` is primarily meant to create ``xugrid``\n  objects from data that were originally created as triangulation or\n  unstructured grid, but that were converted to vector geometry form.</p></div>\n\n## \"Rasterizing\", or \"burning\" vector geometries\n\nRasterizing is a common operation when working with raster and vector data.\nWhile we cannot name the operation \"rasterizing\" when we're dealing with\nunstructured grids, there is a clearly equivalent operation where we mark\ncells that are covered or touched by a polygon.\n\nIn this example, we mark the faces that are covered by a certain province.\n\nWe start by re-projecting the provinces dataset to the coordinate reference\nsystem (CRS), from WGS84 (EPSG:4326) to the Dutch National coordinate system\n(RD New, EPSG: 28992). Then, we give each province a unique id, which we\nburn into the grid.\n\n"
       ]
     },
     {
@@ -87,14 +87,32 @@
       },
       "outputs": [],
       "source": [
-        "provinces = xu.data.provinces_nl().to_crs(28992)\nprovinces[\"value\"] = range(len(provinces))\nburned = xu.burn_vector_geometry(provinces, uda, column=\"value\")\nburned.ugrid.plot()"
+        "provinces = xu.data.provinces_nl().to_crs(28992)\nprovinces[\"id\"] = range(len(provinces))\nburned = xu.burn_vector_geometry(provinces, uda, column=\"id\")\nburned.ugrid.plot()"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "This is a convenient way to create masks and such:\n\n"
+        "This makes it very easy to classify and group data. Let's say\nwe want to compute the average surface elevation per province:\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "burned = xu.burn_vector_geometry(provinces, uda, column=\"id\")\nuda.groupby(burned).mean()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "This is a convenient way to create masks for specific regions:\n\n"
       ]
     },
     {
@@ -126,6 +144,24 @@
         "burned = xu.burn_vector_geometry(utrecht, uda, all_touched=True)\n\nfig, ax = plt.subplots()\nburned.ugrid.plot(ax=ax)\nburned.ugrid.plot.line(ax=ax, edgecolor=\"black\", linewidth=0.5)\nutrecht.plot(ax=ax, edgecolor=\"red\", facecolor=\"none\", linewidth=1.5)\nax.set_xlim(xmin, xmax)\nax.set_ylim(ymin, ymax)"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can also use such \"masks\" to e.g. modify specific parts of the grid data:\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "modified = (uda + 50.0).where(burned == 1, other=uda)\nmodified.ugrid.plot(vmin=-20, vmax=90, cmap=\"terrain\")"
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {},
@@ -141,7 +177,7 @@
       },
       "outputs": [],
       "source": [
-        "by_centroid = xu.burn_vector_geometry(provinces, uda, column=\"value\")\nby_touch = xu.burn_vector_geometry(provinces, uda, column=\"value\", all_touched=True)\n\nfig, axes = plt.subplots(ncols=2, figsize=(10, 5))\nby_centroid.ugrid.plot(ax=axes[0], add_colorbar=False)\nby_touch.ugrid.plot(ax=axes[1], add_colorbar=False)\n\nfor ax, title in zip(axes, (\"centroid\", \"all touched\")):\n    burned.ugrid.plot.line(ax=ax, edgecolor=\"black\", linewidth=0.5)\n    utrecht.plot(ax=ax, edgecolor=\"red\", facecolor=\"none\", linewidth=1.5)\n    ax.set_xlim(xmin, xmax)\n    ax.set_ylim(ymin, ymax)\n    ax.set_title(title)"
+        "by_centroid = xu.burn_vector_geometry(provinces, uda, column=\"id\")\nby_touch = xu.burn_vector_geometry(provinces, uda, column=\"id\", all_touched=True)\n\nfig, axes = plt.subplots(ncols=2, figsize=(10, 5))\nby_centroid.ugrid.plot(ax=axes[0], add_colorbar=False)\nby_touch.ugrid.plot(ax=axes[1], add_colorbar=False)\n\nfor ax, title in zip(axes, (\"centroid\", \"all touched\")):\n    burned.ugrid.plot.line(ax=ax, edgecolor=\"black\", linewidth=0.5)\n    utrecht.plot(ax=ax, edgecolor=\"red\", facecolor=\"none\", linewidth=1.5)\n    ax.set_xlim(xmin, xmax)\n    ax.set_ylim(ymin, ymax)\n    ax.set_title(title)"
       ]
     },
     {
@@ -162,6 +198,42 @@
         "lines = gpd.GeoDataFrame(geometry=provinces.exterior)\nburned = xu.burn_vector_geometry(lines, uda)\n\nfig, ax = plt.subplots()\nburned.ugrid.plot(ax=ax)\nburned.ugrid.plot.line(ax=ax, edgecolor=\"black\", linewidth=0.5)\nprovinces.plot(ax=ax, edgecolor=\"red\", facecolor=\"none\", linewidth=1.5)\nax.set_xlim(xmin, xmax)\nax.set_ylim(ymin, ymax)"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can also burn points.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "province_centroids = gpd.GeoDataFrame(geometry=provinces.centroid)\nburned = xu.burn_vector_geometry(province_centroids, uda)\n\nfig, ax = plt.subplots()\nburned.ugrid.plot(ax=ax)\nprovinces.plot(ax=ax, edgecolor=\"red\", facecolor=\"none\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, it's also possible to combine multiple geometry types in a single\nburn operation.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "combined = pd.concat([lines, province_centroids])\nburned = xu.burn_vector_geometry(combined, uda)\nburned.ugrid.plot()"
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {},

_modules/xugrid/ugrid/burn.html

@@ -416,6 +416,7 @@ <h1>Source code for xugrid.ugrid.burn</h1><div class="highlight"><pre>
 <span class="sd">    If the area created by p, a, b is tiny AND p is within the bounds of a and</span>
 <span class="sd">    b, the point lies very close to the edge.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="c1"># Already in numba_celltree, unreleased.</span>
     <span class="n">dx</span> <span class="o">=</span> <span class="n">b</span><span class="o">.</span><span class="n">x</span> <span class="o">-</span> <span class="n">a</span><span class="o">.</span><span class="n">x</span>
     <span class="n">dy</span> <span class="o">=</span> <span class="n">b</span><span class="o">.</span><span class="n">y</span> <span class="o">-</span> <span class="n">a</span><span class="o">.</span><span class="n">y</span>
     <span class="k">if</span> <span class="nb">abs</span><span class="p">(</span><span class="n">dx</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="nb">abs</span><span class="p">(</span><span class="n">dy</span><span class="p">):</span>
@@ -430,6 +431,7 @@ <h1>Source code for xugrid.ugrid.burn</h1><div class="highlight"><pre>
 
 <span class="nd">@nb</span><span class="o">.</span><span class="n">njit</span><span class="p">(</span><span class="n">inline</span><span class="o">=</span><span class="s2">&quot;always&quot;</span><span class="p">)</span>
 <span class="k">def</span> <span class="nf">point_in_triangle</span><span class="p">(</span><span class="n">p</span><span class="p">:</span> <span class="n">Point</span><span class="p">,</span> <span class="n">t</span><span class="p">:</span> <span class="n">Triangle</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
+    <span class="c1"># TODO: move this into numba_celltree instead?</span>
     <span class="n">ap</span> <span class="o">=</span> <span class="n">to_vector</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span>
     <span class="n">bp</span> <span class="o">=</span> <span class="n">to_vector</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">b</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span>
     <span class="n">cp</span> <span class="o">=</span> <span class="n">to_vector</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span>
@@ -600,7 +602,7 @@ <h1>Source code for xugrid.ugrid.burn</h1><div class="highlight"><pre>
 
 <div class="viewcode-block" id="burn_vector_geometry"><a class="viewcode-back" href="../../../api/xugrid.burn_vector_geometry.html#xugrid.burn_vector_geometry">[docs]</a><span class="k">def</span> <span class="nf">burn_vector_geometry</span><span class="p">(</span>
     <span class="n">gdf</span><span class="p">:</span> <span class="s2">&quot;geopandas.GeoDataframe&quot;</span><span class="p">,</span>  <span class="c1"># type: ignore # noqa</span>
-    <span class="n">like</span><span class="p">:</span> <span class="s2">&quot;xugrid.Ugrid2d&quot;</span><span class="p">,</span>
+    <span class="n">like</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="s2">&quot;xugrid.Ugrid2d&quot;</span><span class="p">,</span> <span class="s2">&quot;xugrid.UgridDataArray&quot;</span><span class="p">,</span> <span class="s2">&quot;xugrid.UgridDataset&quot;</span><span class="p">],</span>
     <span class="n">column</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">fill</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">float</span><span class="p">]</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span><span class="p">,</span>
     <span class="n">all_touched</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
@@ -614,9 +616,12 @@ <h1>Source code for xugrid.ugrid.burn</h1><div class="highlight"><pre>
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
 <span class="sd">    gdf: geopandas.GeoDataFrame</span>
+<span class="sd">        Polygons, points, and/or lines to be burned into the grid.</span>
 <span class="sd">    like: UgridDataArray, UgridDataset, or Ugrid2d</span>
+<span class="sd">        Grid to burn the vector data into.</span>
 <span class="sd">    column: str</span>
-<span class="sd">        Column name of geodataframe to burn into mesh</span>
+<span class="sd">        Name of the geodataframe column of which to the values to burn into</span>
+<span class="sd">        grid.</span>
 <span class="sd">    fill: int, float, optional, default value ``np.nan``.</span>
 <span class="sd">        Fill value for nodata areas.</span>
 <span class="sd">    all_touched: bool, optional, default value ``False``.</span>

_sources/examples-dev/sg_execution_times.rst.txt

@@ -6,8 +6,8 @@
 
 Computation times
 =================
-**00:01.998** total execution time for **examples-dev** files:
+**00:01.996** total execution time for **examples-dev** files:
 
 +----------------------------------------------------------+-----------+--------+
-| :ref:`sphx_glr_examples-dev_voronoi.py` (``voronoi.py``) | 00:01.998 | 0.0 MB |
+| :ref:`sphx_glr_examples-dev_voronoi.py` (``voronoi.py``) | 00:01.996 | 0.0 MB |
 +----------------------------------------------------------+-----------+--------+

_sources/examples-dev/voronoi.rst.txt

@@ -630,7 +630,7 @@ The figure shows:
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** ( 0 minutes  1.998 seconds)
+   **Total running time of the script:** ( 0 minutes  1.996 seconds)
 
 
 .. _sphx_glr_download_examples-dev_voronoi.py:

_sources/examples/connectivity.rst.txt

@@ -129,7 +129,7 @@ By default, the border value for binary erosion is set to ``False`` (equal to
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f985f52fd90>
+    <matplotlib.collections.PolyCollection object at 0x7f34787d46a0>
 
 
 
@@ -165,7 +165,7 @@ start by setting a single value in the center of the grid to ``True``.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f9870e49100>
+    <matplotlib.collections.PolyCollection object at 0x7f3469f904c0>
 
 
 
@@ -200,7 +200,7 @@ alternative border value:
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f98702e58b0>
+    <matplotlib.collections.PolyCollection object at 0x7f3468cd4eb0>
 
 
 
@@ -238,7 +238,7 @@ analyse connected parts of the mesh.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f987089d0d0>
+    <matplotlib.collections.PolyCollection object at 0x7f346a66f820>
 
 
 
@@ -272,7 +272,7 @@ Tesselation.
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f98702536d0>
+    <matplotlib.collections.LineCollection object at 0x7f346a9351c0>
 
 
 
@@ -316,7 +316,7 @@ the original.
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f9871e82790>
+    <matplotlib.collections.LineCollection object at 0x7f3468cee190>
 
 
 
@@ -355,7 +355,7 @@ We can break down one of the Voronoi tesselations from above into triangles:
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f987054dd30>
+    <matplotlib.collections.LineCollection object at 0x7f3469cc1400>
 
 
 
@@ -409,7 +409,7 @@ the upper and lower parts:
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f987074e490>
+    <matplotlib.collections.LineCollection object at 0x7f3469c9d460>
 
 
 
@@ -439,7 +439,7 @@ We can now use Laplace interpolation to fill the gaps in the grid.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f987313ec40>
+    <matplotlib.collections.PolyCollection object at 0x7f346915ec10>
 
 
 
@@ -480,7 +480,7 @@ To illustrate, let's take a look at the connectivity matrix of the Xoxo grid.
  .. code-block:: none
 
 
-    <matplotlib.image.AxesImage object at 0x7f98734300a0>
+    <matplotlib.image.AxesImage object at 0x7f346a6d3400>
 
 
 
@@ -516,14 +516,14 @@ locality:
  .. code-block:: none
 
 
-    <matplotlib.image.AxesImage object at 0x7f9870a7e5b0>
+    <matplotlib.image.AxesImage object at 0x7f346a8fd550>
 
 
 
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** ( 0 minutes  2.244 seconds)
+   **Total running time of the script:** ( 0 minutes  2.019 seconds)
 
 
 .. _sphx_glr_download_examples_connectivity.py: