pydsstools.core.gridinfo

Grid metadata package for HEC-DSS grid data (Version 7).

This package provides a reorganized, type-specific implementation of grid metadata classes for HEC-DSS files. It’s structured for better maintainability and clearer separation of concerns.

Quick Start

>>> from pydsstools.core.gridinfo import GridInfoCreate, GridType, DataType
>>>
>>> # Create HRAP grid
>>> hrap_info = GridInfoCreate(
...     grid_type=GridType.hrap,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=4762.5,
...     data_units="MM"
... )
>>>
>>> # Create Albers/SHG grid
>>> albers_info = GridInfoCreate(
...     grid_type=GridType.albers,
...     data_type=DataType.inst_val,
...     shape=(500, 700),
...     cell_size=2000.0,
...     min_xy=(-1500000, 500000),
...     data_units="M"
... )
>>>
>>> # Create Specified grid with custom CRS
>>> spec_info = GridInfoCreate(
...     grid_type=GridType.specified,
...     data_type=DataType.per_aver,
...     shape=(200, 300),
...     cell_size=1000.0,
...     crs="EPSG:32610",
...     crs_name="WGS84 / UTM zone 10N",
...     nodata=-9999.0,
...     data_units="MM"
... )

Grid Classes

The package supports four grid information types:

• GridInfo - Undefined/basic grid. Generic grid without specific projection information.

• HrapInfo - HRAP (Hydrologic Rainfall Analysis Project). Polar stereographic projection for precipitation data. Standard cell size: 4.7625 km at 60N.

• AlbersInfo - Albers Equal Area Conic. Commonly used for Standard Hydrologic Grid (SHG) in HEC-HMS. Default: NAD83 / Conus Albers (EPSG:5070).

• SpecifiedInfo - User-defined projection. Custom CRS using WKT, PROJ strings, or EPSG codes. Maximum flexibility for any coordinate system.

Public API

• Main Classes: GridInfo, HrapInfo, AlbersInfo, SpecifiedInfo

• Factory: GridInfoCreate - Recommended way to create grid info objects

• Enumerations: GridType, DataType, CompressionMethod, Datum

• Utilities: is_undefined_grid, is_hrap_grid, is_albers_grid, is_specified_grid, grid_extent, grids_overlap, validate_grid_consistency

• v6 Compatibility: gridinfo.v6 - DSS Version 6 structures and conversion

pydsstools.core.gridinfo.GridInfoCreate(**kwargs)

Factory function to create appropriate GridInfo subclass.

Automatically selects the correct GridInfo subclass (GridInfo, HrapInfo, AlbersInfo, or SpecifiedInfo) based on the grid_type parameter.

This is the recommended way to create grid metadata objects as it:

• Provides type validation

• Ensures correct class selection

• Validates all required fields

• Applies default values

Parameters:

**kwargs – Keyword arguments for grid metadata. Must include ‘grid_type’. Other required/optional parameters depend on the grid type.

Returns:

Instance of GridInfo, HrapInfo, AlbersInfo, or SpecifiedInfo.

Return type:

GridInfoBase

Raises:

• TypeError – If no keyword arguments provided.

• ValidationError – If required fields are missing or invalid.

Examples

Create HRAP grid metadata:

>>> from pydsstools.core.gridinfo import GridInfoCreate, GridType, DataType
>>> info = GridInfoCreate(
...     grid_type=GridType.hrap,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=4762.5,
...     data_units="MM",
...     data_source="NEXRAD"
... )
>>> type(info).__name__
'HrapInfo'

Create Albers/SHG grid metadata:

>>> info = GridInfoCreate(
...     grid_type=GridType.albers,
...     data_type=DataType.inst_val,
...     shape=(500, 700),
...     cell_size=2000.0,
...     proj_datum=Datum.nad83,
...     lat_0=23.0,
...     lat_1=29.5,
...     lat_2=45.5,
...     lon_0=-96.0,
...     min_xy=(-1500000, 500000),
...     data_units="M"
... )
>>> type(info).__name__
'AlbersInfo'

Create specified grid with custom CRS:

>>> info = GridInfoCreate(
...     grid_type=GridType.specified,
...     data_type=DataType.per_aver,
...     shape=(200, 300),
...     cell_size=1000.0,
...     crs="EPSG:32610",
...     crs_name="WGS84 / UTM zone 10N",
...     nodata=-9999.0,
...     min_xy=(500000, 4000000),
...     data_units="MM"
... )
>>> type(info).__name__
'SpecifiedInfo'

Create undefined/basic grid:

>>> info = GridInfoCreate(
...     grid_type=GridType.undefined,
...     data_type=DataType.inst_val,
...     shape=(100, 100),
...     cell_size=1000.0,
...     data_units="M"
... )
>>> type(info).__name__
'GridInfo'

With extra fields:

>>> info = GridInfoCreate(
...     grid_type=GridType.hrap,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=4762.5,
...     data_units="MM",
...     custom_field="custom_value",  # Goes to extra dict
...     another_field=123
... )
>>> info.extra_info['custom_field']
'custom_value'

Notes

The factory uses Pydantic’s discriminated union feature to automatically select the correct class based on grid_type. This provides:

• Better error messages for invalid fields

• Type-specific validation

• Clear separation of grid type concerns

Grid Type Mapping:

• GridType.undefined or undefined_time → GridInfo

• GridType.hrap or hrap_time → HrapInfo

• GridType.albers or albers_time → AlbersInfo

• GridType.specified or specified_time → SpecifiedInfo

class pydsstools.core.gridinfo.GridInfo(**data)

Bases: GridInfoBase

Metadata for undefined/basic grid type (DSS v7).

This class represents grid data without specific projection information. It contains all basic grid properties: dimensions, cell size, compression, statistics, and optional spatial bounds.

Use this grid type when working with generic raster data, when projection information is not available or not relevant, or when no coordinate transformation is needed.

Examples

Create a basic undefined grid:

>>> from pydsstools.core.gridinfo import GridInfo, GridType, DataType
>>> info = GridInfo(
...     grid_type=GridType.undefined,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=1000.0,
...     data_units="MM"
... )

Or use the factory function (recommended):

>>> from pydsstools.core.gridinfo import GridInfoCreate
>>> info = GridInfoCreate(
...     grid_type=GridType.undefined,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=1000.0,
...     data_units="MM"
... )

grid_type

Type of grid projection. Only undefined and undefined_time are valid. Default GridType.undefined_time.

Type:

GridType

data_units

Physical units of the data (e.g., “MM”, “M”, “CFS”). Default "".

Type:

str

data_type

Temporal aggregation type (per_aver, per_cum, inst_val, inst_cum, freq). Required.

Type:

DataType

lower_left_cell

(x, y) indices of the lower-left cell. Default (0, 0).

Type:

tuple[int, int] or None

shape

Grid dimensions as (rows, columns). Required.

Type:

tuple[int, int]

cell_size

Cell size in projection units (assumed square cells). Required.

Type:

float

compression_method

Compression algorithm for data storage. Default CompressionMethod.zlib.

Type:

CompressionMethod

compression_base

Base value for compression scaling. Default 0.0.

Type:

float

compression_factor

Scale factor for compression. Default 0.0.

Type:

float

max_val

Maximum data value in grid. Default 0.0.

Type:

float

min_val

Minimum data value in grid. Default 0.0.

Type:

float

mean_val

Mean data value in grid. Default 0.0.

Type:

float

range_vals

Histogram bin edges for data distribution. Default [].

Type:

list[float]

range_counts

Count of values in each histogram bin. Default [].

Type:

list[int]

min_xy

(x_min, y_min) coordinates of grid extent. Default None.

Type:

tuple[float, float] or None

class pydsstools.core.gridinfo.HrapInfo(**data)

Bases: GridInfo

Metadata for HRAP (Hydrologic Rainfall Analysis Project) grid.

HRAP uses a polar stereographic projection centered on the North Pole, commonly used for precipitation data in hydrologic modeling. The standard HRAP grid has 4.7625 km cell size at 60°N latitude.

