Methods for querying the NHDPlus V2 data set. More...

Functions
def	getNHDReachcodeAndMeasureForGageSourceFea (config, source_fea)
	Get NHD Reachcode and measure along reach for a streamflow gage identified by a source_fea (e.g. More...

def	getLocationForStreamGageByGageSourceFea (config, source_fea)
	Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by a source_fea (e.g. More...

def	getLocationForStreamGageByReachcodeAndMeasure (config, reachcode, measure)
	Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by reachcode and measure. More...

def	getLocationForStreamGage (config, whereFilter)
	Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by reachcode and measure. More...

def	getComIdForStreamGage (conn, reachcode, measure)
	Uses NHDFlowline and/or NHDReachCode_ComID table(s) to lookup the ComID associated with a stream gage identified by reach code and measure. More...

def	getPlusFlowPredecessors (conn, comID)
	Get the immediate predecessors of the NHDPlus2 PlusFlow feature of comID. More...

def	getUpstreamReachesSQL (conn, comID, allUpstreamReaches)
	Recursively searches PlusFlow table in an SQLite database for all stream reaches upstream of a given reach. More...

def	getFirstOrderUpstreamReachesNotInSet
	Search for upstream reaches downstream of reaches in the specified set. More...

def	getFirstOrderUpstreamReachesNotInSetSQL (conn, comID, comIdsInSet, upstreamReaches, depth, maxdepth)
	Recursively search for upstream reaches downstream of reaches in the specified set. More...

def	getFirstOrderUpstreamReachesInSet
	Search for first-order upstream reaches in the specified set. More...

def	getFirstOrderUpstreamReachesInSetSQL (conn, comID, comIdsInSet, upstreamReaches, depth, maxdepth)
	Recursively search for first-order upstream reaches in the specified set. More...

def	getBoundingBoxForCatchmentsForGage
	Get bounding box coordinates (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) streamflow gage identified by a reach code and measure. More...

def	getCatchmentFeaturesForReaches
	Get features (in WGS 84) for the drainage area associated with a set of NHD (National Hydrography Dataset) stream reaches. More...

def	getCatchmentFeaturesForComid
	Get features (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) stream reach. More...

def	getCatchmentFeaturesForGage
	Get features (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) streamflow gage identified by a reach code and measure. More...

Variables
	OGR_UPDATE_MODE = False

int	NORTH = 0

int	EAST = 90

int	UPSTREAM_SEARCH_THRESHOLD = 998

Detailed Description

Methods for querying the NHDPlus V2 data set.

Requires that a NHDPlus V2 database be initialized from data archive files using NHDPlusSetup.py

This software is provided free of charge under the New BSD License. Please see the following license information:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the University of North Carolina at Chapel Hill nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author: Brian Miles brian.nosp@m._mil.nosp@m.es@un.nosp@m.c.ed.nosp@m.u

Function Documentation

def ecohydrolib.nhdplus2.networkanalysis.getBoundingBoxForCatchmentsForGage	(	config,
		outputDir,
		reachcode,
		measure,
		deleteIntermediateFiles = `True`
	)

Get bounding box coordinates (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) streamflow gage identified by a reach code and measure.

Parameters

config	A Python ConfigParser containing the following sections and options: 'GDAL/OGR' and option 'PATH_OF_OGR2OGR' (absolute path of ogr2ogr binary) 'NHDPLUS2' and option 'PATH_OF_NHDPLUS2_DB' (absolute path to SQLite3 DB of NHDFlow data) 'NHDPLUS2', 'PATH_OF_NHDPLUS2_CATCHMENT' (absolute path to NHD catchment SQLite3 spatial DB)
outputDir	String representing the absolute/relative path of the directory into which output rasters should be written
reachcode	String representing NHD streamflow gage
measure	Float representing the measure along reach where Stream Gage is located in percent from downstream end of the one or more NHDFlowline features that are assigned to the ReachCode (see NHDPlusV21 GageLoc table)
deleteIntermediateFiles	A boolean, True if intermediate files generated from the analysis should be deleted

Returns: A dictionary with keys: minX, minY, maxX, maxY, srs. The key srs is set to 'EPSG:4326' (WGS 84)

ConfigParser.NoSectionError ConfigParser.NoOptionError IOError(errno.ENOTDIR) if outputDir is not a directory IOError(errno.EACCESS) if outputDir is not writable

def ecohydrolib.nhdplus2.networkanalysis.getCatchmentFeaturesForComid	(	config,
		outputDir,
		catchmentFilename,
		comID,
		format = `OGR_SHAPEFILE_DRIVER_NAME`
	)

Get features (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) stream reach.

Parameters

config	A Python ConfigParser containing the following sections and options: 'NHDPLUS2',
outputDir	String representing the absolute/relative path of the directory into which output rasters should be written
catchmentFilename	String representing name of file to save catchment features to. The appropriate extension will be added to the file name
comID	String representing comid of stream reach whose upstream catchment area is to be determined
format	String representing OGR driver to use

Returns: String representing the name of the dataset in outputDir created to hold the features

ConfigParser.NoSectionError ConfigParser.NoOptionError IOError(errno.ENOTDIR) if outputDir is not a directory IOError(errno.EACCESS) if outputDir is not writable Exception if output format is not known

def ecohydrolib.nhdplus2.networkanalysis.getCatchmentFeaturesForGage	(	config,
		outputDir,
		catchmentFilename,
		reachcode,
		measure,
		format = `OGR_SHAPEFILE_DRIVER_NAME`
	)

Get features (in WGS 84) for the drainage area associated with a given NHD (National Hydrography Dataset) streamflow gage identified by a reach code and measure.

Note: Capable of handling gages with more than 1000 upstream reaches; No return value. catchmentFilename will be written to outputDir if successful

Parameters

config A Python ConfigParser containing the following sections and options: 'NHDPLUS2' and option 'PATH_OF_NHDPLUS2_DB' (absolute path to SQLite3 DB of NHDFlow data)

'NHDPLUS2', 'PATH_OF_NHDPLUS2_CATCHMENT' (absolute path to NHD catchment shapefile)

Parameters

outputDir	String representing the absolute/relative path of the directory into which output rasters should be written
catchmentFilename	String representing name of file to save catchment features to. The appropriate extension will be added to the file name
reachcode	String representing NHD streamflow gage
measure	Float representing the measure along reach where Stream Gage is located in percent from downstream end of the one or more NHDFlowline features that are assigned to the ReachCode (see NHDPlusV21 GageLoc table)
format	String representing OGR driver to use

Returns: String representing the name of the dataset in outputDir created to hold the features

ConfigParser.NoSectionError ConfigParser.NoOptionError IOError(errno.ENOTDIR) if outputDir is not a directory IOError(errno.EACCESS) if outputDir is not writable Exception if output format is not known

def ecohydrolib.nhdplus2.networkanalysis.getCatchmentFeaturesForReaches	(	config,
		outputDir,
		catchmentFilename,
		reaches,
		format = `OGR_SHAPEFILE_DRIVER_NAME`
	)

Get features (in WGS 84) for the drainage area associated with a set of NHD (National Hydrography Dataset) stream reaches.

Parameters

config	A Python ConfigParser containing the following sections and options: 'PATH_OF_NHDPLUS2_CATCHMENT' (absolute path to NHD catchment shapefile)
outputDir	String representing the absolute/relative path of the directory into which output rasters should be written
catchmentFilename	String representing name of file to save catchment features to. The appropriate extension will be added to the file name
reaches	List representing catchment features to be output
format	String representing OGR driver to use

Returns: String representing the name of the dataset in outputDir created to hold the features

ConfigParser.NoSectionError ConfigParser.NoOptionError IOError(errno.ENOTDIR) if outputDir is not a directory IOError(errno.EACCESS) if outputDir is not writable Exception if output format is not known

Todo:: Detect and fix non-closed geometries, e.g. kalisti:archive miles$ ./GetCatchmentsForComidsSP.py -p test -c 10462287 Traceback (most recent call last): File "./GetCatchmentsForComidsSP.py", line 29, in <module> catchmentFilename, comid) File "/Users/miles/Dropbox/EarthCube-Multilayered/RHESSys-workflow/eclipse/EcohydroWorkflowLib/ecohydrolib/nhdplus2/networkanalysis.py", line 506, in getCatchmentFeaturesForComid outGeom = outGeom.Union( inGeom ) File "/usr/local/Cellar/python/2.7.5/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/osgeo/ogr.py", line 4065, in Union return _ogr.Geometry_Union(self, *args) RuntimeError: TopologyException: found non-noded intersection between LINESTRING (-77.9145 37.0768, -77.9147 37.0768) and LINESTRING (-77.9147 37.0768, -77.9145 37.0768) at -77.914621661942761 37.076822779115943

Parameters

config	A Python ConfigParser containing the following sections and options: 'PATH_OF_NHDPLUS2_CATCHMENT' (absolute path to NHD catchment shapefile)
outputDir	String representing the absolute/relative path of the directory into which output rasters should be written
catchmentFilename	String representing name of file to save catchment features to. The appropriate extension will be added to the file name
reaches	List representing catchment features to be output
format	String representing OGR driver to use

Returns: String representing the name of the dataset in outputDir created to hold the features

ConfigParser.NoSectionError ConfigParser.NoOptionError IOError(errno.ENOTDIR) if outputDir is not a directory IOError(errno.EACCESS) if outputDir is not writable Exception if output format is not known

Todo:: Detect and fix non-closed geometries, e.g. kalisti:archive miles$ ./GetCatchmentsForComidsSP.py -p test -c 10462287 Traceback (most recent call last): File "./GetCatchmentsForComidsSP.py", line 29, in <module> catchmentFilename, comid) File "/Users/miles/Dropbox/EarthCube-Multilayered/RHESSys-workflow/eclipse/EcohydroWorkflowLib/ecohydrolib/nhdplus2/networkanalysis.py", line 506, in getCatchmentFeaturesForComid outGeom = outGeom.Union( inGeom ) File "/usr/local/Cellar/python/2.7.5/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/osgeo/ogr.py", line 4065, in Union return _ogr.Geometry_Union(self, *args) RuntimeError: TopologyException: found non-noded intersection between LINESTRING (-77.9145 37.0768, -77.9147 37.0768) and LINESTRING (-77.9147 37.0768, -77.9145 37.0768) at -77.914621661942761 37.076822779115943

