hecstac.hms package

Submodules

hecstac.hms.assets module

HEC-HMS Stac Item asset classes.

class hecstac.hms.assets.ControlAsset(*args, **kwargs)

Bases: GenericAsset[ControlFile]

HEC-HMS Control file asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.control$'

class hecstac.hms.assets.DSSAsset(*args, **kwargs)

Bases: GenericAsset

DSS asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.dss$'

class hecstac.hms.assets.EventBasinAsset(*args, **kwargs)

Bases: GenericAsset[BasinFile]

HEC-HMS Basin file asset from event, with limited basin info.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.basin$'

class hecstac.hms.assets.GageAsset(*args, **kwargs)

Bases: GenericAsset[GageFile]

Gage asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.gage$'

class hecstac.hms.assets.GeojsonAsset(*args, **kwargs)

Bases: GenericAsset

Geojson asset.

regex_parse_str: str = '.*\\.geojson$'

class hecstac.hms.assets.GridAsset(*args, **kwargs)

Bases: GenericAsset[GridFile]

Grid asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.grid$'

class hecstac.hms.assets.LogAsset(*args, **kwargs)

Bases: GenericAsset

Log asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.log$'

class hecstac.hms.assets.MetAsset(*args, **kwargs)

Bases: GenericAsset[MetFile]

HEC-HMS Meteorological file asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.met$'

class hecstac.hms.assets.ModelBasinAsset(*args, **kwargs)

Bases: GenericAsset[BasinFile]

HEC-HMS Basin file asset from authoritative model, containing geometry and other detailed data.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.basin$'

class hecstac.hms.assets.OutAsset(*args, **kwargs)

Bases: GenericAsset

Out asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.out$'

class hecstac.hms.assets.PdataAsset(*args, **kwargs)

Bases: GenericAsset[PairedDataFile]

Pdata asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.pdata$'

class hecstac.hms.assets.ProjectAsset(*args, **kwargs)

Bases: GenericAsset[ProjectFile]

Project asset.

regex_parse_str: str = '.*\\.hms$'

class hecstac.hms.assets.RunAsset(*args, **kwargs)

Bases: GenericAsset[RunFile]

Run asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.run$'

class hecstac.hms.assets.SqliteAsset(*args, **kwargs)

Bases: GenericAsset[SqliteDB]

HEC-HMS SQLite database asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.sqlite$'

class hecstac.hms.assets.TerrainAsset(*args, **kwargs)

Bases: GenericAsset[TerrainFile]

Terrain asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.terrain$'

class hecstac.hms.assets.ThumbnailAsset(*args, **kwargs)

Bases: GenericAsset

Thumbnail asset.

property extra_fields

Return extra fields with added dynamic keys/values.

regex_parse_str: str = '.*\\.png$'

class hecstac.hms.assets.TiffAsset(*args, **kwargs)

Bases: GenericAsset

Tiff Asset.

regex_parse_str: str = '.*\\.tiff$'

hecstac.hms.consts module

HEC-HMS STAC Item constants.

hecstac.hms.data_model module

HEC-HMS STAC Item data classes.

class hecstac.hms.data_model.BasinHeader(attrs)

Bases: object

Header of .basin.

attrs: dict

class hecstac.hms.data_model.BasinLayerProperties(content)

Bases: object

Part of footer of .basin, find via ‘Basin Layer Properties:’. Data is stored as a series of layers rather than a set of attributes, so just storing the raw content for now.

content: str

class hecstac.hms.data_model.BasinSchematicProperties(attrs)

Bases: object

Part of footer of .basin, find via ‘Basin Schematic Properties:’.

attrs: dict

class hecstac.hms.data_model.BasinSpatialProperties(content)

Bases: object

Part of footer of .basin, find via ‘Basin Spatial Properties:’. Data has some complex attributes with nested end-flags, so just storing raw content for now.

content: str

class hecstac.hms.data_model.ComputationPoints(content)

Bases: object

Part of footer of .basin, find via ‘Computation Points:’. Data has some complex attributes with nested end-flags, so just storing raw content for now.

content: str

class hecstac.hms.data_model.Control(name, attrs)

Bases: Element