In addition to the parameters inherited from GridInfo, this class adds data_source for tracking data provenance.

Examples

Create HRAP grid for NEXRAD precipitation:

>>> from pydsstools.core.gridinfo import HrapInfo, GridType, DataType
>>> info = HrapInfo(
...     grid_type=GridType.hrap,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=HRAP_CELL_SIZE,  # 4762.5 m
...     data_units="MM",
...     data_source="NEXRAD"
... )

Or use the factory function (recommended):

>>> from pydsstools.core.gridinfo import GridInfoCreate
>>> info = GridInfoCreate(
...     grid_type=GridType.hrap,
...     data_type=DataType.per_aver,
...     shape=(100, 150),
...     cell_size=HRAP_CELL_SIZE,
...     data_units="MM",
...     data_source="NEXRAD"
... )

Notes

HRAP Projection Parameters:

• Projection: Polar Stereographic

• Latitude of true scale: 60N

• Central meridian: 105W

• False easting: 401 grid cells

• False northing: 1601 grid cells

• Standard cell size: 4.7625 km at 60N

Typical Users:

• National Weather Service (NWS)

• River Forecast Centers (RFCs)

• HEC-HMS for precipitation input

Coordinate System:

• Origin is at the North Pole

• X-axis points along 105W meridian

• Grid cells are 4.7625 km x 4.7625 km at 60N

• Standard grid covers the United States

Common Data Sources:

• NEXRAD - Next-Generation Radar

• MPE - Multi-sensor Precipitation Estimator

• RFC - River Forecast Center

• PRISM - Parameter-elevation Regressions on Independent Slopes Model

References

[hrap1]

NOAA National Weather Service, “HRAP Coordinate System” https://www.nws.noaa.gov/oh/hrl/nwsrfs/users_manual/part2/_pdf/22hrap.pdf

grid_type

Type of grid projection. Only hrap and hrap_time are valid. Default GridType.hrap_time.

Type:

GridType

data_source

Source or provenance of the data. Common values: "NEXRAD", "MPE", "RFC", "PRISM". Default "".

Type:

str

class pydsstools.core.gridinfo.AlbersInfo(**data)

Bases: GridInfo

Metadata for Albers Equal Area Conic projection grid.

Albers grids are commonly used for the Standard Hydrologic Grid (SHG) in HEC-HMS, typically using NAD83 datum with CONUS Albers parameters (EPSG:5070).

In addition to the parameters inherited from GridInfo, this class adds projection parameters for Albers Equal Area Conic projection.

Examples

Create standard SHG grid:

>>> from pydsstools.core.gridinfo import build_shg_gridinfo, DataType
>>> info = build_shg_gridinfo(
...     shape=(500, 700),
...     cell_size=2000.0,  # 2 km cells
...     min_xy=(-1500000, 500000),  # SW corner in EPSG:5070
...     data_type=DataType.inst_val,
...     data_units="M"
... )

Create custom Albers grid:

>>> from pydsstools.core.gridinfo import AlbersInfo, Datum
>>> info = AlbersInfo(
...     grid_type=GridType.albers,
...     data_type=DataType.per_aver,
...     shape=(300, 400),
...     cell_size=5000.0,
...     proj_datum=Datum.nad83,
...     lat_0=37.0,
...     lat_1=34.0,
...     lat_2=40.5,
...     lon_0=-120.0,
...     data_units="MM"
... )

Update from CRS WKT:

>>> wkt = "PROJCS[...]"  # Full WKT string
>>> info = AlbersInfo(...)
>>> update_albers_from_crs(info, wkt)

Notes

Albers Projection Properties:

• Equal-area conic projection

• Preserves area (important for hydrologic modeling)

• Minimizes distortion along standard parallels

• Suitable for east-west oriented regions (e.g., CONUS)

Standard Hydrologic Grid (SHG) Default Parameters (EPSG:5070):

• Datum: NAD83

• Units: meter

• Origin latitude: 23.0°N

• First parallel: 29.5°N

• Second parallel: 45.5°N

• Central meridian: -96.0°W

• False easting/northing: 0, 0

