pygeohydro.nlcd#

Accessing data from the supported databases through their APIs.

Module Contents#

pygeohydro.nlcd.cover_statistics(cover_da)#

Percentages of the categorical NLCD cover data.

Parameters:

cover_da (xarray.DataArray) – Land cover DataArray from a LULC Dataset from the nlcd_bygeom function.

Returns:

Stats – A named tuple with the percentages of the cover classes and categories.

Return type:

pygeohydro.helpers.Stats

pygeohydro.nlcd.nlcd_area_percent(geo_df, year=2019, region='L48')#

Compute the area percentages of the natural, developed, and impervious areas.

Notes

This function uses imperviousness and land use/land cover data from NLCD to compute the area percentages of the natural, developed, and impervious areas. It considers land cover classes of 21 to 24 as urban and the rest as natural. Then, uses imperviousness percentage to partition the urban area into developed and impervious areas. So, urban = developed + impervious and always natural + urban = natural + developed + impervious = 100.

Parameters:

  • geo_df (geopandas.GeoDataFrame or geopandas.GeoSeries) – A GeoDataFrame or GeoSeries with the geometry to query. The indices are used as keys in the output dictionary.

  • year (int, optional) – Year of the NLCD data, defaults to 2019. Available years are 2021, 2019, 2016, 2013, 2011, 2008, 2006, 2004, and 2001.

  • region (str, optional) – Region in the US that the input geometries are located, defaults to L48. Valid values are L48 (for CONUS), HI (for Hawaii), AK (for Alaska), and PR (for Puerto Rico). Both lower and upper cases are acceptable.

Returns:

pandas.DataFrame – A dataframe with the same index as input geo_df and columns are the area percentages of the natural, developed, impervious, and urban (sum of developed and impervious) areas. Sum of urban and natural percentages is always 100, as well as the sum of natural, developed, and impervious percentages.

Return type:

pandas.DataFrame

pygeohydro.nlcd.nlcd_bycoords(coords, years=None, region='L48', ssl=True)#

Get data from NLCD database (2019).

Parameters:

  • coords (list of tuple) – List of coordinates in the form of (longitude, latitude).

  • years (dict, optional) – The years for NLCD layers as a dictionary, defaults to {'impervious': [2019], 'cover': [2019], 'canopy': [2019], "descriptor": [2019]}. Layers that are not in years are ignored, e.g., {'cover': [2016, 2019]} returns land cover data for 2016 and 2019.

  • region (str, optional) – Region in the US that the input geometries are located, defaults to L48. Valid values are L48 (for CONUS), HI (for Hawaii), AK (for Alaska), and PR (for Puerto Rico). Both lower and upper cases are acceptable.

  • ssl (bool, optional) – Whether to use SSL for the connection, defaults to True.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame with the NLCD data and the coordinates.

Return type:

geopandas.GeoDataFrame

pygeohydro.nlcd.nlcd_bygeom(geometry, resolution=30, years=None, region='L48', crs=4326, ssl=True)#

Get data from NLCD database (2019).

Parameters:

  • geometry (geopandas.GeoDataFrame or geopandas.GeoSeries) – A GeoDataFrame or GeoSeries with the geometry to query. The indices are used as keys in the output dictionary.

  • resolution (float, optional) – The data resolution in meters. The width and height of the output are computed in pixel based on the geometry bounds and the given resolution. The default is 30 m which is the native resolution of NLCD data.

  • years (dict, optional) – The years for NLCD layers as a dictionary, defaults to {'impervious': [2019], 'cover': [2019], 'canopy': [2019], "descriptor": [2019]}. Layers that are not in years are ignored, e.g., {'cover': [2016, 2019]} returns land cover data for 2016 and 2019.

  • region (str, optional) – Region in the US that the input geometries are located, defaults to L48. Valid values are L48 (for CONUS), HI (for Hawaii), AK (for Alaska), and PR (for Puerto Rico). Both lower and upper cases are acceptable.

  • crs (str, int, or pyproj.CRS, optional) – The spatial reference system to be used for requesting the data, defaults to epsg:4326.

  • ssl (bool, optional) – Whether to use SSL for the connection, defaults to True.

Returns:

dict of xarray.Dataset or xarray.Dataset – A single or a dict of NLCD datasets. If dict, the keys are indices of the input GeoDataFrame.

Return type:

dict[int | str, xarray.Dataset]

pygeohydro.nlcd.overland_roughness(cover_da)#

Estimate overland roughness from land cover data.

Parameters:

cover_da (xarray.DataArray) – Land cover DataArray from a LULC Dataset from the nlcd_bygeom function.

Returns:

xarray.DataArray – Overland roughness

Return type:

xarray.DataArray