Represents a control element.

class hecstac.hms.data_model.Diversion(name, attrs, geom=None)

Bases: Element

Represents a Diversion element.

geom: Point = None

class hecstac.hms.data_model.ET(name, attrs)

Bases: Element

Represents a ET element.

class hecstac.hms.data_model.Element(name, attrs)

Bases: object

Parent class of basin elements (Subbasins, Reaches, etc).

attrs: OrderedDict

name: str

class hecstac.hms.data_model.ElementSet

Bases: object

Behaves like a dictionary of Basin elements (Subbasins, Reaches, etc) with key conflict checking.

property element_counts: dict

Get a count of each element type.

property element_types: list

Get a list of unique element types.

property gages

Retrieve gage elements with their observed hydrograph gage names.

get_element_type(element_type)

Retrieve elements of a specific type by name.

subset(element_type)

Retrieve a subset of elements of a given type.

class hecstac.hms.data_model.Gage(name, attrs)

Bases: Element

Represents a gage element.

class hecstac.hms.data_model.Grid(name, attrs)

Bases: Element

Represents a grid element.

class hecstac.hms.data_model.Junction(name, attrs, geom=None)

Bases: Element

Represents a Junction element.

geom: Point = None

class hecstac.hms.data_model.Pattern(name, attrs)

Bases: Element

Represents a Pattern element.

class hecstac.hms.data_model.Precipitation(name, attrs)

Bases: Element

Represents a precipitation element.

class hecstac.hms.data_model.Reach(name, attrs, geom=None, slope=typing.Optional[float])

Bases: Element

Represents a Reach element.

geom: LineString = None

slope

alias of float | None

class hecstac.hms.data_model.Reservoir(name, attrs, geom=None)

Bases: Element

Represents a Reservoir element.

geom: Point = None

class hecstac.hms.data_model.Run(name, attrs)

Bases: object

Runs contained in the .run file.

attrs: dict

name: str

class hecstac.hms.data_model.Sink(name, attrs, geom=None)

Bases: Element

Represents a Sink element.

geom: Point = None

class hecstac.hms.data_model.Source(name, attrs, geom=None)

Bases: Element

Represents a Source element.

geom: Point = None

class hecstac.hms.data_model.Subbasin(name, attrs, geom=None)

Bases: Element

Represents a Subbasin element.

geom: Polygon = None

class hecstac.hms.data_model.SubbasinET(name, attrs)

Bases: Element

Represents a Subbasin_ET element.

class hecstac.hms.data_model.Table(name, attrs)

Bases: Element

Represents a Table element.

class hecstac.hms.data_model.Temperature(name, attrs)

Bases: Element

Represents a temperature element.

hecstac.hms.item module

HEC-RAS STAC Item class.

class hecstac.hms.item.HMSModelItem(*args, **kwargs)

Bases: Item

An object representation of a HEC-HMS model.

MODEL_GAGES = 'hms:gages'

MODEL_UNITS = 'hms:unit system'

PROJECT = 'hms:project'

PROJECT_DESCRIPTION = 'hms:description'

PROJECT_TITLE = 'hms:project_title'

PROJECT_UNITS = 'hms:unit_system'

PROJECT_VERSION = 'hms:version'

SUMMARY = 'hms:summary'

add_asset(key, asset)

Subclass asset then add.

property bbox: list[float]

Bounding box of the HMS model.

property datetime: datetime

The datetime for the HMS STAC item.

property factory: AssetFactory

Return AssetFactory for this item.

classmethod from_prj(hms_project_file, item_id, simplify_geometry=True, assets=None, asset_dir=None)

Create an HMSModelItem from a HEC-HMS project file.

Parameters:

• hms_project_file (str) – Path to the HEC-HMS project file (.hms).

• item_id (str) – Unique item ID for the STAC item.

• simplify_geometry (bool, optional) – Whether to simplify geometry. Defaults to True.

Returns:

stac – An instance of the class representing the STAC item.

Return type:

HMSModelItem

property geometry: dict

Return footprint of the model as a GeoJSON.

property geometry_assets: list[BasinFile]

Return list of basin geometry assets.

property hms_project_file: str

