The Lines Module

class sfrmaker.lines.Lines(df=None, asum_units='km', width_units='meters', elevation_units='meters', crs=None, prjfile=None, **kwargs)

Bases: object

Class for working with linestring feature input.

Parameters:

dfDataFrame or GeoDataFrame

Dataframe with linestring features (flowlines) and attribute information. Column descriptions:

id	Sequential integers representing each flowline
toid	Integers representing downstream routing connections
arbolate_sum_column2	(optional) Arbolate sum at the end of each flowline
width1_column	(optional) Stream channel width at the start of each flowline
width2_column	(optional) Stream channel width at the end of each flowline
up_elevation_column	(optional) Streambed elevation at the start of each flowline
dn_elevation_column	(optional) Streambed elevation at the end of each flowline
name_column	(optional) Flowline name
geometry	shapely LineString objects for each feature

asum_unitsstr, optional

Length units for values in arbolate_sum_column2; by default ‘km’.

width_unitsstr, optional

Length units for values in width1_column and width2_column; by default ‘meters’.

elevation_unitsstr, optional

Length units for values in up_elevation_column and dn_elevation_column; by default ‘meters’.

crsobj, optional

Coordinate reference object for df. This argument is only needed if df is not a GeoDataFrame with a valid attached coordinate reference. Can be any of: - PROJ string - Dictionary of PROJ parameters - PROJ keyword arguments for parameters - JSON string with PROJ parameters - CRS WKT string - An authority string [i.e. ‘epsg:4326’] - An EPSG integer code [i.e. 4326] - A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)] - An object with a to_wkt method. - A pyproj.crs.CRS class

prjfile: str, optional

ESRI-style projection file with coordinate reference information for df. This argument is only needed if df is not a GeoDataFrame with a valid attached coordinate reference.

**kwargsdict, optional

Support for deprecated keyword options.

Deprecated since version 0.13: The following arguments will be removed in SFRmaker 0.13.

• attr_length_units (str): use width_units or asum_units instead.

• attr_height_units (str): use elevation_units instead.

• epsg (int): use crs instead.

• proj_str (str): use crs instead.

Attributes:

crssfrmaker.gis.CRS instance

cull(feature, simplify=False, tol=None, feature_crs=None, inplace=False)

Cull linework; retaining only the lines that intersect a polygon feature.

Parameters:

featureshapely Polygon, list of Polygons, or shapefile path

Polygons must be in same CRS as linework; shapefile features will be reprojected if their crs is different.

simplifybool

Option to simplify the polygon, which can speed intersection with the lines.

tol: float

Simplification tolerance (distance), in the units of the LineStrings (usually meters).

feature_crsobj

A Python int, dict, str, or pyproj.crs.CRS instance passed to the pyproj.crs.CRS.from_user_input() See http://pyproj4.github.io/pyproj/stable/api/crs/crs.html#pyproj.crs.CRS.from_user_input. Can be any of:

• PROJ string

• Dictionary of PROJ parameters

• PROJ keyword arguments for parameters

• JSON string with PROJ parameters

• CRS WKT string

• An authority string [i.e. ‘epsg:4326’]

• An EPSG integer code [i.e. 4326]

• A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

• An object with a to_wkt method.

• A pyproj.crs.CRS class

inplacebool

If True, the attribute .df is modified; if False, a copy of .df is returned.

Returns:

dfDataFrame

Version of the Lines.df DataFrame containing only the lines that intersect the feature.

classmethod from_dataframe(df, id_column='id', routing_column='toid', arbolate_sum_column2='asum2', asum_units='km', width1_column='width1', width2_column='width2', width_units='meters', up_elevation_column='elevup', dn_elevation_column='elevdn', elevation_units='meters', geometry_column='geometry', name_column='name', crs=None, prjfile=None, **kwargs)

[summary]

Parameters:

dfDataFrame

Pandas DataFrame or Geopandas GeoDataFrame with flowline information, including shapely LineStrings in a ‘geometry’ column.

id_columnstr, optional

Attribute field with line identifiers, by default ‘id’

routing_columnstr, optional

Attribute field with downstream routing connections, by default ‘toid’

arbolate_sum_column2str, optional

Attribute field with arbolate sums at downstream ends of lines, by default ‘asum2’

asum_unitsstr, optional

Length units for values in arbolate_sum_column2; by default ‘km’.

width1_columnstr, optional

