API Reference

Main functions of hysetter.

Project #

Bases: BaseModel

Project information.

Attributes:

name (str) –

Name of the project.
data_dir (str) –

Path to the directory where the data will be stored.

AOI #

Bases: BaseModel

Area of interest.

Notes

Only one of huc_ids, nhdv2_ids, gagesii_basins, or geometry_file must be provided.

Attributes:

huc_ids ((list, optional)) –

List of HUC IDs, by default None. The IDs must be strings and HUC level will be determined by the length of the string (even numbers between 2 and 12).
nhdv2_ids ((list, optional)) –

List of NHD Feature IDs, by default None. The IDs must be integers and are assumed to be NHDPlus V2 catchment IDs.
gagesii_basins ((list, optional)) –

List of GAGES-II basin IDs, by default None. The IDs must be strings.
mainstem_main ((int, optional)) –

NHDPlus V2 mainstem ID to get only its main upstream flowlines, by default None. The ID must be an integer.
mainstem_tributaries ((bool, optional)) –

NHDPus V2 mainstem ID to get all its upstream tributaries, by default None. The ID must be an integer.
geometry_file ((str, optional)) –

Path to a geometry file, by default None. Supported file extensions are .feather, .parquet, and any format supported by geopandas.read_file (e.g., .shp, .geojson, and .gpkg).
nhdv2_flowlines ((bool, optional)) –

Whether to retrieve the NHDPlus V2 flowlines within the AOI, by default False.
streamcat_attrs ((list, optional)) –

StreamCat attributes to retrieve, by default None. This will set the nhdv2_flowlines to True. Use pynhd.StreamCat().metrics_df to get a dataframe of all available attributes with their descriptions.
nldi_attrs ((list, optional)) –

List of slelect attributes to retrieve, by default None. Use pynhd.nhdplus_attrs_s3() to get a dataframe of all available attributes with their descriptions.

Forcing #

Bases: BaseModel

Forcing data.

Attributes:

source (str) –

Source of the forcing data. Supported sources are "daymet", "gridmet", and "nldas2".
start_date (datetime) –

Start date of the forcing data.
end_date (datetime) –

End date of the forcing data.
variables ((list, optional)) –

List of variables to retrieve, by default None. If not provided, all available variables will be retrieved.
crop ((bool, optional)) –

Whether to crop the data to the geometry of the AOI, by default True. If False, the data will be saved for the bounding box of the AOI.
geometry_buffer ((int, optional)) –

Buffer distance in meters to add to the geometry of the AOI before requesting the data, by default 0. This is useful for cases where additional post-processing is needed that are sensitive to the edges of the data.

Topo #

Bases: BaseModel

Topographic data.

Attributes:

resolution_m (int) –

Resolution of the data in meters.
derived_variables ((list, optional)) –

List of derived variables to calculate, by default None. Supported derived variables are "slope", "aspect", and "curvature".
crop ((bool, optional)) –

Whether to crop the data to the geometry of the AOI, by default True. If False, the data will be saved for the bounding box of the AOI.
geometry_buffer ((int, optional)) –

Buffer distance in meters to add to the geometry of the AOI before requesting the data, by default 0. This is useful for cases where additional post-processing is needed that are sensitive to the edges of the data.

RemoteRasters #

Bases: BaseModel

Remote raster data configuration.

Attributes:

crop ((bool, optional)) –

Whether to crop the data to the geometry of the AOI, by default True.
geometry_buffer ((float, optional)) –

Buffer distance in meters to add to the AOI geometry before requesting data.

Notes

Additional fields are treated as raster names (URLs). Raster names are sanitized: - Lowercased - Stripped of whitespace - Spaces replaced with underscores

rasters `property` #

rasters

Return a dictionary of raster names and URLs.

sanitize_keys `classmethod` #

sanitize_keys(v, info)

Sanitize raster names (keys) and validate URL strings.

Soil #

Bases: BaseModel

Soil data.

Attributes:

source (str) –

Source of the soil data. Supported sources aresoilgrids, gnatsgo, and polaris.
variables (list) –

List of variables to retrieve. Each source has its own set of variables.
crop ((bool, optional)) –

Whether to crop the data to the geometry of the AOI, by default True. If False, the data will be saved for the bounding box of the AOI.
geometry_buffer ((int, optional)) –

Buffer distance in meters to add to the geometry of the AOI before requesting the data, by default 0. This is useful for cases where additional post-processing is needed that are sensitive to the edges of the data.

NLCD #

Bases: BaseModel

National Land Cover Database (NLCD) data.

Attributes:

cover ((list, optional)) –

List of years for land cover data, by default None., which defaults to the most recent data. Available years are 2021, 2019, 2016, 2013, 2011, 2008, 2006, 2004, and 2001.
impervious ((list, optional)) –