def ecohydrolib.nhdplus2.networkanalysis.getComIdForStreamGage	(	conn,
		reachcode,
		measure
	)

Uses NHDFlowline and/or NHDReachCode_ComID table(s) to lookup the ComID associated with a stream gage identified by reach code and measure.

Parameters

conn	An sqlite3 connection to a database that has the NHDFlowline and NHDReachCode_Comid tables
reachcode	An string representing the Reachcode #param measure A float representing the measure along reach where Stream Gage is located in percent from downstream end of the one or more NHDFlowline features that are assigned to the ReachCode (see NHDPlusV21 GageLoc table)

Returns: An integer representing the ComID associated with a Reachcode, or -1 if a reach with Reachcode was not found.

def ecohydrolib.nhdplus2.networkanalysis.getFirstOrderUpstreamReachesInSet	(	config,
		comID,
		comIdsInSet,
		maxdepth = `30`
	)

Search for first-order upstream reaches in the specified set.

Parameters

config	A Python ConfigParser containing the following sections and options: 'NHDPLUS2' and option 'PATH_OF_NHDPLUS2_DB' (absolute path to SQLite3 DB of NHDFlow data)
comID	The ComID of the reach whose first-order upstream reaches are to be discovered
comIdsInSet	A set containing candidate comids
upstreamReaches	List containing integers representing comIDs of upstream reaches in set comIdsInSet
maxdepth	Integer representing maximum depth of recursion

