landlab.io.shapefile

Functions to read shapefiles and create a NetworkModelGrid.

read_shapefile(file, dbf=None, store_polyline_vertices=True, points_shapefile=None, points_dbf=None, link_fields=None, node_fields=None, link_field_conversion=None, node_field_conversion=None, link_field_dtype=None, node_field_dtype=None, threshold=0.0)[source]

Read shapefile and create a NetworkModelGrid.

There are a number of assumptions that are required about the shapefile.

  • The shapefile must be a polyline shapefile.

  • All polylines must be their own object (e.g. no multi-part polylines).

  • Polyline endpoints match perfectly.

You might notice that there is no write_shapefile function. If this is something you need for your work, please make a GitHub issue to start this process.

Parameters:

  • file (str or file-like) – File path or file-like of a valid polyline shapefile

  • dbf (file-like, optional) – If file is file-like, the dbf must also be passed.

  • store_polyline_vertices (bool, optional) – If True (default), store the vertices of the polylines in the at_link fields x_of_polyline and y_of_polyline.

  • points_shapefile (str or file-like) – File path or file-like of a valid point shapefile.

  • points_dbf (file-like, optional) – If file is file-like, the dbf must also be passed.

  • link_fields (list, optional) – List of polyline shapefile attributes to import as landlab at-link fields. Default is to import all.

  • node_fields (list, optional) – List of point shapefile attributes to import as landlab at-node fields. Default is to import all.

  • link_field_conversion (dict, optional) – Dictionary mapping polyline shapefile field names to desired at link field names. Default is no remapping.

  • node_field_conversion (dict, optional) – Dictionary mapping node shapefile field names to desired at node field names. Default is no remapping.

  • link_field_dtype (dict, optional) – Dictionary mapping node shapefile field names to desired dtype. Default is no change to dtype.

  • node_field_dtype (dict, optional) – Dictionary mapping node shapefile field names to desired dtype. Default is no change to dtype.

  • threshold (float, optional) – Maximum distance between a point in the point shapefile and a polyline junction in the polyline shapefile. Units are the same as in the shapefiles. Default is zero (requiring perfect overlap).

Returns:

grid – The network model grid will have nodes at the endpoints of the polylines, and links that connect these nodes. Any fields associated with the shapefile will be added as at-link fields. If a point shapefile is provided those values will be added as at-node fields.

Return type:

NetworkModelGrid instance

Examples

First, we make a simple shapefile

>>> from io import BytesIO
>>> import os

>>> import shapefile
>>> shp = BytesIO()
>>> shx = BytesIO()
>>> dbf = BytesIO()
>>> w = shapefile.Writer(shp=shp, shx=shx, dbf=dbf)
>>> w.shapeType = shapefile.POLYLINE
>>> w.field("spam", "N")
>>> w.line([[[5, 5], [10, 10]]])
>>> w.record(37)
>>> w.line([[[5, 0], [5, 5]]])
>>> w.record(100)
>>> w.line([[[5, 5], [0, 10]]])
>>> w.record(239)
>>> w.close()

Now create a NetworkModelGrid with read_shapefile:

>>> from landlab.io.shapefile import read_shapefile
>>> grid = read_shapefile(shp, dbf=dbf)
>>> grid.nodes
array([0, 1, 2, 3])
>>> grid.x_of_node
array([  5.,   5.,   0.,  10.])
>>> grid.y_of_node
array([  0.,   5.,  10.,  10.])
>>> grid.nodes_at_link
array([[0, 1],
       [2, 1],
       [1, 3]])
>>> assert "spam" in grid.at_link
>>> grid.at_link["spam"]
array([100, 239, 37])

Next lets also include a points file. First create both shapefiles.

>>> shp = BytesIO()
>>> shx = BytesIO()
>>> dbf = BytesIO()
>>> w = shapefile.Writer(shp=shp, shx=shx, dbf=dbf)
>>> w.shapeType = shapefile.POLYLINE
>>> w.field("spam", "N")
>>> w.line([[[5, 5], [10, 10]]])
>>> w.record(37)
>>> w.line([[[5, 0], [5, 5]]])
>>> w.record(100)
>>> w.line([[[5, 5], [0, 10]]])
>>> w.record(239)
>>> w.close()

>>> p_shp = BytesIO()
>>> p_shx = BytesIO()
>>> p_dbf = BytesIO()
>>> p_w = shapefile.Writer(shp=p_shp, shx=p_shx, dbf=p_dbf)
>>> p_w.shapeType = shapefile.POINT
>>> p_w.field("eggs", "N")
>>> p_w.point(5, 0)
>>> p_w.record(2)
>>> p_w.point(5, 5)
>>> p_w.record(4)
>>> p_w.point(0, 10)
>>> p_w.record(8)
>>> p_w.point(10, 10)
>>> p_w.record(6)
>>> p_w.close()

Now read in both files together.

>>> grid = read_shapefile(shp, dbf=dbf, points_shapefile=p_shp, points_dbf=p_dbf)
>>> grid.nodes
array([0, 1, 2, 3])
>>> grid.x_of_node
array([  5.,   5.,   0.,  10.])
>>> grid.y_of_node
array([  0.,   5.,  10.,  10.])
>>> grid.nodes_at_link
array([[0, 1],
       [2, 1],
       [1, 3]])
>>> assert "spam" in grid.at_link
>>> grid.at_link["spam"]
array([100, 239, 37])
>>> assert "eggs" in grid.at_node
>>> grid.at_node["eggs"]
array([2, 4, 8, 6])