pynhd.nhdplus_derived#

Access NLDI and WaterData databases.

Module Contents#

class pynhd.nhdplus_derived.StreamCat#

Get StreamCat API’s properties.

id_kwds(comids=None, regions=None, states=None, counties=None, conus=False)#

Get the keyword arguments for the API’s ID parameters.

validate(name=None, region=None, state=None, county=None, aoi=None)#

Validate input parameters.

pynhd.nhdplus_derived.enhd_attrs(parquet_path=None)#

Get updated NHDPlus attributes from ENHD V2.0.

Notes

This downloads a 160 MB parquet file from here. Although this dataframe does not include geometry, it can be linked to other geospatial NHDPlus dataframes through ComIDs.

Parameters

parquet_path (str or ~Path, optional) – Path to a file with .parquet extension for storing the file, defaults to ./cache/enhd_attrs.parquet.

Returns

pandas.DataFrame – A dataframe that includes ComID-level attributes for 2.7 million NHDPlus flowlines.

pynhd.nhdplus_derived.epa_nhd_catchments(comids, feature)#

Get NHDPlus catchment-scale data from EPA’s HMS REST API.

Notes

For more information about curve number please refer to the project’s webpage on the EPA’s website.

Parameters
  • comids (int or list of int) – ComID(s) of NHDPlus catchments.

  • feature (str) – The feature of interest. Available options are:

    • catchment_metrics: 414 catchment-scale metrics.

    • curve_number: 16-day average Curve Number.

    • comid_info: ComID information.

Returns

dict of pandas.DataFrame or geopandas.GeoDataFrame – A dict of the requested dataframes. A comid_info dataframe is always returned.

Examples

>>> import pynhd
>>> data = nhd.epa_nhd_catchments(1440291, "catchment_metrics")
>>> data["catchment_metrics"].loc[1440291, "AvgWetIndxCat"]
579.532
pynhd.nhdplus_derived.nhd_fcode()#

Get all the NHDPlus FCodes.

pynhd.nhdplus_derived.nhdplus_attrs(attr_name=None)#

Stage the NHDPlus Attributes database and save to nhdplus_attrs.parquet.

Notes

More info can be found here.

Parameters

attr_names (str , *optional*) – Name of NHDPlus attribute to return, defaults to None, i.e., only return a metadata dataframe that includes the attribute names and their description and units.

Returns

pandas.DataFrame – The staged data as a DataFrame.

pynhd.nhdplus_derived.nhdplus_attrs_s3(attr_names=None, nodata=False)#

Access NHDPlus V2.1 derived attributes over CONUS.

Notes

More info can be found here.

Parameters
  • attr_names (str or list of str, optional) – Names of NHDPlus attribute(s) to return, defaults to None, i.e., only return a metadata dataframe that includes the attribute names and their description and units.

  • nodata (bool) – Whether to include NODATA percentages, default is False.

Returns

pandas.DataFrame – A dataframe of requested NHDPlus attributes.

pynhd.nhdplus_derived.nhdplus_vaa(parquet_path=None)#

Get NHDPlus Value Added Attributes with ComID-level roughness and slope values.

Notes

This function downloads a 245 MB parquet file from here . Although this dataframe does not include geometry, it can be linked to other geospatial NHDPlus dataframes through ComIDs.

Parameters

parquet_path (str or ~Path, optional) – Path to a file with .parquet extension for storing the file, defaults to ./cache/nldplus_vaa.parquet.

Returns

pandas.DataFrame – A dataframe that includes ComID-level attributes for 2.7 million NHDPlus flowlines.

Examples

>>> vaa = nhdplus_vaa() 
>>> print(vaa.slope.max()) 
4.6
pynhd.nhdplus_derived.streamcat(metric_names, metric_areas=None, comids=None, regions=None, states=None, counties=None, conus=False, percent_full=False, area_sqkm=False)#

Get various metrics for NHDPlusV2 catchments from EPA’s StreamCat.

Notes

For more information about the service check its webpage at https://www.epa.gov/national-aquatic-resource-surveys/streamcat-dataset.

Parameters
  • metric_names (str or list of str) – Metric name(s) to retrieve. There are 567 metrics available. to get a full list instantiate the StreamCat class and check its valid_names attribute.

  • metric_areas (str or list of str, optional) – Areas to return the metrics for, defaults to None, i.e. all areas. Valid options are: catchment, watershed, riparian_catchment, riparian_watershed, other.

  • comids (int or list of int, optional) – NHDPlus COMID(s), defaults to None. Either comids, regions, states, counties, or conus must be passed. They are mutually exclusive.

  • regions (str or list of str, optional) – Hydro region(s) to retrieve metrics for, defaults to None. For a full list of valid regions, instantiate the StreamCat class and check its valid_regions attribute. Either comids, regions, states, counties, or conus must be passed. They are mutually exclusive.

  • states (str or list of str, optional) – Two letter state abbreviation(s) to retrieve metrics for, defaults to None. For a full list of valid states, instantiate the StreamCat class and check its valid_states attribute. Either comids, regions, states, counties, or conus must be passed. They are mutually exclusive.

  • counties (str or list of str, optional) – County FIPS codes(s) to retrieve metrics for, defaults to None. For a full list of valid county codes, instantiate the StreamCat class and check its valid_counties attribute. Either comids, regions, states, counties, or conus must be passed. They are mutually exclusive.

  • conus (bool, optional) – If True, metric_names of all NHDPlus COMIDs are retrieved, defaults False. Either comids, regions, states, counties, or conus must be passed. They are mutually exclusive.

  • percent_full (bool, optional) – If True, return the percent of each area of interest covered by the metric.

  • area_sqkm (bool, optional) – If True, return the Returns the area in square kilometers of a given area of interest.

Returns

pandas.DataFrame – A dataframe with the requested metrics.