pydsstools.core.gridinfo.specified

Specified grid type implementation and utilities.

This module provides the SpecifiedInfo class for grids with user-defined coordinate reference systems. This is the most flexible grid type, supporting any CRS via WKT, PROJ, or EPSG codes.

Functions

`coords_of_cell0_of_specified_grid`(transform, ...)	Calculate cell (0,0) coordinates for specified grid.
`update_specified_coords_from_transform`(...)	Update coords_cell0 for specified grid from affine transform.

Classes

SpecifiedInfo(**data)

Metadata for user-specified projection grid.

class pydsstools.core.gridinfo.specified.SpecifiedInfo(**data)[source]

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()[source]

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)[source]

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)[source]

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.

pydsstools.core.gridinfo.specified.update_specified_coords_from_transform(gridinfo, transform)[source]

Update coords_cell0 for specified grid from affine transform.

This is a convenience function that calls gridinfo.update_coords_from_transform().

Parameters:

gridinfo (SpecifiedInfo) – Specified grid info object to update.
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.

Examples

>>> from pydsstools.core.gridinfo import SpecifiedInfo, update_specified_coords_from_transform
>>> info = SpecifiedInfo(
...     shape=(200, 300),
...     cell_size=1000.0,
...     crs="EPSG:32610",
...     nodata=-9999.0,
...     data_type=DataType.per_aver
... )
>>> transform = (1000, 0, 500000, 0, -1000, 4200000)
>>> update_specified_coords_from_transform(info, transform)
>>> print(info.coords_cell0)
(500000.0, 4000000.0)
>>> print(info.lower_left_cell)
(0, 0)