Returns: Set containing first order upstream reaches in set

ConfigParser.NoSectionError ConfigParser.NoOptionError

def ecohydrolib.nhdplus2.networkanalysis.getFirstOrderUpstreamReachesInSetSQL	(	conn,
		comID,
		comIdsInSet,
		upstreamReaches,
		depth,
		maxdepth
	)

Recursively search for first-order upstream reaches in the specified set.

Parameters

conn	An sqlite3 connection to a database that has NHDPlus2 tables
comID	The ComID of the reach whose first-order upstream reaches are to be discovered
comIdsInSet	A set containing candidate comids
upstreamReaches	Set containing integers representing comIDs of upstream reaches in set comIdsInSet
depth	Integer current depth
maxdepth	Integer representing maximum depth of recursion

def ecohydrolib.nhdplus2.networkanalysis.getFirstOrderUpstreamReachesNotInSet	(	config,
		comID,
		comIdsInSet,
		maxdepth = `30`
	)

Search for upstream reaches downstream of reaches in the specified set.

Parameters

config	A Python ConfigParser containing the following sections and options: 'NHDPLUS2' and option 'PATH_OF_NHDPLUS2_DB' (absolute path to SQLite3 DB of NHDFlow data)
comID	The ComID of the reach whose upstream reaches downstream of those in the set are to be discovered
comIdsInSet	A set containing candidate comids
upstreamReaches	List containing integers representing comIDs of upstream reaches in set comIdsInSet
maxdepth	Integer representing maximum depth of recursion

Returns: Set containing first order upstream reaches in set

ConfigParser.NoSectionError ConfigParser.NoOptionError

def ecohydrolib.nhdplus2.networkanalysis.getFirstOrderUpstreamReachesNotInSetSQL	(	conn,
		comID,
		comIdsInSet,
		upstreamReaches,
		depth,
		maxdepth
	)

Recursively search for upstream reaches downstream of reaches in the specified set.