Attribute field with channel widths at upstream ends of lines, by default ‘width1’

width2_columnstr, optional

Attribute field with channel widths at downstream ends of lines, by default ‘width2’

width_unitsstr, optional

Length units for values in width1_column and width2_column; by default ‘meters’.

up_elevation_columnstr, optional

Attribute field with elevations at upstream ends of lines, by default ‘elevup’

dn_elevation_columnstr, optional

Attribute field with elevations at downstream ends of lines, by default ‘elevdn’

elevation_unitsstr, optional

Length units for values in up_elevation_column and dn_elevation_column; by default ‘meters’.

name_columnstr, optional

Attribute field with feature names, by default ‘name’

crsobj, optional

Coordinate reference object for df. This argument is only needed if df is not a GeoDataFrame with a valid attached coordinate reference. Can be any of: - PROJ string - Dictionary of PROJ parameters - PROJ keyword arguments for parameters - JSON string with PROJ parameters - CRS WKT string - An authority string [i.e. ‘epsg:4326’] - An EPSG integer code [i.e. 4326] - A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)] - An object with a to_wkt method. - A pyproj.crs.CRS class

prjfile: str, optional

ESRI-style projection file with coordinate reference information for df. This argument is only needed if df is not a GeoDataFrame with a valid attached coordinate reference.

**kwargsdict, optional

Support for deprecated keyword options.

Deprecated since version 0.13: The following arguments will be removed in SFRmaker 0.13.

• attr_length_units (str): use width_units or asum_units instead.

• attr_height_units (str): use elevation_units instead.

• epsg (int): use crs instead.

• proj_str (str): use crs instead.

Returns:

linesLines instance

classmethod from_nhdplus_hr(NHDPlusHR_paths, bbox_filter=None, drop_fcodes=None, drop_ftypes=None, drop_NHDPlusIDs=None, **kwargs)

Parameters:

NHDPlusHR_pathsstr or list of strings

path (or list of paths) to the NHDPlus High Resolution HU-4 Subregion file geodatabase (.gdb) to include, assuming the file structure is the same as when downloaded from the USGS National Map Downloader tool (v2.0) website (https://apps.nationalmap.gov/downloader/#/). For example:

NHDPlusHR_paths=['/NHDPLUS_HR_1/NHDPLUS_H_0202_HU4_GDB.gdb',
                    '/NHDPLUS_HR_2/NHDPLUS_H_0204_HU4_GDB.gdb'] 

for the 4-digit Hydrologic Units 0202 and 0204.

bbox_filtertuple or str, optional

Bounding box (tuple) or shapefile of model stream network area.

drop_fcodesint or list of ints, optional

fcode or list of NHDFlowline FCodes to drop from network. For example, to remove underground aqueducts and general case water pipelines from line network:

drop_fcodes = [42803, 42814]

drop_ftypesint or list of ints, optional

List of NHDFlowline FTypes to drop from network. For example, to remove all pipelines from line network:

drop_fcodes = [428]

drop_NHDPlusIDsint or list of ints, optional

List of NHDFlowlines (as NHDPlusIDs) to drop from network.

**kwargsdict, optional

Support for deprecated keyword options.

Deprecated since version 0.13: The following arguments will be removed in SFRmaker 0.13.

• crs: NHDPlus HR data are assumed to include valid projection information.

• epsg (int): NHDPlus HR data are assumed to include valid projection information.

• proj_str (str): NHDPlus HR data are assumed to include valid projection information.

• filter (tuble): use bbox_filter instead.

Returns:

linesLines instance

classmethod from_nhdplus_v2(NHDPlus_paths=None, NHDFlowlines=None, PlusFlowlineVAA=None, PlusFlow=None, elevslope=None, bbox_filter=None, crs=None, prjfile=None, **kwargs)

Parameters:

NHDPlus_pathsstr or list of strings

List of paths to the root folders of NHDPlus drainage basins to include, assuming the file structure is the same as downloaded from the NHDPlus version 2 website. For example:

NHDPlus_paths=['/NHDPlusGL/NHDPlus04/',
               '/NHDPlusMS/NHDPlus07/']    

for the Great Lakes (04) and Upper Mississippi (07) basins.

NHDFlowlinesstr or list of strings.

Shapefile or list of NHDFlowline shapefiles containing feature geometries (line arcs) for stream network. Must contain the following attribute fields: COMID : common identifier number

PlusFlowlineVAAstr or list of strings.

DBF file or list of DBF files with NHDPlus attribute information. Must contain the following attribute fields: COMID : common identifier number

PlusFlowstr or list of strings.

DBF file or list of DBF files with NHDPlus routing information. Must contain the following attribute fields: COMID : common identifier number

elevslopestr or list of strings.

DBF file or list of DBF files with end elevations for each line arc in NHDFlowlines. Must contain the following attribute fields: COMID : common identifier number

bbox_filtertuple or str

Bounding box (tuple) or shapefile of model stream network area.

crsobj, optional

Coordinate reference object for df. This argument is only needed if the input flowlines don’t have a valid projection file. Can be any of: - PROJ string - Dictionary of PROJ parameters - PROJ keyword arguments for parameters - JSON string with PROJ parameters - CRS WKT string - An authority string [i.e. ‘epsg:4326’] - An EPSG integer code [i.e. 4326] - A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)] - An object with a to_wkt method. - A pyproj.crs.CRS class