Get the path to the HEC-HMS .hms file.

make_thumbnail(gdfs)

Create a png from the geodataframes (values of the dictionary). The dictionary keys are used to label the layers in the legend.

make_thumbnails(basins, pm, asset_dir, overwrite=False)

Create a PNG thumbnail for each basin.

Return type:

list[str]

property pf: ProjectFile

Get a ProjectFile instance for the HMS Model .hms file.

property properties: dict

Properties for the HMS STAC item.

write_element_geojsons(basins, pm, pf, asset_dir, overwrite=False)

Write the HMS elements (Subbasins, Juctions, Reaches, etc.) to geojson.

hecstac.hms.parser module

HEC-HMS file parsing classes.

class hecstac.hms.parser.BaseTextFile(path)

Bases: ABC

Base class for text files.

parse_header()

Scan the file down to the first instance of ‘End:’ and save each colon-separated keyval pair as attrs dict.

read_content()

Read contents of text file.

class hecstac.hms.parser.BasinFile(path, skip_scans=False, fiona_aws_session=None, read_geom=True)

Bases: BaseTextFile

Class for parsing HEC-HMS basin files.

property basin_geom

Return basin geometry.

bbox(crs)

Return basin bounding box.

property crs

Return the CRS.

property diversions

Return diversion elements.

property drainage_area

Return drainage areas..

property elements

Return basin elements.

property epsg

Return the EPSG code.

feature_2_gdf(element_type)

Convert feature to GeoDataFrame.

Return type:

GeoDataFrame

property gages

Return gages.

property hms_methods

Extract unique HMS methods from Subbasins and Reaches.

property hms_schematic_2_gdfs: dict[GeoDataFrame]

Convert HMS schematics to GeoDataframe.

identify_sqlite()

Identify SQLite.

junction_connection_lines()

Return GeoDataframe of junction connection lines.

Return type:

GeoDataFrame

property junctions

Return junction elements.

property observation_points_gdf

Return GeoDataFrame of observation points.

parse_name()

Parse basin name.

property reach_miles

Return reach lengths in miles..

property reaches

Return reach elements.

property reservoirs

Return reservoir elements.

scan_for_headers_and_footers()

Scan for basin headers and footers.

property sinks

Return sink elements.

property sources

Return source elements.

subbasin_bc_lines()

Return subbasin boundary condition lines.

subbasin_connection_lines()

Return GeoDataframe of subbasin connection lines.

Return type:

GeoDataFrame

property subbasins

Return subbasin elements.

property wkt

Return wkt representation of the CRS.

class hecstac.hms.parser.ControlFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS control files.

property name

Return control name.

class hecstac.hms.parser.GageFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS gage files.

property gages

Return gage elements.

property name

Return gage manager name.

scan_for_gages()

Search for all gages.

class hecstac.hms.parser.GridFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS grid files.

property grids

Return grid elements.

property name

Return grid manager name.

remove_grid_type(grid_types)

Remove given grid types.

scan_for_grids()

Scan for all grids.

class hecstac.hms.parser.MetFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS meteorology files.

property name

Return meteorology name.

scan_for_elements()

Scan for meteorology elements.

class hecstac.hms.parser.PairedDataFile(path, client=None, bucket=None)

Bases: BaseTextFile

Class for parsing HEC-HMS paired data files.

property name

Return paired data manager.

scan_for_patterns()

Scan for patterns.

scan_for_tables()

Scan for tables.

class hecstac.hms.parser.ProjectFile(path, recurse=True, assert_uniform_version=True)

Bases: BaseTextFile

Class for parsing HEC-HMS project files.

absolute_paths(paths)

Return absolute path.

assert_uniform_version()

Assert uniform version.

combine_stem_ext(ext)

Combine stem and extension.

Return type:

str

property dss_files

Return dss files.

property file_counts

Return file counts.

property files

Return associated files.

property name

Extract name from project file.

property rasters

Return raster files.

property result_files

Return result files.

scan_for_basins_mets_controls()

Scan for basin, meteorology, and control files.

scan_for_terrain_run_grid_gage_pdata()

Scan for terrain, run, grid, gage, and pdata files.