Parameters

conn	An sqlite3 connection to a database that has NHDPlus2 tables
comID	The ComID of the reach whose upstream reaches downstream of those in the set are to be discovered
comIdsInSet	A set containing candidate comids
upstreamReaches	Set containing integers representing comIDs of upstream reaches in set comIdsInSet
depth	Integer current depth
maxdepth	Integer representing maximum depth of recursion

def ecohydrolib.nhdplus2.networkanalysis.getLocationForStreamGage	(	config,
		whereFilter
	)

Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by reachcode and measure.

Parameters

config	A Python ConfigParser containing the following sections and options: 'NHDPLUS2', 'PATH_OF_NHDPLUS2_GAGELOC' (absolute path to NHD GageLoc SQLite3 spatial database)
whereFilter	String representing the whereFilter to use

Returns: A tuple with (x,y) coordinates in 'EPSG:4326' (WGS 84); None if gage was not found

ConfigParser.NoSectionError ConfigParser.NoOptionError Exception if unable to open gage database IOError(errno.ENOTDIR) if GageLoc is not readable

def ecohydrolib.nhdplus2.networkanalysis.getLocationForStreamGageByGageSourceFea	(	config,
		source_fea
	)

Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by a source_fea (e.g.

USGS Site Number)

    @param config A Python ConfigParser containing the following sections and options:
        'NHDPLUS2', 'PATH_OF_NHDPLUS2_GAGELOC' (absolute path to NHD GageLoc SQLite3 spatial database)
    @param source_fea String representing source_fea of GageLoc gage

    @return A tuple with (x,y) coordinates in 'EPSG:4326' (WGS 84)

def ecohydrolib.nhdplus2.networkanalysis.getLocationForStreamGageByReachcodeAndMeasure	(	config,
		reachcode,
		measure
	)

Get lat/lon, in WGS84 (EPSG:4326), from gage point layer (Gage_Loc) for gage identified by reachcode and measure.

Parameters

config	A Python ConfigParser containing the following sections and options: 'NHDPLUS2', 'PATH_OF_NHDPLUS2_GAGELOC' (absolute path to NHD GageLoc SQLite3 spatial database)
reachcode	String representing NHD streamflow gage
measure	Float representing the measure along reach where Stream Gage is located in percent from downstream end of the one or more NHDFlowline features that are assigned to the ReachCode (see NHDPlusV21 GageLoc table)

Returns: A tuple with (x,y) coordinates in 'EPSG:4326' (WGS 84); None if gage was not found

def ecohydrolib.nhdplus2.networkanalysis.getNHDReachcodeAndMeasureForGageSourceFea	(	config,
		source_fea
	)

Get NHD Reachcode and measure along reach for a streamflow gage identified by a source_fea (e.g.

USGS Site Number)

    @param config A Python ConfigParser containing the following sections and options:
        'NHDPLUS2', 'PATH_OF_NHDPLUS2_DB' (absolute path to NHDPlus2 SQLite3 database)
    @param source_fea String representing source_fea of GageLoc gage

    @return A tuple(string, float) representing the reachcode and measure; None if no gage was found.

    @raise ConfigParser.NoSectionError
    @raise ConfigParser.NoOptionError
    @raise IOError(errno.EACCES) if NHDPlus2 DB is not readable

def ecohydrolib.nhdplus2.networkanalysis.getPlusFlowPredecessors	(	conn,
		comID
	)

Get the immediate predecessors of the NHDPlus2 PlusFlow feature of comID.

Parameters

conn	A connection an SQLite3 database
comdID	String representing the ComID of the reach whose immediate predecessor reaches are to be discovered

Returns: A list of immediate predecessor nodes in the NHDPlus2 PlusFlow graph

def ecohydrolib.nhdplus2.networkanalysis.getUpstreamReachesSQL	(	conn,
		comID,
		allUpstreamReaches
	)

Recursively searches PlusFlow table in an SQLite database for all stream reaches upstream of a given reach.

Note: This method has no return value. Upstream reaches discovered are appended to allUpstreamReaches list.

Parameters

conn	A connection to an SQLite3 database
comID	The ComID of the reach whose upstream reaches are to be discovered
allUpstreamReaches	A list containing integers representing comIDs of upstream reaches

Variable Documentation

int ecohydrolib.nhdplus2.networkanalysis.EAST = 90

int ecohydrolib.nhdplus2.networkanalysis.NORTH = 0

ecohydrolib.nhdplus2.networkanalysis.OGR_UPDATE_MODE = False

int ecohydrolib.nhdplus2.networkanalysis.UPSTREAM_SEARCH_THRESHOLD = 998

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation