Process and access NHDPlus V2 data through NLDI and WaterData web services.
Project description
Package |
Description |
Status |
---|---|---|
Access NWIS, HCDN 2009, NLCD, and SSEBop databases |
||
Send queries to any ArcGIS RESTful-, WMS-, and WFS-based services |
||
Convert responses from PyGeoOGC’s supported web services to datasets |
||
Navigate and subset NHDPlus (MR and HR) using web services |
||
Access topographic data through National Map’s 3DEP web service |
||
Access Daymet for daily climate data both single pixel and gridded |
Features
PyNHD is a part of Hydrodata software stack and provides access to WaterData and NLDI web services. These two web services can be used to navigate and extract vector data from NHDPlus V2 database such as catchments, HUC8, HUC12, GagesII, flowlines, and water bodies. Moreover, the NLDI service includes more than 30 NHDPlus catchment-scale attributes that are associated with NHDPlus ComIDs. Values of these attributes are provided in three characteristic types:
local: For individual reach catchments,
tot: For network-accumulated values using total cumulative drainage area,
div: For network-accumulated values using divergence-routed.
A list of these attributes for each characteristic type can be accessed using NLDI().get_validchars class method.
Additionally, PyNHD offers some extra utilities for processing the flowlines:
prepare_nhdplus: For cleaning up the dataframe by, for example, removing tiny networks, adding a to_comid column, and finding a terminal flowlines if it doesn’t exist.
topoogical_sort: For sorting the river network topologically which is useful for routing and flow accumulation.
vector_accumulation: For computing flow accumulation in a river network. This function is generic and any routing method can be plugged in.
These utilities are developed based on an R package called nhdplusTools.
You can try using PyNHD without installing it on you system by clicking on the binder badge below the PyNHD banner. A Jupyter notebook instance with the Hydrodata software stack pre-installed will be launched in your web browser and you can start coding!
Moreover, requests for additional functionalities can be submitted via issue tracker.
Installation
You can install PyNHD using pip after installing libgdal on your system (for example, in Ubuntu run sudo apt install libgdal-dev):
$ pip install pynhd
Alternatively, PyNHD can be installed from the conda-forge repository using Conda:
$ conda install -c conda-forge pynhd
Quick start
Let’s explore the capabilities of NLDI. We need to instantiate the class first:
from pynhd import NLDI, WaterData, NHDPlusHR
import pynhd as nhd
First, let’s get the watershed geometry of the contributing basin of a USGS station using NLDI:
nldi = NLDI()
station_id = "USGS-01031500"
ut = "upstreamTributaries"
um = "upstreamMain"
basin = nldi.getfeature_byid("nwissite", station_id, basin=True)
The navigate_byid class method can be used to navigate NHDPlus in both upstream and downstream of any point in the database. Let’s get ComIDs and flowlines of the tributaries and the main river channel in the upstream of the station.
args = {
"fsource": "nwissite",
"fid": station_id,
"navigation": um,
"source": "flowlines",
"distance": 1000,
}
flw_main = nldi.navigate_byid(**args)
args["navigation"] = ut
flw_trib = nldi.navigate_byid(**args)
We can get other USGS stations upstream (or downstream) of the station and even set a distance limit (in km):
args.update({
"source" : "nwissite",
})
st_all = nldi.navigate_byid(**args)
args.update({
"distance": 20,
"source" : "nwissite",
})
st_d20 = nldi.navigate_byid(**args)
Now, let’s get the HUC12 pour points:
args.update({
"distance": 1000,
"source" : "huc12pp",
})
pp = nldi.navigate_byid(**args)
Now, let’s get the medium- and high-resolution flowlines within the bounding box of this watershed and compare them.
mr = WaterData("nhdflowline_network")
nhdp_mr = mr.bybox(basin.geometry[0].bounds)
hr = NHDPlusHR("networknhdflowline")
nhdp_hr = hr.bygeom(basin.geometry[0].bounds)
Since NHDPlus HR is still at the pre-release stage let’s use the MR flowlines to demonstrate the vector-based accumulation. Based on a topological sorted river network pynhd.vector_accumulation computes flow accumulation in the network. It returns a dataframe which is sorted from upstream to downstream that shows the accumulated flow in each node.
PyNHD has a utility called prepare_nhdplus that identifies such relationship among other things such as fixing some common issues with NHDPlus flowlines. But first we need to get all the NHDPlus attributes for each ComID since NLDI only provides the flowlines’ geometries and ComIDs which is useful for navigating the vector river network data. For getting the NHDPlus database we use WaterData. Let’s use the nhdflowline_network layer to get required info.
wd = WaterData("nhdflowline_network")
comids = flw_trib.nhdplus_comid.to_list()
nhdp_trib = wd.byid("comid", comids)
flw = nhd.prepare_nhdplus(nhdp_trib, 0, 0, purge_non_dendritic=False)
Now, let’s get Mean Annual Groundwater Recharge using getcharacteristic_byid class method and carry out the accumulation.
char = "CAT_RECHG"
area = "areasqkm"
local = nldi.getcharacteristic_byid(comids, "local", char_ids=char)
flw = flw.merge(local[char], left_on="comid", right_index=True)
def runoff_acc(qin, q, a):
return qin + q * a
flw_r = flw[["comid", "tocomid", char, area]]
runoff = nhd.vector_accumulation(flw_r, runoff_acc, char, [char, area])
def area_acc(ain, a):
return ain + a
flw_a = flw[["comid", "tocomid", area]]
areasqkm = nhd.vector_accumulation(flw_a, area_acc, area, [area])
runoff /= areasqkm
Since these are catchment-scale characteristic, let’s get the catchments then add the accumulated characteristic as a new column and plot the results.
wd = WaterData("catchmentsp")
catchments = wd.byid("featureid", comids)
c_local = catchments.merge(local, left_on="featureid", right_index=True)
c_acc = catchments.merge(runoff, left_on="featureid", right_index=True)
More examples can be found here.
Contributing
Contributions are very welcomed. Please read CONTRIBUTING.rst file for instructions.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pynhd-0.2.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 168d1e09f6353c2a508a100fd5dece06ed17ae31ae2bc3bb728f1b71e51bc87b |
|
MD5 | 5546f7da4a3337e85e6fa7f85a7a189b |
|
BLAKE2b-256 | cae785e6070862a19f57d048c1b2083f15f300f1d1cb71604b396cd76de2788f |