.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "user-guide\02-vector-data.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_user-guide_02-vector-data.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_user-guide_02-vector-data.py:


Vector data and Geopandas
=========================

Geospatial data primarily comes in two forms: raster data and vector data.
This guide focuses on the latter.

Typical examples of file formats containing vector data are:

* ESRI shapefile
* GeoJSON
* Geopackage

Vector data consist of vertices (corner points), optionally connected by paths.
The three primary categories of vector data are:

* Points
* Lines
* Polygons

In groundwater modeling, typical examples of each are:

* Pumping wells, observation wells, boreholes
* Canals, ditches, waterways
* Lakes, administrative boundaries, land use

These data consist of geospatial coordinates, indicating the location in space
and a number of attributes: for a canal, this could be parameters like its
width, depth, and water level. In GIS software like QGIS, the geometry is
visible in the map view, and the attributes can inspected via e.g. the
attribute table.

In Python, such data can be represented by a
:py:class:`geopandas.GeoDataFrame`. Essentially, geopandas is a pandas
DataFrame to store tabular data (the attribute table), and adds a geometry
column to store the geospatial coordinates.

.. GENERATED FROM PYTHON SOURCE LINES 40-49

.. code-block:: Python

    import geopandas as gpd
    import numpy as np

    import imod

    tempdir = imod.util.temporary_directory()
    gdf = imod.data.lakes_shp(tempdir / "lake")
    gdf.iloc[:5, -3:]  # first 5 rows, last 3 columns






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>SHAPE_Leng</th>
          <th>SHAPE_Area</th>
          <th>geometry</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>4689.155578</td>
          <td>511471.386406</td>
          <td>POLYGON ((108774.371 466627.43, 108774.375 466...</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2050.843018</td>
          <td>86091.854890</td>
          <td>POLYGON ((115938.892 463013.165, 115926.865 46...</td>
        </tr>
        <tr>
          <th>2</th>
          <td>5023.190894</td>
          <td>625149.040467</td>
          <td>POLYGON ((111380.977 448065.855, 111378.115 44...</td>
        </tr>
        <tr>
          <th>3</th>
          <td>3724.550747</td>
          <td>467233.192689</td>
          <td>POLYGON ((117298.904 478782.595, 117297.744 47...</td>
        </tr>
        <tr>
          <th>4</th>
          <td>6834.063594</td>
          <td>809445.407846</td>
          <td>POLYGON ((112096.692 450851.187, 112098.812 45...</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 50-52

This geodataframe contains all the data from the shapefile. Note the geometry
column. The geometry can be plotted:

.. GENERATED FROM PYTHON SOURCE LINES 52-55

.. code-block:: Python


    gdf.plot()




.. image-sg:: /user-guide/images/sphx_glr_02-vector-data_001.png
   :alt: 02 vector data
   :srcset: /user-guide/images/sphx_glr_02-vector-data_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: >



.. GENERATED FROM PYTHON SOURCE LINES 56-58

A GeoDataFrame of points can also be easily generated from pairs of x and y
coordinates.

.. GENERATED FROM PYTHON SOURCE LINES 58-67

.. code-block:: Python


    x = np.arange(90_000.0, 120_000.0, 1000.0)
    y = np.arange(450_000.0, 480_000.0, 1000.0)

    geometry = gpd.points_from_xy(x, y)
    points_gdf = gpd.GeoDataFrame(geometry=geometry)

    points_gdf.plot()




.. image-sg:: /user-guide/images/sphx_glr_02-vector-data_002.png
   :alt: 02 vector data
   :srcset: /user-guide/images/sphx_glr_02-vector-data_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: >



.. GENERATED FROM PYTHON SOURCE LINES 68-69

An important feature of every geometry is its geometry type:

.. GENERATED FROM PYTHON SOURCE LINES 69-72

.. code-block:: Python


    gdf.geom_type





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0     Polygon
    1     Polygon
    2     Polygon
    3     Polygon
    4     Polygon
           ...   
    72    Polygon
    73    Polygon
    74    Polygon
    75    Polygon
    76    Polygon
    Length: 77, dtype: object



.. GENERATED FROM PYTHON SOURCE LINES 73-74

As expected, the points are of the type ... Point:

.. GENERATED FROM PYTHON SOURCE LINES 74-77

.. code-block:: Python


    points_gdf.geom_type





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0     Point
    1     Point
    2     Point
    3     Point
    4     Point
    5     Point
    6     Point
    7     Point
    8     Point
    9     Point
    10    Point
    11    Point
    12    Point
    13    Point
    14    Point
    15    Point
    16    Point
    17    Point
    18    Point
    19    Point
    20    Point
    21    Point
    22    Point
    23    Point
    24    Point
    25    Point
    26    Point
    27    Point
    28    Point
    29    Point
    dtype: object



.. GENERATED FROM PYTHON SOURCE LINES 78-84

Input and output
----------------

Geopandas supports many vector file formats. It wraps `fiona`_, which in turns
wraps `OGR`_, which is a part of `GDAL`_. For example, the lake polygons above
are loaded from an ESRI Shapefile:

.. GENERATED FROM PYTHON SOURCE LINES 84-88

.. code-block:: Python


    filenames = [path.name for path in (tempdir / "lake").iterdir()]
    print("\n".join(filenames))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    lakes.cpg
    lakes.dbf
    lakes.prj
    lakes.shp
    lakes.shx




.. GENERATED FROM PYTHON SOURCE LINES 89-91

They can be easily stored into more modern formats as well, such as
`GeoPackage`_:

.. GENERATED FROM PYTHON SOURCE LINES 91-96

.. code-block:: Python


    points_gdf.to_file(tempdir / "points.gpkg")
    filenames = [path.name for path in tempdir.iterdir()]
    print("\n".join(filenames))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    C:\buildagent\work\4b9080cbb3354582\imod-python\.pixi\envs\default\Lib\site-packages\pyogrio\geopandas.py:662: UserWarning: 'crs' was not provided.  The output dataset will not have projection information defined and may not be usable in other systems.
      write(
    lake
    points.gpkg




.. GENERATED FROM PYTHON SOURCE LINES 97-98

... and back:

.. GENERATED FROM PYTHON SOURCE LINES 98-102

.. code-block:: Python


    back = gpd.read_file(tempdir / "points.gpkg")
    back






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>geometry</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>POINT (90000 450000)</td>
        </tr>
        <tr>
          <th>1</th>
          <td>POINT (91000 451000)</td>
        </tr>
        <tr>
          <th>2</th>
          <td>POINT (92000 452000)</td>
        </tr>
        <tr>
          <th>3</th>
          <td>POINT (93000 453000)</td>
        </tr>
        <tr>
          <th>4</th>
          <td>POINT (94000 454000)</td>
        </tr>
        <tr>
          <th>5</th>
          <td>POINT (95000 455000)</td>
        </tr>
        <tr>
          <th>6</th>
          <td>POINT (96000 456000)</td>
        </tr>
        <tr>
          <th>7</th>
          <td>POINT (97000 457000)</td>
        </tr>
        <tr>
          <th>8</th>
          <td>POINT (98000 458000)</td>
        </tr>
        <tr>
          <th>9</th>
          <td>POINT (99000 459000)</td>
        </tr>
        <tr>
          <th>10</th>
          <td>POINT (100000 460000)</td>
        </tr>
        <tr>
          <th>11</th>
          <td>POINT (101000 461000)</td>
        </tr>
        <tr>
          <th>12</th>
          <td>POINT (102000 462000)</td>
        </tr>
        <tr>
          <th>13</th>
          <td>POINT (103000 463000)</td>
        </tr>
        <tr>
          <th>14</th>
          <td>POINT (104000 464000)</td>
        </tr>
        <tr>
          <th>15</th>
          <td>POINT (105000 465000)</td>
        </tr>
        <tr>
          <th>16</th>
          <td>POINT (106000 466000)</td>
        </tr>
        <tr>
          <th>17</th>
          <td>POINT (107000 467000)</td>
        </tr>
        <tr>
          <th>18</th>
          <td>POINT (108000 468000)</td>
        </tr>
        <tr>
          <th>19</th>
          <td>POINT (109000 469000)</td>
        </tr>
        <tr>
          <th>20</th>
          <td>POINT (110000 470000)</td>
        </tr>
        <tr>
          <th>21</th>
          <td>POINT (111000 471000)</td>
        </tr>
        <tr>
          <th>22</th>
          <td>POINT (112000 472000)</td>
        </tr>
        <tr>
          <th>23</th>
          <td>POINT (113000 473000)</td>
        </tr>
        <tr>
          <th>24</th>
          <td>POINT (114000 474000)</td>
        </tr>
        <tr>
          <th>25</th>
          <td>POINT (115000 475000)</td>
        </tr>
        <tr>
          <th>26</th>
          <td>POINT (116000 476000)</td>
        </tr>
        <tr>
          <th>27</th>
          <td>POINT (117000 477000)</td>
        </tr>
        <tr>
          <th>28</th>
          <td>POINT (118000 478000)</td>
        </tr>
        <tr>
          <th>29</th>
          <td>POINT (119000 479000)</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 103-118

Conversion to raster
--------------------

From the perspective of MODFLOW groundwater modeling, we are often interested
in the properties of cells in specific polygons or zones. Refer to the
examples or the API reference for ``imod.prepare``.

GeoPandas provides a full suite of vector based GIS operations, such as
intersections, spatial joins, or plotting.

.. _fiona: https://fiona.readthedocs.io/en/latest/manual.html
.. _OGR: https://gdal.org/faq.html#what-is-this-ogr-stuff
.. _GDAL: https://gdal.org/
.. _GeoPackage: https://www.geopackage.org/
.. _GeoPandas User Guide: https://geopandas.org/en/stable/docs/user_guide.html


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 1.957 seconds)


.. _sphx_glr_download_user-guide_02-vector-data.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 02-vector-data.ipynb <02-vector-data.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 02-vector-data.py <02-vector-data.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 02-vector-data.zip <02-vector-data.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_