property sqlitedbs

Return SQLite database.

class hecstac.hms.parser.RunFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS run files.

property elements

Return run elements.

runs()

Retrieve all runs.

class hecstac.hms.parser.SqliteDB(path, fiona_aws_session=None)

Bases: object

SQLite database class.

class hecstac.hms.parser.TerrainFile(path)

Bases: BaseTextFile

Class for parsing HEC-HMS terrain files.

property name

Return name.

hecstac.hms.s3_utils module

AWS S3 utlity functions.

hecstac.hms.s3_utils.check_storage_extension(asset)

If the file is hosted on S3, add the storage extension.

Return type:

Asset

hecstac.hms.s3_utils.create_fiona_aws_session()

Create fiona s3 session.

hecstac.hms.s3_utils.file_location(file)

Return the location of a file.

Return type:

str

hecstac.hms.s3_utils.get_basic_object_metadata(obj)

Retrieve basic metadata of an AWS S3 object.

Return type:

dict

Parameters:

(ObjectSummary) (obj)

Returns:

dict: A dictionary with the size, ETag, last modified date, storage platform, region, and

storage tier of the object.

hecstac.hms.s3_utils.get_metadata(key)

Read the head object and return metadata.

Return type:

dict

hecstac.hms.s3_utils.init_s3_resources2(minio_mode=False)

Initialize s3 resources.

hecstac.hms.s3_utils.split_s3_key(s3_path)

Split an S3 path into the bucket name and the key.

Return type:

tuple[str, str]

Parameters:

(str) (s3_path)

Returns:

• tuple: A tuple containing the bucket name and the key. If the S3 path does not contain a key, the second element

  of the tuple will be None.

• The function performs the following steps –

  1. Removes the ‘s3://’ prefix from the S3 path.

  2. Splits the remaining string on the first ‘/’ character.

  3. Returns the first part as the bucket name and the second part as the key. If there is no ‘/’, the key will be None.

hecstac.hms.utils module

HEC-HMS STAC Item utlity functions.

class hecstac.hms.utils.StacPathManager(local_catalog_dir)

Bases: object

Build consistent paths for STAC items and collections assuming a top level local catalog.

catalog_asset(item_id, asset_dir='hydro_domains')

Return the catalog asset file path.

Return type:

str

property catalog_dir

Return the catalog directory.

property catalog_file

Return the catalog file path.

catalog_item(item_id)

Return the catalog item file path.

Return type:

str

collection_asset(collection_id, filename)

Return the collection asset filepath.

Return type:

str

collection_dir(collection_id)

Return the collection directory.

Return type:

str

collection_file(collection_id)

Return the collection file path.

Return type:

str

collection_item(collection_id, item_id)

Return the collection item filepath.

Return type:

str

collection_item_asset(collection_id, item_id, filename)

Return the collection item asset filepath.

Return type:

str

collection_item_dir(collection_id, item_id)

Return the collection item directory.

Return type:

str

hecstac.hms.utils.add_no_duplicate(d, key, val)

Insert a key into a dictionary, logging a warning if the key already exists.

hecstac.hms.utils.attrs2list(attrs)

Convert dictionary of attributes to a list.

Return type:

list[str]

hecstac.hms.utils.get_lines_until_end_sentinel(lines)

Retrieve all lines until the End point.

Return type:

list[str]

hecstac.hms.utils.handle_special_cases(key, val)

Handle special cases.

hecstac.hms.utils.insert_after_key(dic, insert_key, new_key, new_val)

Recreate the dictionary to insert key-val after the occurance of the insert_key if key-val doesn’t exist yet in the dictionary.

Return type:

OrderedDict

hecstac.hms.utils.parse_attrs(lines)

Scan the lines down to the first instance of ‘End:’ and return dict containing all of the colon-separated keyval pair.

Return type:

OrderedDict

hecstac.hms.utils.remove_holes(geom)

Remove holes in the geometry.

hecstac.hms.utils.search_contents(lines, search_string, token='=', expect_one=True)

Split a line by a token and returns the second half of the line if the search_string is found in the first half.

Return type:

list[str]

Module contents

HEC-HMS STAC Item module.