List of years for impervious data, by default None., which defaults to the most recent data. Available years are 2021, 2019, 2016, 2013, 2011, 2008, 2006, 2004, and 2001.
canopy ((list, optional)) –

List of years for canopy data, by default None., which defaults to the most recent data. Available years are between 2011 and 2022.
descriptor ((list, optional)) –

List of years for descriptor data, by default None., which defaults to the most recent data. Available years are 2021, 2019, 2016, 2013, 2011, 2008, 2006, 2004, and 2001.
crop ((bool, optional)) –

Whether to crop the data to the geometry of the AOI, by default True. If False, the data will be saved for the bounding box of the AOI.
geometry_buffer ((int, optional)) –

Buffer distance in meters to add to the geometry of the AOI before requesting the data, by default 0. This is useful for cases where additional post-processing is needed that are sensitive to the edges of the data.

NID #

Bases: BaseModel

National Inventory of Dams (NID) data.

Attributes:

within_aoi (bool) –

Whether to retrieve the NID data within the AOI.

Streamflow #

Bases: BaseModel

Streamflow data from NWIS.

Attributes:

start_date (datetime) –

Start date of the streamflow data.
end_date (datetime) –

End date of the streamflow data.
frequency (str) –

Frequency of the streamflow data. Supported frequencies are "daily" and "instantaneous".
within_aoi ((bool, optional)) –

Whether to retrieve the streamflow data for USGS stations that are within the AOI, by default True.
use_col ((str, optional)) –

Instead of getting data for all stations within the AOI, get data for a column in the AOI dataframe that contains the USGS station IDs, by default None.

FileList #

FileList(parent)

Bases: list[Path]

A list of files in a directory, ensuring all elements are Path objects within the directory.

Initialize the FileList object.

Parameters:

parent (str | Path) –

The root directory containing the files.

append #

append(file)

Append a file as a Path relative to the parent directory.

extend #

extend(files)

Extend the list with multiple files as Paths relative to the parent directory.

mkdir #

mkdir(exist_ok=True, parents=True)

Create the parent directory if it does not exist.

rm_tree #

rm_tree()

Remove the directory and all its contents.

FilePaths `dataclass` #

FilePaths(
    project,
    aoi_parquet,
    flowlines,
    streamcat_attrs,
    nldi_attrs,
    forcing,
    topo,
    soil,
    nlcd,
    nid,
    streamflow,
    remote_rasters,
)

File paths to store the data.

Attributes:

project (Path) –

Path to the project directory.
aoi_parquet (Path) –

Path to the AOI data in Parquet format.
flowlines (FileList) –

List of NHDPlus V2 flowlines.
streamcat_attrs (FileList) –

List of StreamCat attributes.
nldi_attrs (FileList) –

List of NLDI attributes.
forcing (FileList) –

List of forcing data files.
topo (FileList) –

List of topographic data files.
soil (FileList) –

List of soil data files.
nlcd (FileList) –

List of NLCD data files.
nid (FileList) –

List of NID data files.
streamflow (FileList) –

List of streamflow data files.
remote_rasters (dict) –

Dictionary of remote raster data files, where keys are raster names and values are FileList objects containing the file paths.

rm_tree #

rm_tree()

Remove the directory and all its contents.

Config #

Config(**data)

Bases: BaseModel

Configuration for HySetter.

Notes

Only project and aoi are required. The rest are optional.

Attributes:

project (Project) –

Project information.
aoi (AOI) –

Area of interest.
forcing ((Forcing, optional)) –

Forcing data, by default None.
topo ((Topo, optional)) –

Topographic data, by default None.
soil ((Soil, optional)) –

Soil data, by default None.
nlcd ((NLCD, optional)) –

National Land Cover Database (NLCD) data, by default None.
nid ((NID, optional)) –

National Inventory of Dams (NID) data, by default None.
streamflow ((Streamflow, optional)) –

Streamflow data from NWIS, by default None.
remote_rasters ((RemoteRasters, optional)) –

Remote raster data, by default None.
overwrite ((bool, optional)) –

Whether to overwrite existing data, by default False.

get_data #

get_data()

Iterate over non-None attributes.

read_config #

read_config(file_path)

Read a configuration file and return a Config object.

Parameters:

file_path (str or Path) –

Path to the configuration file.

Returns:

Config –

A Config object.

write_config #

write_config(config, file_path)

Write a Config object to a file.

Parameters:

config (Config) –

A Config object.
file_path (str or Path) –

Path to the configuration file.

API Reference

Project #

AOI #

Forcing #

Topo #

RemoteRasters #

rasters property #

sanitize_keys classmethod #

Soil #

NLCD #

NID #

Streamflow #

FileList #

append #

extend #

mkdir #

rm_tree #

FilePaths dataclass #

rm_tree #

Config #

get_data #

read_config #

write_config #

rasters `property` #

sanitize_keys `classmethod` #

FilePaths `dataclass` #