Grid Coordinate Concepts:

For Albers/SHG grids, two coordinate pairs are critical:

• coords_cell0: Coordinates of cell (0,0) in the global grid system. Usually equals (false_easting, false_northing) = (0, 0) for SHG. Defines the projection origin.

• lower_left_cell: Cell indices of your grid’s lower-left corner. Calculated as: (floor((xmin - x_0) / cellsize), floor((ymin - y_0) / cellsize)). Indicates which cell in the global SHG grid corresponds to your grid origin.

This allows multiple grid datasets to be spatially referenced in the same coordinate system.

Typical Users:

• HEC-HMS for watershed modeling

• HEC-RAS for floodplain mapping

• Hydrologic modeling in the United States

References

[albers1]

HEC-HMS Technical Reference Manual https://www.hec.usace.army.mil/confluence/hmsdocs/

[albers2]

Standard Hydrologic Grid (SHG) https://www.hec.usace.army.mil/confluence/hmsdocs/hmsum/4.8/geographic-information/coordinate-reference-systems

grid_type

Type of grid projection. Only albers and albers_time are valid. Default GridType.albers_time.

Type:

GridType

proj_datum

Datum for the projection. Default Datum.nad83.

Type:

Datum

proj_units

Linear units of the projection. Default "meter".

Type:

str

lat_0

Latitude of projection origin (degrees). Default 23.0.

Type:

float

lat_1

Latitude of first standard parallel (degrees). Default 29.5.

Type:

float

lat_2

Latitude of second standard parallel (degrees). Default 45.5.

Type:

float

lon_0

Longitude of central meridian (degrees). Default -96.0.

Type:

float

x_0

False easting (projection units). Default 0.0.

Type:

float

y_0

False northing (projection units). Default 0.0.

Type:

float

coords_cell0

(easting, northing) of southwest corner of cell (0,0). Default (0.0, 0.0).

Type:

tuple[float, float] or None

update_lower_left_cell_from_minxy()

Update lower_left_cell indices from min_xy coordinates.

Calculates the cell indices for the lower-left corner of the grid based on min_xy and the projection origin (coords_cell0).

Raises:

ValueError – If min_xy is not set.

Notes

Modifies lower_left_cell in-place.

update_lower_left_cell_from_transform(transform)

Update lower_left_cell indices from affine transform.

Parameters:

transform (Affine) – 6-element affine transform: (dx, 0, xmin, 0, dy, ymax).

Raises:

ValueError – If cell size in transform doesn’t match gridinfo cell_size.

Notes

Modifies lower_left_cell in-place.

update_crs_params(crs_wkt)

normalize(transform=None)

Normalize coords_cell0 and/or lower_left_cell based on grid_type.

This is implemented in the concrete classes.

Parameters:

transform (Affine or None, optional) – Affine transform of grid or raster data. Default is None.

class pydsstools.core.gridinfo.SpecifiedInfo(**data)

Bases: GridInfo

Metadata for user-specified projection grid.

Specified grids allow arbitrary coordinate reference systems defined via WKT, PROJ strings, or EPSG codes. This provides maximum flexibility for custom projections and datums.

In addition to the parameters inherited from GridInfo, this class adds CRS definition and time zone parameters.

Examples

Create specified grid with UTM projection:

>>> from pydsstools.core.gridinfo import SpecifiedInfo, DataType
>>> info = SpecifiedInfo(
...     grid_type=GridType.specified,
...     data_type=DataType.per_aver,
...     shape=(200, 300),
...     cell_size=1000.0,
...     crs="EPSG:32610",  # WGS84 / UTM zone 10N
...     crs_name="WGS84 / UTM zone 10N",
...     nodata=-9999.0,
...     min_xy=(500000, 4000000),  # UTM coordinates
...     data_units="MM",
...     tzid="America/Los_Angeles",
...     tzoffset=-8
... )

Using factory function (recommended):