prjfile: str, optional

ESRI-style projection file with coordinate reference information for df. This argument is only needed if the input flowlines don’t have a valid projection file.

**kwargsdict, optional

Support for deprecated keyword options.

Deprecated since version 0.13: The following arguments will be removed in SFRmaker 0.13.

• epsg (int): use crs instead.

• proj_str (str): use crs instead.

• filter (tuble): use bbox_filter instead.

Returns:

linesLines instance

classmethod from_shapefile(shapefile, id_column='id', routing_column='toid', arbolate_sum_column2='asum2', asum_units='km', width1_column='width1', width2_column='width2', width_units='meters', up_elevation_column='elevup', dn_elevation_column='elevdn', elevation_units='meters', name_column='name', bbox_filter=None, crs=None, prjfile=None, **kwargs)

Create a Lines instance from a shapefile.

Parameters:

shapefilestr or pathlike

Input shapefile

id_columnstr, optional

Attribute field with line identifiers, by default ‘id’

routing_columnstr, optional

Attribute field with downstream routing connections, by default ‘toid’

arbolate_sum_column2str, optional

Attribute field with arbolate sums at downstream ends of lines, by default ‘asum2’

asum_unitsstr, optional

Length units for values in arbolate_sum_column2; by default ‘km’.

width1_columnstr, optional

Attribute field with channel widths at upstream ends of lines, by default ‘width1’

width2_columnstr, optional

Attribute field with channel widths at downstream ends of lines, by default ‘width2’

width_unitsstr, optional

Length units for values in width1_column and width2_column; by default ‘meters’.

up_elevation_columnstr, optional

Attribute field with elevations at upstream ends of lines, by default ‘elevup’

dn_elevation_columnstr, optional

Attribute field with elevations at downstream ends of lines, by default ‘elevdn’

elevation_unitsstr, optional

Length units for values in up_elevation_column and dn_elevation_column; by default ‘meters’.

name_columnstr, optional

Attribute field with feature names, by default ‘name’

bbox_filtertuple, optional

(xmin, ymin, xmax, ymax) bounding box to filter which records are read from the shapefile. By default None.

crsobj, optional

Coordinate reference object for shapefile. This argument is only needed if shapefile does not include a valid projection file. Can be any of: - PROJ string - Dictionary of PROJ parameters - PROJ keyword arguments for parameters - JSON string with PROJ parameters - CRS WKT string - An authority string [i.e. ‘epsg:4326’] - An EPSG integer code [i.e. 4326] - A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)] - An object with a to_wkt method. - A pyproj.crs.CRS class

prjfile: str, optional

ESRI-style projection file with coordinate reference information for df. This argument is only needed if shapefile does not include a valid projection file.

**kwargsdict, optional

Support for deprecated keyword options.

Deprecated since version 0.13: The following arguments will be removed in SFRmaker 0.13.

• attr_length_units (str): use width_units or asum_units instead.

• attr_height_units (str): use elevation_units instead.

• epsg (int): use crs instead.

• proj_str (str): use crs instead.

• filter (tuple): use bbox_filter instead.

Returns:

linesLines instance

property geometry_length_units

Length units of reach LineString geometries.

intersect(grid, size_thresh=100000.0)

Intersect linework with a model grid.

Parameters:

gridinstance of sfrmaker.grid

Must have a valid Coordinate Reference System (CRS).

size_threshint