>>> from pydsstools.core.gridinfo import GridInfoCreate
>>> info = GridInfoCreate(
...     grid_type=GridType.specified,
...     data_type=DataType.inst_val,
...     shape=(100, 150),
...     cell_size=500.0,
...     crs="EPSG:2263",  # NAD83 / New York Long Island (ftUS)
...     crs_name="NY Long Island",
...     nodata=-9999.0,
...     data_units="FT"
... )

Update coords from transform:

>>> transform = (1000, 0, 500000, 0, -1000, 4200000)
>>> info = SpecifiedInfo(...)
>>> update_specified_coords_from_transform(info, transform)

Notes

MetVue Conventions:

HEC-MetVue uses specific conventions for specified grids:

• lower_left_cell is always (0, 0)

• coords_cell0 equals min_xy (lower-left corner coordinates)

• This differs from Albers/SHG where lower_left_cell can be non-zero

CRS Formats Supported:

• EPSG Codes: "EPSG:4326" (WGS84 lat/lon), "EPSG:32610" (UTM zone 10N)

• PROJ Strings: "+proj=utm +zone=10 +datum=WGS84 +units=m +no_defs"

• WKT: Full Well-Known Text representation

Typical Users:

• HEC-MetVue for custom precipitation grids

• Projects with non-standard coordinate systems

• International projects with local datums

Key Differences from Albers/SHG:

• coords_cell0 represents actual grid corner (not projection origin)

• lower_left_cell is always (0,0)

• More flexible but requires explicit CRS definition

Time Zone Handling:

• tzid should be a standard IANA time zone name

• tzoffset is the offset from UTC in hours

• Both can be used; tzid is preferred for DST handling

References

[specified1]

HEC-MetVue User’s Manual https://www.hec.usace.army.mil/confluence/metdoc/metum/3.4.0/

[specified2]

DSS SpecifiedGridInfo in MetVue https://www.hec.usace.army.mil/confluence/metdoc/metum/3.4.0/general-information-and-tips/dss-specifiedgridinfo-in-hec-metvue

grid_type

Type of grid projection. Only specified and specified_time are valid. Default GridType.specified_time.

Type:

GridType

crs

Coordinate reference system definition (WKT, PROJ, or EPSG code). Default "".

Type:

str

crs_name

Short name or identifier for the CRS (e.g., “EPSG:26910”). Default "".

Type:

str

nodata

NoData value for missing/invalid cells (can be NaN or inf). Required.

Type:

float

tzid

Time zone identifier (e.g., “America/Los_Angeles”, “UTC”). Default "".

Type:

str

tzoffset

Time zone offset from UTC in hours (-24 to +24). Default 0.

Type:

int

coords_cell0

Coordinates of southwest corner of cell (0,0). Default (0.0, 0.0).

Type:

tuple[float, float] or None

is_interval

If True, timestamps represent interval end. Default True.

Type:

bool

time_stamped

If True, data is associated with timestamps. Default True.

Type:

bool

update_cell0_from_minxy()

Set coords_cell0 from min_xy.

Following MetVue convention, coords_cell0 equals min_xy for specified grids.

Raises:

ValueError – If min_xy is not set.

Notes

Modifies coords_cell0 and lower_left_cell in-place. lower_left_cell is always set to (0, 0).

update_cell0_from_transform(transform)

Update coords_cell0 from affine transform.

Parameters:

transform (tuple) – 6-element affine transform: (dx, 0, xmin, 0, dy, ymax).

Raises:

ValueError – If cell size in transform doesn’t match gridinfo cell_size.

Notes

Modifies coords_cell0 and lower_left_cell in-place. lower_left_cell is always set to (0, 0).

normalize(transform=None)

Normalize coords_cell0 and/or lower_left_cell based on grid_type.

This is implemented in the concrete classes.

Parameters:

transform (Affine or None, optional) – Affine transform of grid or raster data. Default is None.

Modules

albers	Albers grid type implementation and SHG utilities.
base	Base classes and common utilities for grid metadata.
factory	Factory function for creating grid metadata objects.
hrap	HRAP grid type implementation and utilities.
specified	Specified grid type implementation and utilities.
transforms	Coordinate transformation and grid utility functions.
undefined	Undefined grid type implementation.
v6	DSS Version 6 compatibility layer.