Determines whether spatial indexing will be used. If number of grid cells x number of flowlines > size_thresh, a spatial index (rtree package) will be used to speed up the intersections.

Returns:

reach_dataDataFrame

DataFrame containing intersected reaches with grid cell information and original linework IDs.

make_routing_one_to_one()

property paths

Dictionary of paths, where each value is a list of downstream lines constituting a flow path to an outlet for a given line (key).

property routing

Dictionary of routing connections from ids (keys) to to_ids (values).

to_crs(dest_crs)

Reproject the LineStrings in Lines.df to a different Coordinate Reference System.

Parameters:

dest_crsobj

A Python int, dict, str, or pyproj.crs.CRS instance passed to the pyproj.crs.CRS.from_user_input() See http://pyproj4.github.io/pyproj/stable/api/crs/crs.html#pyproj.crs.CRS.from_user_input. Can be any of:

• PROJ string

• Dictionary of PROJ parameters

• PROJ keyword arguments for parameters

• JSON string with PROJ parameters

• CRS WKT string

• An authority string [i.e. ‘epsg:4326’]

• An EPSG integer code [i.e. 4326]

• A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

• An object with a to_wkt method.

• A pyproj.crs.CRS class

to_sfr(grid=None, active_area=None, isfr=None, model=None, model_length_units='undefined', model_time_units='days', minimum_reach_length=None, width_from_asum_a_param=0.1193, width_from_asum_b_param=0.5032, minimum_reach_width=1.0, consolidate_conductance=False, one_reach_per_cell=False, add_outlets=None, package_name=None, **kwargs)

Create a streamflow routing dataset from the information in sfrmaker.lines class instance and a supplied sfrmaker.grid class instance.

Parameters:

gridsfrmaker.grid or flopy.discretization.StructuredGrid

Numerical model grid instance. Required unless an attached model has a valid modelgrid attribute.

active_areashapely Polygon, list of shapely Polygons, or shapefile path; optional

Shapely Polygons must be in same CRS as input flowlines; shapefile features will be reprojected if their crs is different.

isfrndarray, optional

Numpy integer array of the same size as the model grid, designating area that will be populated with SFR reaches (0=no SFR; 1=SFR). An isfr array of shape nrow x ncol will be broadcast to all layers. Only required if a model is not supplied, or if SFR is only desired in a subset of active model cells. By default, None, in which case the model ibound or idomain array will be used.

modelflopy.modflow.Modflow or flopy.mf6.ModflowGwf, optional

Flopy model instance

model_length_unitsstr; e.g. {‘ft’, ‘feet’, ‘meters’, etc.}, optional

Length units of the model. While SFRmaker will try to read these from a supplied grid (first) and then a supplied model (second), it is good practice to specify them explicitly here.

model_time_unitsstr; e.g. {‘d’, ‘days’}, optional

Time units for model. By default, days.

minimum_reach_lengthfloat, optional

Minimum reach length to retain. Default is to compute an effective mean model cell length by taking the square root of the average cell area, and then set minimum_reach_length to 5% of effective mean cell length.

width_from_asum_a_paramfloat, optional

\(a\) parameter used for estimating channel width from arbolate sum. Only needed if input flowlines are lacking width information. See width_from_arbolate(). By default, 0.1193.

width_from_asum_b_paramfloat, optional

\(b\) parameter used for estimating channel width from arbolate sum. Only needed if input flowlines are lacking width information. See width_from_arbolate(). By default, 0.5032.

minimum_reach_widthfloat, optional

Minimum reach width to specify (in model units), if computing widths from arbolate sum values. (default = 1)

consolidate_conductancebool

If True, total reach conductance each cell is computed, and assigned to the most downstream reach via the hydraulic conductivity parameter.

one_reach_per_cellbool

If True, streambed conductance in each reach is consolidated (consolidate_conductance = True), and additional reaches besides the most downstream reach are dropped.

add_outletssequence of ints

Option to add breaks in routing at specified line ids. For example if controlled flows out of a reservoir are specified as inflows to the SFR network, an outlet can be added above to the dam to prevent double-counting of flow. By default, None

package_namestr

Base name for writing sfr output.

kwargskeyword arguments to SFRData

Returns:

sfrdatasfrmaker.SFRData instance

write_shapefile(outshp='flowlines.shp')

Write a shapefile of Lines.df.

Parameters:

outshpstr, optional

Shapefile name, by default ‘flowlines.shp’